watir

Watir Powered By Selenium!

Gem Version Chrome Tests Edge Tests Firefox Tests IE Tests Safari Tests Unit Tests

Using Watir

This README is for people interested in writing code for Watir or gems in the Watir ecosystem that leverage private-api Watir code.

For our users, everything you'll need is on the Watir website: examples, news, guides, additional resources, support information and more.

Procedure for Patches/Pull Requests

  • Fork the project.
  • Clone onto your local machine.
  • Create a new feature branch (bonus points for good names).
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so we don't unintentionally break it in a future version.
  • Commit, do not change Rakefile, gemspec, or CHANGES files, we'll take care of that on release.
  • Make sure it is passing doctests.
  • Make sure it is passing rubocop.
  • Push to your forked repository.
  • Send a pull request.

Developing Extensions

When developing a gem intended to be used with Watir, you can run your code with WatirSpec to make sure that requiring your code does not break something else in Watir.

First, add WatirSpec Rake tasks to your gem:

# Rakefile
require 'watirspec/rake_tasks'
WatirSpec::RakeTasks.new

Second, initialize WatirSpec for your gem:

$ bundle exec rake watirspec:init

This command will walk you through how to customize your code.

Automatic Element Generation

The majority of element methods Watir provides is autogenerated from specifications. This is done by extracting the IDL parts from the spec and processing them with the WebIDL gem.

Generated elements are currently based on the following specifications:

  • HTML (lib/watir/elements/html_elements.rb)
  • SVG (lib/watir/elements/svg_elements.rb)

To run:

$ bundle exec rake html:update
$ bundle exec rake svg:update

Specs

Github Actions

Watir specs are run with Github Actions.

Watir code is tested on Linux with latest versions of supported browsers and all active Ruby versions.

Doctests

Watir uses yard-doctest to directly test our documentation examples.

mkdir ~/.yard
bundle exec yard config -a autoload_plugins yard-doctest
rake yard:doctest

Coveralls

Watir code is run through Coveralls to encourage PRs to ensure all paths in their code have tests associated with them.

Rubocop

Watir is using Rubocop to ensure a consistent style across the code base. It is run with our minimum supported Ruby version (2.3) We have some established exceptions at .rubocop.yml that might need to be tweaked for new code submissions. This can be addressed in the PR as necessary.

Statistics

Element specs are run with Selenium Statistics gem to verify that changes to the code do not dramatically decrease the performance based on wire calls.

See LICENSE for details