Having screenshots readily available for each test failure is incredibly helpful when trying to quickly diagnose a problem in your failing steps. You can view the source code, and have a screen shot of the page (when applicable), at the time of each failure.

RSpec

Note: As of RSpec Rails 3.0, it is recommended that all your Rails environment code is loaded into rails_helper.rb instead of spec_helper.rb, and as such, the capybara-screenshot require should be located in rails_helper.rb. See the RSpec Rails 3.0 upgrade notes for more info.

Minitest

Typically in 'test/test_helper.rb', please add:

require'capybara-screenshot/minitest'

Also, consider adding include Capybara::Screenshot::MiniTestPlugin to any test classes that fail. For example, to capture screenshots for all failing integration tests in minitest-rails, try something like:

Test::Unit

By default, screenshots will be captured for Test::Unit tests in the path 'test/integration'. You can add additional paths as:

Capybara::Screenshot.testunit_paths <<'test/feature'

Manual screenshots

If you require more control, you can generate the screenshot on demand rather than on failure. This is useful
if the failure occurs at a point where the screen shot is not as useful for debugging a rendering problem. This
can be more useful if you disable the auto-generate on failure feature with the following config

Capybara::Screenshot.autosave_on_failure =false

Anywhere the Capybara DSL methods (visit, click etc.) are available so too are the screenshot methods.

Better looking HTML screenshots

By the default, HTML screenshots will not look very good when opened in a browser. This happens because the browser can't correctly resolve relative paths like <link href="/assets/...." />, which stops CSS, images, etc... from beind loaded. To get a nicer looking page, configure Capybara with:

Capybara.asset_host ='http://localhost:3000'

This will cause Capybara to add <base>http://localhost:3000</base> to the HTML file, which gives the browser enough information to resolve relative paths. Next, start a rails server in development mode, on port 3000, to respond to requests for assets:

rails s -p 3000

Now when you open the page, you should have something that looks much better. You can leave this setup in place and use the default HTML pages when you don't care about the presentation, or start the rails server when you need something better looking.

Driver configuration

The gem supports the default rendering method for Capybara to generate the screenshot, which is:

page.driver.render(path)

There are also some specific driver configurations for Selenium, Webkit, and Poltergeist. See the definitions here. The Rack::Test driver, Rails' default, does not allow
rendering, so it has a driver definition as a noop.

Capybara-webkit defaults to a screenshot size of 1000px by 10px. To specify a custom size, use the following option:

Capybara::Screenshot.webkit_options = { width:1024, height:768 }

If a driver is not found the default rendering will be used. If this doesn't work with your driver, then you can
add another driver configuration like so

# The driver name should match the Capybara driver config name.Capybara::Screenshot.register_driver(:exotic_browser_driver) do |driver, path|
driver.super_dooper_render(path)
end

If your driver is based on existing browser driver, like Firefox, instead of .super_dooper_render do driver.browser.save_screenshot path.

Custom screenshot filename

If you want to control the screenshot filename for a specific test library, to inject the test name into it for example,
you can override how the basename is generated for the file like so

By default capybara-screenshot will append a timestamp to the basename. If you want to disable this behavior set the following option:

Capybara::Screenshot.append_timestamp =false

Custom screenshot directory

By default, when running under Rails, Sinatra, and Padrino, screenshots are saved into $APPLICATION_ROOT/tmp/capybara. Otherwise, they're saved under Dir.pwd.
If you want to customize the location, override the file path as:

Capybara.save_path ="/file/path"

Usage with multiple Capybara sessions

To make screenshots work with multiple Capybara sessions, replace Capybara.using_session with Capybara.using_session_with_screenshot:

Cabybara.using_session_with_screenshot('User 1') do# screenshots will work and use the correct sessionend

Uploading screenshots to S3

You can configure capybara-screenshot to automatically save your screenshots to an AWS S3 bucket.

Pruning old screenshots automatically

By default screenshots are saved indefinitely, if you want them to be automatically pruned on a new failure, then you can specify one of the following prune strategies as follows:

# Keep only the screenshots generated from the last failing test suiteCapybara::Screenshot.prune_strategy =:keep_last_run# Keep up to the number of screenshots specified in the hashCapybara::Screenshot.prune_strategy = { keep:20 }

Callbacks

You can hook your own logic into callbacks after the html/screenshot has been saved.

Information about screenshots in RSpec output

By default, capybara-screenshot extend RSpec’s formatters to include a link to the screenshot and/or saved html page for each failed spec. If you want to disable this feature completely (eg. to avoid problems with CI tools), use:

If you want to further customize the information added to RSpec’s output, just implement your own reporter class and customize Capybara::Screenshot::RSpec::REPORTERS accordingly. See rspec.rb for more info.

Common problems

If you have recently upgraded from v0.2, or you find that screen shots are not automatically being generated, then it's most likely you have not included the necessary require statement for your testing framework described above. As of version 0.3, without the explicit require, Capybara-Screenshot will not automatically take screen shots. Please re-read the installation instructions above.

Also make sure that you're not calling Capybara.reset_sessions! before the screenshot hook runs. For RSpec you want to make sure that you're using append_after instead of after, for instance:

Repository & Contributing to this Gem

Bugs

Contributions

Contributions are welcome. Please fork this gem, and submit a pull request. New features must include test coverage and must pass on all versions of the testing frameworks supported. Run appraisal to set up the your Gems. then appraisal "rake travis:ci" locally to test your changes against all versions of testing framework gems supported.