DEV Community: Maud de Vries

Getting Started With System Tests in Rails With Minitest

Maud de Vries — Wed, 19 Feb 2020 15:55:28 +0000

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.

The Ultimate Checklist to Properly Internationalize Devise

Maud de Vries — Tue, 11 Jun 2019 12:19:37 +0000

Sometimes, the best blog post comes from a need to scratch your own itch. And today's blog post is an example of that!

You probably know Devise—a popular authentication solution for Rails applications. When working with Devise, I found that getting a translation up and running was more complex than I had anticipated. Past me wished that there was a checklist that could help guide me through the process.

So here it is - for future me and you - the ultimate Devise Internationalization Checklist!

When (Not) to Use the devise-i18n Gem?

Devise's policy is to not make the strings in the Devise views translatable. All the strings are hard coded. Kudos to the creators of the devise-i18n gem, which makes all the Devise templates translatable and also provides community-sourced translations. For international apps, where you need multi-language support, the devise-i18n gem is the easiest solution.

However, the devise-i18n gem explicitly chooses to follow the Devise text as closely as possible. But the text that Devise provides isn't very consistent to start with. And since literal translation will never generate fluent language, I'm constantly tweaking translations (and copying files between projects). That is an ongoing struggle because it's hard to get all the translations consistent when looking at one string or one view at a time.

As a result, the quality of the translations of the i18n-devise gem don't reach the standards required for my monolingual, Dutch-only projects.

Another disadvantage of using the gem arrises with customized views. Even when it's only to do with styling, every update of the devise-i18n gem that touches any changes that Devise made to the views, will mean you have to fix things. You will either need to regenerate the views and apply the customizations or you will have to copy/paste the changes into your views. This problem is not solved with the approach in the checklist below, by the way, but it's also not more difficult to solve without the devise-i18n gem. 🤷‍♀

🇳🇱 A Dutch treat

I decided to create one nice Dutch translation file for Devise, and never have to worry about it again. Sounds like a treat? You can find the new and improved translation file on GitHub. See step 3 in the checklist. The rationale for each translation decision is explained in the file.

The Ultimate Checklist

Now that we're flying solo with the :nl translation, let's get started with of all the details and start checking boxes.

Note that this assumes that you have an app ready, with Devise added and installed with a User model, and the Devise views generated. If you're coding along: this is the starting point. And note that nl in *.nl.yml can be replaced by the language of your choice, and that User and :user can be replaced by the model name you use in Devise.

Step One: Set locale

Add :nl to the available locales (if you don't have a strong opinion on the matter, start with putting it in application.rb for now). Now you can set it as default.

# application.rb
config.i18n.available_locales = [:nl, :en]
config.i18n.default_locale = :nl

There are better, perhaps cleaner options to set the locale than adding it to application.rb. Check the Rails i18n guide after reading this post to choose the option that suits you best.

Step Two: Add Rails translation

Add the Rails :nl translation file to take care of the strings in the interface that are not Devise specific (especially the Rails validation error messages).

Step Three: The Devise keys

Translate the Devise keys to :nl: add the New and Improved Dutch Translation! (Link above 🇳🇱)

Step Four: Create views.*.yml files

Add Dutch and English .yml files for the views, views.*.yml. There's an example of a finished views.nl.yml file in the repo, reflecting steps 4, 6 and 7.

#example views.nl.yml
nl:
  devise:
    # to be filled in later with Devise scopes:
    # registrations:
    #   new:
    #     forget_password: Wachtwoord vergeten?

Step Five: The Active Record attributes

Now, add translations for the labels of the Active Record attributes, like email and password. Translate just the ones that the user and the admin user see, for each of the modules that you implemented. No need to translate token names and such (as the i18n gem does). Here's what I consider useful 'translatables':

# In: active_record.nl.yml
# translating the labels that map to User attributes
nl:
  activerecord:
    attributes:
      user:
        current_password: Huidig wachtwoord
        email: e-mailadres
        password: wachtwoord
        password_confirmation: Wachtwoord bevestigen
        remember_me: Ingelogd blijven?
    models:
      user: Gebruiker

Note that the :email and :password values are downcased. That's because of the tweaks to the Rails error messages in step 7.

For now, put the keys in active_record.*.yml.

Step Six: Check every Devise view

Next, all the Devise-specific templates and strings need to be i18n-ed with the corresponding translations. Doing it yourself is an annoying job. Before you dive into it, see if one of these shortcuts work for you:

You could use the 118n-devise gem for the views, but you still have to copy the keys from the gem's .yml files into your project's .yml files. The gem interleaves them in devise.*.yml, but we don't want to overwrite our nice new Dutch translation. And if you have styled the Devise views, you'll need to copy the styling too. Yugh.
If you already have i18n-ed projects, you could copy the view files. (Same disadvantages with this as in the previous option.)
Use the repo for examples of a few views that I used in my latest project.

Or solve it once and for all: head down, create a set of files that you can use from now on, exactly the way you want them to be. The examples in the previous step are my own first version; they may help you kick-start your own. Check out the mini-checklist below for all the requirements.

Mini Checklist for the Devise Forms

Strings that are not Active Record strings need to be 118n-ed and have (properly scoped) keys and translations (stored in, for instance, a views.*.yml file—see example).
Take care that the Dutch translations, when adding your own, are consistent with the new devise.nl.yml.
Ignore the downcased labels; they will be capitalized properly in step 7.
If you already have the mailers i18n-ed, that's okay. If not, you may ignore them until step 8.
The following Devise views need to be made translatable with the Rails translate (t) helper:
- The devise/views/shared/_links partial: all the link names;
- The devise/views/shared/_errors partial (since Devise 4.6)
- In the Devise forms for each of the modules you use: all the strings that are not labels for Active Record attributes.

Step Seven: The Active Record error messages

Next, we need to tweak the Active Record error messages that are related to the Devise functionality. Like "password can't be blank", and other validations.

The thing is, now that we have upgraded the Devise translations, the Active Record messages need tweaking as well because the inconsistency in style is really showing. So I tweaked them too, following the same rules as for the Devise translations, and making sure they are consistent.

You'll see that the format of the messages has changed: from "%{attribute} %{message}" to "%{message}". Now we are referencing the attribute within the translated string instead of forcing it at the start of the string, makes it so much easier to prettify the Dutch messages. I rather have the duplication than putting up with the sometimes weird messages.

The new message format is the reason why, in step 5, the email and password attributes needed to be downcased: in the error messages, they can appear anywhere within a sentence.

I also replaced the :taken message. The Devise policy is to not reveal if an email address is 'not found' or 'invalid'. I extended that policy to the Rails' taken message.

See this file if you want to follow the new messages style. Then replace the corresponding part of the Rails error: messages: keys in the original nl.yml file. One caveat: when you're adding validations for none Devise-related input, please double check if the error messages still make sense. (I need to investigate further; I only checked the ones that are related to Devise.)

Step Eight: Fix the labels we just broke

In step 5, we downcased the email and password translations for use in the new error messages. Now we need to fix their appearance in the labels. There are several options, but the one I like most is adding separate 'label' keys.

This adds some duplication for the user keys, but it keeps the labels in the forms clean.

# in active_record.nl.yml add the label helper keys:
nl:
  activerecord:
    attributes:
      user:
        current_password: Huidig wachtwoord
        email: e-mailadres
        password: wachtwoord
        password_confirmation: Herhaal het wachtwoord
        remember_me: Wil je ingelogd blijven?
    models: 
      user: Gebruiker
  helpers:
    label:
      user:
        email: Emailadres
        password: Wachtwoord

Note that there is already a :helpers scope in the original nl.yml. In general, it's a good idea to keep the keys for a scope together, for easy lookup (by humans).

The other changes we need to make are straightforward. No big surprises will pop up from here on. 🎉.

Step Nine: Update navigation links

Find all the links that point to Devise (think navigation) and i18n them with the Rails t helper.

I like to keep those somewhere in the Devise scope of the .yml's. For example, I'd add t(".devise.sign_out") to have :sign_out in the same scope as :sign_up and :sign_in (see the example files).

Step Ten: Translate the mailers.

Translate the mailer views. There are a few options:

You can 'i18n' every string and link name, just like we did in step 6 with the other views. You may want to add a separate mailer.*.yml.
Or you can add separate mailer views for each locale: devise/mailer/reset_password.nl.html.erb and devise/mailer/reset_password.en.html.erb. Each with their own text. Rails will pick the one that matches the locale that is set.

Alright! Now all the Devise strings are properly translated. Yay!

After Care: Declutter

In my views example, I extracted the shared keys (like :forgot_password) and collected them in the general devise scope. This makes it easier to change them, but Rails can't find them automatically, so we need the verbose syntax (t("devise.forgot_password")), because the dot syntax (t(".new_confirmation_mail")) won't work.

If you go with the active_record.*.yml, it makes sense to collect all the keys with active record scope into that file. Move the Active Record keys from the Rails *.yml files into the corresponding active_record.*.yml.

We also have two pairs of *.yml files that duplicate the devise: scope. Consider mixing the keys from the Devise views into the devise.*.yml views. It is what the Devise-i18n gem does, and I like it. You'd do it like this:

# mixing the view scopes into devise.nl.yml
nl:
  devise:
    confirmations:
      ...
    registrations:
      ...
      edit:
        ...
      new:
        ...

Some Tweaks and Tips

I am not a fan of the header in the error message ('x errors prohibited this user from being saved'), so I removed that from the errors partial.
If you set the default_locale to :nl, Rails will 'humanize' the keys if it can't find a translation. So, t(:some_untranslated_key) will show as Some Untranslated Key in the view.
With the I18n-tasks gem you can clean up unused keys and add missing keys. It's a great tool! However, my IDE has great i18n support and for me that turned out to be a quicker workflow than the gem.

Parting Is Such Sweet Sorrow

A quick final word before we part. When I started this journey I didn't expect it to be as much work as it turned out to be. I'm very happy that I now know where the complexity comes from. And future me and you now have a list of all the changes needed. Woohoo!

But even with this checklist in hand, think before you act: maybe it's worth living with the less optimal translations for a while…

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.