aslakhellesoy-cucumber 0.1.2 → 0.1.3

data/Manifest.txt

@@ -2,6 +2,7 @@ History.txt
 License.txt
 Manifest.txt
 README.textile
+README.txt
 Rakefile
 TODO.txt
 bin/cucumber
@@ -10,8 +11,11 @@ config/requirements.rb
 examples/calculator/Rakefile
 examples/calculator/features/addition.feature
 examples/calculator/features/division.feature
-examples/calculator/features/steps/addition_steps.rb
+examples/calculator/features/steps/calculator_steps.rb
 examples/calculator/lib/calculator.rb
+examples/calculator_ruby_features/Rakefile
+examples/calculator_ruby_features/features/addition.rb
+examples/calculator_ruby_features/features/steps/calculator_steps.rb
 examples/java/README.textile
 examples/java/Rakefile
 examples/java/features/hello.feature
@@ -19,21 +23,26 @@ examples/java/features/steps/hello_steps.rb
 examples/java/features/steps/tree_steps.rb
 examples/java/features/tree.feature
 examples/java/src/cucumber/demo/Hello.java
-examples/pure_ruby/Rakefile
-examples/pure_ruby/features/addition.rb
-examples/pure_ruby/features/steps/addition_steps.rb
-examples/simple_norwegian/Rakefile
-examples/simple_norwegian/features/steps/matte_steg.rb.rb
-examples/simple_norwegian/features/summering.feature
-examples/web/Rakefile
-examples/web/features/search.feature
-examples/web/features/steps/stories_steps.rb
+examples/norwegian_calculator/Rakefile
+examples/norwegian_calculator/features/kalkulator_steps.rb
+examples/norwegian_calculator/features/summering.feature
+examples/watir/Rakefile
+examples/watir/features/search.feature
+examples/watir/features/steps/stories_steps.rb
 gem_tasks/deployment.rake
 gem_tasks/environment.rake
 gem_tasks/fix_cr_lf.rake
+gem_tasks/gemspec.rake
 gem_tasks/rspec.rake
 gem_tasks/treetop.rake
 gem_tasks/website.rake
+generators/cucumber/cucumber_generator.rb
+generators/cucumber/templates/common_webrat.rb
+generators/cucumber/templates/cucumber.rake
+generators/cucumber/templates/env.rb
+generators/feature/feature_generator.rb
+generators/feature/templates/feature.erb
+generators/feature/templates/steps.erb
 lib/cucumber.rb
 lib/cucumber/cli.rb
 lib/cucumber/core_ext/proc.rb
@@ -45,6 +54,7 @@ lib/cucumber/formatters/html_formatter.rb
 lib/cucumber/formatters/pretty_formatter.rb
 lib/cucumber/formatters/progress_formatter.rb
 lib/cucumber/languages.yml
+lib/cucumber/rails/rspec.rb
 lib/cucumber/rails/world.rb
 lib/cucumber/rake/task.rb
 lib/cucumber/step_methods.rb
@@ -78,6 +88,8 @@ spec/cucumber/formatters/ansicolor_spec.rb
 spec/cucumber/formatters/features.html
 spec/cucumber/formatters/html_formatter_spec.rb
 spec/cucumber/sell_cucumbers.feature
+spec/cucumber/treetop_parser/feature_parser_spec.rb
+spec/cucumber/treetop_parser/spaces.feature
 spec/spec.opts
 spec/spec_helper.rb
 website/index.html

data/README.textile

@@ -1,13 +1,19 @@
 h1. Cucumber
 
-"Cucumber":http://github.com/aslakhellesoy/cucumber is a tool that can execute documentation written in plain text. Cucumber targets non technical domain experts as well as
-programmers and QA people. Cucumber itself is written in Ruby, but it can be used to "test" code written in Ruby, Java 
-(or web applications written in any language). When "IronRuby":http://www.ironruby.net/ matures it can be used to "test"
-.NET code too.
+"Cucumber":http://github.com/aslakhellesoy/cucumber is a tool that can execute feature documentation written in plain text. 
+Cucumber targets non technical business analysts, interaction designers, domain experts, testers (for the plain text part) 
+and programmers (for the steps, which are written in Ruby). 
 
-While Cucumber can be thought of as a "testing" tool, most people use it to support "BDD":http://behaviour-driven.org/, so
-the "tests" are typically the first thing that gets written, and the production code is then written outside-in, to make
-the test pass.
+Cucumber itself is also written in Ruby, but it can be used to "test" code written in Ruby, Java (or web applications written 
+in any language). When "IronRuby":http://www.ironruby.net/ matures it can be used to "test" .NET code too.
+
+Cucumber only requires minimal use of Ruby programming, so don't be afraid to try it out even if the code you're
+developing is in a different language. Most programmers should pick up the required Ruby skills and be productive
+with Cucumber in a few of days.
+
+While Cucumber can be thought of as a "testing" tool, the intent of the tool is to support "BDD":http://behaviour-driven.org/
+This means that the "tests" (plain text feature descriptions with scenarios) are typically written before anything else, and 
+the production code is then written outside-in, to make them pass.
 
 h2. Installation
 
@@ -25,16 +31,132 @@ jruby -S gem install aslakhellesoy-cucumber
 
 h2. Getting started
 
-I haven't written a tutorial yet. Take a look at the "examples":http://github.com/aslakhellesoy/cucumber/tree/master/examples.
-Each example directory has a Rakefile, and you can run the features with
+There are several ways to get started, depending on the architecture of your application.
+Take a look at the "examples":http://github.com/aslakhellesoy/cucumber/tree/master/examples.
+Each example directory has a Rakefile, and you can run the features in an example directory with
+
+<pre><code>rake features</code></pre>
+
+The examples deliberately have errors so you can get a taste of how the error output looks like. You can get help by asking 
+for it:
+
+<pre><code>cucumber --help</code></pre>
+
+h2. Ruby on Rails
+
+Cucumber has very nice Rails support, and I really recommend using "Webrat":http://github.com/brynary/webrat
+in the step definitions. Here is how to get you started.
+
+h3. Install Cucumber, Webrat and RSpec
+
+<pre><code>git submodule add cucumber git://github.com/aslakhellesoy/cucumber.git vendor/plugins/cucumber
+git submodule add webrat git://github.com/brynary/webrat.git vendor/plugins/webrat
+git submodule add rspec git://github.com/dchelimsky/rspec.git vendor/plugins/rspec
+git submodule add rspec-rails git://github.com/dchelimsky/rspec-rails.git vendor/plugins/rspec-rails
+</code></pre>
+
+If your own Rails code is not in Git, just replace "submodule add" with "clone".
+
+h3. Install Other dependencies
+
+<pre><code>gem install hpricot cucumber</code></pre>
+
+Yes, you did already install cucumber as a plugin, but this will install all the dependent libraries you need.
+
+h3. Bootstrap Cucumber
+
+You'll need a Rake task and a couple of files that configure Cucumber for use with Ruby on Rails and Webrat.
+You create these with:
+
+<pre><code>ruby script/generate cucumber</code></pre>
+
+Check out the generated files. If you need to, you can go and tweak them later.
+
+h3. Start a feature
+
+It's really, really recommended that you write your features by hand - in collaboration with your
+customer / business analyst / domain expert / interaction designer. However, to get you started (and so you can see how to use
+Webrat), you can use the feature generator to generate the first few features:
+
+<pre><code>ruby script/generate feature Frooble name color description</code></pre>
+
+This will generate a simple plain text feature with associated steps. Don't get addicted to this
+generator - you're better off writing these by hand in the long run. See the BDD tips section below.
+
+h3. Run features
 
 <pre><code>rake features</code></pre>
 
+This should result in failing scenarios, because you haven't written any code yet (I hope). Now you it's time
+to write some code, or generate some. Try this:
+
+<pre><code>script/generate rspec_scaffold Frooble name:string color:string description:text
+rake db:migrate
+rake features
+</code></pre>
+
+h3. Tips
+
+These tips apply to Rails development in general...
+
+* Talk to models directly in *Given* steps to set up a known state. Don't use fixtures.
+* Use Webrat in *When* steps
+* Use *response.should have_tag(...)* (and models) in *Then* steps to verify the *outcomes* (which are on the screen, not only in the database).
+* Organise steps in files named accordingly to resources used
+* Avoid keeping state in @variables in steps. It will couple your steps and make them harder to reuse.
+
+h3. View spec redundancy
+
+Since I recommend you verify outcomes (*Then* steps) by looking at the HTML, you might end up having some degree
+of redundancy with view specs. I recommend you delete generated view specs if you run into too much maintenance
+headaches and rely on the features instead of view specs. However, in some cases it can be handy to use both.
+
+h2. BDD
+
+If you have found a bug or want to add a feature, start by writing a new feature or scenario that describes the
+
+Now run the features again. The one you wrote should have yellow, pending steps - or failing, red ones. 
+(If you don't get that you're doing something wrong, or the feature is already implemented).
+
+This is when you start writing code. You might as well get used to doing it this way, because we won't accept
+any patches unless you also have stories or specs for your code. This is because we don't want to end up with a 
+brittle, unmaintainable, undocumented pile of code that nobody understands. (Yes, stores and specs are *documentation* too).
+
+If you think this sounds annoying, try it out anyway. You'll end up writing better (and less) code this way. Trust me.
+Work outside-in (the outside being the story, the inside being the low level code). Do it the "BDD":http://en.wikipedia.org/wiki/Behavior_driven_development way.
+
+h3. Business value and MMF
+
+You should discuss the "In order to" part of the feature and pop the "why" stack max 5 times (ask why recursively) 
+until you end up with one of the following business values:
+
+* Protect revenue
+* Increase revenue
+* Manage cost
+
+If you're about to implement a feature that doesn't support one of those values, chances are you're about to
+implement a non-valuable feature. Consider tossing it altogether or pushing it down in your backlog. Focus on
+implementing the MMFs (Minimal Marketable Features) that will yield the most value.
+
+h3. Outcomes and bottom-up scenarios.
+
+The value provided by a system is what you can get out of it - not what you put into it. Just like the value
+is expressed at the top of a feature (In order to...), the value should be in the steps of a scenarios too,
+more precicely in the *Then* steps.
+
+When you're writing a new scenario, I recommend you start with the formulation of the desired outcome. Write the
+*Then* steps first. Then write the *When* step to discover the action/operation and finally write the *Given*
+steps that need to be in place in order for the When/Then to make sense.
+
 h2. Background and Credits
 
 Cucumber is a rewrite of RSpec's "Story runner", which was originally written by Dan North. Dan's original
 implementation required that stories be written in Ruby. Shortly after, David Chelimsky added 
-"plain text":http://blog.davidchelimsky.net/articles/2007/10/21/story-runner-in-plain-english support.
+"plain text":http://blog.davidchelimsky.net/articles/2007/10/21/story-runner-in-plain-english support with
+contributions from half a dozen other people.
+
+The business value guidelines and general wording in features is based on several conversations and blog posts
+by Chris Matts, Liz Keogh and Dan North.
 
 This brought executable stories a little closer to non-technical users, which is one of the target audiences
 for this kind of tool.
@@ -49,13 +171,21 @@ Some of the biggest problems with it are:
 * Limited colouring of output.
 * No simple way to execute only one scenario.
 * No command line tool to run stories.
+* No easy before or after hooks.
+
+While all of this could have been fixed in the existing codebase, I figured it would be easier to do a rewrite from scratch. 
+I also had some ideas for extensions of the story grammar (like FIT style tables that you can see in some of the examples), 
+so I decided to base it on a proper 
+"grammar":http://github.com/aslakhellesoy/cucumber/tree/master/lib/cucumber/treetop_parser/feature.treetop.erb using
+"Treetop":http://treetop.rubyforge.org/.
 
-While all of this could have been fixed in the existing codebase, I figured it would be easier to do a rewrite from scratch.
-I also had some ideas for extensions of the story grammar, so I decided to use "Treetop":http://treetop.rubyforge.org/
-and base it on a proper "grammar":http://github.com/aslakhellesoy/cucumber/tree/master/lib/cucumber/treetop_parser/feature.treetop.erb
+Cucumber addresses all of the above mentioned shortcomings of RSpec's Story runner. 
+If the community likes it, perhaps it will replace the RSpec story runner - either by
+being assumed into RSpec proper, or remaining a separate tool like now.
 
-Cucumber addresses all of the shortcomings of RSpec's Story runner. If the community likes it, we'll consider phasing out
-the RSpec story runner.
+The term "Feature" has been adopted in favour of "Story" because I believe it is a more 
+appropriate term. A feature's scenarios typically grow over time - fed by several user
+stories.
 
-The term "Feature" has been adopted in favour of "Story" because I believe it is a more appropriate term. A feature's scenarios
-typically increases over time - fed by several user stories.
+The name Cucumber means absolutely nothing, it was suggested by my girlfriend who was eating a cucumber sandwich
+while I started to write it.

data/README.txt

@@ -0,0 +1,41 @@
+= Cucumber
+
+* http://github.com/aslakhellesoy/cucumber
+
+== DESCRIPTION:
+
+Cucumber executes plain text documentation of code against that code.
+
+== REQUIREMENTS:
+
+* FIX (list of requirements)
+
+== INSTALL:
+
+* gem sources --add http://gems.github.com/ 
+* gem install aslakhellesoy-cucumber
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Aslak Hellesøy
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/config/hoe.rb

@@ -34,7 +34,7 @@ VERS = Cucumber::VERSION::STRING + (REV ? ".#{REV}" : "")
 RDOC_OPTS = ['--quiet', '--title', 'Cucumber documentation',
     "--opname", "index.html",
     "--line-numbers", 
-    "--main", "README",
+    "--main", "README.textile",
     "--inline-source"]
 
 class Hoe

data/examples/calculator/features/addition.feature

@@ -1,16 +1,16 @@
 Feature: Addition
+  In order to avoid silly mistakes
   As a math idiot 
   I want to be told the sum of two numbers
-  So that I don't make silly mistakes
 
   Scenario: Add two numbers
     Given I have entered 50 into the calculator
     And I have entered 70 into the calculator
-    When I add
-    Then the result should be 121 on the screen
+    When I press add
+    Then the result should be 130 on the screen
     And the result class should be Fixnum
 
-    | input_1 | input_2 | output | class  |
-    | 20      | 30      | 50     | Fixnum |
-    | 2       | 5       | 7      | Fixnum |
-    | 20      | 40      | 80     | Number |
+    | input_1 | input_2 | button | output | class  |
+    | 20      | 30      | add    | 50     | Fixnum |
+    | 2       | 5       | add    | 7      | Fixnum |
+    | 0       | 40      | add    | 40     | Fixnum |

data/examples/calculator/features/division.feature

@@ -1,7 +1,7 @@
 Feature: Division
-  As a math genius 
-  I want to be told the division of two floats
-  So that I don't make silly mistakes
+  In order to avoid silly mistakes
+  As a math idiot 
+  I want to be told the division of two numbers
 
   Scenario: Regular numbers
     Given I have entered 3 into the calculator
@@ -9,4 +9,3 @@ Feature: Division
     When I press divide
     Then the result should be 1.5 on the screen
     And the result class should be Float
-    And it should rain on Friday

data/examples/calculator/features/steps/{addition_steps.rb → calculator_steps.rb}

@@ -28,4 +28,3 @@ end
 Given /it should rain on (\w+)/ do |day|
   @calc.rain?(day).should == true
 end
-

data/examples/calculator/lib/calculator.rb

@@ -1,5 +1,7 @@
 class Calculator
   def push(n)
+    n += 2 if n == 0 # a really stupiud bug
+
     @args ||= []
     @args << n
   end
@@ -11,8 +13,4 @@ class Calculator
   def divide
     @args[0].to_f / @args[1].to_f
   end
-  
-  def rain?(day)
-    true
-  end
 end

data/examples/{pure_ruby → calculator_ruby_features}/features/addition.rb

@@ -1,9 +1,9 @@
 require 'cucumber/cli' # Needed in order to run the feature with ruby
 
 Feature %|Addition
+  In order to avoid silly mistakes
   As a math idiot 
-  I want to be told the sum of two numbers
-  So that I don't make silly mistakes| do
+  I want to be told the sum of two numbers| do
 
   Scenario "Add two numbers" do
     Given "I have entered 50 into the calculator"

data/examples/java/src/cucumber/demo/Hello.java

@@ -10,6 +10,6 @@ public class Hello {
     }
     
     public String getPhoneNumber(String who) {
-        return "99999";
+        throw new RuntimeException("My phone is secret!");
     }
 }

data/examples/{simple_norwegian/features/steps/matte_steg.rb.rb → norwegian_calculator/features/kalkulator_steps.rb}

@@ -1,6 +1,6 @@
 require 'spec'
 
-class Calculator
+class Kalkulator
   def push(n)
     @args ||= []
     @args << n
@@ -12,7 +12,7 @@ class Calculator
 end
 
 Before do
-  @calc = Calculator.new
+  @calc = Kalkulator.new
 end
 
 After do

data/examples/{simple_norwegian → norwegian_calculator}/features/summering.feature

@@ -1,9 +1,9 @@
 Egenskap: Summering
-  Som en matteidiot 
-  Vil jeg bli fortalt summen av to tall
-  Slik at jeg ikke gjør dumme feil
+  For å slippe å gjøre dumme feil
+  Som en regnskapsfører
+  Vil jeg kunne legge sammen
 
-  Scenario: 5+7
+  Scenario: to tall
     Gitt at jeg har tastet inn 5
     Og at jeg har tastet inn 7
     Når jeg summerer

data/examples/{web → watir}/features/search.feature

@@ -1,7 +1,7 @@
 Feature: Search
+  In order to learn more
   As an information seeker
   I want to find more information
-  So that I can learn more
 
   Scenario: Find what I'm looking for
     Given I am on the Google search page