vendor/plugins/rspec/doc/src/documentation/rails/writing/views.page

   1 ---
   2 title: Views
   3 ---
   4 h2. Spec::Rails - Specifying Views
   5
   6 View Examples live in $RAILS_ROOT/spec/views/.
   7
   8 Spec::Rails supports the specification of views in complete isolation from their controllers.
   9 This allows you to spec and write your views even before their controllers exist,
  10 or before the related actions have been developed. It also means that bugs introduced
  11 into controllers will not cause view specs to fail.
  12
  13 As noted in the "introduction":index.html, these are great benefits
  14 but they could hide bugs that exist in the interaction between a controller and its
  15 view. We strongly recommend combining these isolated view specs with some sort of
  16 high level "integration":integration.html testing.
  17
  18 Here are some of the methods available to you, but see "Spec::Rails::Expectations":../../../rdoc-rails/index.html for more detail.
  19
  20 h2. Conveniences
  21
  22 h3. assigns
  23
  24 Use assigns[:key] to set instance variables to be used in the view. We highly recommend that
  25 you exploit the mock framework here rather than providing real model objects in order to
  26 keep the view specs isolated from changes to your models.
  27
  28 <ruby>
  29 # example
  30 article = mock_model(Article)
  31 article.should_receive(:author).and_return("Joe")
  32 article.should_receive(:text).and_return("this is the text of the article")
  33 assigns[:article] = article
  34 assigns[:articles] = [article]
  35
  36 # template
  37 <% for article in @articles -%>
  38 <!-- etc -->
  39 </ruby>
  40
  41 h3. flash, params and session
  42
  43 Use flash[:key], params[:key] and session[:key] to set values in the example that can
  44 be accessed by the view.
  45
  46 <ruby>
  47 # example
  48 flash[:notice] = "Message in flash"
  49 params[:account_id] = "1234"
  50 session[:user_id] = "5678"
  51
  52 # template
  53 <%= flash[:notice] %>
  54 <%= params[:account_id] %>
  55 <%= session[:user_id] %>
  56 </ruby>
  57
  58 h2. Expectations
  59
  60 Spec::Rails' View Examples support the following custom expectations.
  61
  62 h3. template.expect_render/stub_render
  63
  64 This is a custom mock-like expectation that allows you to set expectations about partials and included
  65 files that will be rendered, intercepting those calls to the #render method, while ignoring other calls
  66 and passing them on to ActionView::Base. <code>expect_render</code> is verified at the end of the
  67 example, while <code>stub_render</code> is not.
  68
  69 %{color:red;font-weight:bold}WARNING%: expect_render and stub_render, while very useful, act
  70 differently from standard Message Expectations (a.k.a. mock expectations), which would never pass calls
  71 through to the real object. This can be very confusing when there are failures if you're not aware of this
  72 fact, because some calls will be passed through while others will not. This is especially confusing when
  73 you use <code>stub_render</code> because, as with all Method Stubs, you will get very little feedback
  74 about what is going on.
  75
  76 <ruby>
  77 template.expect_render(:partial => 'person', :object => @person) #auto-verified
  78 template.stub_render(:partial => 'person', :object => @person)   #not verified
  79 </ruby>
  80
  81
  82 h3. response.should have_tag
  83
  84 This wraps assert_select and is available in both View Examples and Controller Examples run in integration mode.
  85
  86 <ruby>
  87 response.should have_tag('div') #passes if any div tags appear
  88 response.should have_tag('div#interesting_div')
  89 response.should have_tag('div', 'expected content')
  90 response.should have_tag('div', /regexp matching expected content/)
  91 response.should have_tag('form[action=?]', things_path)
  92 response.should have_tag("input[type=?][checked=?]", 'checkbox', 'checked')
  93 response.should have_tag('ul') do
  94   with_tag('li', 'list item 1')
  95   with_tag('li', 'list item 2')
  96   with_tag('li', 'list item 3')
  97 end
  98 </ruby>
  99
 100 Note that any of the hash values can be either Strings or Regexps and will be
 101 evaluated accordingly.
 102
 103 h2. Mocking and stubbing helpers
 104
 105 If you wish to mock or stub helper methods, this must be done on the <tt>template</tt> object:
 106
 107 <ruby>
 108 template.should_receive(:current_user).and_return(mock("user"))
 109 </ruby>
 110
 111 %{color:red;font-weight:bold}WARNING:% Do NOT use mocks on the template object for expecting partials.
 112 Instead, use expect_render or stub_render, described above.
 113
 114 h2. Sample View Examples
 115
 116 <ruby file="../example_rails_app/spec/views/person/list_view_spec.rb"/>