Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Ticket #7803: other_assertions_docs.diff

File other_assertions_docs.diff, 20.5 kB (added by jeremymcanally, 2 years ago)

UPDATED: I think I got all the typos ironed out

  • actionpack/lib/action_controller/assertions/routing_assertions.rb

    old new  
    11module ActionController 
    22  module Assertions 
     3    # Suite of assertions to test routes generated by Rails and the handling of requests made to them. 
    34    module RoutingAssertions 
    4       # Asserts that the routing of the given path was handled correctly and that the parsed options match. 
     5      # Asserts that the routing of the given +path+ was handled correctly and that the parsed options (given in the +expected_options+ hash)  
     6      # match +path+.  Basically, it asserts that Rails recognizes the route given by +expected_options+. 
    57      # 
    6       #   assert_recognizes({:controller => 'items', :action => 'index'}, 'items') # check the default action 
    7       #   assert_recognizes({:controller => 'items', :action => 'list'}, 'items/list') # check a specific action 
    8       #   assert_recognizes({:controller => 'items', :action => 'list', :id => '1'}, 'items/list/1') # check an action with a parameter 
    9       # 
    10       # Pass a hash in the second argument to specify the request method.  This is useful for routes 
     8      # Pass a hash in the second argument (+path+) to specify the request method.  This is useful for routes 
    119      # requiring a specific HTTP method.  The hash should contain a :path with the incoming request path 
    1210      # and a :method containing the required HTTP verb. 
    1311      # 
    1412      #   # assert that POSTing to /items will call the create action on ItemsController 
    1513      #   assert_recognizes({:controller => 'items', :action => 'create'}, {:path => 'items', :method => :post}) 
    1614      # 
    17       # You can also pass in "extras" with a hash containing URL parameters that would normally be in the query string.  This can be used 
     15      # You can also pass in +extras+ with a hash containing URL parameters that would normally be in the query string.  This can be used 
    1816      # to assert that values in the query string string will end up in the params hash correctly.  To test query strings you must use the 
    1917      # extras argument, appending the query string on the path directly will not work.  For example:  
    2018      # 
    2119      #   # assert that a path of '/items/list/1?view=print' returns the correct options 
    2220      #   assert_recognizes({:controller => 'items', :action => 'list', :id => '1', :view => 'print'}, 'items/list/1', { :view => "print" })  
     21      # 
     22      # The +message+ parameter allows you to pass in an error message that is displayed upon failure.  
     23      # 
     24      # ==== Examples 
     25      #   # Check the default route (i.e., the index action) 
     26      #   assert_recognizes({:controller => 'items', :action => 'index'}, 'items')     
     27      # 
     28      #   # Test a specific action 
     29      #   assert_recognizes({:controller => 'items', :action => 'list'}, 'items/list') 
     30      # 
     31      #   # Test an action with a parameter 
     32      #   assert_recognizes({:controller => 'items', :action => 'destroy', :id => '1'}, 'items/destroy/1') 
     33      # 
     34      #   # Test a custom route 
     35      #   assert_recognizes({:controller => 'items', :action => 'show', :id => '1'}, 'view/item1') 
     36      # 
     37      #   # Check a Simply RESTful generated route 
     38      #   assert_recognizes(list_items_url, 'items/list') 
    2339      def assert_recognizes(expected_options, path, extras={}, message=nil) 
    2440        if path.is_a? Hash 
    2541          request_method = path[:method] 
    …… 
    4359        end 
    4460      end 
    4561 
    46       # Asserts that the provided options can be used to generate the provided path.  This is the inverse of assert_recognizes. 
    47       # For example: 
     62      # Asserts that the provided options can be used to generate the provided path.  This is the inverse of #assert_recognizes. 
     63      # The +extras+ parameter is used to tell the request the names and values of additional request parameters that would be in 
     64      # a query string. The +message+ parameter allows you to specify a custom error message for assertion failures. 
    4865      # 
     66      # The +defaults+ parameter is unused. 
     67      #  
     68      # ==== Examples 
     69      #   # Asserts that the default action is generated for a route with no action 
    4970      #   assert_generates("/items", :controller => "items", :action => "index") 
     71      # 
     72      #   # Tests that the list action is properly routed 
    5073      #   assert_generates("/items/list", :controller => "items", :action => "list") 
     74      # 
     75      #   # Tests the generation of a route with a parameter 
    5176      #   assert_generates("/items/list/1", { :controller => "items", :action => "list", :id => "1" })  
     77      # 
     78      #   # Asserts that the generated route gives us our custom route 
     79      #   assert_generates "changesets/12", { :controller => 'scm', :action => 'show_diff', :revision => "12" } 
    5280      def assert_generates(expected_path, options, defaults={}, extras = {}, message=nil) 
    5381        clean_backtrace do  
    5482          expected_path = "/#{expected_path}" unless expected_path[0] == ?/ 
    …… 
    6795        end 
    6896      end 
    6997 
    70       # Asserts that path and options match both ways; in other words, the URL generated from  
    71       # options is the same as path, and also that the options recognized from path are the same as options.  This 
    72       # essentially combines assert_recognizes and assert_generates into one step. 
     98      # Asserts that path and options match both ways; in other words, it verifies that <tt>path</tt> generates  
     99      # <tt>options</tt> and then that <tt>options</tt> generates <tt>path</tt>.  This essentially combines #assert_recognizes  
     100      # and #assert_generates into one step. 
     101      # 
     102      # The +extras+ hash allows you to specify options that would normally be provided as a query string to the action.  The 
     103      # +message+ parameter allows you to specify a custom error message to display upon failure.   
     104      # 
     105      # ==== Examples 
     106      #  # Assert a basic route: a controller with the default action (index) 
     107      #  assert_routing('/home', :controller => 'home', :action => 'index') 
     108      # 
     109      #  # Test a route generated with a specific controller, action, and parameter (id) 
     110      #  assert_routing('/entries/show/23', :controller => 'entries', :action => 'show', id => 23) 
     111      # 
     112      #  # Assert a basic route (controller + default action), with an error message if it fails 
     113      #  assert_routing('/store', { :controller => 'store', :action => 'index' }, {}, {}, 'Route for store index not generated properly') 
     114      # 
     115      #  # Tests a route, providing a defaults hash 
     116      #  assert_routing 'controller/action/9', {:id => "9", :item => "square"}, {:controller => "controller", :action => "action"}, {}, {:item => "square"} 
    73117      def assert_routing(path, options, defaults={}, extras={}, message=nil) 
    74118        assert_recognizes(options, path, extras, message) 
    75119         

  • actionpack/lib/action_controller/assertions/tag_assertions.rb

    old new  
    33 
    44module ActionController 
    55  module Assertions 
     6    # Pair of assertions to testing elements in the HTML output of the response. 
    67    module TagAssertions 
    78      # Asserts that there is a tag/node/element in the body of the response 
    89      # that meets all of the given conditions. The +conditions+ parameter must 
    …… 
    4849      # * if the condition is +true+, the value must not be +nil+. 
    4950      # * if the condition is +false+ or +nil+, the value must be +nil+. 
    5051      # 
    51       # Usage: 
     52      # === Examples 
    5253      # 
    53       #   # assert that there is a "span" tag 
     54      #   # Assert that there is a "span" tag 
    5455      #   assert_tag :tag => "span" 
    5556      # 
    56       #   # assert that there is a "span" tag with id="x" 
     57      #   # Assert that there is a "span" tag with id="x" 
    5758      #   assert_tag :tag => "span", :attributes => { :id => "x" } 
    5859      # 
    59       #   # assert that there is a "span" tag using the short-hand 
     60      #   # Assert that there is a "span" tag using the short-hand 
    6061      #   assert_tag :span 
    6162      # 
    62       #   # assert that there is a "span" tag with id="x" using the short-hand 
     63      #   # Assert that there is a "span" tag with id="x" using the short-hand 
    6364      #   assert_tag :span, :attributes => { :id => "x" } 
    6465      # 
    65       #   # assert that there is a "span" inside of a "div" 
     66      #   # Assert that there is a "span" inside of a "div" 
    6667      #   assert_tag :tag => "span", :parent => { :tag => "div" } 
    6768      # 
    68       #   # assert that there is a "span" somewhere inside a table 
     69      #   # Assert that there is a "span" somewhere inside a table 
    6970      #   assert_tag :tag => "span", :ancestor => { :tag => "table" } 
    7071      # 
    71       #   # assert that there is a "span" with at least one "em" child 
     72      #   # Assert that there is a "span" with at least one "em" child 
    7273      #   assert_tag :tag => "span", :child => { :tag => "em" } 
    7374      # 
    74       #   # assert that there is a "span" containing a (possibly nested) 
     75      #   # Assert that there is a "span" containing a (possibly nested) 
    7576      #   # "strong" tag. 
    7677      #   assert_tag :tag => "span", :descendant => { :tag => "strong" } 
    7778      # 
    78       #   # assert that there is a "span" containing between 2 and 4 "em" tags 
     79      #   # Assert that there is a "span" containing between 2 and 4 "em" tags 
    7980      #   # as immediate children 
    8081      #   assert_tag :tag => "span", 
    8182      #              :children => { :count => 2..4, :only => { :tag => "em" } }  
    8283      # 
    83       #   # get funky: assert that there is a "div", with an "ul" ancestor 
     84      #   # Get funky: assert that there is a "div", with an "ul" ancestor 
    8485      #   # and an "li" parent (with "class" = "enum"), and containing a  
    8586      #   # "span" descendant that contains text matching /hello world/ 
    8687      #   assert_tag :tag => "div", 
    …… 
    105106       
    106107      # Identical to #assert_tag, but asserts that a matching tag does _not_ 
    107108      # exist. (See #assert_tag for a full discussion of the syntax.) 
     109      # 
     110      # === Examples 
     111      #   # Assert that there is not a "div" containing a "p" 
     112      #   assert_no_tag :tag => "div", :descendant => { :tag => "p" } 
     113      # 
     114      #   # Assert that an unordered list is empty 
     115      #   assert_no_tag :tag => "ul", :descendant => { :tag => "li" } 
     116      # 
     117      #   # Assert that there is not a "p" tag with between 1 to 3 "img" tags 
     118      #   # as immediate children 
     119      #   assert_no_tag :tag => "p", 
     120      #              :children => { :count => 1..3, :only => { :tag => "img" } } 
    108121      def assert_no_tag(*opts) 
    109122        clean_backtrace do 
    110123          opts = opts.size > 1 ? opts.last.merge({ :tag => opts.first.to_s }) : opts.first 

  • actionpack/lib/action_controller/assertions/response_assertions.rb

    old new  
    33 
    44module ActionController 
    55  module Assertions 
     6    # A small suite of assertions that test responses from Rails applications. 
    67    module ResponseAssertions 
    78      # Asserts that the response is one of the following types: 
    89      # 
    …… 
    1011      # * <tt>:redirect</tt>: Status code was in the 300-399 range 
    1112      # * <tt>:missing</tt>: Status code was 404 
    1213      # * <tt>:error</tt>:  Status code was in the 500-599 range 
     14      # * Your own custom explicit status number 
    1315      # 
    14       # You can also pass an explicit status number like assert_response(501) 
    15       # or its symbolic equivalent assert_response(:not_implemented). 
     16      # This explicit status number can be a number (like <tt>assert_response(501)</tt>) 
     17      # or its symbolic equivalent (like <tt>assert_response(:not_implemented)</tt>). 
    1618      # See ActionController::StatusCodes for a full list. 
     19      # 
     20      # ==== Examples 
     21      #  # Makes sure we got a successful response 
     22      #  assert_response(:success)        # => assert_response(200) 
     23      # 
     24      #  # Asserts the response was Document Not Found (404 error) 
     25      #  assert_response(404)             # => assert_response(:missing) 
     26      # 
     27      #  # Asserts that the response was 401, with a custom error message if it was not 
     28      #  assert_response(401, "Expecting 'Not Authorized,' but did not receive 401 error") 
     29      # 
     30      #  # Tests that the response code was 304 to test the "unmodified view" response from Rails 
     31      #  assert_response(304, "View was modified or Rails did not return the proper 'Not Modified' response") 
    1732      def assert_response(type, message = nil) 
    1833        clean_backtrace do 
    1934          if [ :success, :missing, :redirect, :error ].include?(type) && @response.send("#{type}?") 
    …… 
    2843        end 
    2944      end 
    3045 
    31       # Assert that the redirection options passed in match those of the redirect called in the latest action. This match can be partial, 
    32       # such that assert_redirected_to(:controller => "weblog") will also match the redirection of 
    33       # redirect_to(:controller => "weblog", :action => "show") and so on. 
     46      # Assert that the redirection options passed in as +options+ match those of the redirect called in the latest action.  
     47      # This match can be partial, such that assert_redirected_to(:controller => "weblog") will also match the redirection of 
     48      # redirect_to(:controller => "weblog", :action => "show") and so on.  The +message+ parameter allows you to display a custom 
     49      # error message if the assertion fails.   
     50      # 
     51      # ==== Examples 
     52      #  # Matches account/login, account/index, account/signup, and so on... 
     53      #  assert_redirected_to(:controller => 'account')                     
     54      # 
     55      #  # Only matches /home/index or /home 
     56      #  assert_redirected_to(:controller => 'home', action => 'index')    
    3457      def assert_redirected_to(options = {}, message=nil) 
    3558        clean_backtrace do 
    3659          assert_response(:redirect, message) 
    …… 
    104127      end 
    105128 
    106129      # Asserts that the request was rendered with the appropriate template file. 
     130      # 
     131      # ==== Examples 
     132      #  assert_template('user/new') 
     133      #  assert_template('store/checkout', "Checkout template is not being used") 
    107134      def assert_template(expected = nil, message=nil) 
    108135        clean_backtrace do 
    109136          rendered = expected ? @response.rendered_file(!expected.include?('/')) : @response.rendered_file 

  • actionpack/lib/action_controller/assertions/model_assertions.rb

    old new  
    11module ActionController 
    22  module Assertions 
    33    module ModelAssertions 
    4       # ensures that the passed record is valid by active record standards. returns the error messages if not 
     4      # Ensures that the <tt>record</tt> is valid by Active Record standards using the <tt>valid?</tt> method.  
     5      # It returns any error messages if it is not valid. 
     6      # 
     7      # ==== Example 
     8      #  my_person = Person.find(:first) 
     9      #  assert_valid(my_person) 
    510      def assert_valid(record) 
    611        clean_backtrace do 
    712          assert record.valid?, record.errors.full_messages.join("\n") 

  • actionpack/lib/action_controller/assertions/selector_assertions.rb

    old new  
    1313    end 
    1414 
    1515    # Adds the #assert_select method for use in Rails functional 
    16     # test cases. 
    17     # 
    18     # Use #assert_select to make assertions on the response HTML of a controller 
     16    # test cases, which can be used to make assertions on the response HTML of a controller 
    1917    # action. You can also call #assert_select within another #assert_select to 
    2018    # make assertions on elements selected by the enclosing assertion. 
    2119    # 
    2220    # Use #css_select to select elements without making an assertions, either 
    2321    # from the response HTML or elements selected by the enclosing assertion. 
    24     # 
     22    #  
    2523    # In addition to HTML responses, you can make the following assertions: 
    2624    # * #assert_select_rjs    -- Assertions on HTML content of RJS update and 
    2725    #     insertion operations. 
    …… 
    2927    #     for example for dealing with feed item descriptions. 
    3028    # * #assert_select_email    -- Assertions on the HTML body of an e-mail. 
    3129    # 
    32     # Also see HTML::Selector for learning how to use selectors. 
     30    # Also see HTML::Selector to learn how to use selectors. 
    3331    module SelectorAssertions 
    3432      # :call-seq: 
    3533      #   css_select(selector) => array 
    …… 
    4947      # The selector may be a CSS selector expression (+String+), an expression 
    5048      # with substitution values (+Array+) or an HTML::Selector object. 
    5149      # 
    52       # For example: 
     50      # ==== Examples 
     51      #   # Selects all div tags 
     52      #   divs = css_select("div") 
     53      # 
     54      #   # Selects all paragraph tags and does something interesting 
     55      #   pars = css_select("p") 
     56      #   pars.each do |par| 
     57      #     # Do something fun with paragraphs here... 
     58      #   end 
     59      # 
     60      #   # Selects all list items in unordered lists 
     61      #   items = css_select("ul>li")  
     62      #       
     63      #   # Selects all form tags and then all inputs inside the form 
    5364      #   forms = css_select("form") 
    5465      #   forms.each do |form| 
    5566      #     inputs = css_select(form, "input") 
    5667      #     ... 
    5768      #   end 
     69      # 
    5870      def css_select(*args) 
    5971        # See assert_select to understand what's going on here. 
    6072        arg = args.shift 
    …… 
    105117      # response HTML. Calling #assert_select inside an #assert_select block will 
    106118      # run the assertion for each element selected by the enclosing assertion. 
    107119      # 
    108       # For example: 
     120      # ==== Example 
    109121      #   assert_select "ol>li" do |elements| 
    110122      #     elements.each do |element| 
    111123      #       assert_select element, "li" 
    112124      #     end 
    113125      #   end 
     126      # 
    114127      # Or for short: 
    115128      #   assert_select "ol>li" do 
    116129      #     assert_select "li" 
    …… 
    148161      # If the method is called with a block, once all equality tests are 
    149162      # evaluated the block is called with an array of all matched elements. 
    150163      # 
    151       # === Examples 
     164      # ==== Examples 
    152165      # 
    153166      #   # At least one form element 
    154167      #   assert_select "form" 
    …… 
    342355      # but without distinguishing whether the content is returned in an HTML 
    343356      # or JavaScript. 
    344357      # 
    345       # === Examples 
     358      # ==== Examples 
    346359      # 
    347360      #   # Replacing the element foo. 
    348361      #   # page.replace 'foo', ... 
    …… 
    454467      # The content of each element is un-encoded, and wrapped in the root 
    455468      # element +encoded+. It then calls the block with all un-encoded elements. 
    456469      # 
    457       # === Example 
     470      # ==== Examples 
     471      #   # Selects all bold tags from within the title of an ATOM feed's entries (perhaps to nab a section name prefix) 
     472      #   assert_select_feed :atom, 1.0 do 
     473      #     # Select each entry item and then the title item 
     474      #     assert_select "entry>title" do 
     475      #       # Run assertions on the encoded title elements 
     476      #       assert_select_encoded do 
     477      #         assert_select "b" 
     478      #       end 
     479      #     end 
     480      #   end 
     481      #    
    458482      # 
     483      #   # Selects all paragraph tags from within the description of an RSS feed 
    459484      #   assert_select_feed :rss, 2.0 do 
    460485      #     # Select description element of each feed item. 
    461486      #     assert_select "channel>item>description" do 
    …… 
    506531      # You must enable deliveries for this assertion to work, use: 
    507532      #   ActionMailer::Base.perform_deliveries = true 
    508533      # 
    509       # === Example 
     534      # ==== Examples 
    510535      # 
    511       # assert_select_email do 
    512       #   assert_select "h1", "Email alert" 
    513       # end 
     536      #  assert_select_email do 
     537      #    assert_select "h1", "Email alert" 
     538      #  end 
     539      # 
     540      #  assert_select_email do 
     541      #    items = assert_select "ol>li" 
     542      #    items.each do 
     543      #       # Work with items here... 
     544      #    end 
     545      #  end 
     546      # 
    514547      def assert_select_email(&block) 
    515548        deliveries = ActionMailer::Base.deliveries 
    516549        assert !deliveries.empty?, "No e-mail in delivery list"