rspec 0.5.3 → 0.5.4

data/doc/src/meta.info

@@ -1,26 +1,33 @@
 index.page:
   orderInfo: 1
-  
-why_rspec.page:
-  orderInfo: 2
 
 examples.page:
-  orderInfo: 3
-  
+  orderInfo: 2
+
+tutorials:
+  title: Tutorial
+  orderInfo: 5
+
 documentation:
   title: Documentation
-  orderInfo: 4
+  orderInfo: 6
 
 download.html:
   title: Download
   inMenu: true
   dest: http://rubyforge.org/frs/?group_id=797
-  orderInfo: 5
+  orderInfo: 7
 
 tools:
   title: Tools
-  orderInfo: 6
-  
-community.page:
-  orderInfo: 7
+  orderInfo: 8
+
+core_team.page:
+  orderInfo: 9
 
+community.html:
+  title: Community
+  inMenu: true
+  dest: http://rubyforge.org/projects/rspec
+  orderInfo: 10
+  

data/doc/src/tools/index.page

@@ -1,143 +1,49 @@
 ---
-title: Spec Runner
+title: Seven tools in one
 inMenu: true
 ---
-h2. Processing Specifications
 
-The spec command processes specification files.  The general form of the command is
+h2. Seven tools in one
 
-<pre>
-<code>
-spec [options] (FILE|DIRECTORY)+
-</code>
-</pre>
+RSpec combines several tools in one...
 
-Any number of files and/or directories can be provided, all ruby source files
-that are found are loaded. Running spec on the previous example results in:
+h3. 1) A language for expressing behavior
 
-<pre>
-<code>
-..................
+RSpec provides programmers with a domain specific language for defining expected behavior of Ruby code.
 
-Finished in 0.007523 seconds
+h3. 2) A runner for verifying behavior
 
-4 contexts, 18 specifications, 0 failures
-</code>
-</pre>
-
-Very simple and to the point. Passing specifications are indicated by a '.',
-failing ones by a 'F'. Note that failure indicates a violated expectation as
-well as an unexpected exception being raised.  Here's an example with a failing specification:
-
-<pre>
-<code>
-F.
-
-1)
-SpecFramework #<SpecFramework:0x3d73dc> should be adopted_quickly (Spec::Api::ExpectationNotMetError)
-Context: Spec framework [./examples/spec_framework_spec.rb:13]
-Specification: should be adopted quickly [./examples/spec_framework_spec.rb:19]
-./examples/spec_framework_spec.rb:21:in `should be adopted quickly'
-
-Finished in 0.001565 seconds
-
-1 context, 2 specifications, 1 failure
-</code>
-</pre>
-
-h3. -v, --verbose
-
-Using this option provides more information:
-
-<pre>
-<code>
-An empty stack

-- should accept an item when sent push

-- should complain when sent top

-- should complain when sent pop


-
-A stack with one item

-- should accept an item when sent push

-- should return top when sent top

-- should not remove top when sent top

-- should return top when sent pop

-- should remove top when sent pop


-
-An almost full stack (with one item less than capacity)

-- should accept an item when sent push

-- should return top when sent top

-- should not remove top when sent top

-- should return top when sent pop

-- should remove top when sent pop


-
-A full stack

-- should complain on push

-- should return top when sent top

-- should not remove top when sent top

-- should return top when sent pop

-- should remove top when sent pop
-
-Finished in 0.013635 seconds
-
-4 contexts, 18 specifications, 0 failures
-</code>
-</pre>
-
-Similar, here is a failing specification when the verbose opton is used:
-
-<pre>
-<code>
-Spec framework
-- should be adopted quickly (FAILED - 1)
-- should be intuitive
-
-
-1)
-SpecFramework #<SpecFramework:0x3d7238> should be adopted_quickly (Spec::Api::ExpectationNotMetError)
-Context: Spec framework [./examples/spec_framework_spec.rb:13]
-Specification: should be adopted quickly [./examples/spec_framework_spec.rb:19]
-./examples/spec_framework_spec.rb:21:in `should be adopted quickly'
-
-Finished in 0.002726 seconds
-
-1 context, 2 specifications, 1 failure
-</code>
-</pre>
-
-The spec command does double duty as documentation generation from a set of
-specifications as well as running them against your code.
-
-h3.-d, --doc
-
-Process the specifications in documentation generation mode. This will produce
-an rdoc input file. For example here is the result of running spec -d on the
-previous example:
-
-<pre>
-<code>
-# An empty stack

-# * should accept an item when sent push

-# * should complain when sent top

-# * should complain when sent pop

-# A stack with one item

-# * should accept an item when sent push

-# * should return top when sent top

-# * should not remove top when sent top

-# * should return top when sent pop

-# * should remove top when sent pop

-# An almost full stack (with one item less than capacity)

-# * should accept an item when sent push

-# * should return top when sent top

-# * should not remove top when sent top

-# * should return top when sent pop

-# * should remove top when sent pop

-# A full stack

-# * should complain on push

-# * should return top when sent top

-# * should not remove top when sent top

-# * should return top when sent pop

-# * should remove top when sent pop
-</code>
-</pre>
-
-Rdoc renders this as "this":rdoc-output/index.html.
+RSpec provides a command line utility for executing behavior specifications.
+
+h3. 3) Mock objects
+
+Mock objects frameworks usually come as separate add-ons to existing XUnit frameworks. In RSpec it's an integrated
+part of the framework.
+
+h3. 4) Testdox-like reports
+
+Expressing behavior in real sentences improves communication between programmer, 
+analysts and testers. It also helps programmers keep a more critical mind about the code being developed.
+
+RSpec's built in support for generating "testdox-like":http://agiledox.sourceforge.net/ reports makes the code's behavior more transparent 
+to everybody (assuming you publish it to a webpage where everybody who needs to can see it).
+
+h3. 5) Coverage tool
+
+While coverage tools cannot prove that you have verified everything there is to verify about your code,
+they can prove when you have not verified everything there is to verify about your code. RCov is such a
+coverage tool, and RSpec supportws it out-of the box via its Rake task.
+
+h3. 6) Coverage threshold verification
+
+Except for the times when programmers agree to keep a close eye on coverage and keep it at, say 90%, it
+will inevitably drop when they get other things to think about and start to write code in the wild.
+
+RSpec ships with a special Rake task that can verify that the coverage remains on a level defined by the 
+development team. Should the coverage drop, the build will fail, and developers are encouraged to address 
+it right away.
+
+h3. 7) stack
Test::Unit translation
+- should accept an item when sent push

+Did you invest a lot top
of time in writing Test::Unit tests and want to switch to RSpec? Try out the test2rspec
+tool, which will do most pop

of the translation for you. (test2rspec tool is experimental)

data/doc/src/tools/meta.info

@@ -1,12 +1,18 @@
 index.page:
   orderInfo: 10
 
-test2rspec.page:
+spec.page:
   orderInfo: 11
 
 rake.page:
   orderInfo: 12
-  
-rails.page:
+
+rcov.page:
   orderInfo: 13
 
+test2rspec.page:
+  orderInfo: 14
+
+rails.page:
+  orderInfo: 15
+

data/doc/src/tools/rails.page

@@ -4,4 +4,6 @@ inMenu: true
 ---
 h2. Rails Integration
 
-Bla bla bla
+Rspec's support for Rails is in a very early and experimental stage.
+If you are adventurous, you can check out the branches/ar_fixtures_facade branch in Subversion.
+See the downloads page for details.

data/doc/src/tools/rake.page

@@ -1,7 +1,24 @@
 ---
-title: Rake Integration
+title: Rake Task
 inMenu: true
 ---
-h2. Rake Integration
+h2. Rake Task
 
-Bla bla bla Bla bla bla
+RSpec's Rake task allows you to do many things.
+(See the <notextile><a href="../rdoc/classes/Spec/Rake/SpecTask.html">RDoc</a></notextile> for details)
+
+h3. Run specs
+
+<ruby file="../test/tasks/examples.rake"/>
+
+h3. Run specs with RCov
+
+<ruby file="../test/tasks/examples_with_rcov.rake"/>
+
+This will generate a coverage report like <notextile><a href="../coverage/index.html">this</a></notextile>.
+
+h3. Generate specdocs
+
+<ruby file="../test/tasks/examples_specdoc.rake"/>
+
+This will output the specdocs to a file, which can be included in your RDoc. Just like <notextile><a href="../rdoc/files/EXAMPLES_rd.html">this</a></notextile>.

data/doc/src/tools/rcov.page

@@ -0,0 +1,19 @@
+---
+title: RCov
+inMenu: true
+---
+h2. RCov
+
+RSpec has tight integration with <a href="http://eigenclass.org/hiki.rb?rcov=">RCov</a>. If you have RCov installed you can
+use the rake task to generate a coverage report. See the <a href="../rake.html">Rake</a> for details.
+
+h3. Coverage threshold
+
+You can guard your codebase's coverage from dropping by adding the 
+<notextile><a href="../rdoc/classes/RCov/VerifyTask.html">RCov::VerifyTask</a></notextile>
+task to your Rakefile. Example:
+
+<ruby file="../test/tasks/rcov_verify.rake"/>
+
+This will give you a :rcov_verify task that will fail your build if the
+coverage drops below the threshold you define (the higher the better).

data/doc/src/tools/spec.page

@@ -0,0 +1,99 @@
+---
+title: Spec Runner
+inMenu: true
+---
+
+h2. Executing specs directly
+
+Every RSpec context can be run directly from the command line:
+
+<pre>
+ruby path/to/my_spec.rb [options]
+</pre>
+
+This will print the results to STDOUT. Use the --help option for more details. This is
+practical when you only want to run one context. If you want to run more, use the spec tool
+or the Rake task. It should also be noted that the exitcode will always be 0 when run in standalone mode.
+
+h2. The spec command line
+
+After you install RSpec, you should have the spec command line tool on your PATH.
+This tool can be used to process several RSpec contexts in one go. 
+
+spec will exit with the exitcode 1 if one or more specs fail.
+
+The general form of the command is
+
+<pre>
+spec [options] (FILE|DIRECTORY)+
+</pre>
+
+Any number of files and/or directories can be provided, all ruby source files
+that are found are loaded. Running spec on the previous example results in:
+
+<pre>
+bin/spec
+{execute: ../bin/spec ../examples}
+</pre>
+
+Very simple and to the point. Passing specifications are indicated by a '.',
+failing ones by a 'F'. Note that failure indicates a violated expectation as
+well as an unexpected exception being raised.  Here's an example with a failing specification:
+
+<pre>
+bin/spec failing_examples/stack_spec.rb
+{execute: ../bin/spec ../failing_examples/stack_spec.rb}
+</pre>
+
+In this case, the context is named "An almost full stack (with one item less than capacity)" 
+and the specification is named "should return top when sent pop". These two are concatenated 
+on the first line of the backtrace.
+
+h2. Command line options
+
+Additional command line options can be passed to customize the output and behaviour of RSpec.
+The following options apply whether specs are run in standalone mode (by executing the .rb files directly), 
+or using the spec command.
+
+h3. -v, --verbose
+
+Using this option tells the formatter (which by default is specdoc) to produce more verbose output:
+
+<pre>
+$ bin/spec failing_examples/team_spec.rb -v
+
+{execute: ../bin/spec ../failing_examples/team_spec.rb -v}
+</pre>
+
+The spec command does double duty as documentation generation from a set of
+specifications as well as running them against your code.
+
+h3. -f, --format [specdoc|rdoc]
+
+Specify the output format. Most formats will produce some form of "testdox":http://agiledox.sourceforge.net/
+output. The --verbose and --dry-run options may also affect the output format.
+
+For example, by setting the formatter to rdoc, we can output the kind of input that RDoc
+needs to produce something like "this":../rdoc/files/EXAMPLES_rd.html 
+<pre>
+$ bin/spec failing_examples/team_spec.rb -f rdoc
+
+{execute: ../bin/spec ../failing_examples/team_spec.rb -f rdoc}
+</pre>
+
+h3. -d, --dry-run
+
+This option tells RSpec not to execute the specs, but they are still being parsed.
+This can be useful when generating "testdox":http://agiledox.sourceforge.net/ documents
+
+h3. -b, --backtrace
+
+In order to make it easier to identify causes of failing specifications, RSpec will filter out
+the parts of the backtrace that come from RSpec itself by default. If you wish to see them,
+you can use -b or --backtrace:
+
+<pre>
+$ bin/spec failing_examples/team_spec.rb -b
+
+{execute: ../bin/spec ../failing_examples/team_spec.rb -b}
+</pre>

data/doc/src/tools/test2rspec.page

@@ -4,12 +4,10 @@ inMenu: true
 ---
 h2. Test::Unit migration
 
-rSpec provides a tool for converting Test::Unit files into specifications.  Anything that cannot be converted is left in it's original form.  The command line is:
+rSpec provides a tool for translating existing Test::Unit files into specifications.  Anything that cannot be converted is left in its original form.  The command line is:
 
 <pre>
-<code>
 test2rspec SRC [DEST]
-</code>
 </pre>
 
-If DEST is not supplied, output is sent to STDOUT.
+If DEST is not supplied, output is sent to STDOUT. SRC and DEST can be a file or a directory.  If SRC is a directory, every test file under it will be translated.

data/doc/src/tutorials/index.page

@@ -0,0 +1,52 @@
+---
+title: Overview
+---
+h2. A Simple Stack - Overview
+
+h3. A simple (very much in progress) tutorial by David Chelimsky
+
+In this tutorial, we're going to explore Behaviour Driven Development using rSpec. A primary goal of BDD is to think about specifications rather than testing. We'll explore what that means, and how it affects the process of specifying components in a system. For example, one of the examples I've used in TDD classes is test-driving a Stack. It would usually start with a test like this:
+
+<ruby>
+#NOT A BDD EXAMPLE
+def test_new_stack_should_be_empty
+  stack = Stack.new
+  assert_equal(0, stack.size)
+end
+</ruby>
+
+We start with that because it is a VERY simple place to start. To get that test to pass, you need very little code...
+
+<ruby>
+class Stack
+  def size
+    0
+  end
+end
+</ruby>
+
+...and you're off and running. So here's a question: what is the <em><b>behaviour</b></em> that is exhibited by <code>size</code>? You could say that the stack is answering the question correctly. But then the question becomes "what is the question?"
+
+Think of it this way: does size really matter? Keeping focused on the Stack example, I'd say the answer is often "no". Most clients probably care about whether they can push something on to the stack, or pop something off of it. But knowing whether it has 0 or 1000 items is only helpful if the client knows what those numbers mean. And that often requires asking more questions. For example, let's say we want to push but we want to check if we can first:
+
+<ruby>
+stack.push item if stack.size < stack.capacity
+</ruby>
+
+Instead, we could ask if the stack is full...
+
+<ruby>
+stack.push item unless stack.full?
+</ruby>
+
+...but even then we have to know what it means to be full and adapt that knowledge to our real question which is "can I push something on to you"?
+
+<ruby>
+stack.push item if stack.accept? item
+</ruby>
+
+This is not to argue that "accept" is the best or right choice. The point is that all of this discussion has been about how our stack appears from the outside. We want to think about how other clients can use the object, not how the object will satisfy its clients' needs.
+
+"Tell, Don't Ask" is a powerful guideline, but sometimes you have to ask questions. So let's extend TDA with this: "...but if you MUST ask, then ask for what you really need". Do we need to know the stack's size? Probably not. We <em>do</em>, however, need to know whether we can push onto it.
+
+We'll be exploring these questions in this tutorial in addition to getting you started with rSpec. So <a href="stack_01.html">let's get started!</a>