# watir

Watir Powered By Selenium!

[![Gem Version](https://badge.fury.io/rb/watir.svg)](http://badge.fury.io/rb/watir)
[![Unit Tests](https://github.com/watir/watir/workflows/Unit%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Unit+Tests%22)
[![Mac Tests](https://github.com/watir/watir/workflows/Mac%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Mac+Tests%22)
[![Windows Tests](https://github.com/watir/watir/workflows/Windows%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Windows+Tests%22)
[![Linux Tests](https://github.com/watir/watir/workflows/Linux%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Linux+Tests%22)
[![Code Climate](https://codeclimate.com/github/watir/watir.svg)](https://codeclimate.com/github/watir/watir)
[![Coverage Status](https://coveralls.io/repos/github/watir/watir/badge.svg?branch=main)](https://coveralls.io/github/watir/watir?branch=main)

## 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](http://watir.com): 
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:

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

Second, initialize WatirSpec for your gem:

```bash
$ 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](https://github.com/jarib/webidl).

Generated elements are currently based on the following specifications:

* [HTML](https://www.w3.org/TR/2017/REC-html52-20171214/) (`lib/watir/elements/html_elements.rb`)
* [SVG](https://www.w3.org/TR/2018/CR-SVG2-20180807/) (`lib/watir/elements/svg_elements.rb`)

To run:
```bash
$ bundle exec rake html:update
$ bundle exec rake svg:update
```

## Specs

#### Github Actions

Watir specs are run with [Github Actions](https://github.com/watir/watir/workflows).

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

#### Doctests

Watir uses [yard-doctest](https://github.com/p0deje/yard-doctest) to directly test
our documentation examples.

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

#### Coveralls

Watir code is run through [Coveralls](https://coveralls.io/github/watir/watir) to encourage PRs
to ensure all paths in their code have tests associated with them.

#### Rubocop

Watir is using [Rubocop](https://github.com/rubocop-hq/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](https://github.com/watir/watir/blob/main/.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](https://github.com/titusfortner/selenium_statistics)
to verify that changes to the code do not dramatically decrease the performance based
on wire calls.

## Copyright

See LICENSE for details