capybara 2.13.0 → 2.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 266938107d80bacdd4f95cc21e79fe6b7af2e131
-  data.tar.gz: dac8ea7395988fc218da8a556df246db661125b0
+SHA256:
+  metadata.gz: fb46b7bc5ae7408ca3870b781d015a84bd84abd0a9c7e3ea2bcdf3d8fff85ce8
+  data.tar.gz: 1865dc1efa384c3792161a134bc536c56dca3aa0670ca298ad9f3aa12b49830d
 SHA512:
-  metadata.gz: a548da527db279933776ebd86daa6ddf1d7e714bc9b22225959d58b67bbecfa8458f503cde377fc262f0d4442ef6d0f47a88a1bcf66efd58bc5014d80b80f87d
-  data.tar.gz: f040e322ba5e591dbc3546b0e5c7672f21b6e9eab99ff848780f42e1e1d9e5ce87bdfe242ae0dbb7a45b4ecb37611d3c1c1a202cedcc1e16cc00040114422213
+  metadata.gz: 9bc2cb739af408323d977b7ca829aa0862ef68ab7d1778c5ae67fb127a47a09258c1f5b53f9d7955bcfcd2892c869a136d7a5346b9115a9e55713ea47c95ebb3
+  data.tar.gz: e8d234ded45305e026b615c60e4eb8597e31fd67b7daefff51d13ab3d79868745e21668a6b45452366ac5a552b38e8c01dc669e73dbe45a9b38ecf8363b54e83

data/History.md

@@ -1,4 +1,159 @@
-#Version 2.13.0
+#Version 2.18.0
+Release date: 2018-02-12
+
+### Fixed
+
+* Firefox/geckodriver setting of contenteditable childs contents
+* Ignore Selenium::WebDriver::Error::SessionNotCreatedError when quitting driver [Tim Connor]
+
+### Removed
+
+* Headless chrome modal JS injection that is no longer needed for Chrome 64+/chromedriver 2.35+
+
+# Version 2.17.0
+Release date: 2018-01-02
+
+### Added
+
+* `have_all_of_selectors`, `have_none_of_selectors` RSpec matchers for parity with minitest assertions [Thomas Walpole]
+
+### Fixed
+
+* Allow xpath 3.x gem [Thomas Walpole]
+* Issue when drivers returned nil for `current_path` and a matcher was used with a Regexp [Thomas Walpole]
+* Error message when visible element not found, but non-visible was [Andy Klimczak]
+
+# Version 2.16.1
+Release date: 2017-11-20
+
+### Fixed
+
+* Fix rack_test driver for rack_test 0.7.1/0.8.0 [Thomas Walpole]
+* `accept_prompt` response text can contain quotes when using selenium with headless chrome [Thomas Walpole]
+
+# Version 2.16.0
+Release date: 2017-11-13
+
+### Added
+
+* Attempt to move element into view when selenium doesn't correctly do it - See PR #1917 [Thomas Walpole]
+* `current_path` matchers will now autodetect path vs url based on string to be matched. Deprecates
+  `:only_path` in favor of `:ignore_query` option [Thomas Walpole]
+* Session#evaluate_async_script [Thomas Walpole]
+
+### Fixed
+
+* Default prompt value when using headless Chrome works correctly [Thomas Walpole]
+* Support new modal error returned by selenium-webdriver 3.7 for W3C drivers [Thomas Walpole]
+* Calling `respond_to?` on the object passed to `Capybara.configure` block - Issue #1935
+
+# Version 2.15.4
+Release date: 2017-10-07
+
+### Fixed
+*  Visiting an absolute URL shouldn't overwrite the port when no server or always_include_port=false - Issue #1921
+
+# Version 2.15.3
+Release date: 2017-10-03
+
+### Fixed
+*  Visiting '/' when Capybara.app_host has a trailing '/' - Issue #1918 [Thomas Walpole]
+
+# Version 2.15.2
+Release date: 2017-10-02
+
+### Fixed
+
+*  Include within scope description in element not found/ambiguous errors [Thomas Walpole]
+*  Raise error when no activation block is passed to modal methods if using headless chrome [Thomas Walpole]
+*  Don't retry element access when inspecting [Ivan Neverov]
+*  Don't override a specified port (even if it is default port) in visited url [Thomas Walpole]
+
+# Version 2.15.1
+
+Release date: 2017-08-04
+
+### Fixed
+
+*  `attach_file` with no extension/MIME type when using the `:rack_test` driver [Thomas Walpole]
+
+# Version 2.15.0
+
+Release date: 2017-08-04
+
+### Added
+
+*  `sibling` and `ancestor` finders added [Thomas Walpole]
+*  Added ability to pass options to registered servers when setting
+*  Added basic built-in driver registrations `:selenium_chrome` and `:selenium_chrome_headless` [Thomas Walpole]
+*  Add `and_then` to Capybara RSpec matchers which behaves like the previous `and` compounder. [Thomas Walpole]
+*  Compound RSpec expectations with Capybara matchers now run both matchers inside a retry loop rather
+   than waiting for one to pass/fail before checking the second.  Will make `#or` more performant and confirm
+   both conditions are true "simultaneously" for `and`.  [Thomas Walpole]
+   If you still want the
+*  Default filter values are now included in error descriptions [Thomas Walpole]
+*  Add `Session#refresh` [Thomas Walpole]
+*  Loosened restrictions on where `Session#within_window` can be called from [Thomas Walpole]
+*  Switched from `mime-types` dependency to `mini_mime` [Jason Frey]
+
+# Version 2.14.4
+
+Release date: 2017-06-27
+
+### Fixed
+
+* Fix retrieval of session_options for HaveSelector matcher descriptions - Issue #1883
+
+# Version 2.14.3
+
+Release date: 2017-06-15
+
+### Fixed
+
+* Minitest assertions now raise the correct error type - Issue #1879 [Thomas Walpole]
+* Improve flexibility of detecting Chrome headless mode [Thomas Walpole]
+
+# Version 2.14.2
+
+Release date: 2017-06-09
+
+### Fixed
+
+* Workaround for system modals when using headless Chrome now works if the page changes
+
+# Version 2.14.1
+
+Release date: 2017-06-07
+
+### Fixed
+
+* Catch correct error when unexpected system modals are discovered in latest selenium [Thomas Walpole]
+* Update default `puma` server registration to encourage it to run in single mode [Thomas Walpole]
+* Suppress invalid element errors raised while lazily evaluating the results of `all` [Thomas Walpole]
+* Added missing `with_selected` option to the :select selector to match `options`/`with_options` options - Issue #1865 [Bartosz Nowak]
+* Workaround broken system modals when using selenium with headless Chrome
+
+# Version 2.14.0
+
+Release date: 2017-05-01
+
+### Added
+
+* "threadsafe" mode that allows per-session configuration
+* `:type` filter added to the `:fillable_field` selector
+* Proxy methods when using RSpec for `all`/`within` that call either the Capybara::DSL or RSpec matchers
+  depending on arguments passed
+* Support for the new errors in selenium-webdriver 3.4
+
+### Fixed
+
+* Element#inspect doesn't raise an error on obsolete elements
+* Setting a contenteditable element with Selenium and Chrome 59
+* Workaround a hang while setting the window size when using geckodriver 0.16 and Firefox 53
+* Clicking on url with a blank href goes to the current url when using the RackTest driver
+
+# Version 2.13.0
+
 Release date: 2017-03-16
 
 ### Added
@@ -7,16 +162,19 @@ Release date: 2017-03-16
 * rack_test driver supports click on checkboxes and radio buttons to change their states [Thomas Walpole]
 * Support RSpec equivalent assertions and expectations for MiniTest [Thomas Walpole]
 
-### Foxed
+### Fixed
+
 * Editing of content editable children with selenium
 
-#Version 2.12.1
+# Version 2.12.1
+
 Release date: 2017-02-16
 
 ### Fixed
 *  Disable lazy Capybara::Results evaluation for JRuby due to ongoing issues
 
-#Version 2.12.0
+# Version 2.12.0
+
 Release date: 2017-01-22
 
 ### Added
@@ -35,6 +193,7 @@ Release date: 2017-01-22
 * `within_element` as an alias of `within` due to RSpec collision
 
 ### Fixed
+
 *  Fields inside a disabled fieldset are now correctly considered disabled - Issue #1816 [Thomas Walpole]
 *  Lazy Capybara::Results evaluation enabled for JRuby 9.1.6.0+
 *  A driver returning nil for #current_url won't raise an exception when calling #current_path [Dylan Reichstadt]
@@ -42,10 +201,12 @@ Release date: 2017-01-22
 *  RackTest driver no longer modifies the text content of textarea elements in order to behave more like a real browser [Thomas Walpole]
 *  TextQuery (assert_text/have_text/etc) now ignores errors when trying to generate more helpful errors messages so the original error isn't hidden [Thomas Walpole]
 
-#Version 2.11.0
+# Version 2.11.0
+
 Release date: 2016-12-05
 
 ### Added
+
 * Options for clearing session/local storage on reset added to the Selenium driver
 * Window size changes wait for the size to stabilize
 * Defined return value for most actions
@@ -54,17 +215,21 @@ Release date: 2016-12-05
 * Capybara::Result#each now returns an `Enumerator` when called without a block - Issue #1777 [Thomas Walpole]
 
 ### Fixed
+
 * Selenium driver with Chrome should support multiple file upload [Thomas Walpole]
 * Fix visible: :hidden with :text option behavior [Thomas Walpole]
 
-#Version 2.10.2
+# Version 2.10.2
+
 Release date: 2016-11-30
 
 ### Fixed
+
 * App exceptions with multiple parameter initializers now re-raised correctly - Issue #1785 [Michael Lutsiuk]
 * Use Addressable::URI when parsing current_path since it's more lenient of technically invalid URLs - Issue #1801 [Marcos Duque, Thomas Walpole]
 
-#Version 2.10.1
+# Version 2.10.1
+
 Release date: 2016-10-08
 
 ### Fixed
@@ -72,52 +237,64 @@ Release date: 2016-10-08
 * Capybara::Result optimization disabled in JRuby due to issue with lazy enumerator evaluation [Thomas Walpole]
   See: https://github.com/jruby/jruby/issues/4212
 
-#Version 2.10.0
+# Version 2.10.0
+
 Release date: 2016-10-05
 
 ### Added
+
 * Select `<button>` elements with descendant images with `alt` attributes matching the locator [Ian Lesperance]
 * Locator string is optional in selector based matchers [Thomas Walpole]
 * Selectors can specify their default visible setting [Thomas Walpole]
 * Selector based finders and matchers can be passed a block to filter the results within the retry behavior [Thomas Walpole]
 
-#Version 2.9.2
+# Version 2.9.2
+
 Release date: 2016-09-29
 
 ### Fixed
 * :label built-in selector finds nested label/control by control id if the label has no 'for' attribute [Thomas Walpole]
 * Warning issued if an unknown selector type is specified [Thomas Walpole]
 
-#Version 2.9.1
+# Version 2.9.1
+
 Release date: 2016-09-23
 
 ### Fixed
+
 * allow_label_click option did not work in some cases with Poltergeist - Issue #1762 [Thomas Walpole]
 * matches_selector? should have access to all of a selectors options except the count options [Thomas Walpole]
 
-#Version 2.9.0
+# Version 2.9.0
+
 Release date: 2016-09-19
 
 ### Fixed
+
 * Issue with rack-test driver and obselete mime-types when using `#attach_file` - Issue #1756 [Thomas Walpole]
 
 ### Added
+
 * `:class` option to many of the built-in selectors [Thomas Walpole]
 * Removed need to specify value when creating `:boolean` filter type in custom selectors [Thomas Walpole]
 * Filters can now be implemented through the XPath/CSS expressions in custom selectors [Thomas Walpole]
 * `Element#matches_xpath?` and `Element#matches_css?` [Thomas Walpole]
 
-#Version 2.8.1
+# Version 2.8.1
+
 Release date: 2016-08-25
 
-###Fixed
+### Fixed
+
 * Fixed error message from have_text when text is not found but contains regex special characters [Ryunosuke Sato]
 * Warn when :exact option is passed that has no effect [Thomas Walpole]
 
 # Version 2.8.0
+
 Release date: 2016-08-16
 
 ### Fixed
+
 * Issue with modals present when closing the page using selenium - Issue #1696 [Jonas Nicklas, Thomas Walpole]
 * Server errors raised in test code have the cause set to an explanatory exception
   in rubies that support Exception#cause rather than a confusing ExpectationNotMet - Issue #1719 [Thomas Walpole]
@@ -125,6 +302,7 @@ Release date: 2016-08-16
 * Fixed setting of unexpectedAlertError now that Selenium will be freezing the Capabilities::DEFAULTS [Thomas Walpole]
 
 ### Added
+
 * 'check', 'uncheck', and 'choose' can now optionally click the associated label if the checkbox/radio button is not visible [Thomas Walpole]
 * Raise error if Capybara.app_host/default_host are specified incorrectly [Thomas Walpole]
 * Capybara::Selector::FilterSet allows for sharing filter definitions between selectors [Thomas Walpole]
@@ -136,19 +314,22 @@ Release date: 2016-08-16
 * Support matching on aria-label attribute when finding fields/links/buttons - Issue #1528 [Thomas Walpole]
 * Optimize Capybara::Result to only apply fields as necessary in common use-case of `.all[idx]` [Thomas Walpole]
 
-#Version 2.7.1
+# Version 2.7.1
+
 Release date: 2016-05-01
 
 ### Fixed
+
 * Issue where within_Frame would fail with Selenium if the frame is removed from within itself [Thomas Walpole]
 * Reset sessions in reverse order so sessions with active servers are reset last - Issue #1692 [Jonas Nicklas, Thomas Walpole]
 
 # Version 2.7.0
+
 Release date: 2016-04-07
 
 ### Fixed
-* Element#visible?/checked?/disabled?/selected? Now return boolean
-  as expected when using the rack_test driver [Thomas Walpole]
+
+* Element#visible?/checked?/disabled?/selected? Now return boolean as expected when using the rack_test driver [Thomas Walpole]
 * The rack_test driver now considers \<input type="hidden"> elements as non-visible [Thomas Walpole]
 * A nil locator passed to the built-in html type selectors now behaves consistently, and finds elements of the expected types [Thomas Walpole]
 * Capybara::Server now searches for available ports on the same interface it binds to [Aaron Stone]
@@ -156,6 +337,7 @@ Release date: 2016-04-07
 * Warning output if unused parameters are passed to a selector query [Thomas Walpole]
 
 ### Added
+
 * Capybara now waits for requests to Capybaras server to complete while restting the session [John Hawthorn, Thomas Walpole]
 * Capybara.reuse_server option to allow disabling of sharing server instance between sessions [Thomas Walpole]
 * :multiple filter added to relevant selectors [Thomas Walpole]
@@ -168,22 +350,28 @@ Release date: 2016-04-07
   save_page/save_screenshot [Thomas Walpole]
 * :label selector [Thomas Walpole]
 
-#Version 2.6.2
+# Version 2.6.2
+
 Relase date: 2016-01-27
 
 ### Fixed
+
 * support for more than just addressable 2.4.0 [Thomas Walpole]
 
 # Version 2.6.1
+
 Release date: 2016-01-27
 
 ### Fixed
+
 * Add missing require for addressable [Jorge Bejar]
 
 # Version 2.6.0
+
 Relase date: 2016-01-17
 
 ### Fixed
+
 * Fixed path escaping issue with current_path matchers [Thomas Walpole, Luke Rollans] (Issue #1611)
 * Fixed circular require [David Rodríguez]
 * Capybara::RackTest::Form no longer overrides Object#method [David Rodriguez]
@@ -192,6 +380,7 @@ Relase date: 2016-01-17
 
 
 ### Added
+
 * Capybara.modify_selector [Thomas Walpole]
 * xfeature and ffeature aliases added when using RSpec [Filip Bartuzi]
 * Selenium driver supports a :clear option to #set to handle different strategies for clearing a field [Thomas Walpole]
@@ -200,15 +389,18 @@ Relase date: 2016-01-17
 * Modal API methods now default wait time to Capybara.default_max_wait_time [Thomas Walpole]
 
 # Version 2.5.0
+
 Release date: 2015-08-25
 
 ### Fixed
+
 * Error message now raised correctly when invalid options passed to 'have_text'/'have_content' [Thomas Walpole]
 * Rack-test driver correctly gets document title when elements on the page have nested title elements (SVG) [Thomas Walpole]
 * 'save_page' no longer errors when using Capybara.asset_host if the page has no \<head> element [Travis Grathwell]
 * rack-test driver will ignore clicks on links with href starting with '#' or 'javascript:'
 
 ### Added
+
 * has_current_path? and associated asserts/matchers added [Thomas Walpole]
 * Implement Node#path in selenium driver [Soutaro Matsumoto]
 * 'using_session' is now nestable [Thomas Walpole]
@@ -226,25 +418,32 @@ Release date: 2015-08-25
 * Clear field using backspaces in Selenium driver by using `:fill_options => { :clear => :backspace }` [Joe Lencioni]
 
 ### Deprecated
+
 * Capybara.default_wait_time deprecated in favor of Capybara.default_max_wait_time to more clearly explain its purpose [Paul Pettengill]
 
-#Version 2.4.4
+# Version 2.4.4
+
 Release date: 2014-10-13
 
 ### Fixed
+
 * Test for visit behavior updated [Phil Baker]
 * Removed concurrency prevention in favor of a note in the README - due to load order issues
 
 # Version 2.4.3
+
 Relase date: 2014-09-21
 
 ### Fixed
+
 * Update concurrency prevention to match Rails 4.2 behavior
 
 # Version 2.4.2
+
 Release date: 2014-09-20
 
 ### Fixed
+
 * Prevent concurrency issue when testing Rails app with default test environment [Thomas Walpole]
 * Tags for windows API tests fixed [Dmitry Vorotilin]
 * Documentation Fixes [Andrey Botalov]
@@ -279,6 +478,7 @@ Release date: 2014-07-03
 Release date: 2014-06-02
 
 ### Added
+
 * New window management API [Andrey Botalov]
 * Speed improvement for visible text detection in RackTest [Thomas Walpole]
   Thanks to Phillipe Creux for instigating this

data/README.md

@@ -10,24 +10,14 @@ interact with your app. It is agnostic about the driver running your tests and
 comes with Rack::Test and Selenium support built in. WebKit is supported
 through an external gem.
 
-**Need help?** Ask on the mailing list (please do not open an issue on
-GitHub): http://groups.google.com/group/ruby-capybara
+## Support Capybara
 
-**Note: Firefox 48+** If you're using Firefox with selenium-webdriver and want full functionality stay on either Firefox [45.0esr](https://ftp.mozilla.org/pub/firefox/releases/45.0esr/) or [47.0.1](https://ftp.mozilla.org/pub/firefox/releases/47.0.1/).
-If using selenium-webdriver 3.0+ this will require configuring your driver with the `marionette: false` option as shown below
+If you and/or your company find value in Capybara and would like to contribute financially to its ongoing maintenance and development, please visit
+<a href="https://www.patreon.com/capybara">Patreon</a>
 
-```ruby
-Capybara.register_driver :selenium do |app|
-  Capybara::Selenium::Driver.new(
-    app,
-    browser: :firefox,
-    desired_capabilities: Selenium::WebDriver::Remote::Capabilities.firefox(marionette: false)
-  )
-end
-```
 
-Using Firefox 48+ requires geckodriver and selenium-webdriver v3, the combo of which currently has multiple issues and is feature incomplete.
-You can read more about the missing features [here](https://github.com/teamcapybara/capybara/issues/1710).
+**Need help?** Ask on the mailing list (please do not open an issue on
+GitHub): http://groups.google.com/group/ruby-capybara
 
 ## Table of contents
 
@@ -67,6 +57,7 @@ You can read more about the missing features [here](https://github.com/teamcapyb
 - [Beware the XPath // trap](#beware-the-xpath--trap)
 - [Configuring and adding drivers](#configuring-and-adding-drivers)
 - [Gotchas:](#gotchas)
+- ["Threadsafe" mode](#threadsafe)
 - [Development](#development)
 
 ## <a name="key-benefits"></a>Key benefits
@@ -87,7 +78,7 @@ Capybara requires Ruby 1.9.3 or later. To install, add this line to your
 gem 'capybara'
 ```
 
-**Note:** If using Ruby < 2.0 you will also need to limit the version of mime-types to < 3.0 and the version of rack to < 2.0
+**Note:** If using Ruby < 2.0 you will also need to limit the version of rack to < 2.0
 
 If the application that you are testing is a Rails app, add this line to your test helper file:
 
@@ -105,7 +96,13 @@ Capybara.app = MyRackApp
 ```
 
 If you need to test JavaScript, or if your app interacts with (or is located at)
-a remote URL, you'll need to [use a different driver](#drivers).
+a remote URL, you'll need to [use a different driver](#drivers).  If using Rails 5.0+, but not using the Rails system tests from 5.1, you'll probably also
+want to swap the "server" used to launch your app to Puma in order to match Rails defaults.
+
+```ruby
+Capybara.server = :puma # Until your setup is working
+Capybara.server = :puma, { Silent: true } # To clean up your test output
+```
 
 ## <a name="using-capybara-with-cucumber"></a>Using Capybara with Cucumber
 
@@ -139,8 +136,7 @@ Scenario: do something Ajaxy
   ...
 ```
 
-There are also explicit `@selenium` and `@rack_test`
-tags set up for you.
+There are also explicit tags for each registered driver set up for you (`@selenium`, `@rack_test`, etc).
 
 ## <a name="using-capybara-with-rspec"></a>Using Capybara with RSpec
 
@@ -241,6 +237,9 @@ RSpec.describe "todos/show.html.erb", type: :view do
 end
 ```
 
+**Note: When you require 'capybara/rspec' proxy methods are installed to work around name collisions between Capybara::DSL methods
+  `all`/`within` and the identically named built-in RSpec matchers. If you opt not to require 'capybara/rspec' you can install the proxy methods by requiring 'capybara/rspec/matcher_proxies' after requiring RSpec and 'capybara/dsl'**
+
 ## <a name="using-capybara-with-testunit"></a>Using Capybara with Test::Unit
 
 * If you are using `Test::Unit`, define a base class for your Capybara tests
@@ -339,7 +338,7 @@ these limitations, you can set up a different default driver for your features.
 For example if you'd prefer to run everything in Selenium, you could do:
 
 ```ruby
-Capybara.default_driver = :selenium
+Capybara.default_driver = :selenium # :selenium_chrome and :selenium_chrome_headless are also registered
 ```
 
 However, if you are using RSpec or Cucumber, you may instead want to consider
@@ -388,7 +387,7 @@ See the section on adding and configuring drivers.
 
 ### <a name="selenium"></a>Selenium
 
-At the moment, Capybara supports [Selenium 2.0
+At the moment, Capybara supports [Selenium 2.0+
 (Webdriver)](http://seleniumhq.org/docs/01_introducing_selenium.html#selenium-2-aka-selenium-webdriver),
 *not* Selenium RC. In order to use Selenium, you'll need to install the
 `selenium-webdriver` gem, and add it to your Gemfile if you're using bundler.
@@ -550,7 +549,7 @@ If you find yourself needing to use this a lot you may be better off adding a [c
 ```ruby
 find_field('First Name'){ |el| el['data-xyz'] == '123' }
 find("#img_loading"){ |img| img['complete'] == true }
-````
+```
 
 **Note**: `find` will wait for an element to appear on the page, as explained in the
 Ajax section. If the element does not appear it will raise an error.
@@ -743,6 +742,9 @@ Capybara 1.x, set `Capybara.match` to `:prefer_exact`.
 
 ## <a name="transactions-and-database-setup"></a>Transactions and database setup
 
+**Note:**  Rails 5.1+ now "safely" shares the database connection between the app and test threads.  Therefore,
+if using Rails 5.1+ you SHOULD be able to ignore this section.
+
 Some Capybara drivers need to run against an actual HTTP server. Capybara takes
 care of this and starts one for you in the same process as your test, but on
 another thread. Selenium is one of those drivers, whereas RackTest is not.
@@ -892,7 +894,7 @@ To permanently switch the current session to a different session
 
 ```ruby
 Capybara.session_name = "some other session"
-````
+```
 
 ### <a name="using-sessions-manually"></a>Using sessions manually
 
@@ -1045,6 +1047,35 @@ additional info about how the underlying driver can be configured.
   are testing for specific server errors and using multiple sessions make sure to test for the
   errors using the initial session (usually :default)
 
+## <a name="threadsafe"></a>"Threadsafe" mode - BETA - may change
+
+In normal mode most of Capybara's configuration options are global settings which can cause issues
+if using multiple sessions and wanting to change a setting for only one of the sessions.  To provide
+support for this type of usage Capybara now provides a "threadsafe" mode which can be enabled by setting
+
+```ruby
+Capybara.threadsafe = true
+```
+
+This setting can only be changed before any sessions have been created.  In "threadsafe" mode the following
+behaviors of Capybara change
+
+* Most options can now be set on a session.  These can either be set at session creation time or after, and
+  default to the global options at the time of session creation.  Options which are NOT session specific are
+  `app`, `reuse_server`, `default_driver`, `javascript_driver`, and (obviously) `threadsafe`.  Any drivers and servers
+  registered through `register_driver` and `register_server` are also global.
+
+  ```ruby
+  my_session = Capybara::Session.new(:driver, some_app) do |config|
+    config.automatic_label_click = true # only set for my_session
+  end
+  my_session.config.default_max_wait_time = 10 # only set for my_session
+  Capybara.default_max_wait_time = 2 # will not change the default_max_wait in my_session
+  ```
+
+* `current_driver` and `session_name` are thread specific.  This means that `using_session` and
+  `using_driver` also only affect the current thread.
+
 ## <a name="development"></a>Development
 
 To set up a development environment, simply do: