diff --git a/guides/source/documents.yaml b/guides/source/documents.yaml index 140dbe7d570b7..ab6c77230f019 100644 --- a/guides/source/documents.yaml +++ b/guides/source/documents.yaml @@ -170,7 +170,7 @@ - name: Testing Rails Applications url: testing.html - description: This is a rather comprehensive guide to the various testing facilities in Rails. It covers everything from 'What is a test?' to Integration Testing. Enjoy. + description: This guide explores how to write tests in Rails. It also covers test configuration and compares approaches to testing an application. - name: Securing Rails Applications url: security.html diff --git a/guides/source/testing.md b/guides/source/testing.md index 2c541e9026134..0f5fae6563783 100644 --- a/guides/source/testing.md +++ b/guides/source/testing.md @@ -3,77 +3,103 @@ Testing Rails Applications ========================== -This guide covers built-in mechanisms in Rails for testing your application. +This guide explores how to write tests in Rails. After reading this guide, you will know: * Rails testing terminology. -* How to write unit, functional, integration, and system tests for your application. +* How to write unit, functional, integration, and system tests for your + application. * Other popular testing approaches and plugins. -------------------------------------------------------------------------------- -Why Write Tests for Your Rails Applications? --------------------------------------------- - -Rails makes it super easy to write your tests. It starts by producing skeleton test code while you are creating your models and controllers. +Why Write Tests? +---------------- -By running your Rails tests you can ensure your code adheres to the desired functionality even after some major code refactoring. +Writing automated tests can be a faster way of ensuring your code continues to +work as expected than manual testing through the browser or the console. Failing +tests can quickly reveal issues, allowing you to identify and fix bugs early in +the development process. This practice not only improves the reliability of your +code but also improves confidence in your changes. -Rails tests can also simulate browser requests and thus you can test your application's response without having to test it through your browser. +Rails makes it easy to write tests. You can read more about Rails' built in +support for testing in the next section. Introduction to Testing ----------------------- -Testing support was woven into the Rails fabric from the beginning. It wasn't an "oh! let's bolt on support for running tests because they're new and cool" epiphany. +With Rails, testing is central to the development process right from the +creation of a new application. -### Rails Sets up for Testing from the Word Go +### Test Setup -Rails creates a `test` directory for you as soon as you create a Rails project using `rails new` _application_name_. If you list the contents of this directory then you shall see: +Rails creates a `test` directory for you as soon as you create a Rails project +using `bin/rails new` _application_name_. If you list the contents of this directory +then you will see: ```bash $ ls -F test -application_system_test_case.rb controllers/ helpers/ mailers/ system/ -channels/ fixtures/ integration/ models/ test_helper.rb +application_system_test_case.rb controllers/ helpers/ mailers/ system/ fixtures/ integration/ models/ test_helper.rb ``` -The `helpers`, `mailers`, and `models` directories are meant to hold tests for view helpers, mailers, and models, respectively. The `channels` directory is meant to hold tests for Action Cable connection and channels. The `controllers` directory is meant to hold tests for controllers, routes, and views. The `integration` directory is meant to hold tests for interactions between controllers. +### Test Directories + +The `helpers`, `mailers`, and `models` directories store tests for [view +helpers](#testing-view-helpers), [mailers](#testing-mailers), and +[models](#testing-models), respectively. -The system test directory holds system tests, which are used for full browser -testing of your application. System tests allow you to test your application -the way your users experience it and help you test your JavaScript as well. -System tests inherit from Capybara and perform in browser tests for your -application. +The `controllers` directory is used for +[tests related to controllers](#functional-testing-for-controllers), routes, and +views, where HTTP requests will be simulated and assertions made on the +outcomes. -Fixtures are a way of organizing test data; they reside in the `fixtures` directory. +The `integration` directory is reserved for [tests that cover +interactions between controllers](#integration-testing). -A `jobs` directory will also be created when an associated test is first generated. +The `system` test directory holds [system tests](#system-testing), which are +used for full browser testing of your application. System tests allow you to +test your application the way your users experience it and help you test your +JavaScript as well. System tests inherit from +[Capybara](https://github.com/teamcapybara/capybara) and perform in-browser +tests for your application. + +[Fixtures](https://api.rubyonrails.org/v3.1/classes/ActiveRecord/Fixtures.html) +are a way of mocking up data to use in your tests, so that you don't have to use +'real' data. They are stored in the `fixtures` directory, and you can read more +about them in the [Fixtures](#fixtures) section below. + +A `jobs` directory will also be created for your job tests when you first +[generate a job](active_job_basics.html#create-the-job). The `test_helper.rb` file holds the default configuration for your tests. -The `application_system_test_case.rb` holds the default configuration for your system -tests. +The `application_system_test_case.rb` holds the default configuration for your +system tests. ### The Test Environment -By default, every Rails application has three environments: development, test, and production. +By default, every Rails application has three environments: development, test, +and production. -Each environment's configuration can be modified similarly. In this case, we can modify our test environment by changing the options found in `config/environments/test.rb`. +Each environment's configuration can be modified similarly. In this case, we can +modify our test environment by changing the options found in +`config/environments/test.rb`. -NOTE: Your tests are run under `RAILS_ENV=test`. +NOTE: Your tests are run under `RAILS_ENV=test`. This is set by Rails automatically. -### Rails Meets Minitest +### Writing Your First Test -If you remember, we used the `bin/rails generate model` command in the -[Getting Started with Rails](getting_started.html) guide. We created our first -model, and among other things it created test stubs in the `test` directory: +We introduced the `bin/rails generate model` command in the [Getting Started +with Rails](getting_started.html#mvc-and-you-generating-a-model) guide. +Alongside creating a model, this command also creates a test stub in the `test` +directory: ```bash $ bin/rails generate model article title:string body:text ... create app/models/article.rb create test/models/article_test.rb -create test/fixtures/articles.yml ... ``` @@ -89,13 +115,16 @@ class ArticleTest < ActiveSupport::TestCase end ``` -A line by line examination of this file will help get you oriented to Rails testing code and terminology. +A line by line examination of this file will help get you oriented to Rails +testing code and terminology. ```ruby require "test_helper" ``` -By requiring this file, `test_helper.rb`, the default configuration to run our tests is loaded. We will include this with all the tests we write, so any methods added to this file are available to all our tests. +Requiring the file, `test_helper.rb`, loads the default configuration to run +tests. All methods added to this file are also available in tests when this file +is included. ```ruby class ArticleTest < ActiveSupport::TestCase @@ -103,12 +132,20 @@ class ArticleTest < ActiveSupport::TestCase end ``` -The `ArticleTest` class defines a _test case_ because it inherits from `ActiveSupport::TestCase`. `ArticleTest` thus has all the methods available from `ActiveSupport::TestCase`. Later in this guide, we'll see some of the methods it gives us. +This is called a test case, because the `ArticleTest` class inherits from +`ActiveSupport::TestCase`. It therefore also has all the methods from +`ActiveSupport::TestCase` available to it. [Later in this +guide](#assertions-in-test-cases), we'll see some of the methods this gives us. -Any method defined within a class inherited from `Minitest::Test` -(which is the superclass of `ActiveSupport::TestCase`) that begins with `test_` is simply called a test. So, methods defined as `test_password` and `test_valid_password` are legal test names and are run automatically when the test case is run. +Any method defined within a class inherited from `Minitest::Test` (which is the +superclass of `ActiveSupport::TestCase`) that begins with `test_` is simply +called a test. So, methods defined as `test_password` and `test_valid_password` +are test names and are run automatically when the test case is run. -Rails also adds a `test` method that takes a test name and a block. It generates a normal `Minitest::Unit` test with method names prefixed with `test_`. So you don't have to worry about naming the methods, and you can write something like: +Rails also adds a `test` method that takes a test name and a block. It generates +a standard `Minitest::Unit` test with method names prefixed with `test_`, +allowing you to focus on writing the test logic without having to think about +naming the methods. For example, you can write: ```ruby test "the truth" do @@ -124,40 +161,56 @@ def test_the_truth end ``` -Although you can still use regular method definitions, using the `test` macro allows for a more readable test name. +Although you can still use regular method definitions, using the `test` macro +allows for a more readable test name. -NOTE: The method name is generated by replacing spaces with underscores. The result does not need to be a valid Ruby identifier though — the name may contain punctuation characters, etc. That's because in Ruby technically any string may be a method name. This may require use of `define_method` and `send` calls to function properly, but formally there's little restriction on the name. +NOTE: The method name is generated by replacing spaces with underscores. The +result does not need to be a valid Ruby identifier, as Ruby allows any string to +serve as a method name, including those containing punctuation characters. While +this may require using `define_method` and `send` to define and invoke such +methods, there are few formal restrictions on the names themselves. -Next, let's look at our first assertion: +This part of a test is called an 'assertion': ```ruby assert true ``` -An assertion is a line of code that evaluates an object (or expression) for expected results. For example, an assertion can check: +An assertion is a line of code that evaluates an object (or expression) for +expected results. For example, an assertion can check: -* does this value = that value? +* does this value equal that value? * is this object nil? * does this line of code throw an exception? * is the user's password greater than 5 characters? -Every test may contain one or more assertions, with no restriction as to how many assertions are allowed. Only when all the assertions are successful will the test pass. +Every test may contain one or more assertions, with no restriction as to how +many assertions are allowed. Only when all the assertions are successful will +the test pass. #### Your First Failing Test -To see how a test failure is reported, you can add a failing test to the `article_test.rb` test case. +To see how a test failure is reported, you can add a failing test to the +`article_test.rb` test case. In this example, it is asserted that the article +will not save without meeting certain criteria; hence, if the article saves +successfully, the test will fail, demonstrating a test failure. -```ruby -test "should not save article without title" do - article = Article.new - assert_not article.save +```ruby#4-7 +require "test_helper" + +class ArticleTest < ActiveSupport::TestCase + test "should not save article without title" do + article = Article.new + assert_not article.save + end end ``` -Let us run this newly added test (where `6` is the line number where the test is defined). +Here is the output if this newly added test is run: ```bash -$ bin/rails test test/models/article_test.rb:6 +$ bin/rails test test/models/article_test.rb +Running 1 tests in a single process (parallelization threshold is 50) Run options: --seed 44656 # Running: @@ -165,11 +218,11 @@ Run options: --seed 44656 F Failure: -ArticleTest#test_should_not_save_article_without_title [/path/to/blog/test/models/article_test.rb:6]: +ArticleTest#test_should_not_save_article_without_title [/path/to/blog/test/models/article_test.rb:4]: Expected true to be nil or false -bin/rails test test/models/article_test.rb:6 +bin/rails test test/models/article_test.rb:4 @@ -178,7 +231,12 @@ Finished in 0.023918s, 41.8090 runs/s, 41.8090 assertions/s. 1 runs, 1 assertions, 1 failures, 0 errors, 0 skips ``` -In the output, `F` denotes a failure. You can see the corresponding trace shown under `Failure` along with the name of the failing test. The next few lines contain the stack trace followed by a message that mentions the actual value and the expected value by the assertion. The default assertion messages provide just enough information to help pinpoint the error. To make the assertion failure message more readable, every assertion provides an optional message parameter, as shown here: +In the output, `F` indicates a test failure. The section under `Failure` +includes the name of the failing test, followed by a stack trace and a message +showing the actual value and the expected value from the assertion. The default +assertion messages offer just enough information to help identify the error. For +improved readability, every assertion allows an optional message parameter to +customize the failure message, as shown below: ```ruby test "should not save article without title" do @@ -195,7 +253,8 @@ ArticleTest#test_should_not_save_article_without_title [/path/to/blog/test/model Saved the article without a title ``` -Now to get this test to pass we can add a model level validation for the _title_ field. +To get this test to pass a model-level validation can be added for the `title` +field. ```ruby class Article < ApplicationRecord @@ -203,10 +262,13 @@ class Article < ApplicationRecord end ``` -Now the test should pass. Let us verify by running the test again: +Now the test should pass, as the article in our test has not been initialized +with a `title`, so the model validation will prevent the save. This can be +verified by running the test again: ```bash $ bin/rails test test/models/article_test.rb:6 +Running 1 tests in a single process (parallelization threshold is 50) Run options: --seed 31252 # Running: @@ -218,13 +280,14 @@ Finished in 0.027476s, 36.3952 runs/s, 36.3952 assertions/s. 1 runs, 1 assertions, 0 failures, 0 errors, 0 skips ``` -Now, if you noticed, we first wrote a test which fails for a desired -functionality, then we wrote some code which adds the functionality and finally -we ensured that our test passes. This approach to software development is -referred to as -[_Test-Driven Development_ (TDD)](http://c2.com/cgi/wiki?TestDrivenDevelopment). +The small green dot displayed means that the test has passed successfully. -#### What an Error Looks Like +TIP: In the process above, a test was written first which fails for a desired +functionality, then after, some code was written which adds the functionality. +Finally, the test was run again to ensure it passes. This approach to software +development is referred to as _Test-Driven Development_ (TDD). + +#### Reporting Errors To see how an error gets reported, here's a test containing an error: @@ -240,11 +303,12 @@ Now you can see even more output in the console from running the tests: ```bash $ bin/rails test test/models/article_test.rb +Running 2 tests in a single process (parallelization threshold is 50) Run options: --seed 1808 # Running: -.E +E Error: ArticleTest#test_should_report_error: @@ -254,31 +318,34 @@ NameError: undefined local variable or method 'some_undefined_variable' for #Hello, from a fixture ``` -Notice the `category` key of the `first` Article found in `fixtures/articles.yml` has a value of `about`, and that the `record` key of the `first_content` entry found in `fixtures/action_text/rich_texts.yml` has a value of `first (Article)`. This hints to Active Record to load the Category `about` found in `fixtures/categories.yml` for the former, and Action Text to load the Article `first` found in `fixtures/articles.yml` for the latter. +Notice the `category` key of the `first` Article found in +`fixtures/articles.yml` has a value of `web_frameworks`, and that the `record` key of the +`first_content` entry found in `fixtures/action_text/rich_texts.yml` has a value +of `first (Article)`. This hints to Active Record to load the Category `web_frameworks` +found in `fixtures/categories.yml` for the former, and Action Text to load the +Article `first` found in `fixtures/articles.yml` for the latter. -NOTE: For associations to reference one another by name, you can use the fixture name instead of specifying the `id:` attribute on the associated fixtures. Rails will auto assign a primary key to be consistent between runs. For more information on this association behavior please read the [Fixtures API documentation](https://api.rubyonrails.org/classes/ActiveRecord/FixtureSet.html). +NOTE: For associations to reference one another by name, you can use the fixture +name instead of specifying the `id:` attribute on the associated fixtures. Rails +will auto-assign a primary key to be consistent between runs. For more +information on this association behavior please read the [Fixtures API +documentation](https://api.rubyonrails.org/classes/ActiveRecord/FixtureSet.html). #### File Attachment Fixtures @@ -807,11 +731,15 @@ first_thumbnail_attachment: blob: first_thumbnail_blob ``` -[image/png]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#image_types +[image/png]: + https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#image_types -#### ERB'in It Up +#### Embedding Code in Fixtures -ERB allows you to embed Ruby code within templates. The YAML fixture format is pre-processed with ERB when Rails loads fixtures. This allows you to use Ruby to help you generate some sample data. For example, the following code generates a thousand users: +ERB allows you to embed Ruby code within templates. The YAML fixture format is +pre-processed with ERB when Rails loads fixtures. This allows you to use Ruby to +help you generate some sample data. For example, the following code generates a +thousand users: ```erb <% 1000.times do |n| %> @@ -830,11 +758,19 @@ default. Loading involves three steps: 2. Load the fixture data into the table 3. Dump the fixture data into a method in case you want to access it directly -TIP: In order to remove existing data from the database, Rails tries to disable referential integrity triggers (like foreign keys and check constraints). If you are getting annoying permission errors on running tests, make sure the database user has privilege to disable these triggers in testing environment. (In PostgreSQL, only superusers can disable all triggers. Read more about PostgreSQL permissions [here](https://www.postgresql.org/docs/current/sql-altertable.html)). +TIP: In order to remove existing data from the database, Rails tries to disable +referential integrity triggers (like foreign keys and check constraints). If you +are getting permission errors on running tests, make sure the database user has +the permission to disable these triggers in the testing environment. (In +PostgreSQL, only superusers can disable all triggers. Read more about +[permissions in the PostgreSQL +docs](https://www.postgresql.org/docs/current/sql-altertable.html)). #### Fixtures are Active Record Objects -Fixtures are instances of Active Record. As mentioned in point #3 above, you can access the object directly because it is automatically available as a method whose scope is local of the test case. For example: +Fixtures are instances of Active Record. As mentioned above, you can access the +object directly because it is automatically available as a method whose scope is +local to the test case. For example: ```ruby # this will return the User object for the fixture named david @@ -843,308 +779,512 @@ users(:david) # this will return the property for david called id users(:david).id -# one can also access methods available on the User class +# methods available to the User object can also be accessed david = users(:david) david.call(david.partner) ``` -To get multiple fixtures at once, you can pass in a list of fixture names. For example: +To get multiple fixtures at once, you can pass in a list of fixture names. For +example: ```ruby # this will return an array containing the fixtures david and steve users(:david, :steve) ``` +### Transactions -Model Testing -------------- +By default, Rails automatically wraps tests in a database transaction that is +rolled back once completed. This makes tests independent of each other and means +that changes to the database are only visible within a single test. -Model tests are used to test the various models of your application. +```ruby +class MyTest < ActiveSupport::TestCase + test "newly created users are active by default" do + # Since the test is implicitly wrapped in a database transaction, the user + # created here won't be seen by other tests. + assert User.create.active? + end +end +``` -Rails model tests are stored under the `test/models` directory. Rails provides -a generator to create a model test skeleton for you. +The method +[`ActiveRecord::Base.current_transaction`](https://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html#method-i-current_transaction) +still acts as intended, though: -```bash -$ bin/rails generate test_unit:model article title:string body:text -create test/models/article_test.rb -create test/fixtures/articles.yml +```ruby +class MyTest < ActiveSupport::TestCase + test "Active Record current_transaction method works as expected" do + # The implicit transaction around tests does not interfere with the + # application-level semantics of the current_transaction. + assert User.current_transaction.blank? + end +end ``` -Model tests don't have their own superclass like `ActionMailer::TestCase`. Instead, they inherit from [`ActiveSupport::TestCase`](https://api.rubyonrails.org/classes/ActiveSupport/TestCase.html). +If there are [multiple writing databases](active_record_multiple_databases.html) +in place, tests are wrapped in as many respective transactions, and all of them +are rolled back. + +#### Opting-out of Test Transactions -System Testing +Individual test cases can opt-out: + +```ruby +class MyTest < ActiveSupport::TestCase + # No implicit database transaction wraps the tests in this test case. + self.use_transactional_tests = false +end +``` + +Testing Models -------------- -System tests allow you to test user interactions with your application, running tests -in either a real or a headless browser. System tests use Capybara under the hood. +Model tests are used to test the models of your application and their associated +logic. You can test this logic using the assertions and fixtures that we've +explored in the sections above. -For creating Rails system tests, you use the `test/system` directory in your -application. Rails provides a generator to create a system test skeleton for you. +Rails model tests are stored under the `test/models` directory. Rails provides a +generator to create a model test skeleton for you. ```bash -$ bin/rails generate system_test users - invoke test_unit - create test/system/users_test.rb +$ bin/rails generate test_unit:model article +create test/models/article_test.rb ``` -Here's what a freshly generated system test looks like: +This command will generate the following file: ```ruby -require "application_system_test_case" +# article_test.rb +require "test_helper" -class UsersTest < ApplicationSystemTestCase - # test "visiting the index" do - # visit users_url - # - # assert_selector "h1", text: "Users" +class ArticleTest < ActiveSupport::TestCase + # test "the truth" do + # assert true # end end ``` -By default, system tests are run with the Selenium driver, using the Chrome -browser, and a screen size of 1400x1400. The next section explains how to -change the default settings. +Model tests don't have their own superclass like `ActionMailer::TestCase`. +Instead, they inherit from +[`ActiveSupport::TestCase`](https://api.rubyonrails.org/classes/ActiveSupport/TestCase.html). -By default, Rails will attempt to rescue from exceptions raised during tests and respond with HTML error pages. This behavior can be controlled by the [`config.action_dispatch.show_exceptions`](/configuring.html#config-action-dispatch-show-exceptions) configuration. +Functional Testing for Controllers +---------------------------------- -### Changing the Default Settings +When writing functional tests, you are focusing on testing how controller +actions handle the requests and the expected result or response. Functional +controller tests are sometimes used in cases where system tests are not +appropriate, e.g., to confirm an API response. -Rails makes changing the default settings for system tests very simple. All -the setup is abstracted away so you can focus on writing your tests. +### What to Include in Your Functional Tests -When you generate a new application or scaffold, an `application_system_test_case.rb` file -is created in the test directory. This is where all the configuration for your -system tests should live. +You could test for things such as: -If you want to change the default settings you can change what the system -tests are "driven by". Say you want to change the driver from Selenium to -Cuprite. First add the `cuprite` gem to your `Gemfile`. Then in your -`application_system_test_case.rb` file do the following: +* was the web request successful? +* was the user redirected to the right page? +* was the user successfully authenticated? +* was the correct information displayed in the response? -```ruby -require "test_helper" -require "capybara/cuprite" +The easiest way to see functional tests in action is to generate a controller +using the scaffold generator: -class ApplicationSystemTestCase < ActionDispatch::SystemTestCase - driven_by :cuprite -end +```bash +$ bin/rails generate scaffold_controller article +... +create app/controllers/articles_controller.rb +... +invoke test_unit +create test/controllers/articles_controller_test.rb +... ``` -The driver name is a required argument for `driven_by`. The optional arguments -that can be passed to `driven_by` are `:using` for the browser (this will only -be used by Selenium), `:screen_size` to change the size of the screen for -screenshots, and `:options` which can be used to set options supported by the -driver. +This will generate the controller code and tests for an `Article` resource. You +can take a look at the file `articles_controller_test.rb` in the +`test/controllers` directory. -```ruby -require "test_helper" +If you already have a controller and just want to generate the test scaffold +code for each of the seven default actions, you can use the following command: -class ApplicationSystemTestCase < ActionDispatch::SystemTestCase - driven_by :selenium, using: :firefox -end +```bash +$ bin/rails generate test_unit:scaffold article +... +invoke test_unit +create test/controllers/articles_controller_test.rb +... ``` -If you want to use a headless browser, you could use Headless Chrome or Headless Firefox by adding -`headless_chrome` or `headless_firefox` in the `:using` argument. - -```ruby -require "test_helper" - -class ApplicationSystemTestCase < ActionDispatch::SystemTestCase - driven_by :selenium, using: :headless_chrome -end -``` +NOTE: if you are generating test scaffold code, you will see an `@article` value +is set and used throughout the test file. This instance of `article` uses the +attributes nested within a `:one` key in the `test/fixtures/articles.yml` file. +Make sure you have set the key and related values in this file before you try to +run the tests. -If you want to use a remote browser, e.g. -[Headless Chrome in Docker](https://github.com/SeleniumHQ/docker-selenium), -you have to add remote `url` and set `browser` as remote through `options`. +Let's take a look at one such test, `test_should_get_index` from the file +`articles_controller_test.rb`. ```ruby -require "test_helper" - -class ApplicationSystemTestCase < ActionDispatch::SystemTestCase - url = ENV.fetch("SELENIUM_REMOTE_URL", nil) - options = if url - { browser: :remote, url: url } - else - { browser: :chrome } +# articles_controller_test.rb +class ArticlesControllerTest < ActionDispatch::IntegrationTest + test "should get index" do + get articles_url + assert_response :success end - driven_by :selenium, using: :headless_chrome, options: options end ``` -Now you should get a connection to remote browser. +In the `test_should_get_index` test, Rails simulates a request on the action +called `index`, making sure the request was successful, and also ensuring that +the right response body has been generated. -```bash -$ SELENIUM_REMOTE_URL=http://localhost:4444/wd/hub bin/rails test:system +The `get` method kicks off the web request and populates the results into the +`@response`. It can accept up to 6 arguments: + +* The URI of the controller action you are requesting. This can be in the form + of a string or a route helper (e.g. `articles_url`). +* `params`: option with a hash of request parameters to pass into the action + (e.g. query string parameters or article variables). +* `headers`: for setting the headers that will be passed with the request. +* `env`: for customizing the request environment as needed. +* `xhr`: whether the request is AJAX request or not. Can be set to true for + marking the request as AJAX. +* `as`: for encoding the request with different content type. + +All of these keyword arguments are optional. + +Example: Calling the `:show` action (via a `get` request) for the first +`Article`, passing in an `HTTP_REFERER` header: + +```ruby +get article_url(Article.first), headers: { "HTTP_REFERER" => "http://example.com/home" } ``` -If your application in test is running remote too, e.g. Docker container, -Capybara needs more input about how to -[call remote servers](https://github.com/teamcapybara/capybara#calling-remote-servers). +Another example: Calling the `:update` action (via a `patch` request) for the +last `Article`, passing in new text for the `title` in `params`, as an AJAX +request: ```ruby -require "test_helper" +patch article_url(Article.last), params: { article: { title: "updated" } }, xhr: true +``` -class ApplicationSystemTestCase < ActionDispatch::SystemTestCase - def setup - Capybara.server_host = "0.0.0.0" # bind to all interfaces - Capybara.app_host = "http://#{IPSocket.getaddress(Socket.gethostname)}" if ENV["SELENIUM_REMOTE_URL"].present? - super +One more example: Calling the `:create` action (via a `post` request) to create +a new article, passing in text for the `title` in `params`, as JSON request: + +```ruby +post articles_url, params: { article: { title: "Ahoy!" } }, as: :json +``` + +NOTE: If you try running the `test_should_create_article` test from +`articles_controller_test.rb` it will (correctly) fail due to the newly added +model-level validation. + +Now to modify the `test_should_create_article` test in +`articles_controller_test.rb` so that this test passes: + +```ruby +test "should create article" do + assert_difference("Article.count") do + post articles_url, params: { article: { body: "Rails is awesome!", title: "Hello Rails" } } end - # ... + + assert_redirected_to article_path(Article.last) end ``` -Now you should get a connection to remote browser and server, regardless if it -is running in Docker container or CI. +You can now run this test and it will pass. -If your Capybara configuration requires more setup than provided by Rails, this -additional configuration could be added into the `application_system_test_case.rb` -file. +NOTE: If you followed the steps in the [Basic +Authentication](getting_started.html#adding-authentication) section, you'll need +to add authorization to every request header to get all the tests passing: -Please see [Capybara's documentation](https://github.com/teamcapybara/capybara#setup) -for additional settings. +```ruby +post articles_url, params: { article: { body: "Rails is awesome!", title: "Hello Rails" } }, headers: { Authorization: ActionController::HttpAuthentication::Basic.encode_credentials("dhh", "secret") } +``` -### Screenshot Helper +### HTTP Request Types for Functional Tests -The `ScreenshotHelper` is a helper designed to capture screenshots of your tests. -This can be helpful for viewing the browser at the point a test failed, or -to view screenshots later for debugging. +If you're familiar with the HTTP protocol, you'll know that `get` is a type of +request. There are 6 request types supported in Rails functional tests: -Two methods are provided: `take_screenshot` and `take_failed_screenshot`. -`take_failed_screenshot` is automatically included in `before_teardown` inside -Rails. +* `get` +* `post` +* `patch` +* `put` +* `head` +* `delete` -The `take_screenshot` helper method can be included anywhere in your tests to -take a screenshot of the browser. +All of the request types have equivalent methods that you can use. In a typical +CRUD application you'll be using `post`, `get`, `put`, and `delete` most +often. -### Implementing a System Test +NOTE: Functional tests do not verify whether the specified request type is +accepted by the action; instead, they focus on the result. For testing the +request type, request tests are available, making your tests more purposeful. -Now we're going to add a system test to our blog application. We'll demonstrate -writing a system test by visiting the index page and creating a new blog article. +### Testing XHR (AJAX) Requests -If you used the scaffold generator, a system test skeleton was automatically -created for you. If you didn't use the scaffold generator, start by creating a -system test skeleton. +An AJAX request (Asynchronous Javscript and XML) is a technique where content is +fetched from the server using asynchronous HTTP requests and the relevant parts +of the page are updated without requiring a full page load. -```bash -$ bin/rails generate system_test articles -``` +To test AJAX requests, you can specify the `xhr: true` option to `get`, `post`, +`patch`, `put`, and `delete` methods. For example: -It should have created a test file placeholder for us. With the output of the -previous command you should see: +```ruby +test "AJAX request" do + article = articles(:one) + get article_url(article), xhr: true + assert_equal "hello world", @response.body + assert_equal "text/javascript", @response.media_type +end ``` - invoke test_unit - create test/system/articles_test.rb + +### Testing Other Request Objects + +After any request has been made and processed, you will have 3 Hash objects +ready for use: + +* `cookies` - Any cookies that are set +* `flash` - Any objects living in the flash +* `session` - Any object living in session variables + +As is the case with normal Hash objects, you can access the values by +referencing the keys by string. You can also reference them by symbol name. For +example: + +```ruby +flash["gordon"] # or flash[:gordon] +session["shmession"] # or session[:shmession] +cookies["are_good_for_u"] # or cookies[:are_good_for_u] ``` -Now let's open that file and write our first assertion: +### Instance Variables + +You also have access to three instance variables in your functional tests after +a request is made: + +* `@controller` - The controller processing the request +* `@request` - The request object +* `@response` - The response object ```ruby -require "application_system_test_case" +class ArticlesControllerTest < ActionDispatch::IntegrationTest + test "should get index" do + get articles_url -class ArticlesTest < ApplicationSystemTestCase - test "viewing the index" do - visit articles_path - assert_selector "h1", text: "Articles" + assert_equal "index", @controller.action_name + assert_equal "application/x-www-form-urlencoded", @request.media_type + assert_match "Articles", @response.body end end ``` -The test should see that there is an `h1` on the articles index page and pass. +### Setting Headers and CGI Variables -Run the system tests. +HTTP headers are pieces of information sent along with HTTP requests to provide +important metadata. CGI variables are environment variables used to exchange +information between the web server and the application. -```bash -$ bin/rails test:system +HTTP headers and CGI variables can be tested by being passed as headers: + +```ruby +# setting an HTTP Header +get articles_url, headers: { "Content-Type": "text/plain" } # simulate the request with custom header + +# setting a CGI variable +get articles_url, headers: { "HTTP_REFERER": "http://example.com/home" } # simulate the request with custom env variable ``` -NOTE: By default, running `bin/rails test` won't run your system tests. -Make sure to run `bin/rails test:system` to actually run them. -You can also run `bin/rails test:all` to run all tests, including system tests. +### Testing `flash` Notices -#### Creating Articles System Test +As can be seen in the [testing other request objects +section](#testing-other-request-objects), one of the three hash objects that is +accessible in the tests is `flash`. This section outlines how to test the +appearance of a `flash` message in our blog application whenever someone +successfully creates a new article. -Now let's test the flow for creating a new article in our blog. +First, an assertion should be added to the `test_should_create_article` test: ```ruby -test "should create Article" do - visit articles_path +test "should create article" do + assert_difference("Article.count") do + post articles_url, params: { article: { title: "Some title" } } + end - click_on "New Article" + assert_redirected_to article_path(Article.last) + assert_equal "Article was successfully created.", flash[:notice] +end +``` - fill_in "Title", with: "Creating an Article" - fill_in "Body", with: "Created this article successfully!" +If the test is run now, it should fail: - click_on "Create Article" +```bash +$ bin/rails test test/controllers/articles_controller_test.rb -n test_should_create_article +Running 1 tests in a single process (parallelization threshold is 50) +Run options: -n test_should_create_article --seed 32266 - assert_text "Creating an Article" +# Running: + +F + +Finished in 0.114870s, 8.7055 runs/s, 34.8220 assertions/s. + + 1) Failure: +ArticlesControllerTest#test_should_create_article [/test/controllers/articles_controller_test.rb:16]: +--- expected ++++ actual +@@ -1 +1 @@ +-"Article was successfully created." ++nil + +1 runs, 4 assertions, 1 failures, 0 errors, 0 skips +``` + +Now implement the flash message in the controller. The `:create` action should +look like this: + +```ruby +def create + @article = Article.new(article_params) + + if @article.save + flash[:notice] = "Article was successfully created." + redirect_to @article + else + render "new" + end end ``` -The first step is to call `visit articles_path`. This will take the test to the -articles index page. +Now, if the tests are run they should pass: -Then the `click_on "New Article"` will find the "New Article" button on the -index page. This will redirect the browser to `/articles/new`. +```bash +$ bin/rails test test/controllers/articles_controller_test.rb -n test_should_create_article +Running 1 tests in a single process (parallelization threshold is 50) +Run options: -n test_should_create_article --seed 18981 -Then the test will fill in the title and body of the article with the specified -text. Once the fields are filled in, "Create Article" is clicked on which will -send a POST request to create the new article in the database. +# Running: -We will be redirected back to the articles index page and there we assert -that the text from the new article's title is on the articles index page. +. -#### Testing for Multiple Screen Sizes +Finished in 0.081972s, 12.1993 runs/s, 48.7972 assertions/s. -If you want to test for mobile sizes on top of testing for desktop, -you can create another class that inherits from `ActionDispatch::SystemTestCase` and use it in your -test suite. In this example a file called `mobile_system_test_case.rb` is created -in the `/test` directory with the following configuration. +1 runs, 4 assertions, 0 failures, 0 errors, 0 skips +``` + +NOTE: If you generated your controller using the scaffold generator, the flash +message will already be implemented in your `create` action. + +### Tests for `show`, `update`, and `delete` Actions + +So far in the guide tests for the `:index` as well as the`:create` action have +been outlined. What about the other actions? + +You can write a test for `:show` as follows: ```ruby -require "test_helper" +test "should show article" do + article = articles(:one) + get article_url(article) + assert_response :success +end +``` -class MobileSystemTestCase < ActionDispatch::SystemTestCase - driven_by :selenium, using: :chrome, screen_size: [375, 667] +If you remember from our discussion earlier on [fixtures](#fixtures), the +`articles()` method will provide access to the articles fixtures. + +How about deleting an existing article? + +```ruby +test "should delete article" do + article = articles(:one) + assert_difference("Article.count", -1) do + delete article_url(article) + end + + assert_redirected_to articles_path end ``` -To use this configuration, create a test inside `test/system` that inherits from `MobileSystemTestCase`. -Now you can test your app using multiple different configurations. +Here is a test for updating an existing article: ```ruby -require "mobile_system_test_case" +test "should update article" do + article = articles(:one) -class PostsTest < MobileSystemTestCase - test "visiting the index" do - visit posts_url - assert_selector "h1", text: "Posts" - end + patch article_url(article), params: { article: { title: "updated" } } + + assert_redirected_to article_path(article) + # Reload article to refresh data and assert that title is updated. + article.reload + assert_equal "updated", article.title end ``` -#### Taking It Further +Notice that there is some duplication in these three tests - they both access +the same article fixture data. It is possible to DRY ('Don't Repeat +Yourself') the implementation by using the `setup` and `teardown` methods +provided by `ActiveSupport::Callbacks`. + +The tests might look like this: + +```ruby +require "test_helper" + +class ArticlesControllerTest < ActionDispatch::IntegrationTest + # called before every single test + setup do + @article = articles(:one) + end -The beauty of system testing is that it is similar to integration testing in -that it tests the user's interaction with your controller, model, and view, but -system testing is much more robust and actually tests your application as if -a real user were using it. Going forward, you can test anything that the user -themselves would do in your application such as commenting, deleting articles, -publishing draft articles, etc. + # called after every single test + teardown do + # when controller is using cache it may be a good idea to reset it afterwards + Rails.cache.clear + end + + test "should show article" do + # Reuse the @article instance variable from setup + get article_url(@article) + assert_response :success + end + + test "should destroy article" do + assert_difference("Article.count", -1) do + delete article_url(@article) + end + + assert_redirected_to articles_path + end + + test "should update article" do + patch article_url(@article), params: { article: { title: "updated" } } + + assert_redirected_to article_path(@article) + # Reload association to fetch updated data and assert that title is updated. + @article.reload + assert_equal "updated", @article.title + end +end +``` + +NOTE: Similar to other callbacks in Rails, the `setup` and `teardown` methods +can also accept a block, lambda, or a method name as a symbol to be called. Integration Testing ------------------- -Integration tests are used to test how various parts of our application interact. They are generally used to test important workflows within our application. +Integration tests take functional controller tests one step further - they focus +on testing how several parts of an application interact, and are generally used +to test important workflows. Rails integration tests are stored in the +`test/integration` directory. -For creating Rails integration tests, we use the `test/integration` directory for our application. Rails provides a generator to create an integration test skeleton for us. +Rails provides a generator to create an integration test skeleton as follows: ```bash $ bin/rails generate integration_test user_flows - exists test/integration/ + invoke test_unit create test/integration/user_flows_test.rb ``` @@ -1160,41 +1300,33 @@ class UserFlowsTest < ActionDispatch::IntegrationTest end ``` -Here the test is inheriting from `ActionDispatch::IntegrationTest`. This makes some additional helpers available for us to use in our integration tests. - -By default, Rails will attempt to rescue from exceptions raised during tests and respond with HTML error pages. This behavior can be controlled by the [`config.action_dispatch.show_exceptions`](/configuring.html#config-action-dispatch-show-exceptions) configuration. - -### Helpers Available for Integration Tests - -In addition to the standard testing helpers, inheriting from `ActionDispatch::IntegrationTest` comes with some additional helpers available when writing integration tests. Let's get briefly introduced to the three categories of helpers we get to choose from. - -For dealing with the integration test runner, see [`ActionDispatch::Integration::Runner`](https://api.rubyonrails.org/classes/ActionDispatch/Integration/Runner.html). - -When performing requests, we will have [`ActionDispatch::Integration::RequestHelpers`](https://api.rubyonrails.org/classes/ActionDispatch/Integration/RequestHelpers.html) available for our use. - -If we need to upload files, take a look at [`ActionDispatch::TestProcess::FixtureFile`](https://api.rubyonrails.org/classes/ActionDispatch/TestProcess/FixtureFile.html) to help. - -If we need to modify the session, or state of our integration test, take a look at [`ActionDispatch::Integration::Session`](https://api.rubyonrails.org/classes/ActionDispatch/Integration/Session.html) to help. +Here the test is inheriting from +[`ActionDispatch::IntegrationTest`](https://api.rubyonrails.org/classes/ActionDispatch/IntegrationTest.html). +This makes some additional [helpers available for integration +tests](testing.html#helpers-available-for-integration-tests) alongside the +standard testing helpers. ### Implementing an Integration Test -Let's add an integration test to our blog application. We'll start with a basic workflow of creating a new blog article, to verify that everything is working properly. +Let's add an integration test to our blog application, by starting with a basic +workflow of creating a new blog article to verify that everything is working +properly. -We'll start by generating our integration test skeleton: +Start by generating the integration test skeleton: ```bash $ bin/rails generate integration_test blog_flow ``` -It should have created a test file placeholder for us. With the output of the -previous command we should see: +It should have created a test file placeholder. With the output of the previous +command you should see: ``` invoke test_unit create test/integration/blog_flow_test.rb ``` -Now let's open that file and write our first assertion: +Now open that file and write the first assertion: ```ruby require "test_helper" @@ -1202,18 +1334,23 @@ require "test_helper" class BlogFlowTest < ActionDispatch::IntegrationTest test "can see the welcome page" do get "/" - assert_select "h1", "Welcome#index" + assert_selector "h1", "Welcome#index" end end ``` -We will take a look at `assert_select` to query the resulting HTML of a request in the [Testing Views](#testing-views) section below. It is used for testing the response of our request by asserting the presence of key HTML elements and their content. +If you visit the root path, you should see `welcome/index.html.erb` rendered for +the view. So this assertion should pass. -When we visit our root path, we should see `welcome/index.html.erb` rendered for the view. So this assertion should pass. +NOTE: The assertion `assert_selector` is available in integration tests to check +the presence of key HTML elements and their content. It is similar to +`assert_dom`, which should be used when [testing views](#testing-views) as +outlined in the section below. #### Creating Articles Integration -How about testing our ability to create a new article in our blog and see the resulting article. +To test the ability to create a new article in our blog and display the +resulting article, see the example below: ```ruby test "can create an article" do @@ -1225,15 +1362,15 @@ test "can create an article" do assert_response :redirect follow_redirect! assert_response :success - assert_select "p", "Title:\n can create" + assert_dom "p", "Title:\n can create" end ``` -Let's break this test down so we can understand it. +The `:new` action of our Articles controller is called first, and the response +should be successful. -We start by calling the `:new` action on our Articles controller. This response should be successful. - -After this we make a post request to the `:create` action of our Articles controller: +Next, a `post` request is made to the `:create` action of the Articles +controller: ```ruby post "/articles", @@ -1242,378 +1379,331 @@ assert_response :redirect follow_redirect! ``` -The two lines following the request are to handle the redirect we setup when creating a new article. - -NOTE: Don't forget to call `follow_redirect!` if you plan to make subsequent requests after a redirect is made. +The two lines following the request are to handle the redirect setup when +creating a new article. -Finally we can assert that our response was successful and our new article is readable on the page. - -#### Taking It Further +NOTE: Don't forget to call `follow_redirect!` if you plan to make subsequent +requests after a redirect is made. -We were able to successfully test a very small workflow for visiting our blog and creating a new article. If we wanted to take this further we could add tests for commenting, removing articles, or editing comments. Integration tests are a great place to experiment with all kinds of use cases for our applications. +Finally it can be asserted that the response was successful and the +newly-created article is readable on the page. +A very small workflow for visiting our blog and creating a new article was +successfully tested above. To extend this, additional tests could be added for +features like adding comments, editing comments or removing articles. +Integration tests are a great place to experiment with all kinds of use cases +for our applications. -Functional Tests for Your Controllers -------------------------------------- +### Helpers Available for Integration Tests -In Rails, testing the various actions of a controller is a form of writing functional tests. Remember your controllers handle the incoming web requests to your application and eventually respond with a rendered view. When writing functional tests, you are testing how your actions handle the requests and the expected result or response, in some cases an HTML view. +There are numerous helpers to choose from for use in integration tests. Some +include: -### What to Include in Your Functional Tests +* [`ActionDispatch::Integration::Runner`](https://api.rubyonrails.org/classes/ActionDispatch/Integration/Runner.html) + for helpers relating to the integration test runner, including creating a new + session. -You should test for things such as: +* [`ActionDispatch::Integration::RequestHelpers`](https://api.rubyonrails.org/classes/ActionDispatch/Integration/RequestHelpers.html) + for performing requests. -* was the web request successful? -* was the user redirected to the right page? -* was the user successfully authenticated? -* was the appropriate message displayed to the user in the view? -* was the correct information displayed in the response? +* [`ActionDispatch::TestProcess::FixtureFile`](https://api.rubyonrails.org/classes/ActionDispatch/TestProcess/FixtureFile.html) + for uploading files. -The easiest way to see functional tests in action is to generate a controller using the scaffold generator: +* [`ActionDispatch::Integration::Session`](https://api.rubyonrails.org/classes/ActionDispatch/Integration/Session.html) + to modify sessions or the state of the integration tests. -```bash -$ bin/rails generate scaffold_controller article title:string body:text -... -create app/controllers/articles_controller.rb -... -invoke test_unit -create test/controllers/articles_controller_test.rb -... -``` +System Testing +-------------- -This will generate the controller code and tests for an `Article` resource. -You can take a look at the file `articles_controller_test.rb` in the `test/controllers` directory. +Similarly to integration testing, system testing allows you to test how the +components of your app work together, but from the point of view of a user. It +does this by running tests in either a real or a headless browser (a browser +which runs in the background without opening a visible window). System tests use +[Capybara](https://www.rubydoc.info/github/jnicklas/capybara) under the hood. -If you already have a controller and just want to generate the test scaffold code for -each of the seven default actions, you can use the following command: +Rails system tests are stored in the `test/system` directory in your +application. To generate a system test skeleton, run the following command: ```bash -$ bin/rails generate test_unit:scaffold article -... -invoke test_unit -create test/controllers/articles_controller_test.rb -... +$ bin/rails generate system_test users + invoke test_unit + create test/system/users_test.rb ``` -Let's take a look at one such test, `test_should_get_index` from the file `articles_controller_test.rb`. +Here's what a freshly generated system test looks like: ```ruby -# articles_controller_test.rb -class ArticlesControllerTest < ActionDispatch::IntegrationTest - test "should get index" do - get articles_url - assert_response :success - end +require "application_system_test_case" + +class UsersTest < ApplicationSystemTestCase + # test "visiting the index" do + # visit users_url + # + # assert_selector "h1", text: "Users" + # end end ``` -In the `test_should_get_index` test, Rails simulates a request on the action called `index`, making sure the request was successful -and also ensuring that the right response body has been generated. - -The `get` method kicks off the web request and populates the results into the `@response`. It can accept up to 6 arguments: - -* The URI of the controller action you are requesting. - This can be in the form of a string or a route helper (e.g. `articles_url`). -* `params`: option with a hash of request parameters to pass into the action - (e.g. query string parameters or article variables). -* `headers`: for setting the headers that will be passed with the request. -* `env`: for customizing the request environment as needed. -* `xhr`: whether the request is Ajax request or not. Can be set to true for marking the request as Ajax. -* `as`: for encoding the request with different content type. +By default, system tests are run with the Selenium driver, using the Chrome +browser, and a screen size of 1400x1400. The next section explains how to change +the default settings. -All of these keyword arguments are optional. +### Changing the Default Settings -Example: Calling the `:show` action for the first `Article`, passing in an `HTTP_REFERER` header: +Rails makes changing the default settings for system tests very simple. All the +setup is abstracted away so you can focus on writing your tests. -```ruby -get article_url(Article.first), headers: { "HTTP_REFERER" => "http://example.com/home" } -``` +When you generate a new application or scaffold, an +`application_system_test_case.rb` file is created in the test directory. This is +where all the configuration for your system tests should live. -Another example: Calling the `:update` action for the last `Article`, passing in new text for the `title` in `params`, as an Ajax request: +If you want to change the default settings, you can change what the system tests +are "driven by". If you want to change the driver from Selenium to Cuprite, +you'd add the [`cuprite`](https://github.com/rubycdp/cuprite) gem to your +`Gemfile`. Then in your `application_system_test_case.rb` file you'd do the +following: ```ruby -patch article_url(Article.last), params: { article: { title: "updated" } }, xhr: true -``` - -One more example: Calling the `:create` action to create a new article, passing in -text for the `title` in `params`, as JSON request: +require "test_helper" +require "capybara/cuprite" -```ruby -post articles_path, params: { article: { title: "Ahoy!" } }, as: :json +class ApplicationSystemTestCase < ActionDispatch::SystemTestCase + driven_by :cuprite +end ``` -NOTE: If you try running `test_should_create_article` test from `articles_controller_test.rb` it will fail on account of the newly added model level validation and rightly so. - -Let us modify `test_should_create_article` test in `articles_controller_test.rb` so that all our test pass: +The driver name is a required argument for `driven_by`. The optional arguments +that can be passed to `driven_by` are `:using` for the browser (this will only +be used by Selenium), `:screen_size` to change the size of the screen for +screenshots, and `:options` which can be used to set options supported by the +driver. ```ruby -test "should create article" do - assert_difference("Article.count") do - post articles_url, params: { article: { body: "Rails is awesome!", title: "Hello Rails" } } - end +require "test_helper" - assert_redirected_to article_path(Article.last) +class ApplicationSystemTestCase < ActionDispatch::SystemTestCase + driven_by :selenium, using: :firefox end ``` -Now you can try running all the tests and they should pass. - -NOTE: If you followed the steps in the [Basic Authentication](getting_started.html#basic-authentication) section, you'll need to add authorization to every request header to get all the tests passing: - -```ruby -post articles_url, params: { article: { body: "Rails is awesome!", title: "Hello Rails" } }, headers: { Authorization: ActionController::HttpAuthentication::Basic.encode_credentials("dhh", "secret") } -``` - -By default, Rails will attempt to rescue from exceptions raised during tests and respond with HTML error pages. This behavior can be controlled by the [`config.action_dispatch.show_exceptions`](/configuring.html#config-action-dispatch-show-exceptions) configuration. - -### Available Request Types for Functional Tests - -If you're familiar with the HTTP protocol, you'll know that `get` is a type of request. There are 6 request types supported in Rails functional tests: - -* `get` -* `post` -* `patch` -* `put` -* `head` -* `delete` - -All of request types have equivalent methods that you can use. In a typical C.R.U.D. application you'll be using `get`, `post`, `put`, and `delete` more often. - -NOTE: Functional tests do not verify whether the specified request type is accepted by the action, we're more concerned with the result. Request tests exist for this use case to make your tests more purposeful. - -### Testing XHR (Ajax) Requests - -To test Ajax requests, you can specify the `xhr: true` option to `get`, `post`, -`patch`, `put`, and `delete` methods. For example: +If you want to use a headless browser, you could use Headless Chrome or Headless +Firefox by adding `headless_chrome` or `headless_firefox` in the `:using` +argument. ```ruby -test "ajax request" do - article = articles(:one) - get article_url(article), xhr: true +require "test_helper" - assert_equal "hello world", @response.body - assert_equal "text/javascript", @response.media_type +class ApplicationSystemTestCase < ActionDispatch::SystemTestCase + driven_by :selenium, using: :headless_chrome end ``` -### The Three Hashketeers! - -After a request has been made and processed, you will have 3 Hash objects ready for use: - -* `cookies` - Any cookies that are set -* `flash` - Any objects living in the flash -* `session` - Any object living in session variables - -As is the case with normal Hash objects, you can access the values by referencing the keys by string. You can also reference them by symbol name. For example: - -```ruby -flash["gordon"] # or flash[:gordon] -session["shmession"] # or session[:shmession] -cookies["are_good_for_u"] # or cookies[:are_good_for_u] -``` - -### Instance Variables Available - -**After** a request is made, you also have access to three instance variables in your functional tests: - -* `@controller` - The controller processing the request -* `@request` - The request object -* `@response` - The response object - +If you want to use a remote browser, e.g. [Headless Chrome in +Docker](https://github.com/SeleniumHQ/docker-selenium), you have to add a remote +`url` and set `browser` as remote through `options`. ```ruby -class ArticlesControllerTest < ActionDispatch::IntegrationTest - test "should get index" do - get articles_url +require "test_helper" - assert_equal "index", @controller.action_name - assert_equal "application/x-www-form-urlencoded", @request.media_type - assert_match "Articles", @response.body +class ApplicationSystemTestCase < ActionDispatch::SystemTestCase + url = ENV.fetch("SELENIUM_REMOTE_URL", nil) + options = if url + { browser: :remote, url: url } + else + { browser: :chrome } end + driven_by :selenium, using: :headless_chrome, options: options end ``` -### Setting Headers and CGI Variables - -[HTTP headers](https://datatracker.ietf.org/doc/html/rfc2616#section-5.3) -and -[CGI variables](https://datatracker.ietf.org/doc/html/rfc3875#section-4.1) -can be passed as headers: - -```ruby -# setting an HTTP Header -get articles_url, headers: { "Content-Type": "text/plain" } # simulate the request with custom header +Now you should get a connection to the remote browser. -# setting a CGI variable -get articles_url, headers: { "HTTP_REFERER": "http://example.com/home" } # simulate the request with custom env variable +```bash +$ SELENIUM_REMOTE_URL=http://localhost:4444/wd/hub bin/rails test:system ``` -### Testing `flash` Notices - -If you remember from earlier, one of the Three Hashketeers was `flash`. - -We want to add a `flash` message to our blog application whenever someone -successfully creates a new Article. - -Let's start by adding this assertion to our `test_should_create_article` test: +If your application is remote, e.g. within a Docker container, Capybara needs +more input about how to [call remote +servers](https://github.com/teamcapybara/capybara#calling-remote-servers). ```ruby -test "should create article" do - assert_difference("Article.count") do - post articles_url, params: { article: { title: "Some title" } } - end +require "test_helper" - assert_redirected_to article_path(Article.last) - assert_equal "Article was successfully created.", flash[:notice] +class ApplicationSystemTestCase < ActionDispatch::SystemTestCase + setup do + Capybara.server_host = "0.0.0.0" # bind to all interfaces + Capybara.app_host = "http://#{IPSocket.getaddress(Socket.gethostname)}" if ENV["SELENIUM_REMOTE_URL"].present? + end + # ... end ``` -If we run our test now, we should see a failure: +Now you should get a connection to a remote browser and server, regardless if it +is running in a Docker container or CI. -```bash -$ bin/rails test test/controllers/articles_controller_test.rb -n test_should_create_article -Run options: -n test_should_create_article --seed 32266 +If your Capybara configuration requires more setup than provided by Rails, this +additional configuration can be added into the `application_system_test_case.rb` +file. -# Running: +Please see [Capybara's +documentation](https://github.com/teamcapybara/capybara#setup) for additional +settings. -F +### Implementing a System Test -Finished in 0.114870s, 8.7055 runs/s, 34.8220 assertions/s. +This section will demonstrate how to add a system test to your application, +which tests a visit to the index page to create a new blog article. - 1) Failure: -ArticlesControllerTest#test_should_create_article [/test/controllers/articles_controller_test.rb:16]: ---- expected -+++ actual -@@ -1 +1 @@ --"Article was successfully created." -+nil +If you used the scaffold generator, a system test skeleton was automatically +created for you. If you didn't use the scaffold generator, start by creating a +system test skeleton. -1 runs, 4 assertions, 1 failures, 0 errors, 0 skips +```bash +$ bin/rails generate system_test articles +``` + +It should have created a test file placeholder. With the output of the previous +command you should see: + +``` + invoke test_unit + create test/system/articles_test.rb ``` -Let's implement the flash message now in our controller. Our `:create` action should now look like this: +Now, let's open that file and write the first assertion: ```ruby -def create - @article = Article.new(article_params) +require "application_system_test_case" - if @article.save - flash[:notice] = "Article was successfully created." - redirect_to @article - else - render "new" +class ArticlesTest < ApplicationSystemTestCase + test "viewing the index" do + visit articles_path + assert_selector "h1", text: "Articles" end end ``` -Now if we run our tests, we should see it pass: +The test should see that there is an `h1` on the articles index page and pass. + +Run the system tests. ```bash -$ bin/rails test test/controllers/articles_controller_test.rb -n test_should_create_article -Run options: -n test_should_create_article --seed 18981 +$ bin/rails test:system +``` -# Running: +NOTE: By default, running `bin/rails test` won't run your system tests. Make +sure to run `bin/rails test:system` to actually run them. You can also run +`bin/rails test:all` to run all tests, including system tests. -. +#### Creating Articles System Test -Finished in 0.081972s, 12.1993 runs/s, 48.7972 assertions/s. +Now you can test the flow for creating a new article. -1 runs, 4 assertions, 0 failures, 0 errors, 0 skips -``` +```ruby +test "should create Article" do + visit articles_path -### Putting It Together + click_on "New Article" -At this point our Articles controller tests the `:index` as well as `:new` and `:create` actions. What about dealing with existing data? + fill_in "Title", with: "Creating an Article" + fill_in "Body", with: "Created this article successfully!" -Let's write a test for the `:show` action: + click_on "Create Article" -```ruby -test "should show article" do - article = articles(:one) - get article_url(article) - assert_response :success + assert_text "Creating an Article" end ``` -Remember from our discussion earlier on fixtures, the `articles()` method will give us access to our Articles fixtures. +The first step is to call `visit articles_path`. This will take the test to the +articles index page. + +Then the `click_on "New Article"` will find the "New Article" button on the +index page. This will redirect the browser to `/articles/new`. + +Then the test will fill in the title and body of the article with the specified +text. Once the fields are filled in, "Create Article" is clicked on which will +send a POST request to `/articles/create`. + +This redirects the user back to the articles index page, and there it is +asserted that the text from the new article's title is on the articles index +page. + +#### Testing for Multiple Screen Sizes -How about deleting an existing Article? +If you want to test for mobile sizes in addition to testing for desktop, you can +create another class that inherits from `ActionDispatch::SystemTestCase` and use +it in your test suite. In this example, a file called +`mobile_system_test_case.rb` is created in the `/test` directory with the +following configuration. ```ruby -test "should destroy article" do - article = articles(:one) - assert_difference("Article.count", -1) do - delete article_url(article) - end +require "test_helper" - assert_redirected_to articles_path +class MobileSystemTestCase < ActionDispatch::SystemTestCase + driven_by :selenium, using: :chrome, screen_size: [375, 667] end ``` -We can also add a test for updating an existing Article. +To use this configuration, create a test inside `test/system` that inherits from +`MobileSystemTestCase`. Now you can test your app using multiple different +configurations. ```ruby -test "should update article" do - article = articles(:one) - - patch article_url(article), params: { article: { title: "updated" } } +require "mobile_system_test_case" - assert_redirected_to article_path(article) - # Reload association to fetch updated data and assert that title is updated. - article.reload - assert_equal "updated", article.title +class PostsTest < MobileSystemTestCase + test "visiting the index" do + visit posts_url + assert_selector "h1", text: "Posts" + end end ``` -Notice we're starting to see some duplication in these three tests, they both access the same Article fixture data. We can D.R.Y. this up by using the `setup` and `teardown` methods provided by `ActiveSupport::Callbacks`. +#### Capybara Assertions -Our test should now look something as what follows. Disregard the other tests for now, we're leaving them out for brevity. - -```ruby -require "test_helper" +Here's an extract of the assertions provided by +[`Capybara`](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Minitest/Assertions) +which can be used in system tests. -class ArticlesControllerTest < ActionDispatch::IntegrationTest - # called before every single test - setup do - @article = articles(:one) - end +| Assertion | Purpose | +| ---------------------------------------------------------------- | ------- | +| `assert_button(locator = nil, **options, &optional_filter_block)`| Checks if the page has a button with the given text, value or id. | +| `assert_current_path(string, **options)` | Asserts that the page has the given path. | +| `assert_field(locator = nil, **options, &optional_filter_block)` | Checks if the page has a form field with the given label, name or id. | +| `assert_link(locator = nil, **options, &optional_filter_block)` | Checks if the page has a link with the given text or id. | +| `assert_selector(*args, &optional_filter_block)` | Asserts that a given selector is on the page. | +| `assert_table(locator = nil, **options, &optional_filter_block` | Checks if the page has a table with the given id or caption. | +| `assert_text(type, text, **options)` | Asserts that the page has the given text content. | - # called after every single test - teardown do - # when controller is using cache it may be a good idea to reset it afterwards - Rails.cache.clear - end - test "should show article" do - # Reuse the @article instance variable from setup - get article_url(@article) - assert_response :success - end +#### Screenshot Helper - test "should destroy article" do - assert_difference("Article.count", -1) do - delete article_url(@article) - end +The +[`ScreenshotHelper`](https://api.rubyonrails.org/v5.1.7/classes/ActionDispatch/SystemTesting/TestHelpers/ScreenshotHelper.html) +is a helper designed to capture screenshots of your tests. This can be helpful +for viewing the browser at the point a test failed, or to view screenshots later +for debugging. - assert_redirected_to articles_path - end +Two methods are provided: `take_screenshot` and `take_failed_screenshot`. +`take_failed_screenshot` is automatically included in `before_teardown` inside +Rails. - test "should update article" do - patch article_url(@article), params: { article: { title: "updated" } } +The `take_screenshot` helper method can be included anywhere in your tests to +take a screenshot of the browser. - assert_redirected_to article_path(@article) - # Reload association to fetch updated data and assert that title is updated. - @article.reload - assert_equal "updated", @article.title - end -end -``` +#### Taking It Further -Similar to other callbacks in Rails, the `setup` and `teardown` methods can also be used by passing a block, lambda, or method name as a symbol to call. +System testing is similar to [integration testing](#integration-testing) in that +it tests the user's interaction with your controller, model, and view, but +system testing tests your application as if a real user were using it. With +system tests, you can test anything that a user would do in your application +such as commenting, deleting articles, publishing draft articles, etc. -### Test Helpers +Test Helpers +------------ -To avoid code duplication, you can add your own test helpers. -Sign in helper can be a good example: +To avoid code duplication, you can add your own test helpers. Here is an example +for signing in: ```ruby # test/test_helper.rb @@ -1643,10 +1733,11 @@ class ProfileControllerTest < ActionDispatch::IntegrationTest end ``` -#### Using Separate Files +### Using Separate Files -If you find your helpers are cluttering `test_helper.rb`, you can extract them into separate files. -One good place to store them is `test/lib` or `test/test_helpers`. +If you find your helpers are cluttering `test_helper.rb`, you can extract them +into separate files. A good place to store them is `test/lib` or +`test/test_helpers`. ```ruby # test/test_helpers/multiple_assertions.rb @@ -1657,7 +1748,7 @@ module MultipleAssertions end ``` -These helpers can then be explicitly required as needed and included as needed +These helpers can then be explicitly required and included as needed: ```ruby require "test_helper" @@ -1666,13 +1757,13 @@ require "test_helpers/multiple_assertions" class NumberTest < ActiveSupport::TestCase include MultipleAssertions - test "420 is a multiple of forty two" do + test "420 is a multiple of 42" do assert_multiple_of_forty_two 420 end end ``` -or they can continue to be included directly into the relevant parent classes +They can also continue to be included directly into the relevant parent classes: ```ruby # test/test_helper.rb @@ -1683,123 +1774,91 @@ class ActionDispatch::IntegrationTest end ``` -#### Eagerly Requiring Helpers +### Eagerly Requiring Helpers -You may find it convenient to eagerly require helpers in `test_helper.rb` so your test files have implicit access to them. This can be accomplished using globbing, as follows +You may find it convenient to eagerly require helpers in `test_helper.rb` so +your test files have implicit access to them. This can be accomplished using +globbing, as follows ```ruby # test/test_helper.rb Dir[Rails.root.join("test", "test_helpers", "**", "*.rb")].each { |file| require file } ``` -This has the downside of increasing the boot-up time, as opposed to manually requiring only the necessary files in your individual tests. +This has the downside of increasing the boot-up time, as opposed to manually +requiring only the necessary files in your individual tests. Testing Routes -------------- -Like everything else in your Rails application, you can test your routes. Route tests reside in `test/controllers/` or are part of controller tests. +Like everything else in your Rails application, you can test your routes. Route +tests are stored in `test/controllers/` or are part of controller tests. If your +application has complex routes, Rails provides a number of useful helpers to +test them. -NOTE: If your application has complex routes, Rails provides a number of useful helpers to test them. - -For more information on routing assertions available in Rails, see the API documentation for [`ActionDispatch::Assertions::RoutingAssertions`](https://api.rubyonrails.org/classes/ActionDispatch/Assertions/RoutingAssertions.html). +For more information on routing assertions available in Rails, see the API +documentation for +[`ActionDispatch::Assertions::RoutingAssertions`](https://api.rubyonrails.org/classes/ActionDispatch/Assertions/RoutingAssertions.html). Testing Views ------------- -Testing the response to your request by asserting the presence of key HTML elements and their content is a common way to test the views of your application. Like route tests, view tests reside in `test/controllers/` or are part of controller tests. The `assert_select` method allows you to query HTML elements of the response by using a simple yet powerful syntax. - -There are two forms of `assert_select`: +Testing the response to your request by asserting the presence of key HTML +elements and their content is one way to test the views of your application. +Like route tests, view tests are stored in `test/controllers/` or are part of +controller tests. -`assert_select(selector, [equality], [message])` ensures that the equality condition is met on the selected elements through the selector. The selector may be a CSS selector expression (String) or an expression with substitution values. +### Querying the HTML -`assert_select(element, selector, [equality], [message])` ensures that the equality condition is met on all the selected elements through the selector starting from the _element_ (instance of `Nokogiri::XML::Node` or `Nokogiri::XML::NodeSet`) and its descendants. +Methods like `assert_dom` and `assert_dom_equal` allow you to query HTML +elements of the response by using a simple yet powerful syntax. -For example, you could verify the contents on the title element in your response with: +`assert_dom` is an assertion that will return true if matching elements are +found. For example, you could verify that the page title is "Welcome to the +Rails Testing Guide" as follows: ```ruby -assert_select "title", "Welcome to Rails Testing Guide" +assert_dom "title", "Welcome to the Rails Testing Guide" ``` -You can also use nested `assert_select` blocks for deeper investigation. +You can also use nested `assert_dom` blocks for deeper investigation. -In the following example, the inner `assert_select` for `li.menu_item` runs -within the collection of elements selected by the outer block: +In the following example, the inner `assert_dom` for `li.menu_item` runs within +the collection of elements selected by the outer block: ```ruby -assert_select "ul.navigation" do - assert_select "li.menu_item" +assert_dom "ul.navigation" do + assert_dom "li.menu_item" end ``` -A collection of selected elements may be iterated through so that `assert_select` may be called separately for each element. - -For example if the response contains two ordered lists, each with four nested list elements then the following tests will both pass. +A collection of selected elements may also be iterated through so that +`assert_dom` may be called separately for each element. For example, if the +response contains two ordered lists, each with four nested list elements then +the following tests will both pass. ```ruby -assert_select "ol" do |elements| +assert_dom "ol" do |elements| elements.each do |element| - assert_select element, "li", 4 + assert_dom element, "li", 4 end end -assert_select "ol" do - assert_select "li", 8 -end -``` - -This assertion is quite powerful. For more advanced usage, refer to its [documentation](https://github.com/rails/rails-dom-testing/blob/main/lib/rails/dom/testing/assertions/selector_assertions.rb). - -### Additional View-Based Assertions - -There are more assertions that are primarily used in testing views: - -| Assertion | Purpose | -| --------------------------------------------------------- | ------- | -| `assert_select_email` | Allows you to make assertions on the body of an e-mail. | -| `assert_select_encoded` | Allows you to make assertions on encoded HTML. It does this by un-encoding the contents of each element and then calling the block with all the un-encoded elements.| -| `css_select(selector)` or `css_select(element, selector)` | Returns an array of all the elements selected by the _selector_. In the second variant it first matches the base _element_ and tries to match the _selector_ expression on any of its children. If there are no matches both variants return an empty array.| - -Here's an example of using `assert_select_email`: - -```ruby -assert_select_email do - assert_select "small", "Please click the 'Unsubscribe' link if you want to opt-out." +assert_dom "ol" do + assert_dom "li", 8 end ``` -Testing View Partials ---------------------- - -Partial templates - usually called "partials" - are another device for breaking the rendering process into more manageable chunks. With partials, you can extract pieces of code from your templates to separate files and reuse them throughout your templates. - -View tests provide an opportunity to test that partials render content the way you expect. View partial tests reside in `test/views/` and inherit from `ActionView::TestCase`. - -To render a partial, call `render` like you would in a template. The content is -available through the test-local `#rendered` method: +The `assert_dom_equal` method compares two HTML strings to see if they are +equal: ```ruby -class ArticlePartialTest < ActionView::TestCase - test "renders a link to itself" do - article = Article.create! title: "Hello, world" - - render "articles/article", article: article - - assert_includes rendered, article.title - end -end +assert_dom_equal 'Read more', + link_to("Read more", "http://www.further-reading.com") ``` -Tests that inherit from `ActionView::TestCase` also have access to [`assert_select`](#testing-views) and the [other additional view-based assertions](#additional-view-based-assertions) provided by [rails-dom-testing][]: - -```ruby -test "renders a link to itself" do - article = Article.create! title: "Hello, world" - - render "articles/article", article: article - - assert_select "a[href=?]", article_url(article), text: article.title -end -``` +For more advanced usage, refer to the [`rails-dom-testing` +documentation](https://github.com/rails/rails-dom-testing). In order to integrate with [rails-dom-testing][], tests that inherit from `ActionView::TestCase` declare a `document_root_element` method that returns the @@ -1818,9 +1877,12 @@ test "renders a link to itself" do end ``` -If your application uses Ruby >= 3.0 or higher, depends on [Nokogiri >= 1.14.0](https://github.com/sparklemotion/nokogiri/releases/tag/v1.14.0) or -higher, and depends on [Minitest >= >5.18.0](https://github.com/minitest/minitest/blob/v5.18.0/History.rdoc#5180--2023-03-04-), -`document_root_element` supports [Ruby's Pattern Matching](https://docs.ruby-lang.org/en/master/syntax/pattern_matching_rdoc.html): +If your application depends on [Nokogiri >= +1.14.0](https://github.com/sparklemotion/nokogiri/releases/tag/v1.14.0) or +higher, and [minitest >= +5.18.0](https://github.com/minitest/minitest/blob/v5.18.0/History.rdoc#5180--2023-03-04-), +`document_root_element` supports [Ruby's Pattern +Matching](https://docs.ruby-lang.org/en/master/syntax/pattern_matching_rdoc.html): ```ruby test "renders a link to itself" do @@ -1836,10 +1898,11 @@ test "renders a link to itself" do end ``` -If you'd like to access the same [Capybara-powered Assertions](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Minitest/Assertions) -that your [Functional and System Testing](#functional-and-system-testing) tests -utilize, you can define a base class that inherits from `ActionView::TestCase` -and transforms the `document_root_element` into a `page` method: +If you'd like to access the same [Capybara-powered +Assertions](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Minitest/Assertions) +that your [System Testing](#system-testing) tests utilize, you can define a base +class that inherits from `ActionView::TestCase` and transforms the +`document_root_element` into a `page` method: ```ruby # test/view_partial_test_case.rb @@ -1870,14 +1933,20 @@ class ArticlePartialTest < ViewPartialTestCase end ``` -Starting in Action View version 7.1, the `#rendered` helper method returns an +More information about the assertions included by Capybara can be found in the +[Capybara Assertions](#capybara-assertions) section. + +### Parsing View Content + +Starting in Action View version 7.1, the `rendered` helper method returns an object capable of parsing the view partial's rendered content. -To transform the `String` content returned by the `#rendered` method into an -object, define a parser by calling `.register_parser`. Calling -`.register_parser :rss` defines a `#rendered.rss` helper method. For example, -to parse rendered [RSS content][] into an object with `#rendered.rss`, register -a call to `RSS::Parser.parse`: +To transform the `String` content returned by the `rendered` method into an +object, define a parser by calling +[`register_parser`](https://apidock.com/rails/v7.1.3.4/ActionView/TestCase/Behavior/ClassMethods/register_parser). +Calling `register_parser :rss` defines a `rendered.rss` helper method. For +example, to parse rendered [RSS content][] into an object with `rendered.rss`, +register a call to `RSS::Parser.parse`: ```ruby register_parser :rss, -> rendered { RSS::Parser.parse(rendered) } @@ -1893,8 +1962,10 @@ end By default, `ActionView::TestCase` defines a parser for: -* `:html` - returns an instance of [Nokogiri::XML::Node](https://nokogiri.org/rdoc/Nokogiri/XML/Node.html) -* `:json` - returns an instance of [ActiveSupport::HashWithIndifferentAccess](https://api.rubyonrails.org/classes/ActiveSupport/HashWithIndifferentAccess.html) +* `:html` - returns an instance of + [Nokogiri::XML::Node](https://nokogiri.org/rdoc/Nokogiri/XML/Node.html) +* `:json` - returns an instance of + [ActiveSupport::HashWithIndifferentAccess](https://api.rubyonrails.org/classes/ActiveSupport/HashWithIndifferentAccess.html) ```ruby test "renders HTML" do @@ -1917,11 +1988,69 @@ end [rails-dom-testing]: https://github.com/rails/rails-dom-testing [RSS content]: https://www.rssboard.org/rss-specification -Testing Helpers ---------------- +### Additional View-Based Assertions + +There are more assertions that are primarily used in testing views: + +| Assertion | Purpose | +| --------------------------------------------------------- | ------- | +| `assert_dom_email` | Allows you to make assertions on the body of an e-mail. | +| `assert_dom_encoded` | Allows you to make assertions on encoded HTML. It does this by un-encoding the contents of each element and then calling the block with all the un-encoded elements.| +| `css_select(selector)` or `css_select(element, selector)` | Returns an array of all the elements selected by the _selector_. In the second variant it first matches the base _element_ and tries to match the _selector_ expression on any of its children. If there are no matches both variants return an empty array.| + +Here's an example of using `assert_dom_email`: + +```ruby +assert_dom_email do + assert_dom "small", "Please click the 'Unsubscribe' link if you want to opt-out." +end +``` + +### Testing View Partials + +[Partial](layouts_and_rendering.html#using-partials) templates - usually called +"partials" - can break the rendering process into more manageable chunks. With +partials, you can extract sections of code from your views to separate files and +reuse them in multiple places. + +View tests provide an opportunity to test that partials render content the way +you expect. View partial tests can be stored in `test/views/` and inherit from +`ActionView::TestCase`. + +To render a partial, call `render` like you would in a template. The content is +available through the test-local `rendered` method: + +```ruby +class ArticlePartialTest < ActionView::TestCase + test "renders a link to itself" do + article = Article.create! title: "Hello, world" + + render "articles/article", article: article + + assert_includes rendered, article.title + end +end +``` -A helper is just a simple module where you can define methods which are -available in your views. +Tests that inherit from `ActionView::TestCase` also have access to +[`assert_dom`](#testing-views) and the [other additional view-based +assertions](#additional-view-based-assertions) provided by +[rails-dom-testing][]: + +```ruby +test "renders a link to itself" do + article = Article.create! title: "Hello, world" + + render "articles/article", article: article + + assert_dom "a[href=?]", article_url(article), text: article.title +end +``` + +### Testing View Helpers + +A helper is a module where you can define methods which are available in your +views. In order to test helpers, all you need to do is check that the output of the helper method matches what you'd expect. Tests related to the helpers are @@ -1952,14 +2081,11 @@ end Moreover, since the test class extends from `ActionView::TestCase`, you have access to Rails' helper methods such as `link_to` or `pluralize`. -Testing Your Mailers --------------------- - -Testing mailer classes requires some specific tools to do a thorough job. - -### Keeping the Postman in Check +Testing Mailers +--------------- -Your mailer classes - like every other part of your Rails application - should be tested to ensure that they are working as expected. +Your mailer classes - like every other part of your Rails application - should +be tested to ensure that they are working as expected. The goals of testing your mailer classes are to ensure that: @@ -1967,23 +2093,38 @@ The goals of testing your mailer classes are to ensure that: * the email content is correct (subject, sender, body, etc) * the right emails are being sent at the right times -#### From All Sides - -There are two aspects of testing your mailer, the unit tests and the functional tests. In the unit tests, you run the mailer in isolation with tightly controlled inputs and compare the output to a known value (a fixture). In the functional tests you don't so much test the minute details produced by the mailer; instead, we test that our controllers and models are using the mailer in the right way. You test to prove that the right email was sent at the right time. +There are two aspects of testing your mailer, the unit tests and the functional +tests. In the unit tests, you run the mailer in isolation with tightly +controlled inputs and compare the output to a known value (a +[fixture](#fixtures)). In the functional tests you don't so much test the +details produced by the mailer; instead, you test that the controllers and +models are using the mailer in the right way. You test to prove that the right +email was sent at the right time. ### Unit Testing -In order to test that your mailer is working as expected, you can use unit tests to compare the actual results of the mailer with pre-written examples of what should be produced. +In order to test that your mailer is working as expected, you can use unit tests +to compare the actual results of the mailer with pre-written examples of what +should be produced. -#### Revenge of the Fixtures +#### Mailer Fixtures -For the purposes of unit testing a mailer, fixtures are used to provide an example of how the output _should_ look. Because these are example emails, and not Active Record data like the other fixtures, they are kept in their own subdirectory apart from the other fixtures. The name of the directory within `test/fixtures` directly corresponds to the name of the mailer. So, for a mailer named `UserMailer`, the fixtures should reside in `test/fixtures/user_mailer` directory. +For the purposes of unit testing a mailer, fixtures are used to provide an +example of how the output _should_ look. Because these are example emails, and +not Active Record data like the other fixtures, they are kept in their own +subdirectory apart from the other fixtures. The name of the directory within +`test/fixtures` directly corresponds to the name of the mailer. So, for a mailer +named `UserMailer`, the fixtures should reside in `test/fixtures/user_mailer` +directory. -If you generated your mailer, the generator does not create stub fixtures for the mailers actions. You'll have to create those files yourself as described above. +If you generated your mailer, the generator does not create stub fixtures for +the mailers actions. You'll have to create those files yourself as described +above. #### The Basic Test Case -Here's a unit test to test a mailer named `UserMailer` whose action `invite` is used to send an invitation to a friend. It is an adapted version of the base test created by the generator for an `invite` action. +Here's a unit test to test a mailer named `UserMailer` whose action `invite` is +used to send an invitation to a friend: ```ruby require "test_helper" @@ -2008,9 +2149,14 @@ class UserMailerTest < ActionMailer::TestCase end ``` -In the test we create the email and store the returned object in the `email` variable. We then ensure that it was sent (the first assert), then, in the second batch of assertions, we ensure that the email does indeed contain what we expect. The helper `read_fixture` is used to read in the content from this file. +In the test the email is created and the returned object is stored in the +`email` variable. The first assert checks it was sent, then, in the second batch +of assertions, the email contents are checked. The helper `read_fixture` is used +to read in the content from this file. -NOTE: `email.body.to_s` is present when there's only one (HTML or text) part present. If the mailer provides both, you can test your fixture against specific parts with `email.text_part.body.to_s` or `email.html_part.body.to_s`. +NOTE: `email.body.to_s` is present when there's only one (HTML or text) part +present. If the mailer provides both, you can test your fixture against specific +parts with `email.text_part.body.to_s` or `email.html_part.body.to_s`. Here's the content of the `invite` fixture: @@ -2022,17 +2168,32 @@ You have been invited. Cheers! ``` -This is the right time to understand a little more about writing tests for your mailers. The line `ActionMailer::Base.delivery_method = :test` in `config/environments/test.rb` sets the delivery method to test mode so that email will not actually be delivered (useful to avoid spamming your users while testing) but instead it will be appended to an array (`ActionMailer::Base.deliveries`). +#### Configuring the Delivery Method for Test -NOTE: The `ActionMailer::Base.deliveries` array is only reset automatically in `ActionMailer::TestCase` and `ActionDispatch::IntegrationTest` tests. If you want to have a clean slate outside these test cases, you can reset it manually with: `ActionMailer::Base.deliveries.clear` +The line `ActionMailer::Base.delivery_method = :test` in +`config/environments/test.rb` sets the delivery method to test mode so that the +email will not actually be delivered (useful to avoid spamming your users while +testing). Instead, the email will be appended to an array +(`ActionMailer::Base.deliveries`). + +NOTE: The `ActionMailer::Base.deliveries` array is only reset automatically in +`ActionMailer::TestCase` and `ActionDispatch::IntegrationTest` tests. If you +want to have a clean slate outside these test cases, you can reset it manually +with: `ActionMailer::Base.deliveries.clear` #### Testing Enqueued Emails -You can use the `assert_enqueued_email_with` assertion to confirm that the email has been enqueued with all of the expected mailer method arguments and/or parameterized mailer parameters. This allows you to match any email that have been enqueued with the `deliver_later` method. +You can use the `assert_enqueued_email_with` assertion to confirm that the email +has been enqueued with all of the expected mailer method arguments and/or +parameterized mailer parameters. This allows you to match any emails that have +been enqueued with the `deliver_later` method. -As with the basic test case, we create the email and store the returned object in the `email` variable. The following examples include variations of passing arguments and/or parameters. +As with the basic test case, we create the email and store the returned object +in the `email` variable. The following examples include variations of passing +arguments and/or parameters. -This example will assert that the email has been enqueued with the correct arguments: +This example will assert that the email has been enqueued with the correct +arguments: ```ruby require "test_helper" @@ -2050,7 +2211,8 @@ class UserMailerTest < ActionMailer::TestCase end ``` -This example will assert that a mailer has been enqueued with the correct mailer method named arguments by passing a hash of the arguments as `args`: +This example will assert that a mailer has been enqueued with the correct mailer +method named arguments by passing a hash of the arguments as `args`: ```ruby require "test_helper" @@ -2061,15 +2223,17 @@ class UserMailerTest < ActionMailer::TestCase email = UserMailer.create_invite(from: "me@example.com", to: "friend@example.com") # Test that the email got enqueued with the correct named arguments - assert_enqueued_email_with UserMailer, :create_invite, args: [{ from: "me@example.com", - to: "friend@example.com" }] do + assert_enqueued_email_with UserMailer, :create_invite, + args: [{ from: "me@example.com", to: "friend@example.com" }] do email.deliver_later end end end ``` -This example will assert that a parameterized mailer has been enqueued with the correct parameters and arguments. The mailer parameters are passed as `params` and the mailer method arguments as `args`: +This example will assert that a parameterized mailer has been enqueued with the +correct parameters and arguments. The mailer parameters are passed as `params` +and the mailer method arguments as `args`: ```ruby require "test_helper" @@ -2080,15 +2244,16 @@ class UserMailerTest < ActionMailer::TestCase email = UserMailer.with(all: "good").create_invite("me@example.com", "friend@example.com") # Test that the email got enqueued with the correct mailer parameters and arguments - assert_enqueued_email_with UserMailer, :create_invite, params: { all: "good" }, - args: ["me@example.com", "friend@example.com"] do + assert_enqueued_email_with UserMailer, :create_invite, + params: { all: "good" }, args: ["me@example.com", "friend@example.com"] do email.deliver_later end end end ``` -This example shows an alternative way to test that a parameterized mailer has been enqueued with the correct parameters: +This example shows an alternative way to test that a parameterized mailer has +been enqueued with the correct parameters: ```ruby require "test_helper" @@ -2108,7 +2273,10 @@ end ### Functional and System Testing -Unit testing allows us to test the attributes of the email while functional and system testing allows us to test whether user interactions appropriately trigger the email to be delivered. For example, you can check that the invite friend operation is sending an email appropriately: +Unit testing allows us to test the attributes of the email while functional and +system testing allows us to test whether user interactions appropriately trigger +the email to be delivered. For example, you can check that the invite friend +operation is sending an email appropriately: ```ruby # Integration Test @@ -2141,7 +2309,13 @@ class UsersTest < ActionDispatch::SystemTestCase end ``` -NOTE: The `assert_emails` method is not tied to a particular deliver method and will work with emails delivered with either the `deliver_now` or `deliver_later` method. If we explicitly want to assert that the email has been enqueued we can use the `assert_enqueued_email_with` ([examples above](#testing-enqueued-emails)) or `assert_enqueued_emails` methods. More information can be found in the [documentation here](https://api.rubyonrails.org/classes/ActionMailer/TestHelper.html). +NOTE: The `assert_emails` method is not tied to a particular deliver method and +will work with emails delivered with either the `deliver_now` or `deliver_later` +method. If we explicitly want to assert that the email has been enqueued we can +use the `assert_enqueued_email_with` ([examples +above](#testing-enqueued-emails)) or `assert_enqueued_emails` methods. More +information can be found in the +[documentation](https://api.rubyonrails.org/classes/ActionMailer/TestHelper.html). Testing Jobs ------------ @@ -2154,7 +2328,7 @@ Jobs can be tested in isolation (focusing on the job's behavior) and in context When you generate a job, an associated test file will also be generated in the `test/jobs` directory. -Here is an example test for a billing job: +Here is a test you could write for a billing job: ```ruby require "test_helper" @@ -2177,9 +2351,12 @@ The test uses `perform_enqueued_jobs` and [`perform_later`][] instead of [`perform_now`][] so that if retries are configured, retry failures are caught by the test instead of being re-enqueued and ignored. -[`perform_enqueued_jobs`]: https://api.rubyonrails.org/classes/ActiveJob/TestHelper.html#method-i-perform_enqueued_jobs -[`perform_later`]: https://api.rubyonrails.org/classes/ActiveJob/Enqueuing/ClassMethods.html#method-i-perform_later -[`perform_now`]: https://api.rubyonrails.org/classes/ActiveJob/Execution/ClassMethods.html#method-i-perform_now +[`perform_enqueued_jobs`]: + https://api.rubyonrails.org/classes/ActiveJob/TestHelper.html#method-i-perform_enqueued_jobs +[`perform_later`]: + https://api.rubyonrails.org/classes/ActiveJob/Enqueuing/ClassMethods.html#method-i-perform_later +[`perform_now`]: + https://api.rubyonrails.org/classes/ActiveJob/Execution/ClassMethods.html#method-i-perform_now ### Testing Jobs in Context @@ -2209,12 +2386,17 @@ class AccountTest < ActiveSupport::TestCase end ``` -[`ActiveJob::TestHelper`]: https://api.rubyonrails.org/classes/ActiveJob/TestHelper.html -[`assert_enqueued_with`]: https://api.rubyonrails.org/classes/ActiveJob/TestHelper.html#method-i-assert_enqueued_with +[`ActiveJob::TestHelper`]: + https://api.rubyonrails.org/classes/ActiveJob/TestHelper.html +[`assert_enqueued_with`]: + https://api.rubyonrails.org/classes/ActiveJob/TestHelper.html#method-i-assert_enqueued_with ### Testing that Exceptions are Raised -Testing that your job raises an exception in certain cases can be tricky, especially when you have retries configured. The `perform_enqueued_jobs` helper fails any test where a job raises an exception, so to have the test succeed when the exception is raised you have to call the job's `perform` method directly. +Testing that your job raises an exception in certain cases can be tricky, +especially when you have retries configured. The `perform_enqueued_jobs` helper +fails any test where a job raises an exception, so to have the test succeed when +the exception is raised you have to call the job's `perform` method directly. ```ruby require "test_helper" @@ -2229,21 +2411,25 @@ class BillingJobTest < ActiveJob::TestCase end ``` -This method is not recommended in general, as it circumvents some parts of the framework, such as argument serialization. +This method is not recommended in general, as it circumvents some parts of the +framework, such as argument serialization. Testing Action Cable -------------------- -Since Action Cable is used at different levels inside your application, -you'll need to test both the channels, connection classes themselves, and that other +Since Action Cable is used at different levels inside your application, you'll +need to test both the channels, connection classes themselves, and that other entities broadcast correct messages. ### Connection Test Case -By default, when you generate a new Rails application with Action Cable, a test for the base connection class (`ApplicationCable::Connection`) is generated as well under `test/channels/application_cable` directory. +By default, when you generate a new Rails application with Action Cable, a test +for the base connection class (`ApplicationCable::Connection`) is generated as +well under `test/channels/application_cable` directory. -Connection tests aim to check whether a connection's identifiers get assigned properly -or that any improper connection requests are rejected. Here is an example: +Connection tests aim to check whether a connection's identifiers get assigned +properly or that any improper connection requests are rejected. Here is an +example: ```ruby class ApplicationCable::ConnectionTest < ActionCable::Connection::TestCase @@ -2275,12 +2461,15 @@ test "connects with cookies" do end ``` -See the API documentation for [`ActionCable::Connection::TestCase`](https://api.rubyonrails.org/classes/ActionCable/Connection/TestCase.html) for more information. +See the API documentation for +[`ActionCable::Connection::TestCase`](https://api.rubyonrails.org/classes/ActionCable/Connection/TestCase.html) +for more information. ### Channel Test Case -By default, when you generate a channel, an associated test will be generated as well -under the `test/channels` directory. Here's an example test with a chat channel: +By default, when you generate a channel, an associated test will be generated as +well under the `test/channels` directory. Here's an example test with a chat +channel: ```ruby require "test_helper" @@ -2297,9 +2486,11 @@ class ChatChannelTest < ActionCable::Channel::TestCase end ``` -This test is pretty simple and only asserts that the channel subscribes the connection to a particular stream. +This test is pretty simple and only asserts that the channel subscribes the +connection to a particular stream. -You can also specify the underlying connection identifiers. Here's an example test with a web notifications channel: +You can also specify the underlying connection identifiers. Here's an example +test with a web notifications channel: ```ruby require "test_helper" @@ -2315,13 +2506,19 @@ class WebNotificationsChannelTest < ActionCable::Channel::TestCase end ``` -See the API documentation for [`ActionCable::Channel::TestCase`](https://api.rubyonrails.org/classes/ActionCable/Channel/TestCase.html) for more information. +See the API documentation for +[`ActionCable::Channel::TestCase`](https://api.rubyonrails.org/classes/ActionCable/Channel/TestCase.html) +for more information. ### Custom Assertions And Testing Broadcasts Inside Other Components -Action Cable ships with a bunch of custom assertions that can be used to lessen the verbosity of tests. For a full list of available assertions, see the API documentation for [`ActionCable::TestHelper`](https://api.rubyonrails.org/classes/ActionCable/TestHelper.html). +Action Cable ships with a bunch of custom assertions that can be used to lessen +the verbosity of tests. For a full list of available assertions, see the API +documentation for +[`ActionCable::TestHelper`](https://api.rubyonrails.org/classes/ActionCable/TestHelper.html). -It's a good practice to ensure that the correct message has been broadcasted inside other components (e.g. inside your controllers). This is precisely where +It's a good practice to ensure that the correct message has been broadcasted +inside other components (e.g. inside your controllers). This is precisely where the custom assertions provided by Action Cable are pretty useful. For instance, within a model: @@ -2337,8 +2534,8 @@ class ProductTest < ActionCable::TestCase end ``` -If you want to test the broadcasting made with `Channel.broadcast_to`, you should use -`Channel.broadcasting_for` to generate an underlying stream name: +If you want to test the broadcasting made with `Channel.broadcast_to`, you +should use `Channel.broadcasting_for` to generate an underlying stream name: ```ruby # app/jobs/chat_relay_job.rb @@ -2366,50 +2563,188 @@ class ChatRelayJobTest < ActiveJob::TestCase end ``` -Testing Eager Loading ---------------------- +Running tests in Continuous Integration (CI) +-------------------------------------------- -Normally, applications do not eager load in the `development` or `test` environments to speed things up. But they do in the `production` environment. +Continuous Integration (CI) is a development practice where changes are +frequently integrated into the main codebase, and as such, are automatically +tested before merge. -If some file in the project cannot be loaded for whatever reason, you better detect it before deploying to production, right? +To run all tests in a CI environment, there's just one command you need: -### Continuous Integration +```bash +$ bin/rails test +``` + +If you are using [System Tests](#system-testing), `bin/rails test` will not run +them, since they can be slow. To also run them, add another CI step that runs +`bin/rails test:system`, or change your first step to `bin/rails test:all`, +which runs all tests including system tests. + +Parallel Testing +---------------- + +Running tests in parallel reduces the time it takes your entire test suite to +run. While forking processes is the default method, threading is supported as +well. + +### Parallel Testing with Processes -If your project has CI in place, eager loading in CI is an easy way to ensure the application eager loads. +The default parallelization method is to fork processes using Ruby's DRb system. +The processes are forked based on the number of workers provided. The default +number is the actual core count on the machine, but can be changed by the number +passed to the `parallelize` method. -CIs typically set some environment variable to indicate the test suite is running there. For example, it could be `CI`: +To enable parallelization add the following to your `test_helper.rb`: ```ruby -# config/environments/test.rb -config.eager_load = ENV["CI"].present? +class ActiveSupport::TestCase + parallelize(workers: 2) +end +``` + +The number of workers passed is the number of times the process will be forked. +You may want to parallelize your local test suite differently from your CI, so +an environment variable is provided to be able to easily change the number of +workers a test run should use: + +```bash +$ PARALLEL_WORKERS=15 bin/rails test ``` -Starting with Rails 7, newly generated applications are configured that way by default. +When parallelizing tests, Active Record automatically handles creating a +database and loading the schema into the database for each process. The +databases will be suffixed with the number corresponding to the worker. For +example, if you have 2 workers the tests will create `test-database-0` and +`test-database-1` respectively. -### Bare Test Suites +If the number of workers passed is 1 or fewer the processes will not be forked +and the tests will not be parallelized and they will use the original +`test-database` database. -If your project does not have continuous integration, you can still eager load in the test suite by calling `Rails.application.eager_load!`: +Two hooks are provided, one runs when the process is forked, and one runs before +the forked process is closed. These can be useful if your app uses multiple +databases or performs other tasks that depend on the number of workers. -#### Minitest +The `parallelize_setup` method is called right after the processes are forked. +The `parallelize_teardown` method is called right before the processes are +closed. ```ruby -require "test_helper" +class ActiveSupport::TestCase + parallelize_setup do |worker| + # setup databases + end -class ZeitwerkComplianceTest < ActiveSupport::TestCase - test "eager loads all files without errors" do - assert_nothing_raised { Rails.application.eager_load! } + parallelize_teardown do |worker| + # cleanup databases + end + + parallelize(workers: :number_of_processors) +end +``` + +These methods are not needed or available when using parallel testing with +threads. + +### Parallel Testing with Threads + +If you prefer using threads or are using JRuby, a threaded parallelization +option is provided. The threaded parallelizer is backed by minitest's +`Parallel::Executor`. + +To change the parallelization method to use threads over forks put the following +in your `test_helper.rb`: + +```ruby +class ActiveSupport::TestCase + parallelize(workers: :number_of_processors, with: :threads) +end +``` + +Rails applications generated from JRuby or TruffleRuby will automatically +include the `with: :threads` option. + +NOTE: As in the section above, you can also use the environment variable +`PARALLEL_WORKERS` in this context, to change the number of workers your test +run should use. + +### Testing Parallel Transactions + +When you want to test code that runs parallel database transactions in threads, +those can block each other because they are already nested under the implicit +test transaction. + +To workaround this, you can disable transactions in a test case class by setting +`self.use_transactional_tests = false`: + +```ruby +class WorkerTest < ActiveSupport::TestCase + self.use_transactional_tests = false + + test "parallel transactions" do + # start some threads that create transactions end end ``` -#### RSpec +NOTE: With disabled transactional tests, you have to clean up any data tests +create as changes are not automatically rolled back after the test completes. + +### Threshold to Parallelize tests + +Running tests in parallel adds an overhead in terms of database setup and +fixture loading. Because of this, Rails won't parallelize executions that +involve fewer than 50 tests. + +You can configure this threshold in your `test.rb`: + +```ruby +config.active_support.test_parallelization_threshold = 100 +``` + +And also when setting up parallelization at the test case level: + +```ruby +class ActiveSupport::TestCase + parallelize threshold: 100 +end +``` + +Testing Eager Loading +--------------------- + +Normally, applications do not eager load in the `development` or `test` +environments to speed things up. But they do in the `production` environment. + +If some file in the project cannot be loaded for whatever reason, it is +important to detect it before deploying to production. + +### Continuous Integration + +If your project has CI in place, eager loading in CI is an easy way to ensure +the application eager loads. + +CIs typically set an environment variable to indicate the test suite is running +there. For example, it could be `CI`: + +```ruby +# config/environments/test.rb +config.eager_load = ENV["CI"].present? +``` + +Starting with Rails 7, newly generated applications are configured that way by +default. + +If your project does not have continuous integration, you can still eager load +in the test suite by calling `Rails.application.eager_load!`: ```ruby -require "rails_helper" +require "test_helper" -RSpec.describe "Zeitwerk compliance" do - it "eager loads all files without errors" do - expect { Rails.application.eager_load! }.not_to raise_error +class ZeitwerkComplianceTest < ActiveSupport::TestCase + test "eager loads all files without errors" do + assert_nothing_raised { Rails.application.eager_load! } end end ``` @@ -2417,9 +2752,18 @@ end Additional Testing Resources ---------------------------- +### Errors + +In system tests, integration tests and functional controller tests, Rails will +attempt to rescue from errors raised and respond with HTML error pages by +default. This behavior can be controlled by the +[`config.action_dispatch.show_exceptions`](/configuring.html#config-action-dispatch-show-exceptions) +configuration. + ### Testing Time-Dependent Code -Rails provides built-in helper methods that enable you to assert that your time-sensitive code works as expected. +Rails provides built-in helper methods that enable you to assert that your +time-sensitive code works as expected. The following example uses the [`travel_to`][travel_to] helper: @@ -2438,7 +2782,10 @@ end assert_equal Date.new(2004, 10, 24), user.activation_date ``` -Please see [`ActiveSupport::Testing::TimeHelpers`][time_helpers_api] API reference for more information about the available time helpers. +Please see [`ActiveSupport::Testing::TimeHelpers`][time_helpers_api] API +reference for more information about the available time helpers. -[travel_to]: https://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html#method-i-travel_to -[time_helpers_api]: https://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html +[travel_to]: + https://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html#method-i-travel_to +[time_helpers_api]: + https://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html