Cucumber Screenshot

Cucumber Screenshot makes it easy to capture HTML snapshots and PNG screenshots of the pages generated by your Rails application as it runs your Cucumber/Webrat features.

It uses WebKit to generate the PNG screenshots and so they are only available for OS X.

If you want to take bitmap screenshots on any other platform then take a look at this example from Cucumber.


A Rails application with some features written in Cucumber/Webrat.


To install the latest release as a gem

gem install cucumber-screenshot

If you want to take PNG screenshots you will also need to install snapurl

gem install snapurl --version=0.3.0

Set up your rails application

Create a cucumber_screenshot_env.rb file in the ./features/support/ directory in your Rails project and put the following in it.

  require 'cucumber_screenshot'

  After do |scenario|
    if scenario.failed?

  AfterStep('@screenshot') do |scenario|
    if screenshot_due?
rescue Exception => e
  puts "Snapshots not available for this environment. Try installing
    cucumber-screenshot with\n\n  gem install cucumber-screenshot\n"

By default cucumber screenshot will do it’s best to fix up references to your public assets (images, css, js, etc.) in the HTML for your screenshots to point at the public folder on your file system.

However you may find that rendering is improved if you configure it to reference these via HTTP. Say you have a webserver running on localhost:3000 that will serve the public files then add a cucumber_screenshot.yml file containing the following to your application’s ./config/ directory

base_url: http://localhost:3000


Once you have set up your rails application then simply use the ‘rake cucumber’ and ‘rake cucumber:wip’ tasks as per usual.

Screenshots will be captured for every step failure and for every step in scenarios tagged @screenshot. The PNG screenshots and HTML snapshots will be saved to a the ./features/screenshots/ and ./features/screenshots/html directories respectively in your project.

Capturing a single screenshot

If you want to capture a single PNG screenshot/HTML snapshot rather than every page then add the following step to one of your Rails application’s step files

Then "screenshot" do

and then add

Then screenshot

to your feature file in the place where you want to capture a screenshot of the page that your application generated.


  • Offer option to clean out existing snapshots before each run

  • Add a Rails generator to add the env and step code to a project


Copyright © 2009 Joel Chippindale. See MIT-LICENSE.txt in this directory.