Introduction

In this tutorial, we’ll cover how to do integration tests in Rails using Minitest and Capybara. We’ll also cover how integration tests can sometimes serve as a replacement for controller tests.

Prerequisites

To follow this tutorial, you’ll need to have Ruby installed along with Rails. This tutorial was tested using Ruby version 2.3.3, Rails version 5.0.0.1, Minitest version 5.10.1, and Capybara version 2.11.1.

Currently, there are no known issues with using earlier or later versions of any of those, however there will be some differences.

To get started, you can use gem install rails , and you should be good to go.

gem install rails

What is Minitest?

Minitest is a complete testing suite for Ruby, supporting test-driven development (TDD), behavior-driven development (BDD), mocking, and benchmarking. It’s small, fast, and it aims to make tests clean and readable.

If you’re new to Minitest, you can take a look at our tutorial on getting started with Minitest.

Minitest is the default testing suite included by default with new Rails applications, so no further setting up is required to get it to work. Minitest and RSpec are the two most common testing suites used in Ruby. If you’d like to learn more about RSpec, you can read our tutorial on getting started with RSpec as well as this tutorial on mocking with RSpec: doubles and expectations.

What is Capybara?

Capybara is an acceptance test framework for web applications, often used to do end-to-end testing in Rails applications.

It allows developers to simulate a user on a web page, make assertions based on the content and environment of the page, and it also provides an API to interact with the web page.

By default, it will run in headless mode, but it can also use a browser or a number of other drivers instead.

What is Integration Testing?

While unit tests make sure that individual parts of your application work, integration tests are used to test that different parts of your application work together. They are normally used to test at least the most important workflows of applications.

Terminology

Although we refer to this kind of testing as integration testing, it might also be referred to as acceptance testing. The authors of Capybara refer to it as an acceptance testing framework. Sometimes, these kind of tests are also called end-to-end tests.

Integration Tests vs. Controller Tests

The default method for testing controllers in Rails is to use functional tests. However, since controllers are ideally very lean in Rails, and our integration tests are exercising all code paths, they can be omitted in favor of thorough integration tests.

For example, an integration test for a user signup can assert that the welcome email was sent out just as well as a functional controller test can.

Some people prefer to test controllers in isolation. Sometimes, there is a good reason to do this, if your controllers are very complex.

Setup

Provided you have installed Ruby and Rails, you can set up a new Rails application.

rails new integration-testing-minitest

We’ll need to add Capybara to our Gemfile in the group test. This can be done at the bottom of the file. Note that we’re using a gem called minitest-rails-capybara, which integrates Capybara with Minitest and Rails.

# Gemfile ... group :test do gem ' minitest-rails-capybara ' end

We’ll also need to load Capybara in order to use it in our tests.

# test/test_helper.rb ENV [ ' RAILS_ENV ' ] ||= ' test ' require File .expand_path( ' ../../config/environment ' , __FILE__ ) require ' rails/test_help ' require " minitest/rails/capybara " ...

We’re now all set to start writing our example application.

Example Application

Now that we have everything set up, we’ll introduce an example application where we make use of integration tests.

Our example application is a blog where we’ll have an index of posts and a link to a page for writing new posts. Each post has a title and a body, and every time a new post is created, an email is sent out to an admin to notify them about the new post.

Since we’re focusing on integration testing, we’ll use generators where we can, and avoid focusing much on other kinds of tests in order to keep this tutorial brief.

Let’s start by running the scaffold generator to create posts.

rails generate scaffold Post title:string body:text

We’ve omitted the output here, it should create all the necessary files for posts. Next we need to migrate the database.

rake db:migrate == 20161214213527 CreatePosts: migrating ====================================== -- create_table(:posts) - > 0.0020s == 20161214213527 CreatePosts: migrated (0.0024s) =============================

The generator created some tests for us, and although we are not going to be using those, it’s a good idea to run them to make sure everything works.

rake # Running: ....... Finished in 1.103736s, 6.3421 runs/s, 8.1541 assertions/s. 7 runs, 9 assertions, 0 failures, 0 errors, 0 skips

You can also issue rails server at the command line and navigate to http://localhost:3000/posts to check the result. We’re going to be using integration tests to automatically test all of this.

Integration Tests

Let’s create our first integration test. We want to navigate to the index and make sure it lists all the blog posts in our database. Let’s start by updating our fixtures so we can write a test for this.

# test/fixtures/posts.yml one : title : Post Title One body : Post body one. two : title : Post Title Two body : Post body two.

Here’s our first integration test.

# test/integration/post_flow_test.rb require ' test_helper ' class PostFlowTest < Capybara::Rails::TestCase def setup @one = posts :one @two = posts :two end test ' post index ' do visit posts_path assert page.has_content?( @one .title) assert page.has_content?( @two .title) end end

All we did here was visit the post index and make sure that the titles for both posts in our fixtures are present. Let’s run all of our tests again to make sure they all pass. This test should pass without us having to do anything, since the scaffold we generated earlier does this already.

rake # Running: ........ Finished in 0.515325s, 15.5242 runs/s, 21.3458 assertions/s. 8 runs, 11 assertions, 0 failures, 0 errors, 0 skips

Let move on to something a bit more complicated, and test that we can write a new post and submit it. Place it below the other test in our integration test for posts.

# test/integration/post_flow_test.rb ... test ' writing a new post ' do visit posts_path click_on ' New Post ' fill_in ' Title ' , with: ' Test Title ' fill_in ' Body ' , with: ' Test Body ' click_on ' Create Post ' assert_current_path post_path( Post .last) assert page.has_content?( ' Test Title ' ) assert page.has_content?( ' Test Body ' ) end end

In this test, we navigate to the post index, click the link to write a new post, fill in the form with some text, and submit the post. We make sure that we’re redirected to the right page and that it contains the text we wrote in the post.

Run the tests again to make sure everything passes. Again, we don’t need to write any code since this test will already pass because of the code generated by the scaffold.

rake # Running: ......... Finished in 0.551475s, 16.3199 runs/s, 23.5731 assertions/s. 9 runs, 13 assertions, 0 failures, 0 errors, 0 skips

Now, we have one last feature to add, the email alert to an admin email once a post has been submitted. Let’s start by adding a new test for writing a new post and checking if an admin notice email was sent.

# test/integration/post_flow_test.rb require ' test_helper ' class PostFlowTest < Capybara::Rails::TestCase include ActiveJob :: TestHelper def setup @one = posts :one @two = posts :two end test ' post index ' do visit posts_path assert page.has_content?( @one .title) assert page.has_content?( @two .title) end test ' writing a new post ' do write_new_post latest_post = Post .last assert_current_path post_path(latest_post) assert page.has_content?( ' Test Title ' ) assert page.has_content?( ' Test Body ' ) end test ' writing a new post sends admin notice ' do perform_enqueued_jobs do write_new_post last_post = Post .last mail = ActionMailer :: Base .deliveries.last assert_equal ' admin@example.com ' , mail[ ' to ' ].to_s assert_equal ' New post added ' , mail.subject end end private def write_new_post visit posts_path click_on ' New Post ' fill_in ' Title ' , with: ' Test Title ' fill_in ' Body ' , with: ' Test Body ' click_on ' Create Post ' end end

Quite a few things changed in this file. At the top, we include ActiveJob::TestHelper so we can tell ActiveJob to perform_enqueued_jobs before running our tests. This is necessary since we plan on using ActiveJob to deliver our email later, instead of doing so in the client request.

We also refactor writing a new post into a private method to keep the tests for writing a new post and for ensuring that the admin email gets sent separate. When it comes to integration tests, this is optional, you could also keep it all in the same test, and split it into methods.

Finally, we get the last email sent by ActionMailer and make sure it has the correct recipient and subject. We don’t have to go further than that, since the content of the mail should be tested in the test for the mailer itself. This is to avoid testing the same thing in many places, and make our tests less rigid and easier to update.

Now, if you try running running our new tests, they’ll fail since we haven’t added the notification email yet. We’ll be adding a mailer and calling it from PostsController#create and testing in our integration test instead of writing a separate functional test for the controller to do it.

Let’s create the mailer first:

rails generate mailer PostMailer

This should set up the mailer. Now we need to add our admin notice email to it:

# app/mailers/post_mailer.rb class PostMailer < ApplicationMailer def admin_notice ( post ) @post = post mail to: ' admin@example.com ' , subject: ' New post added ' end end

We also need the corresponding views:

<%# app/views/post_mailer/admin_notice.html.erb %> < p >A new post has been added! Here's the post:</ p > < p > <%= @post .title %> </ p > <%= simple_format @post .body %>

<%# app/views/post_mailer/admin_notice.text.erb %> A new post has been added! Here's the post: Title: <%= @post .title %> <%= @post .body %>

We’ll skip the tests for this mailer to keep this tutorial from getting too long. All we have to do now is call the mailer from the controller after a post has been created.

# app/controllers/posts_controller.rb ... # POST /posts # POST /posts.json def create @post = Post . new (post_params) respond_to do | format | if @post .save PostMailer .admin_notice( @post ).deliver_later format .html { redirect_to @post , notice: ' Post was successfully created. ' } format .json { render :show , status: :created , location: @post } else format .html { render :new } format .json { render json: @post .errors, status: :unprocessable_entity } end end end ...

We added only one line there to call the mailer. Now, let’s run our tests again and see if they pass.

rake # Running: .......... Finished in 0.975611s, 10.2500 runs/s, 15.3750 assertions/s. 10 runs, 15 assertions, 0 failures, 0 errors, 0 skips

All the tests should pass, and we now have an application that is integration tested end-to-end with Minitest and Capybara.

Conclusion

In this tutorial, we covered how to integration test Rails applications with Minitest and Capybara. We now have a functional Rails application that is covered with integration tests. After reading this tutorial, you should have an idea of how integration tests can be used to simulate a user within your Rails application, as well as how integration tests can in part, or fully, replace functional controller tests.

If you found this tutorial helpful, you might want to check out some of the other tutorials on testing in the Semaphore Community.

If you’d like to learn how to set up a BDD stack on a Rails 5 application, this tutorial is the best next read for you.

We’d also like to hear your comments and questions, so feel free to leave them in the section below.

P.S. Would you like to learn how to build sustainable Rails apps and ship more often? We’ve recently published an ebook covering just that — “Rails Testing Handbook”. Learn more and download a free copy.