Debug Capybara feature spec failures with build artifacts

Ever have feature specs fail on your CI server but always pass locally? Debugging nondeterministic failures is extremely frustrating. Thankfully Capybara gives us the ability to save the current page when a test fails so we can at least get some idea what the unexpected page structure looked like.

RSpec.configure do |config|
  config.after(:each, :type => :feature) do
    if example.exception
      artifact = save_page
      puts "\"#{example.description}\" failed. Page saved to #{artifact}"
    end
  end
end

When running specs on a continuous integration system it is often helpful to expose these page snapshots as build artifacts so they can be retrieved from a failed build. For example when running on CircleCI we want to save artifacts to a path given in an environment variable.

if ENV['CIRCLE_ARTIFACTS']
  Capybara.save_and_open_page_path = ENV['CIRCLE_ARTIFACTS']
end

Once we can see the state of the page which caused our test failure instead of just a "expected page to contain selector" error it becomes much easier to fix our feature specs.

If it is not clear why a spec is nondeterministic Writing Deterministic & Performant Specs with Capybara may be helpful.