Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Update rspec-rails section (still in progress)

- clean up main page
- include generators on main page and redirect from old generators page
  to main page
- add placeholders for routing and mailer spec docs
  • Loading branch information...
commit 32bc233a78f7eff9b428e93834800f1574c016d2 1 parent ada9e2a
David Chelimsky dchelimsky authored
2  content/css/default.css
View
@@ -158,7 +158,7 @@ acronym {
}
#content code {
font-family:monospace;
- font-size:1.3em;
+ /* font-size:1.2em; */
background-color:#F0F0F0;
}
#content pre {
2  content/rails/generators.html
View
@@ -1,3 +1,3 @@
<script language="javascript">
- window.location = "/rspec-rails/generators.html"
+ window.location = "/rspec-rails/"
</script>
2  content/rspec-rails/changelog.page
View
@@ -1,6 +1,6 @@
---
title: changelog
-order: 5
+order: 9
filter:
- erb
- textile
31 content/rspec-rails/generators.page
View
@@ -1,31 +0,0 @@
----
-title: generators
-order: 3
-filter:
- - erb
- - textile
----
-
-h2. <%= @page.title %>
-
-Spec::Rails contains generators that you can use to generate models and RESTful controllers
-in a similar fashion to Rails' builtin generators. The only difference is that they generate specs instead
-of tests and fixtures will be put under the spec folder. Example:
-
-<pre>
-ruby script/generate rspec_scaffold purchase order_id:integer created_at:datetime amount:decimal
-</pre>
-
-or
-
-<pre>
-ruby script/generate rspec_model person
-</pre>
-
-or
-
-<pre>
-ruby script/generate rspec_controller person
-</pre>
-
-For more information on each generator, just run them without any arguments.
152 content/rspec-rails/index.page
View
@@ -3,68 +3,38 @@ title: rspec-rails
order: 4
filter:
- erb
- - textile
+ - markdown
---
-h2. <%= @page.title %>
+## <%= @page.title %>
-A Rails plugin that brings RSpec to Rails.
+The rspec-rails gem extends rspec-core and Rails' built-in testing framework to
+support full-stack, application-level specs (request specs), as well is
+isolated specs for models, views, controllers, helpers, mailers, and routing.
-h3. Features
+## Install
-* Use RSpec to independently specify models, views, controllers and helpers.
-* Integrated fixture loading.
-* Special generators for models and controllers that generate specs instead of tests.
-* Special RSpec matchers for even more readable specs.
+First, add rspec-rails to your Gemfile:
-h3. Vision
-
-For people for whom TDD is a brand new concept, the testing support built into Rails is a huge
-leap forward. The fact that it's built right in is fantastic, and Rails
-apps are generally much easier to maintain than they would have been without such support.
-
-For those of us coming from a history with TDD, and now BDD, the existing support
-presents some problems related to dependencies across specs. To that end, RSpec
-supports 4 types of specs. This is largely inspired by Test::Rails, which is
-the rails testing framework built into "ZenTest":http://zentest.rubyforge.org.
-We've also built in first class mocking and stubbing support in order to
-break dependencies across these different concerns.
-
-h2. Different Types of Example Groups
-
-Spec::Rails supports different ExampleGroup subclasses for the following types of specs:
-
-h3. Model Examples
-
-These are the equivalent of unit tests in Rails' built in testing. Ironically
-(for the traditional TDD'er) these are the only specs that we feel should actually interact
-with the database. "Learn more ...":writing/models.html.
-
-h3. Controller Examples
-
-These align somewhat with functional tests in rails, except
-that they do not actually render views (though you can force rendering of views
-if you prefer). Instead of setting expectations about what goes on a page, you
-set expectations about what templates get rendered. "Learn more...":writing/controllers.html.
-
-h3. View Examples
-
-This is the other half of Rails' functional testing. View specs allow
-you to set up assigns (thanks to ZenTest). "Learn more ...":writing/views.html.
-
-h3. Helper Examples
+<% coderay do -%>
+gem "rspec-rails", :group => [:development, :test]
+<% end -%>
-... let you specify directly methods that live in your helpers. "Learn more ...":writing/helpers.html.
+It needs to be in the `:development` group to expose the generators and rake
+tasks to your development environment. Otherwise you'd have to type
+`RAILS_ENV=test rails generate ....`, and who wants that?
-h2. Fixtures
+Now install the bundle and the rspec files and directories:
-You can use fixture in any of your specs, be they model, view, controller, or helper. If you have fixtures that you want to use
-globally, you can set them in spec/spec_helper.rb. See that file for more information.
+<% coderay :shell do -%>
+bundle install
+rails generate rspec:install
+<% end -%>
-h2. Naming conventions
+## Directory structure
-For clarity and consistency, RSpec uses a slightly different naming convention
-for directories and Rake tasks than what you get from the Test::Unit testing built into rails.
+rspec-rails uses a directory naming convention based on the component being
+spec'd:
<% coderay do -%>
project
@@ -81,43 +51,75 @@ project
|
+-- helpers
|
+ +-- mailers
+ |
+-- models
|
+ +-- requests
+ |
+ +-- routing
+ |
+ +-- support
+ |
+-- views
<% end -%>
-The Rake tasks are named accordingly.
+Model, view, controller, helper, mailer, and routing specs each focus on the
+named component.
-h2. Introduction to Writing Examples using Spec::Rails
+Request specs wrap Rails' integration tests. These go through the full stack,
+including the router. By themselves, or combined with
+[Capybara](https://github.com/jnicklas/capybara), request specs are a great
+starting point for outside-in development if you're not using another tool like
+[Cucumber](http://cukes.info) or [Fitnesse](http://fitnesse.org). The name
+"request specs" came out of the Merb project. We use that instead of
+"integration" or "acceptance" due to the lack of consensus on what those names
+mean.
-Spec::Rails supports 4 different types of Executable Examples:
+The generated `spec_helper.rb` file requires any `.rb` files in the "support"
+directory, which is the conventional container for helpers, custom matchers,
+etc.
-* "Model Examples":models.html
-* "View Examples":views.html
-* "Controller Examples":controllers.html
-* "Helper Examples":helpers.html
+## Fixtures
-Each of these use specialized ExampleGroup subclasses to give you access to
-the appropriate services and methods. The specific type of ExampleGroup is
-determined implicitly by placing the examples in an appropriately named file
-(*_spec.rb) within an appropriately named directory:
+While most of the Rails world uses factories these days, you _can_ still use
+Rails fixtures the same way you would use them in the Rails testing framework.
+First, declare their location in `spec_helper.rb`:
-<pre>
-spec/controllers/**/*_spec.rb
-spec/helpers/**/*_spec.rb
-spec/models/**/*_spec.rb
-spec/views/**/*_spec.rb
-</pre>
+<% coderay do -%>
+RSpec.configure do |config|
+ config.fixture_path = "#{::Rails.root}/spec/fixtures"
+end
+<% end -%>
-%{color:red;font-weight:bold}WARNING:% If you do not follow these conventions,
-you will not get the correct ExampleGroup subclass. If you prefer to disregard
-this convention, you can get the correct ExampleGroup subclass by passing a
-hash to the describe method:
+Now declare which fixtures you want to use in each example group:
<% coderay do -%>
-describe "some model", :type => :model do
- ...
+describe WidgetsController do
+ fixtures :widgets
end
<% end -%>
-This works with <code>:model, :view, :controller and :helper</code>.
+You can also declare them globally in `spec_helper.rb`:
+
+<% coderay do -%>
+RSpec.configure do |config|
+ config.global_fixtures = [:things, :widgets]
+end
+<% end -%>
+
+## Generators
+
+When you include rspec-rails in the `:development` group in your `Gemfile`,
+rspec-rails registers itself with Rails as the generator for tests. The only
+rspec-specific generator you need to know about is `rspec:install`, mentioned
+above. Otherwise, just run the rails generators and you'll get specs for free:
+
+<% coderay do -%>
+rails generate model thing name:string
+ invoke active_record
+ create db/migrate/20111013140413_create_things.rb
+ create app/models/thing.rb
+ invoke rspec
+ create spec/models/thing_spec.rb
+<% end -%>
11 content/rspec-rails/mailers.page
View
@@ -0,0 +1,11 @@
+---
+title: mailers
+order: 5
+filter:
+ - erb
+ - textile
+---
+
+h2. <%= @page.title %>
+
+Coming soon ...
11 content/rspec-rails/routing.page
View
@@ -0,0 +1,11 @@
+---
+title: routing
+order: 6
+filter:
+ - erb
+ - textile
+---
+
+h2. <%= @page.title %>
+
+Coming soon ...
2  content/rspec-rails/runners.page
View
@@ -1,6 +1,6 @@
---
title: runners
-order: 4
+order: 8
filter:
- erb
- textile
63 content/rspec-rails/views.page
View
@@ -3,32 +3,36 @@ title: views
order: 2
filter:
- erb
- - textile
+ - markdown
---
-h2. <%= @page.title %>
+## <%= @page.title %>
-View Examples live in $RAILS_ROOT/spec/views/.
+View examples live in `spec/views/`.
-Spec::Rails supports the specification of views in complete isolation from their controllers.
-This allows you to spec and write your views even before their controllers exist,
-or before the related actions have been developed. It also means that bugs introduced
-into controllers will not cause view specs to fail.
+rspec-rails supports the specification of views in complete isolation from
+their controllers. This allows you to spec and write your views even before
+their controllers exist, or before the related actions have been developed. It
+also means that bugs introduced into controllers will not cause view specs to
+fail.
-As noted in the "introduction":index.html, these are great benefits
-but they could hide bugs that exist in the interaction between a controller and its
-view. We strongly recommend combining these isolated view specs with some sort of
-high level integration testing, ideally using "Cucumber":http://github.com/aslakhellesoy/cucumber
+As noted in the "introduction":index.html, these are great benefits but they
+could hide bugs that exist in the interaction between a controller and its
+view. We strongly recommend combining these isolated view specs with some sort
+of application level functional testing, ideally using
+"Cucumber":http://github.com/aslakhellesoy/cucumber
-Here are some of the methods available to you, but see "Spec::Rails::Expectations":../../../rdoc-rails/index.html for more detail.
+Here are some of the methods available to you, but see
+"rspec-rails::Expectations":../../../rdoc-rails/index.html for more detail.
-h2. Conveniences
+## Conveniences
-h3. assigns
+### assigns
-Use assigns[:key] to set instance variables to be used in the view. We highly recommend that
-you exploit the mock framework here rather than providing real model objects in order to
-keep the view specs isolated from changes to your models.
+Use assigns[:key] to set instance variables to be used in the view. We highly
+recommend that you exploit the mock framework here rather than providing real
+model objects in order to keep the view specs isolated from changes to your
+models.
<% coderay do -%>
# example
@@ -43,10 +47,10 @@ assigns[:articles] = [article]
<!-- etc -->
<% end -%>
-h3. flash, params and session
+### flash, params and session
-Use flash[:key], params[:key] and session[:key] to set values in the example that can
-be accessed by the view.
+Use flash[:key], params[:key] and session[:key] to set values in the example
+that can be accessed by the view.
<% coderay do -%>
# example
@@ -60,13 +64,14 @@ session[:user_id] = "5678"
<%%= session[:user_id] %>
<% end -%>
-h2. Expectations
+## Expectations
-Spec::Rails' View Examples support the following custom expectations.
+rspec-rails' View Examples support the following custom expectations.
-h3. response.should have_tag
+### response.should have_tag
-This wraps assert_select and is available in both View Examples and Controller Examples run in integration mode.
+This wraps assert_select and is available in both View Examples and Controller
+Examples run in integration mode.
<% coderay do -%>
response.should have_tag('div') #passes if any div tags appear
@@ -85,9 +90,10 @@ end
Note that any of the hash values can be either Strings or Regexps and will be
evaluated accordingly.
-h3. response[:capture].should have_tag
+### response[:capture].should have_tag
-This way you can access content that has been captured with <tt>content_for</tt>.
+This way you can access content that has been captured with
+<tt>content_for</tt>.
<ruby>
# example
@@ -99,9 +105,10 @@ response[:sidebar].should have_tag('div')
&lt;% end %>
</ruby>
-h2. Mocking and stubbing helpers
+## Mocking and stubbing helpers
-If you wish to mock or stub helper methods, this must be done on the <tt>template</tt> object:
+If you wish to mock or stub helper methods, this must be done on the
+<tt>template</tt> object:
<% coderay do -%>
template.should_receive(:current_user).and_return(mock("user"))
Please sign in to comment.
Something went wrong with that request. Please try again.