Migrating from feature specs to system specs

Rails supports writing Capybara tests out of the box since the 5.1 release in the form of system tests. This means you don’t need to configure database cleaning strategies or have a separate webdriver configuration file with hard-to-understand configuration settings, or other verbose capybara/selenium configurations in the rails_helper file. A few driven_by declarations in rails_helper are pretty much all we need and it just works.


Our Gemfile should include the following gems:


group :test do
    gem "capybara"
    gem "selenium-webdriver"
    gem "rspec-rails"

The rails_helper configuration is also much simpler.


RSpec.configure do |config|

    config.before(:each, type: :system) do
        driven_by :rack_test # rack_test by default, for performance

    config.before(:each, type: :system, js: true) do
        driven_by :selenium_chrome_headless # selenium when we need javascript

You might notice we’re using rack_test as our default driver for performance; you can refer to this article for more details.

Git history Gotcha

When migrating to system specs you’ll need to move your specs files from spec/features/ to spec/system/. This will mess up the git history of those files as it will look like they were first created as part of that change. Old commits for the feature files will not be automatically tied to that file.

However, if you have log.follow set to true in your gitconfig, then Git will track the history back through the old filename and the complete history will be visible.

Additional resources

Ruby on Rails 5.1 Release Notes

Rspec system specs documentation

Upgrading to RSpec 3.7.2 and system specs

Have fun writing system specs 🎉