123456789_123456789_123456789_123456789_123456789_

Class: ActionController::TestCase

Overview

Superclass for ::ActionController functional tests. Functional tests allow you to test a single controller action per test method.

Use integration style controller tests over functional style controller tests.

Rails discourages the use of functional tests in favor of integration tests (use ::ActionDispatch::IntegrationTest).

New Rails applications no longer generate functional style controller tests and they should only be used for backward compatibility. Integration style controller tests perform actual requests, whereas functional style controller tests merely simulate a request. Besides, integration tests are as fast as functional tests and provide lot of helpers such as as, parsed_body for effective testing of controller actions including even API endpoints.

Basic example

Functional tests are written as follows:

  1. First, one uses the get, post, patch, put, delete, or head method to simulate an HTTP request.

  2. Then, one asserts whether the current state is as expected. “State” can be anything: the controller’s HTTP response, the database contents, etc.

For example:

class BooksControllerTest < ActionController::TestCase
  def test_create
    # Simulate a POST response with the given HTTP parameters.
    post(:create, params: { book: { title: "Love Hina" }})

    # Asserts that the controller tried to redirect us to
    # the created book's URI.
    assert_response :found

    # Asserts that the controller really put the book in the database.
    assert_not_nil Book.find_by(title: "Love Hina")
  end
end

You can also send a real document in the simulated HTTP request.

def test_create
  json = {book: { title: "Love Hina" }}.to_json
  post :create, body: json
end

Special instance variables

TestCase will also automatically provide the following instance variables for use in the tests:

@controller

The controller instance that will be tested.

@request

An ActionController::TestRequest, representing the current HTTP request. You can modify this object before sending the HTTP request. For example, you might want to set some session properties before sending a GET request.

@response

An ActionDispatch::TestResponse object, representing the response of the last HTTP response. In the above example, @response becomes valid after calling post. If the various assert methods are not sufficient, then you may use this object to inspect the HTTP response in detail.

Controller is automatically inferred

TestCase will automatically infer the controller under test from the test class name. If the controller cannot be inferred from the test class name, you can explicitly set it with tests.

class SpecialEdgeCaseWidgetsControllerTest < ActionController::TestCase
  tests WidgetController
end

Testing controller internals

In addition to these specific assertions, you also have easy access to various collections that the regular test/unit assertions can be used against. These collections are:

  • session: Objects being saved in the session.

  • flash: The flash objects currently in the session.

  • cookies: Cookies being sent to the user on this request.

These collections can be used just like any other hash:

assert_equal "Dave", cookies[:name] # makes sure that a cookie called :name was set as "Dave"
assert flash.empty? # makes sure that there's nothing in the flash

On top of the collections, you have the complete URL that a given action redirected to available in redirect_to_url.

For redirects within the same controller, you can even call follow_redirect and the redirect will be followed, triggering another action call which can then be asserted against.

Manipulating session and cookie variables

Sometimes you need to set up the session and cookie variables for a test. To do this just assign a value to the session or cookie collection:

session[:key] = "value"
cookies[:key] = "value"

To clear the cookies for a test just clear the cookie collection:

cookies.clear

Testing named routes

If you’re using named routes, they can be easily tested using the original named routes’ methods straight in the test case.

assert_redirected_to page_url(title: 'foo')

Constant Summary

::ActiveSupport::TestCase - Inherited

Assertion

Behavior - Attributes & Methods

Class Attribute Summary

::ActiveSupport::TestCase - Inherited

.file_fixture_path, .file_fixture_path?,
.test_order

Returns the order in which test cases are run.

.test_order=

Sets the order in which test cases are run.

Class Method Summary

::ActiveSupport::TestCase - Inherited

.fixture_paths

Returns the ::ActiveRecord::FixtureSet collection.

.fixture_paths=

Sets the given path to the fixture set.

.parallelize

Parallelizes the test suite.

.parallelize_setup

Set up hook for parallel testing.

.parallelize_teardown

Clean up hook for parallel testing.

::ActiveSupport::Testing::Declarative - Extended

test

Helper to define a test method using a ::String.

Instance Attribute Summary

Instance Method Summary

::ActionDispatch::Assertions - self

::ActionDispatch::Assertions::RoutingAssertions - Included

#assert_generates

Asserts that the provided options can be used to generate the provided path.

#assert_recognizes

Asserts that the routing of the given path was handled correctly and that the parsed options (given in the expected_options hash) match path.

#assert_routing

Asserts that path and options match both ways; in other words, it verifies that path generates options and then that options generates path.

#method_missing

ROUTES TODO: These assertions should really work in an integration context.

#with_routing

A helper to make it easier to test different route configurations.

::ActionDispatch::Assertions::ResponseAssertions - Included

#assert_redirected_to

Asserts that the response is a redirect to a URL matching the given options.

#assert_response

Asserts that the response is one of the following types:

Behavior - Included

#build_response, #controller_class_name,
#delete

Simulate a DELETE request with the given parameters and set/volley the response.

#generated_path,
#get

Simulate a GET request with the given parameters.

#head

Simulate a HEAD request with the given parameters and set/volley the response.

#patch

Simulate a PATCH request with the given parameters and set/volley the response.

#post

Simulate a POST request with the given parameters and set/volley the response.

#process

Simulate an HTTP request to action by specifying request method, parameters and set/volley the response.

#put

Simulate a PUT request with the given parameters and set/volley the response.

#query_parameter_names, #setup_controller_request_and_response

::ActionDispatch::TestProcess - Included

::ActionDispatch::TestProcess::FixtureFile - Included

#file_fixture_upload

Shortcut for Rack::Test::UploadedFile.new(File.join(ActionDispatch::IntegrationTest.file_fixture_path, path), type):

#fixture_file_upload

::ActiveSupport::TestCase - Inherited

::ActiveSupport::Testing::FileFixtures - Included

#file_fixture

Returns a ::Pathname to the fixture file named fixture_name.

::ActiveSupport::Testing::TimeHelpers - Included

#after_teardown,
#freeze_time

Calls travel_to with Time.now.

#travel

Changes current time to the time in the future or in the past by a given time difference by stubbing Time.now, Date.today, and DateTime.now.

#travel_back

Returns the current time back to its original state, by removing the stubs added by travel, travel_to, and freeze_time.

#travel_to

Changes current time to the given time by stubbing Time.now, Time.new, Date.today, and DateTime.now to return the time or date passed into this method.

#unfreeze_time

::ActiveSupport::Testing::ConstantStubbing - Included

#stub_const

Changes the value of a constant for the duration of a block.

::ActiveSupport::Testing::Deprecation - Included

#assert_deprecated

Asserts that a matching deprecation warning was emitted by the given deprecator during the execution of the yielded block.

#assert_not_deprecated

Asserts that no deprecation warnings are emitted by the given deprecator during the execution of the yielded block.

#collect_deprecations

Returns the return value of the block and an array of all the deprecation warnings emitted by the given deprecator during the execution of the yielded block.

::ActiveSupport::Testing::ErrorReporterAssertions - Included

#assert_error_reported

Assertion that the block should cause at least one exception to be reported to Rails.error.

#assert_no_error_reported

Assertion that the block should not cause an exception to be reported to Rails.error.

::ActiveSupport::Testing::Assertions - Included

#assert_changes

Assertion that the result of evaluating an expression is changed before and after invoking the passed in block.

#assert_difference

Test numeric difference between the return value of an expression as a result of what is evaluated in the yielded block.

#assert_no_changes

Assertion that the result of evaluating an expression is not changed before and after invoking the passed in block.

#assert_no_difference

Assertion that the numeric result of evaluating an expression is not changed before and after invoking the passed in block.

#assert_not

Asserts that an expression is not truthy.

#assert_nothing_raised

Assertion that the block should not raise an exception.

#assert_raise
#assert_raises

Asserts that a block raises one of exp.

Class Attribute Details

._controller_class (rw)

[ GitHub ]

  
# File 'actionpack/lib/action_controller/test_case.rb', line 571

class_attribute :_controller_class

._controller_class?Boolean (rw)

[ GitHub ]

  
# File 'actionpack/lib/action_controller/test_case.rb', line 571

class_attribute :_controller_class

Instance Attribute Details

#_controller_class (rw)

[ GitHub ]

  
# File 'actionpack/lib/action_controller/test_case.rb', line 571

class_attribute :_controller_class

#_controller_class?Boolean (rw)

[ GitHub ]

  
# File 'actionpack/lib/action_controller/test_case.rb', line 571

class_attribute :_controller_class

#executor_around_each_request (rw)

[ GitHub ]

  
# File 'actionpack/lib/action_controller/test_case.rb', line 346

singleton_class.attr_accessor :executor_around_each_request