diff options
Diffstat (limited to 'railties/doc/guides/source/testing_rails_applications.txt')
| -rw-r--r-- | railties/doc/guides/source/testing_rails_applications.txt | 183 |
1 files changed, 96 insertions, 87 deletions
diff --git a/railties/doc/guides/source/testing_rails_applications.txt b/railties/doc/guides/source/testing_rails_applications.txt index cb77829fc1..054260e276 100644 --- a/railties/doc/guides/source/testing_rails_applications.txt +++ b/railties/doc/guides/source/testing_rails_applications.txt @@ -228,16 +228,15 @@ NOTE: +db:test:prepare+ will fail with an error if db/schema.rb doesn't exists. ==== Rake Tasks for Preparing your Application for Testing ==== -[grid="all"] -|------------------------------------------------------------------------------------ -|Tasks Description -|------------------------------------------------------------------------------------ -|+rake db:test:clone+ Recreate the test database from the current environment's database schema -|+rake db:test:clone_structure+ Recreate the test databases from the development structure -|+rake db:test:load+ Recreate the test database from the current +schema.rb+ -|+rake db:test:prepare+ Check for pending migrations and load the test schema -|+rake db:test:purge+ Empty the test database. -|------------------------------------------------------------------------------------ +[options="header"] +|========================================================================================================== +|Tasks |Description +|+rake db:test:clone+ |Recreate the test database from the current environment's database schema +|+rake db:test:clone_structure+ |Recreate the test databases from the development structure +|+rake db:test:load+ |Recreate the test database from the current +schema.rb+ +|+rake db:test:prepare+ |Check for pending migrations and load the test schema +|+rake db:test:purge+ |Empty the test database. +|========================================================================================================== TIP: You can see all these rake tasks and their descriptions by running +rake \-\-tasks \-\-describe+ @@ -404,30 +403,29 @@ By now you've caught a glimpse of some of the assertions that are available. Ass There are a bunch of different types of assertions you can use. Here's the complete list of assertions that ship with +test/unit+, the testing library used by Rails. The +[msg]+ parameter is an optional string message you can specify to make your test failure messages clearer. It's not required. -[grid="all"] -`-----------------------------------------------------------------`------------------------------------------------------------------------ -Assertion Purpose ------------------------------------------------------------------------------------------------------------------------------------------- -+assert( boolean, [msg] )+ Ensures that the object/expression is true. -+assert_equal( obj1, obj2, [msg] )+ Ensures that +obj1 == obj2+ is true. -+assert_not_equal( obj1, obj2, [msg] )+ Ensures that +obj1 == obj2+ is false. -+assert_same( obj1, obj2, [msg] )+ Ensures that +obj1.equal?(obj2)+ is true. -+assert_not_same( obj1, obj2, [msg] )+ Ensures that +obj1.equal?(obj2)+ is false. -+assert_nil( obj, [msg] )+ Ensures that +obj.nil?+ is true. -+assert_not_nil( obj, [msg] )+ Ensures that +obj.nil?+ is false. -+assert_match( regexp, string, [msg] )+ Ensures that a string matches the regular expression. -+assert_no_match( regexp, string, [msg] )+ Ensures that a string doesn't matches the regular expression. -+assert_in_delta( expecting, actual, delta, [msg] )+ Ensures that the numbers `expecting` and `actual` are within `delta` of each other. -+assert_throws( symbol, [msg] ) { block }+ Ensures that the given block throws the symbol. -+assert_raises( exception1, exception2, ... ) { block }+ Ensures that the given block raises one of the given exceptions. -+assert_nothing_raised( exception1, exception2, ... ) { block }+ Ensures that the given block doesn't raise one of the given exceptions. -+assert_instance_of( class, obj, [msg] )+ Ensures that +obj+ is of the +class+ type. -+assert_kind_of( class, obj, [msg] )+ Ensures that +obj+ is or descends from +class+. -+assert_respond_to( obj, symbol, [msg] )+ Ensures that +obj+ has a method called +symbol+. -+assert_operator( obj1, operator, obj2, [msg] )+ Ensures that +obj1.operator(obj2)+ is true. -+assert_send( array, [msg] )+ Ensures that executing the method listed in +array[1]+ on the object in +array[0]+ with the parameters of +array[2 and up]+ is true. This one is weird eh? -+flunk( [msg] )+ Ensures failure. This is useful to explicitly mark a test that isn't finished yet. ------------------------------------------------------------------------------------------------------------------------------------------- +[options="header"] +|========================================================================================================================================== +|Assertion |Purpose +|+assert( boolean, [msg] )+ |Ensures that the object/expression is true. +|+assert_equal( obj1, obj2, [msg] )+ |Ensures that +obj1 == obj2+ is true. +|+assert_not_equal( obj1, obj2, [msg] )+ |Ensures that +obj1 == obj2+ is false. +|+assert_same( obj1, obj2, [msg] )+ |Ensures that +obj1.equal?(obj2)+ is true. +|+assert_not_same( obj1, obj2, [msg] )+ |Ensures that +obj1.equal?(obj2)+ is false. +|+assert_nil( obj, [msg] )+ |Ensures that +obj.nil?+ is true. +|+assert_not_nil( obj, [msg] )+ |Ensures that +obj.nil?+ is false. +|+assert_match( regexp, string, [msg] )+ |Ensures that a string matches the regular expression. +|+assert_no_match( regexp, string, [msg] )+ |Ensures that a string doesn't matches the regular expression. +|+assert_in_delta( expecting, actual, delta, [msg] )+ |Ensures that the numbers `expecting` and `actual` are within `delta` of each other. +|+assert_throws( symbol, [msg] ) { block }+ |Ensures that the given block throws the symbol. +|+assert_raises( exception1, exception2, ... ) { block }+ |Ensures that the given block raises one of the given exceptions. +|+assert_nothing_raised( exception1, exception2, ... ) { block }+ |Ensures that the given block doesn't raise one of the given exceptions. +|+assert_instance_of( class, obj, [msg] )+ |Ensures that +obj+ is of the +class+ type. +|+assert_kind_of( class, obj, [msg] )+ |Ensures that +obj+ is or descends from +class+. +|+assert_respond_to( obj, symbol, [msg] )+ |Ensures that +obj+ has a method called +symbol+. +|+assert_operator( obj1, operator, obj2, [msg] )+ |Ensures that +obj1.operator(obj2)+ is true. +|+assert_send( array, [msg] )+ |Ensures that executing the method listed in +array[1]+ on the object in +array[0]+ with the parameters of +array[2 and up]+ is true. This one is weird eh? +|+flunk( [msg] )+ |Ensures failure. This is useful to explicitly mark a test that isn't finished yet. +|========================================================================================================================================= Because of the modular nature of the testing framework, it is possible to create your own assertions. In fact, that's exactly what Rails does. It includes some specialized assertions to make your life easier. @@ -437,19 +435,18 @@ NOTE: Creating your own assertions is an advanced topic that we won't cover in t Rails adds some custom assertions of its own to the +test/unit+ framework: -[grid="all"] -`----------------------------------------------------------------------------------`------------------------------------------------------- -Assertion Purpose ------------------------------------------------------------------------------------------------------------------------------------------- -+assert_valid(record)+ Ensures that the passed record is valid by Active Record standards and returns any error messages if it is not. -+assert_difference(expressions, difference = 1, message = nil) {|| ...}+ Test numeric difference between the return value of an expression as a result of what is evaluated in the yielded block. -+assert_no_difference(expressions, message = nil, &block)+ Asserts that the numeric result of evaluating an expression is not changed before and after invoking the passed in block. -+assert_recognizes(expected_options, path, extras={}, message=nil)+ Asserts that the routing of the given path was handled correctly and that the parsed options (given in the expected_options hash) match path. Basically, it asserts that Rails recognizes the route given by expected_options. -+assert_generates(expected_path, options, defaults={}, extras = {}, message=nil)+ Asserts that the provided options can be used to generate the provided path. This is the inverse of assert_recognizes. The extras parameter is used to tell the request the names and values of additional request parameters that would be in a query string. The message parameter allows you to specify a custom error message for assertion failures. -+assert_response(type, message = nil)+ Asserts that the response comes with a specific status code. You can specify +:success+ to indicate 200, +:redirect+ to indicate 300-399, +:missing+ to indicate 404, or +:error+ to match the 500-599 range -+assert_redirected_to(options = {}, message=nil)+ Assert that the redirection options passed in match those of the redirect called in the latest action. This match can be partial, such that +assert_redirected_to(:controller => "weblog")+ will also match the redirection of +redirect_to(:controller => "weblog", :action => "show")+ and so on. -+assert_template(expected = nil, message=nil)+ Asserts that the request was rendered with the appropriate template file. ------------------------------------------------------------------------------------------------------------------------------------------- +[options="header"] +|=========================================================================================================================================================== +|Assertion |Purpose +|+assert_valid(record)+ |Ensures that the passed record is valid by Active Record standards and returns any error messages if it is not. +|+assert_difference(expressions, difference = 1, message = nil) {...}+ |Test numeric difference between the return value of an expression as a result of what is evaluated in the yielded block. +|+assert_no_difference(expressions, message = nil, &block)+ |Asserts that the numeric result of evaluating an expression is not changed before and after invoking the passed in block. +|+assert_recognizes(expected_options, path, extras={}, message=nil)+ |Asserts that the routing of the given path was handled correctly and that the parsed options (given in the expected_options hash) match path. Basically, it asserts that Rails recognizes the route given by expected_options. +|+assert_generates(expected_path, options, defaults={}, extras = {}, message=nil)+ |Asserts that the provided options can be used to generate the provided path. This is the inverse of assert_recognizes. The extras parameter is used to tell the request the names and values of additional request parameters that would be in a query string. The message parameter allows you to specify a custom error message for assertion failures. +|+assert_response(type, message = nil)+ |Asserts that the response comes with a specific status code. You can specify +:success+ to indicate 200, +:redirect+ to indicate 300-399, +:missing+ to indicate 404, or +:error+ to match the 500-599 range +|+assert_redirected_to(options = {}, message=nil)+ |Assert that the redirection options passed in match those of the redirect called in the latest action. This match can be partial, such that +assert_redirected_to(:controller => "weblog")+ will also match the redirection of +redirect_to(:controller => "weblog", :action => "show")+ and so on. +|+assert_template(expected = nil, message=nil)+ |Asserts that the request was rendered with the appropriate template file. +|=========================================================================================================================================================== You'll see the usage of some of these assertions in the next chapter. @@ -595,7 +592,7 @@ For example, you could verify the contents on the title element in your response assert_select 'title', "Welcome to Rails Testing Guide" -------------------------------------------------- -You can also use nested +assert_select+ blocks. In this case the inner +assert_select+ will run the assertion on each element selected by the outer `assert_select` block: +You can also use nested +assert_select+ blocks. In this case the inner +assert_select+ runs the assertion on the complete collection of elements selected by the outer `assert_select` block: [source,ruby] -------------------------------------------------- @@ -604,21 +601,35 @@ assert_select 'ul.navigation' do end -------------------------------------------------- -The +assert_select+ assertion is quite powerful. For more advanced usage, refer to its link:http://api.rubyonrails.com/classes/ActionController/Assertions/SelectorAssertions.html#M000749[documentation]. +Alternatively the collection of elements selected by the outer +assert_select+ may be iterated through so that +assert_select+ may be called separately for each element. Suppose for example that the response contains two ordered lists, each with four list elements then the following tests will both pass. + +[source,ruby] +-------------------------------------------------- +assert_select "ol" do |elements| + elements.each do |element| + assert_select element, "li", 4 + end +end + +assert_select "ol" do + assert_select "li", 8 +end +-------------------------------------------------- + +The +assert_select+ assertion is quite powerful. For more advanced usage, refer to its link:http://api.rubyonrails.com/classes/ActionController/Assertions/SelectorAssertions.html[documentation]. ==== Additional View-based Assertions ==== There are more assertions that are primarily used in testing views: -[grid="all"] -`----------------------------------------------------------------------------------`------------------------------------------------------- -Assertion Purpose ------------------------------------------------------------------------------------------------------------------------------------------- -+assert_select_email+ Allows you to make assertions on the body of an e-mail. -+assert_select_rjs+ Allows you to make assertions on RJS response. +assert_select_rjs+ has variants which allow you to narrow down on the updated element or even a particular operation on an element. -+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. ------------------------------------------------------------------------------------------------------------------------------------------- +[options="header"] +|========================================================================================================================================= +|Assertion |Purpose +|+assert_select_email+ |Allows you to make assertions on the body of an e-mail. +|+assert_select_rjs+ |Allows you to make assertions on RJS response. +assert_select_rjs+ has variants which allow you to narrow down on the updated element or even a particular operation on an element. +|+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+: @@ -664,22 +675,21 @@ Integration tests inherit from +ActionController::IntegrationTest+. This makes a In addition to the standard testing helpers, there are some additional helpers available to integration tests: -[grid="all"] -`----------------------------------------------------------------------------------`------------------------------------------------------- -Helper Purpose ------------------------------------------------------------------------------------------------------------------------------------------- -+https?+ Returns +true+ if the session is mimicking a secure HTTPS request. -+https!+ Allows you to mimic a secure HTTPS request. -+host!+ Allows you to set the host name to use in the next request. -+redirect?+ Returns +true+ if the last request was a redirect. -+follow_redirect!+ Follows a single redirect response. -+request_via_redirect(http_method, path, [parameters], [headers])+ Allows you to make an HTTP request and follow any subsequent redirects. -+post_via_redirect(path, [parameters], [headers])+ Allows you to make an HTTP POST request and follow any subsequent redirects. -+get_via_redirect(path, [parameters], [headers])+ Allows you to make an HTTP GET request and follow any subsequent redirects. -+put_via_redirect(path, [parameters], [headers])+ Allows you to make an HTTP PUT request and follow any subsequent redirects. -+delete_via_redirect(path, [parameters], [headers])+ Allows you to make an HTTP DELETE request and follow any subsequent redirects. -+open_session+ Opens a new session instance. ------------------------------------------------------------------------------------------------------------------------------------------- +[options="header"] +|========================================================================================================================================= +|Helper |Purpose +|+https?+ |Returns +true+ if the session is mimicking a secure HTTPS request. +|+https!+ |Allows you to mimic a secure HTTPS request. +|+host!+ |Allows you to set the host name to use in the next request. +|+redirect?+ |Returns +true+ if the last request was a redirect. +|+follow_redirect!+ |Follows a single redirect response. +|+request_via_redirect(http_method, path, [parameters], [headers])+ |Allows you to make an HTTP request and follow any subsequent redirects. +|+post_via_redirect(path, [parameters], [headers])+ |Allows you to make an HTTP POST request and follow any subsequent redirects. +|+get_via_redirect(path, [parameters], [headers])+ |Allows you to make an HTTP GET request and follow any subsequent redirects. +|+put_via_redirect(path, [parameters], [headers])+ |Allows you to make an HTTP PUT request and follow any subsequent redirects. +|+delete_via_redirect(path, [parameters], [headers])+ |Allows you to make an HTTP DELETE request and follow any subsequent redirects. +|+open_session+ |Opens a new session instance. +|========================================================================================================================================= === Integration Testing Examples === @@ -767,18 +777,17 @@ end You don't need to set up and run your tests by hand on a test-by-test basis. Rails comes with a number of rake tasks to help in testing. The table below lists all rake tasks that come along in the default Rakefile when you initiate a Rail project. -[grid="all"] ------------------------------------------------------------------------------------- -Tasks Description ------------------------------------------------------------------------------------- -+rake test+ Runs all unit, functional and integration tests. You can also simply run +rake+ as the _test_ target is the default. -+rake test:units+ Runs all the unit tests from +test/unit+ -+rake test:functionals+ Runs all the functional tests from +test/functional+ -+rake test:integration+ Runs all the integration tests from +test/integration+ -+rake test:recent+ Tests recent changes -+rake test:uncommitted+ Runs all the tests which are uncommitted. Only supports Subversion -+rake test:plugins+ Run all the plugin tests from +vendor/plugins/*/**/test+ (or specify with +PLUGIN=_name_+) ------------------------------------------------------------------------------------- +[options="header"] +|=================================================================================== +|Tasks |Description +|+rake test+ |Runs all unit, functional and integration tests. You can also simply run +rake+ as the _test_ target is the default. +|+rake test:units+ |Runs all the unit tests from +test/unit+ +|+rake test:functionals+ |Runs all the functional tests from +test/functional+ +|+rake test:integration+ |Runs all the integration tests from +test/integration+ +|+rake test:recent+ |Tests recent changes +|+rake test:uncommitted+ |Runs all the tests which are uncommitted. Only supports Subversion +|+rake test:plugins+ |Run all the plugin tests from +vendor/plugins/*/**/test+ (or specify with +PLUGIN=_name_+) +|=================================================================================== == Brief Note About Test::Unit == @@ -983,7 +992,7 @@ The built-in +test/unit+ based testing is not the only way to test Rails applica * link:http://avdi.org/projects/nulldb/[NullDB], a way to speed up testing by avoiding database use. * link:http://github.com/thoughtbot/factory_girl/tree/master[Factory Girl], as replacement for fixtures. * link:http://www.thoughtbot.com/projects/shoulda[Shoulda], an extension to +test/unit+ with additional helpers, macros, and assertions. -* link: http://rspec.info/[RSpec], a behavior-driven development framework +* link:http://rspec.info/[RSpec], a behavior-driven development framework == Changelog == |