Getting Started With System Tests in Rails With Minitest

In today's post, we'll look at system tests in Rails 6. System tests are meant to auto-test the way users interact with your application, including the Javascript in your user interface. Minitest, being the default testing framework in Rails, is a great match for system testing. With all the configuration that Rails handles for us, there are just a few steps needed before we have our first tests up and running.

System tests were added to the Rails stack in Rails 5.1. When I sat down to start using them, I found it hard to gather relevant, up to date information that is not about RSpec. Here’s all the latest and greatest that I collected on working with the system tests with Minitest.

Introduction to System Tests

In Rails jargon, system testing refers to "testing an application as a whole system". That is done by using a browser in the tests. Instead of testing separate parts, with system tests, we can test a whole 'workflow', just like what a user goes through while interacting with our app, including the JavaScript parts. In practice, it means that we don't want a system test to check if a record is created in the database when a user clicks a button; we just test if that new record appears on their screen. These kinds of user interaction tests are also called feature tests or acceptance tests. They are different from integration tests: integration tests are for testing the behavior, especially of all the parts of the app together, but not via the user interface.

Configuration

The configuration is so simple, it's almost confusing.

The Capybara gem is used for interacting with the browser. It's through Capybara that we can make the tests visit pages, fill in forms, click on links and buttons. If you've worked with Capybara before, you're aware of all the things you have to coordinate to make it work with a database cleaning strategy and the browser configuration. Hooray for the Rails system test set up: it takes care of all the configuration that is needed to work with Capybara out-of-the-box. So we can focus on the actual test writing. It uses the Selenium driver by default.

From the docs: “By default, ActionDispatch::SystemTestCase is driven by the Selenium driver, with the Chrome browser, and a browser size of 1400x1400.” The Selenium driver is different from Capybara's default and is chosen because it works with Javascript.

All the settings are available through application_system_test_case.rb. The only thing you need to do is require this in each test file.

#application_system_test_case.rb (default)


require "test_helper"

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  driven_by :selenium, using: :chrome, screen_size: [1400, 1400]
end

If you generated a new app with Rails 6, this is really all you need. Meaning: you can skip all the advice on how to set up the Selenium driver that the Internet shows for user interface tests or RSpec's feature tests.

In existing apps, generating a scaffold will automatically generate the application_system_test_case.rb and everything you need for the system tests.

When Eileen Uchitelle introduced system tests, Chrome was chosen over Firefox because at the time FF didn't play nicely with Selenium. That is fixed in later versions of Firefox. So I replace Chrome with FF, like so:

#application_system_test_case.rb (change driver to Firefox)

require "test_helper"

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  driven_by :selenium, using: :firefox, screen_size: [1400, 1400]
end

(Initially, I ran $ rails db:test:prepare after switching drivers to ensure a clean start, BUT the new test runner takes care of that too: invoking test will autorun :prepare.)

New in Rails 6

Since the introduction of system tests in 5.1, the chromedriver-helper gem has been deprecated. In new Rails 6 apps, it is replaced with the webdrivers gem. In Rails 5 apps, you should replace the chromedriver-helper with the webdrivers gem if you haven't done that yet. With the webdrivers gem in place, you don't even need the selenium-webdriver gem; webdrivers takes care of that one too. Fun fact: Rails 6 gives us both the selenium-webdriver gem and the webdrivers gem.

Sanity Check: What You Don't Need Anymore

Setting up Capybara used to be a pain. It wasn't clear what you needed to set it up from scratch, including finding the correct database cleaning strategy, the dependencies of the capybara-webkit gem and all kinds of unexpected requirements that you needed to figure out before you could start writing tests. Now that Rails provides everything we need, I found the only confusing part to be all the information available in guides and documentation that is obsolete now. Here are some things that we can ignore now.

First, the precooked Rails setup means that we can omit more gems that are often mentioned in regards to testing, like minitest-rails-capybara, or the extras for Minitest: like-colored output, fast failing tests and running one line/test. These Minitest features are in the test runner introduced in Rails 5.0.

There's no need for the database_cleaner gem anymore; Rails does the cleanup for us ('transactional tests').

Since Rails uses Selenium instead of the Capybara default, we don't need capybara-webkit and we don't need to do any extras to include testing of Javascript elements.

You don't even need to use Capybara's save_and_open_screenshot, because Rails provides a take_screenshot method. It saves a screenshot in /tmp and provides a link in the test output for easy access.

Choosing Between a Real Browser and Headless Browser

I can't get enough of watching the system tests running in the browser and see how all the links are clicked, forms are filled in, etc. But, it is slow. To speed up the test run, you can use a 'headless' browser: that is a browser that has the same access to your app as a regular browser, but without the graphical user interface. Meaning: it works the same but you don't actually see the tests doing their work since a headless driver doesn't open an actual browser window.

If you do want to go headless, there's headless_chrome and headless_firefox. To use them, there's one small change needed:

# To change driver to headless_*
#application_system_test_case.rb (change driver to headless_*:)

require "test_helper"

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  driven_by :selenium, using: :headless_firefox
end

Note: In the Rails documentation and in several articles I found, Poltergeist was named as an option for the driver. It used to be popular as the - headless - PhantomJS driver for Capybara. PhantomJS has been abandoned. So, no need to dive into the particulars—the reason I mention it here is because Poltergeist and PhantomJS are still mentioned in the Rails docs.

There's more customization you can do, but to get started, this is really all you need.

Running the Tests

$ rails test will run all the tests except the system tests. You need to explicitly run $ rails test:system. (Fun fact: the $ rails command will always run through bin/rails. No need to type $ bin/rails anymore.)

• Run all the system tests: $ rails test:system
• Run test in a specific file (here: users_test.rb) $ rails test/system/users_test
• ... or one specific test: $ rails test test/system/users_test.rb:21
• To run all the tests: run the system tests first: $ rails test:system test

Note: the options flags don't work with test:system; if you want to use flags like -f (for fail fast) or -v (for verbose), use $ rails test test/system -v -f

What (Not) to Test

System tests are complementary to unit tests, not a substitute. It will do to test a happy path, plus maybe one path with an error message or redirect. System tests are not meant to test all the edge cases in the browser; just cover the main features.

When choosing my test subject, I try to find an entity to test that reflects how the user uses the app. For the naming of my tests, I borrowed GitLab's naming convention of ROLE_ACTION_test.rb, which fits this approach well. For instance: user_shares_card_test.rb.

General Tips and Tricks

• If you use Devise for authentication, you can use the Devise integration helpers to log in and log out test users. Add include Devise::Test::IntegrationHelpers to a test class, or add it in the test_helper.rb file to make them available in all tests. Now you can create a user and sign_in(@user). If you put that in a setup method, you don’t need to log out the user in a teardown. Rails takes care of cleaning up what's in the setup method.
• Working with forms, it's tempting to reference the ids that Rails creates automatically from model name + field name and the button types for click_ons. ( fill_in "user_email", click_on :commit). But since systems tests are about what a user would actually see on their screen, it makes sense to use visible elements, i.e. texts. A reasonable option would be to have reference keys in i18n locale files and use those keys instead of the ever-changing literal texts. (fill_in :user_email). Capybara finds the text only with the full I18n syntax: assert_selector "h1", text: I18n.t("activerecord.models.things").
• The path helpers are included by default. For some libraries you need to include the helpers in the test class, for instance include ActionMailer::TestHelper, to use the assert_emails method.
• Create custom classes to run the tests on different screen sizes. Check out the guides.
• The screenshot feature can also be used to take screenshots for your documentation and promotional materials. If you make it a screencast and slow down the playback speed, you have a product video in minutes!
• Rails provides a generator for system tests.
• Minitest in Rails is slightly different than Minitest itself, and also adds Rails specific methods and assertions. Check the Rails docs first before the Minitest docs.

I had good fun with the system tests, and that was, for the most part, thanks to how easy it was to use it out-of-the-box.

Conclusion

In this post, we looked at what configuration Rails delivers out-of-the-box and what minimal customizations we may want to add. Minitest is great for writing System tests. A few tips and tricks should help to get your first system tests up and running. Watch them do their magic in the browser!

Guest author Maud de Vries is a freelance Ruby on Rails developer, a Coach for (solo) entrepreneurs and she used to be an editor as well. The writer inside sometimes escapes.