<commit_before>= Capybara

* http://github.com/jnicklas/capybara

== Description:

Capybara aims to simplify the process of integration testing Rack applications,
such as Rails, Sinatra or Merb. Capybara simulates how a real user would
interact with a web application. It is agnostic about the driver running your
tests and currently comes with Rack::Test and Selenium support built in.
HtmlUnit, WebKit and env.js are supported through external gems.

A complete reference is available at
{at rubydoc.info}[http://rubydoc.info/github/jnicklas/capybara/master].

== Install:

Install as a gem:

    sudo gem install capybara

On OSX you may have to install libffi, you can install it via MacPorts with:

    sudo port install libffi

== Development:

* Source hosted at {GitHub}[http://github.com/jnicklas/capybara].
* Please direct questions, discussion or problems to the {mailing list}[http://groups.google.com/group/ruby-capybara].
* If you found a reproducible bug, open a {GitHub Issue}[http://github.com/jnicklas/capybara/issues] to submit a bug report.
* Please do not contact any of the maintainers directly, unless you have found a security related issue.

Pull requests are very welcome (and even better than bug reports)! Make sure
your patches are well tested, Capybara is a testing tool after all. Please
create a topic branch for every separate change you make.

Capybara uses bundler in development. To set up a development environment, simply do:

    git submodule update --init
    gem install bundler
    bundle install

== Using Capybara with Cucumber

Capybara is built to work nicely with Cucumber. Support for Capybara is built into
cucumber-rails. In your Rails app, just run:

    rails generate cucumber:install --capybara

And everything should be set up and ready to go.

If you want to use Capybara with Cucumber outside Rails (for example with Merb
or Sinatra), you'll need to require Capybara and set the Rack app manually:

    require 'capybara/cucumber'
    Capybara.app = MyRackApp

Now you can use it in your steps:

    When /I sign in/ do
      within("#session") do
        fill_in 'Login', :with => '<EMAIL>'
        fill_in 'Password', :with => 'password'
      end
      click_link 'Sign in'
    end

Capybara sets up some {tags}[http://wiki.github.com/aslakhellesoy/cucumber/tags]
for you to use in Cucumber. Often you'll want to run only some scenarios with a
driver that supports JavaScript, Capybara makes this easy: simply tag the
scenario (or feature) with <tt>@javascript</tt>:

    @javascript
    Scenario: do something Ajaxy
      When I click the Ajax link
      ...

You can change which driver Capybara uses for JavaScript:

    Capybara.javascript_driver = :culerity

There are also explicit <tt>@selenium</tt>, <tt>@culerity</tt> and
<tt>@rack_test</tt> tags set up for you.

== Using Capybara with RSpec

If you prefer RSpec to using Cucumber, you can use the built in RSpec support
by adding the following line (typically to your <tt>spec_helper.rb</tt> file):

    require 'capybara/rspec'

You can now write your specs like so:

    describe "the signup process", :type => :request do
      before :each do
        User.make(:email => '<EMAIL>', :password => '<PASSWORD>')
      end

      it "signs me in" do
        within("#session") do
          fill_in 'Login', :with => '<EMAIL>'
          fill_in 'Password', :with => 'password'
        end
        click_link 'Sign in'
      end
    end

Capybara is only included in example groups tagged with
<tt>:type => :request</tt> (or <tt>:acceptance</tt> for compatibility with Steak).

If you are testing a Rails app and using the <tt>rspec-rails</tt> gem, these
<tt>:request</tt> example groups may look familiar to you. That's because they
are RSpec versions of Rails integration tests. So, in this case essentially what you are getting are Capybara-enhanced request specs. This means that you can
use the Capybara helpers <i>and</i> you have access to things like named route
helpers in your tests (so you are able to say, for instance, <tt>visit
edit_user_path(user)</tt>, instead of <tt>visit "/users/#{user.id}/edit"</tt>,
if you prefer that sort of thing). A good place to put these specs is
<tt>spec/requests</tt>, as <tt>rspec-rails</tt> will automatically tag them with
<tt>:type => :request</tt>. (In fact, <tt>spec/integration</tt> and
<tt>spec/acceptance</tt> will work just as well.)

<tt>rspec-rails</tt> will also automatically include Capybara in <tt>:controller</tt> and <tt>:mailer</tt> example groups.

RSpec's metadata feature can be used to switch to a different driver. Use
<tt>:js => true</tt> to switch to the javascript driver, or provide a
<tt>:driver</tt> option to switch to one specific driver. For example:

    describe 'some stuff which requires js', :js => true do
      it 'will use the default js driver'
      it 'will switch to one specific driver', :driver => :celerity
    end

Finally, Capybara also comes with a built in DSL for creating descriptive acceptance tests:

    feature "Signing up" do
      background do
        User.make(:email => '<EMAIL>', :password => '<PASSWORD>')
      end

      scenario "Signing in with correct credentials" do
        within("#session") do
          fill_in 'Login', :with => '<EMAIL>'
          fill_in 'Password', :with => '<PASSWORD>'
        end
        click_link 'Sign in'
      end
    end

This is, in fact, just a shortcut for making a request spec, where
<tt>feature</tt> is an alias for <tt>describe ..., :type => :request</tt>,
<tt>background</tt> is an alias for <tt>before</tt>, and <tt>scenario</tt>
is an alias for <tt>it</tt>/<tt>specify</tt>.

Note that Capybara's built in RSpec support only works with RSpec 2.0 or later.
You'll need to roll your own for earlier versions of RSpec.

== Using Capybara with Test::Unit

To use Capybara with Test::Unit, include the DSL (<tt>include Capybara</tt> up
until version 0.4.x, <tt>include Capybara::DSL</tt> for newer versions) in
whatever test class you are using.  For example, if your classes derive from
<tt>ActionDispatch::IntegrationTest</tt>, use

    class ActionDispatch::IntegrationTest
      include Capybara::DSL
    end

Test::Unit does not support selecting the driver through test metadata, but you
can switch the driver for specific classes using the <tt>setup</tt> and
<tt>teardown</tt> methods.  See the section "Selecting the Driver".

== Using Capybara with Ruby on Rails

If you are using the Rails framework, add this line to automatically configure
Capybara to test against your Rails application:

    require 'capybara/rails'

== Using Capybara with Rack

If you're using Capybara with a non-Rails Rack application, set
<tt>Capybara.app</tt> to your application class:

    Capybara.app = MyRackApp

== Drivers

Capybara uses the same DSL to drive a variety of browser and headless drivers.

=== Selecting the Driver

By default, Capybara uses the <tt>:rack_test</tt> driver, which is fast but does not
support JavaScript.  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:

    Capybara.default_driver = :selenium

However, if you are using RSpec or Cucumber, you may instead want to consider
leaving the faster <tt>:rack_test</tt> as the +default_driver+, and marking only those<commit_msg>Add MiniTest::Spec section in README.<commit_after>= Capybara

* http://github.com/jnicklas/capybara

== Description:

Capybara aims to simplify the process of integration testing Rack applications,
such as Rails, Sinatra or Merb. Capybara simulates how a real user would
interact with a web application. It is agnostic about the driver running your
tests and currently comes with Rack::Test and Selenium support built in.
HtmlUnit, WebKit and env.js are supported through external gems.

A complete reference is available at
{at rubydoc.info}[http://rubydoc.info/github/jnicklas/capybara/master].

== Install:

Install as a gem:

    sudo gem install capybara

On OSX you may have to install libffi, you can install it via MacPorts with:

    sudo port install libffi

== Development:

* Source hosted at {GitHub}[http://github.com/jnicklas/capybara].
* Please direct questions, discussion or problems to the {mailing list}[http://groups.google.com/group/ruby-capybara].
* If you found a reproducible bug, open a {GitHub Issue}[http://github.com/jnicklas/capybara/issues] to submit a bug report.
* Please do not contact any of the maintainers directly, unless you have found a security related issue.

Pull requests are very welcome (and even better than bug reports)! Make sure
your patches are well tested, Capybara is a testing tool after all. Please
create a topic branch for every separate change you make.

Capybara uses bundler in development. To set up a development environment, simply do:

    git submodule update --init
    gem install bundler
    bundle install

== Using Capybara with Cucumber

Capybara is built to work nicely with Cucumber. Support for Capybara is built into
cucumber-rails. In your Rails app, just run:

    rails generate cucumber:install --capybara

And everything should be set up and ready to go.

If you want to use Capybara with Cucumber outside Rails (for example with Merb
or Sinatra), you'll need to require Capybara and set the Rack app manually:

    require 'capybara/cucumber'
    Capybara.app = MyRackApp

Now you can use it in your steps:

    When /I sign in/ do
      within("#session") do
        fill_in 'Login', :with => '<EMAIL>'
        fill_in 'Password', :with => 'password'
      end
      click_link 'Sign in'
    end

Capybara sets up some {tags}[http://wiki.github.com/aslakhellesoy/cucumber/tags]
for you to use in Cucumber. Often you'll want to run only some scenarios with a
driver that supports JavaScript, Capybara makes this easy: simply tag the
scenario (or feature) with <tt>@javascript</tt>:

    @javascript
    Scenario: do something Ajaxy
      When I click the Ajax link
      ...

You can change which driver Capybara uses for JavaScript:

    Capybara.javascript_driver = :culerity

There are also explicit <tt>@selenium</tt>, <tt>@culerity</tt> and
<tt>@rack_test</tt> tags set up for you.

== Using Capybara with RSpec

If you prefer RSpec to using Cucumber, you can use the built in RSpec support
by adding the following line (typically to your <tt>spec_helper.rb</tt> file):

    require 'capybara/rspec'

You can now write your specs like so:

    describe "the signup process", :type => :request do
      before :each do
        User.make(:email => '<EMAIL>', :password => '<PASSWORD>')
      end

      it "signs me in" do
        within("#session") do
          fill_in 'Login', :with => '<EMAIL>'
          fill_in 'Password', :with => 'password'
        end
        click_link 'Sign in'
      end
    end

Capybara is only included in example groups tagged with
<tt>:type => :request</tt> (or <tt>:acceptance</tt> for compatibility with Steak).

If you are testing a Rails app and using the <tt>rspec-rails</tt> gem, these
<tt>:request</tt> example groups may look familiar to you. That's because they
are RSpec versions of Rails integration tests. So, in this case essentially what you are getting are Capybara-enhanced request specs. This means that you can
use the Capybara helpers <i>and</i> you have access to things like named route
helpers in your tests (so you are able to say, for instance, <tt>visit
edit_user_path(user)</tt>, instead of <tt>visit "/users/#{user.id}/edit"</tt>,
if you prefer that sort of thing). A good place to put these specs is
<tt>spec/requests</tt>, as <tt>rspec-rails</tt> will automatically tag them with
<tt>:type => :request</tt>. (In fact, <tt>spec/integration</tt> and
<tt>spec/acceptance</tt> will work just as well.)

<tt>rspec-rails</tt> will also automatically include Capybara in <tt>:controller</tt> and <tt>:mailer</tt> example groups.

RSpec's metadata feature can be used to switch to a different driver. Use
<tt>:js => true</tt> to switch to the javascript driver, or provide a
<tt>:driver</tt> option to switch to one specific driver. For example:

    describe 'some stuff which requires js', :js => true do
      it 'will use the default js driver'
      it 'will switch to one specific driver', :driver => :celerity
    end

Finally, Capybara also comes with a built in DSL for creating descriptive acceptance tests:

    feature "Signing up" do
      background do
        User.make(:email => '<EMAIL>', :password => '<PASSWORD>')
      end

      scenario "Signing in with correct credentials" do
        within("#session") do
          fill_in 'Login', :with => '<EMAIL>'
          fill_in 'Password', :with => '<PASSWORD>'
        end
        click_link 'Sign in'
      end
    end

This is, in fact, just a shortcut for making a request spec, where
<tt>feature</tt> is an alias for <tt>describe ..., :type => :request</tt>,
<tt>background</tt> is an alias for <tt>before</tt>, and <tt>scenario</tt>
is an alias for <tt>it</tt>/<tt>specify</tt>.

Note that Capybara's built in RSpec support only works with RSpec 2.0 or later.
You'll need to roll your own for earlier versions of RSpec.

== Using Capybara with Test::Unit

To use Capybara with Test::Unit, include the DSL (<tt>include Capybara</tt> up
until version 0.4.x, <tt>include Capybara::DSL</tt> for newer versions) in
whatever test class you are using.  For example, if your classes derive from
<tt>ActionDispatch::IntegrationTest</tt>, use

    class ActionDispatch::IntegrationTest
      include Capybara::DSL
    end

Test::Unit does not support selecting the driver through test metadata, but you
can switch the driver for specific classes using the <tt>setup</tt> and
<tt>teardown</tt> methods.  See the section "Selecting the Driver".

== Using Capybara with MiniTest::Spec

Include Capybara::DSL like in Test::Unit. Be sure to include it in the proper class,
which could be something other than ActionDispatch::IntegrationTest.

The capybara_minitest_spec gem ({Github}[https://github.com/ordinaryzelig/capybara_minitest_spec],
{rubygems.org}[https://rubygems.org/gems/capybara_minitest_spec]) provides MiniTest::Spec
expectations for Capybara. For example:

    page.must_have_content('Important!')

== Using Capybara with Ruby on Rails

If you are using the Rails framework, add this line to automatically configure
Capybara to test against your Rails application:

    require 'capybara/rails'

== Using Capybara with Rack

If you're using Capybara with a non-Rails Rack application, set
<tt>Capybara.app</tt> to your application class:

    Capybara.app = MyRackApp

== Drivers

Capybara uses the same DSL to drive a variety of browser and headless drivers.

=== Selecting the Driver

By default, Capybara uses the <tt>:rack_test</tt> driver, which is fast but does not
support JavaScript.  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:

    Capybara.default_driver = :selenium

However, if you are using RSpec or Cucumber, you may instead want to consider
leaving the faster <tt>:rack_test</tt> as the +default_driver+, and marking only those
{'fraction_non_alphanumeric': 0.08893566635968951, 'fraction_numerical': 0.0005262465465070386, 'mean_word_length': 3.850989151244416, 'pattern_counts': {'":': 0, '<': 167, '<?xml version=': 0, '>': 201, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6043936', 'n_tokens_mistral': 4526, 'n_tokens_neox': 4358, 'n_words': 1973}