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

Changeset 8300

Show
Ignore:
Timestamp:
12/05/07 18:17:23 (1 year ago)
Author:
marcel
Message:

Add many examples to assertion documentation. Closes #7803 [jeremymcanally]

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/actionpack/CHANGELOG

    r8287 r8300  
    11*SVN* 
     2 
     3* Add many examples to assertion documentation. Closes #7803 [jeremymcanally] 
    24 
    35* Document the supported options for sortable_element. Closes #8820 [berkelep] 

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

    r8284 r8300  
    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: 

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

    r6470 r8300  
    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. 
    …… 
    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:  
    …… 
    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 
    …… 
    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  
    …… 
    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) 

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

    r8237 r8300  
    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. 
    …… 
    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 
    …… 
    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: 
    …… 
    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| 
    …… 
    5667      #     ... 
    5768      #   end 
     69      # 
    5870      def css_select(*args) 
    5971        # See assert_select to understand what's going on here. 
    …… 
    107119      # run the assertion for each element selected by the enclosing assertion. 
    108120      # 
    109       # For example: 
     121      # ==== Example 
    110122      #   assert_select "ol>li" do |elements| 
    111123      #     elements.each do |element| 
    …… 
    113125      #     end 
    114126      #   end 
     127      # 
    115128      # Or for short: 
    116129      #   assert_select "ol>li" do 
    …… 
    150163      # evaluated the block is called with an array of all matched elements. 
    151164      # 
    152       # === Examples 
     165      # ==== Examples 
    153166      # 
    154167      #   # At least one form element 
    …… 
    354367      # or JavaScript. 
    355368      # 
    356       # === Examples 
     369      # ==== Examples 
    357370      # 
    358371      #   # Replacing the element foo. 
    …… 
    469482      # element +encoded+. It then calls the block with all un-encoded elements. 
    470483      # 
    471       # === Example 
    472       # 
     484      # ==== Examples 
     485      #   # Selects all bold tags from within the title of an ATOM feed's entries (perhaps to nab a section name prefix) 
     486      #   assert_select_feed :atom, 1.0 do 
     487      #     # Select each entry item and then the title item 
     488      #     assert_select "entry>title" do 
     489      #       # Run assertions on the encoded title elements 
     490      #       assert_select_encoded do 
     491      #         assert_select "b" 
     492      #       end 
     493      #     end 
     494      #   end 
     495      #    
     496      # 
     497      #   # Selects all paragraph tags from within the description of an RSS feed 
    473498      #   assert_select_feed :rss, 2.0 do 
    474499      #     # Select description element of each feed item. 
    …… 
    521546      #   ActionMailer::Base.perform_deliveries = true 
    522547      # 
    523       # === Example 
    524       # 
    525       # assert_select_email do 
    526       #   assert_select "h1", "Email alert" 
    527       # end 
     548      # ==== Examples 
     549      # 
     550      #  assert_select_email do 
     551      #    assert_select "h1", "Email alert" 
     552      #  end 
     553      # 
     554      #  assert_select_email do 
     555      #    items = assert_select "ol>li" 
     556      #    items.each do 
     557      #       # Work with items here... 
     558      #    end 
     559      #  end 
     560      # 
    528561      def assert_select_email(&block) 
    529562        deliveries = ActionMailer::Base.deliveries 

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

    r8095 r8300  
    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 
    …… 
    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/ 
    …… 
    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