teamcapybara--capybara/UPGRADING.md

Upgrading from Capybara 2.x to 3.x

Server

Capybara 3 changes the default server to Puma. If you do not use Puma in your project you can revert to the previous default of WEBRick by specifying

Capybara.server = :webrick

Finders

The biggest user differences between Capybara 2.x and 3.x are the changes in behavior of first and all. In Capybara 2.x both methods would, by default, return immediately with nil if no matching elements exist on the page. In Capybara 3.x this has changed to include the waiting/retrying behavior found in the other Capybara finders and matchers.

first will now wait up to Capybara.default_max_wait_time seconds for at least one matching element to exist, and return the first matching element. If no matching elements are found within the time it will now raise a Capybara::ElementNotFound error instead of returning nil. If you need to maintain the previous behavior you can pass minimum: 0 as an option to first

first('div', minimum: 0)

all will now wait up to Capybara.default_max_wait_time seconds for at least one matching element to exist, and return the matching elements. If no matching elements are found within the time it will return an empty result set. If you need to maintain the previous behavior you can pass wait: false as an option to all

all('div', wait: false)

Node

Node#text no longer fully normalizes whitespace, instead returning text as close as possible to "as rendered". This means non-blanking spaces will no longer be collapsed, carriage returns may be returned in text strings, etc. This affects not only the Node#text method but also methods that take a :text option as well as the text related predicates, assertions, and matchers (has_text?, has_content?, assert_text, have_text, etc.).