<commit_before># Spreewald

Spreewald is a collection of useful steps for cucumber. Feel free to fork.

You can find a list of all contained steps at the end of this README.

## Installation

Add this line to your application's Gemfile:

    gem 'spreewald'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install spreewald


## Supported RSpec versions

Spreewald supports RSpec >= 2.13.0

## Usage

Require all Spreewald steps by putting

    require 'spreewald/all_steps'

into either your `support/env.rb` or `step_definitions/spreewald_steps.rb`.

Steps are grouped into a number of categories. If you only want to use a subset
of Spreewald's steps, you can pick and choose single categories by requiring
single files like this:

    require 'spreewald/email_steps'
    require 'spreewald/web_steps'


## Spreewald binary

Spreewald comes with a binary that prints a list of all Cucumber steps from
Spreewald _and your project_. It will filter the list by any string you
pass it. Example usage:

```bash
spreewald # lists all steps
spreewald mail # lists all steps that contain "mail"
```

The binary also prints paths and selectors; run `spreewald --help` to learn more.


## Waiting for page load

Spreewald's web steps are all aware that you might run them with a Selenium/Capybara webdriver, and wait for the browser to finish loading the page, if necessary.

This is done by rerunning any assertions until they succeed or a timeout is reached.

We consider a couple of potential exceptions as "retriable", including

    Capybara::ElementNotFound, (R)Spec::Expectations::ExpectationNotMetError, Capybara::Poltergeist::ClickFailed

You can add your own error class with

    ToleranceForSeleniumSyncIssues::RETRY_ERRORS << 'MyCustomError'

You can achieve this in your own steps by wrapping them inside a `patiently do` block, like

    Then /^I should see "([^\"]*)" in the HTML$/ do |text|
      patiently do
        page.body.should include(text)
      end
    end

More info [here](https://makandracards.com/makandra/12139-waiting-for-page-load-with-spreewald).


## Overriding steps

Thanks to [cucumber_priority](https://github.com/makandra/cucumber_priority) you can override any step definition from Spreewald with your own pattern. Cucumber will not raise `Cucumber::Ambiguous` if your custom steps collide with a Spreewald step.


## A note on Capybara 3

If you are upgrading from Capybara 2 to Capybara 3, you might [see failing tests](https://github.com/makandra/spreewald/issues/95) with Spreewald steps like `I should see`. This is caused by a breaking change in [Capybara's Finders](https://www.rubydoc.info/github/jnicklas/capybara/Capybara/Node/Finders) that accept a `:text` option. To activate Capybara 2 behavior globally in your project, enable this flag:

```ruby
Capybara.default_normalize_ws = true
````

This will affect all Spreewald steps that are using Capybara's `:text` option.

Furthermore, we recommend setting [Capybara's matching strategy](https://github.com/teamcapybara/capybara/blob/master/README.md#strategy) to `:prefer_exact`. This will positively affect Spreewald steps as it prevents the `Capybara::Ambiguous` error in the edge case when two fields are matching the given name, but one of the matches includes the name only as a substring,

```ruby
Capybara.match = :prefer_exact
````

## Contributing

### Testing

[Gemika](https://github.com/makandra/gemika) is used to manage Gemfiles for different ruby versions.

Spreewald has different kind of tests:
- Unit tests live in `spec/`<commit_msg>Add instruction for aria-label support<commit_after># Spreewald

Spreewald is a collection of useful steps for cucumber. Feel free to fork.

You can find a list of all contained steps at the end of this README.

## Installation

Add this line to your application's Gemfile:

    gem 'spreewald'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install spreewald


## Supported RSpec versions

Spreewald supports RSpec >= 2.13.0

## Usage

Require all Spreewald steps by putting

    require 'spreewald/all_steps'

into either your `support/env.rb` or `step_definitions/spreewald_steps.rb`.

Steps are grouped into a number of categories. If you only want to use a subset
of Spreewald's steps, you can pick and choose single categories by requiring
single files like this:

    require 'spreewald/email_steps'
    require 'spreewald/web_steps'

Have a look at our [recommended Capybara defaults](#recommended-capybara-defaults) as they impact the behavior of many Spreewald steps.

## Spreewald binary

Spreewald comes with a binary that prints a list of all Cucumber steps from
Spreewald _and your project_. It will filter the list by any string you
pass it. Example usage:

```bash
spreewald # lists all steps
spreewald mail # lists all steps that contain "mail"
```

The binary also prints paths and selectors; run `spreewald --help` to learn more.


## Waiting for page load

Spreewald's web steps are all aware that you might run them with a Selenium/Capybara webdriver, and wait for the browser to finish loading the page, if necessary.

This is done by rerunning any assertions until they succeed or a timeout is reached.

We consider a couple of potential exceptions as "retriable", including

    Capybara::ElementNotFound, (R)Spec::Expectations::ExpectationNotMetError, Capybara::Poltergeist::ClickFailed

You can add your own error class with

    ToleranceForSeleniumSyncIssues::RETRY_ERRORS << 'MyCustomError'

You can achieve this in your own steps by wrapping them inside a `patiently do` block, like

    Then /^I should see "([^\"]*)" in the HTML$/ do |text|
      patiently do
        page.body.should include(text)
      end
    end

More info [here](https://makandracards.com/makandra/12139-waiting-for-page-load-with-spreewald).


## Overriding steps

Thanks to [cucumber_priority](https://github.com/makandra/cucumber_priority) you can override any step definition from Spreewald with your own pattern. Cucumber will not raise `Cucumber::Ambiguous` if your custom steps collide with a Spreewald step.


## Recommended Capybara defaults

If you are upgrading from Capybara 2 to Capybara 3, you might [see failing tests](https://github.com/makandra/spreewald/issues/95) with Spreewald steps like `I should see`. This is caused by a breaking change in [Capybara's Finders](https://www.rubydoc.info/github/jnicklas/capybara/Capybara/Node/Finders) that accept a `:text` option. To activate Capybara 2 behavior globally in your project, enable this flag:

```ruby
Capybara.default_normalize_ws = true
````

This will affect all Spreewald steps that are using Capybara's `:text` option.

Furthermore, we recommend setting [Capybara's matching strategy](https://github.com/teamcapybara/capybara/blob/master/README.md#strategy) to `:prefer_exact`. This will positively affect Spreewald steps as it prevents the `Capybara::Ambiguous` error in the edge case when two fields are matching the given name, but one of the matches includes the name only as a substring,

```ruby
Capybara.match = :prefer_exact
````

If you want Spreewald to match fields, links and buttons against the `aria-label` attribute, enable the following global configuration in Capybara 2.8+: 

```ruby
Capybara.enable_aria_label = true
```

## Contributing

### Testing

[Gemika](https://github.com/makandra/gemika) is used to manage Gemfiles for different ruby versions.

Spreewald has different kind of tests:
- Unit tests live in `spec/`
{'fraction_non_alphanumeric': 0.07488693801542963, 'fraction_numerical': 0.004123437084330939, 'mean_word_length': 4.4683636363636365, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 5, 'https://': 12, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2508250', 'n_tokens_mistral': 2293, 'n_tokens_neox': 2155, 'n_words': 931}