cukesalad 0.2.0

data/Gemfile.lock

@@ -0,0 +1,47 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    aruba (0.3.5)
+      childprocess (>= 0.1.7)
+      cucumber (>= 0.10.0)
+      rspec (>= 2.5.0)
+    builder (3.0.0)
+    childprocess (0.1.7)
+      ffi (~> 0.6.3)
+    cucumber (0.10.0)
+      builder (>= 2.1.2)
+      diff-lcs (~> 1.1.2)
+      gherkin (~> 2.3.2)
+      json (~> 1.4.6)
+      term-ansicolor (~> 1.0.5)
+    diff-lcs (1.1.2)
+    ffi (0.6.3)
+      rake (>= 0.8.7)
+    gherkin (2.3.3)
+      json (~> 1.4.6)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    json (1.4.6)
+    rake (0.8.7)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.5.0)
+    term-ansicolor (1.0.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  aruba (= 0.3.5)
+  bundler (~> 1.0.0)
+  cucumber (= 0.10.0)
+  jeweler (~> 1.5.2)
+  rspec (= 2.5.0)

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2010 RiverGlide
+
+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/README.md

@@ -0,0 +1,273 @@
+# Cuke Salad
+
+_Cucumber, washed and ready to eat for Friction-free ATDD/BDD_
+
+**This is a work in progress - feedback welcome**
+e-mail feedback to <talktous@riverglide.com>
+
+** ToDo: **
+
+* Support more step structures - such as tables as input
+* Move beyond current examples by documenting CukeSalad with Cucumber
+* Remembering data between steps
+* Multiple role/actor scenarios
+
+## This project has step-free access!
+
+CukeSalad allows you to focus on the task at hand - expressing examples, the roles involved in those examples and what those roles can do with the product under development.
+
+With CukeSalad you don't need to write step-definitions.
+
+Of course, you still have to write some code - but only the code that expresses:
+
+* the roles and the actions they can perform
+* the tasks and the actions involved in completing that task
+
+## Goals->Tasks->Actions
+The terms *"actions"* and *"tasks"* above come from Task Analysis, as used in User Centred Design (UCD) of Human Computer Interfaces (HCI) a.k.a. User Experience (UX):
+
+* *Goal:* What we’re trying to achieve which has one or more…
+* *Tasks:* The high-level work-item that we complete to fulfil the goal, each having one or more…
+* *Actions:* The specific steps or interactions we execute to complete the task.
+
+More information about Goals, Tasks and Actions can be found in this [blog post](http://antonymarcano.com/blog/2011/03/goals-tasks-action/)
+
+Let's see how this works with a simple example...
+
+## Install
+
+    gem install cukesalad
+
+## Let's Get started
+
+Create a new project Calculator:
+
+    mkdir Calculator
+    cd Calculator
+    mkdir features
+    mkdir features/support
+    mkdir features/lib
+    mkdir features/lib/tasks
+    mkdir features/lib/roles
+
+In idiomatic Cucumber style, we use `features/support/env.rb` to require _CukeSalad_: 
+
+    require 'cukesalad'
+    begin require 'rspec/expectations'; rescue LoadError; require 'spec/expectations'; end
+
+Cucumber will automatically find our project's _roles_ and _tasks_, as it loads
+all .rb files beneath the project's `features/` directory.
+
+## Write Features
+
+In `features/`, let's create our first feature file - `a_place_to_start.feature`:
+
+    Feature: A Place To Start
+    As Callie, a calculating individual
+    I want to know when my calculator is on
+    So that I know when I can start calculating
+
+    Scenario: Let's Begin
+      Given I am a Calculating Individual
+      When  I attempt to switch on the calculator
+      Then  I should see the answer '0'
+
+Let's take a moment to understand this scenario:
+
+    Scenario: Let's Begin
+      Given I am a <some role>
+      When  I attempt to <do some task>
+      Then  I should <ask some question> '<expected answer>'
+
+To get this working, we don't need to write any steps.
+Just explain how to do the _task_ using a class...
+
+## Create Tasks
+
+Explaining how to do a _task_ is easy:
+Create a new file, `features/lib/tasks/switch_on_the_calculator.rb`
+
+Remember the step `When  I attempt to switch on the calculator`
+
+    in_order_to "SwitchOnTheCalculator" do
+      @calc = switch_on_the_calculator
+    end
+
+Remember the step `Then  I should see the answer '0'`
+Now we need `task/see_the_answer.rb`
+
+    in_order_to "SeeTheAnswer" do
+      look_at_the_display
+    end
+
+Now we've explained the _tasks_, we need to define the _role_ that performs them. In
+this example, we need to explain how the `CalculatingIndividual` _role_ works...
+
+## Create Roles
+
+Remember the step `Given I am a Calculating Individual`?
+
+We explain a _role_ by creating a new file
+called `features/lib/roles/calculating_individual.rb`
+
+    module CalculatingIndividual
+
+      def switch_on_the_calculator
+        @calculator = Calculator.new
+      end
+
+      def look_at_the_display
+        @calculator.display
+      end
+    end
+
+You'll need a class called Calculator on the load path of course, but that's it.
+
+From your project folder, run (_note: '%' is our command prompt_)
+
+  % cucumber
+
+We now have our first passing Feature, without creating a single step definition!
+
+## Wash, rinse, repeat
+
+Let's try another scenario...
+
+    Scenario Outline: Find the sum of two numbers
+      Given I am a Calculating Individual
+      And I was able to switch on the calculator
+      When I attempt to add: the number '10' to the number '10'
+      Then I should see the answer '20'
+
+Notice that we've reused 'switch on the calculator'.
+
+The new _When_ step has a slightly different layout.
+Let's examine that for a second... Notice the ':' (colon) after <do something> and the name-value pairs:
+
+    When I attempt to <do something>: <name> '<value>' <name> '<value>'
+
+You can have as many name-value pairs as you like.
+
+So, we need a task called `tasks/add.rb` that explains the individual actions required to complete the task:
+
+    in_order_to "Add" do
+      enter @value_of(:the_number)
+      press :plus
+      enter @value_of(:to_the_number)
+      press :equals
+    end
+
+Notice how the `value_of` lines use symbols that correspond to the wording `'the number '10' to the number '10'` in the "When" step.
+
+There is some 'syntactic sugar' that we can use to dress this up a little and make it read nicer... a simple attribute mapping:
+
+    in_order_to "Add", the_number: :first_number, to_the_number: :second_number do
+        enter the :first_number
+        press :plus
+        enter the :second_number
+        press :equals
+    end
+
+All we've done is mapped "the_number" to "first_number". There is a special method called "the" that allows you to reference the mapped values rather than the symbols derived from the scenario.
+
+Now all we need to do is modify our `calculating_individual.rb` to receive those calls...
+
+    module CalculatingIndividual
+
+      def switch_on_the_calculator
+        @calculator = Calculator.new
+        @operate_with = {
+          plus: :+,
+         minus: :-
+        }
+      end
+
+      def enter value
+        @calculator.enter value.to_i
+      end
+
+      def press next_operator
+        if next_operator == :equals
+          equals
+        else
+          @calculator.get_ready_to @operate_with[next_operator]
+        end
+      end
+
+      def equals
+        @calculator.equals
+      end
+
+      def look_at_the_display
+        @calculator.display
+      end
+    end
+
+Now, you can run cucumber again:
+
+    % cucumber
+
+There's no need to write `step_definitions`...
+Simply express the _roles_ and the _tasks_ in clear,
+concise, easy to read classes.
+
+After adding some more scenarios and tasks and an alternative "Calculating Individual" (see below for why), our finished Calculator directory structure looks like this...
+
+    ├── cucumber.yml
+    ├── features
+    │   ├── A_PlaceToStart.feature
+    │   ├── Addition.feature
+    │   ├── Complex_calculations.feature
+    │   ├── LOOK_MA_NO_STEP_DEFS.txt
+    │   ├── Subtraction.feature
+    │   ├── Typical_workflow.feature
+    │   ├── lib
+    │   │   ├── alternative
+    │   │   │   ├── roles
+    │   │   │   │   └── calculating_web_user.rb
+    │   │   │   └── tasks
+    │   │   └── default
+    │   │       ├── roles
+    │   │       │   └── calculating_individual.rb
+    │   │       └── tasks
+    │   │           ├── add.rb
+    │   │           ├── perform.rb
+    │   │           ├── see_the_answer.rb
+    │   │           ├── subtract.rb
+    │   │           └── switch_on_the_calculator.rb
+    │   └── support
+    │       └── env.rb
+    ├── lib
+    │   ├── calculator.rb
+    │   └── web_calculator.rb
+    └── spec
+        ├── calculator_spec.rb
+        └── web_calculator_spec.rb
+
+Take a look around the examples and the code to see how it all works. We hope you enjoy reading as much as we enjoyed writing it.
+
+## Alternative Roles
+
+As our features _describe the value of a calculator application and not its
+implementation_, we have the opportunity to reuse them.
+
+In the Calculator example, we create a new _role_ in
+`./features/lib/alternative/roles/calculating_web_user.rb`, which we can swap
+into our tests using a Cucumber profile defined in `features/cucumber.yml`:
+
+    default --exclude features/lib/alternative/
+    alternative -r features/lib/alternative/ -r features/support/env.rb -r features/lib/default/tasks/
+
+We can run our alternative configuration like so:
+
+  `%cucumber --profile alternative`
+
+The Calculating Web User masquerades as the Calculating Individual from our
+previous example, and provides the same API, allowing us to reuse all of our
+existing features and _tasks_.
+
+The alternative, `./lib/web_calculator.rb`, implementation is a simple [Sinatra](http://www.sinatrarb.com) application,
+which we drive with the [Capybara](http://github.com/jnicklas/capybara) web testing framework.
+
+By writing a single new _role_ class we're able to reuse all of our existing features,
+_tasks_ and even the `Calculator` itself, which the web calculator delegates to in order to do its calculations.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "cukesalad"
+  gem.homepage = "https://github.com/RiverGlide/CukeSalad"
+  gem.platform = Gem::Platform::RUBY
+  gem.license = "MIT"
+  gem.summary = %Q{Friction Free BDD/ATDD with cucumber}
+  gem.description = %Q{CukeSalad allows you to focus on the tasks at hand - expressing examples, the roles involved in those examples and the tasks that those roles need to perform with the product under development.}
+  gem.email = "talktous@riverglide.com"
+  gem.authors = ["RiverGlide"]
+
+  # The following two lines need to be commented out in order to gain access to the version rake tasks
+  gem_version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  gem.version = gem_version
+  gem.executables = ["cukesalad"]
+  gem.files.include 'lib/cukesalad/cli.rb'
+end
+
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+  spec.rspec_opts = "-cfd"
+end
+
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new(:cucumber)
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "CukeSalad #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/bin/cukesalad

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'cukesalad/cli'
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: cukesalad [new | configure] project_name"
+
+  begin
+    opts.parse!(ARGV)
+  rescue OptionParser::ParseError => e
+    warn e.message
+    puts opts
+    exit 1
+  end
+end
+
+if ARGV.empty?
+  abort "Usage: cukesalad new <project name>\nOr: cukesalad configure"
+elsif ARGV.first == 'new'
+  project = ARGV[1]
+  puts "Creating project #{project}..."
+  CukeSalad::CLI.create_new_project project 
+  puts "Done!"
+elsif ARGV.first == 'configure'
+  CukeSalad::CLI.configure_existing_project
+  puts "Done!"
+end

data/cucumber.yml

@@ -0,0 +1,4 @@
+default: --tags ~@draft
+all: features
+autotest: --color
+autotest-all: --color

data/cukesalad/cli.rb

@@ -0,0 +1,68 @@
+require 'aruba/api'
+module CukeSalad
+  class CLI
+
+    def self.create_new_project project
+      structure = Structure.new
+      structure.setup project
+    end
+
+    def self.configure_existing_project project=nil
+      `cd #{project}` if project
+      structure = Structure.new
+      structure.setup_cucumber_with_cukesalad
+    end
+
+    class Structure
+      include Aruba::Api
+
+      def initialize
+        set_aruba_path_to_current
+      end
+
+      def setup project
+        create_and_navigate_to project
+        setup_cucumber_with_cukesalad
+      end
+
+      def setup_cucumber_with_cukesalad
+        create_dir_structure
+        configure
+      end
+
+      private
+      def set_aruba_path_to_current
+        @dirs = ["./"]
+      end
+
+      def create_dir_structure
+        create_cucumber_structure
+        create_cukesalad_structure
+      end
+
+      def create_cucumber_structure
+        create_and_navigate_to "features"
+        create_dir "support"
+      end
+
+      def create_cukesalad_structure
+        create_and_navigate_to "lib"
+        create_and_navigate_to "default"
+        create_dir "roles"
+        create_dir "tasks"
+        cd "../../../"
+      end
+
+      def configure
+        cd "features/support"
+        content = "require 'cukesalad'\n begin require 'rspec/expectations'; rescue LoadError; require 'spec/expectations'; end"
+        append_to_file "env.rb",content
+      end
+
+      def create_and_navigate_to directory
+        create_dir directory
+        cd directory
+      end
+    end
+  end
+end

data/examples/Calculator/features/lib/alternative/roles/calculating_web_user.rb

@@ -0,0 +1,55 @@
+# To run with this version of the Calculating Individual:
+# cucumber --profile alternative 
+
+require 'web_calculator'
+require 'capybara'
+require 'capybara/dsl'
+
+Capybara.app = WebCalculator
+Capybara.default_driver = :rack_test
+
+module CalculatingIndividual
+
+  # Uses a Browser to perform its tasks
+  include Capybara
+  # This is not a page object. It is a WebUser, specialised to our application
+  # See the comments in the 'enter' and 'press' method for an explanation of why
+
+  def switch_on_the_calculator
+    visit '/'
+  end
+
+  def enter value
+    fill_in 'number', :with => value
+    # Because the calculator is a simple web_app with only
+    # one page we can put the id for the field here. In a more complex web-app
+    # we would pass in the id of the thing to enter
+    # The task would express the action as: enter( :the_number, "10")
+    # Because we can change the id used in our application,
+    # we would just change the id in the application to be 'the_number'.
+    # If we were on a project where we could not change the id 
+    # in the application we would write an 'ApplicationExpert' 
+    # to map :the_number to the id for the field 'number'. Our CalculatingIndividual
+    # would ask the ApplicationExpert for the id of the symbol :the_number
+    # See 'press' below for am explanation of how an ApplicationExpert 
+    # would work 
+  end
+  
+  def press operator
+    click_button operator.to_s
+    # Here, our 'operator' happens to also match the id for the button.
+    # If we were on a project where we could not choose what the id
+    # was for buttons, we would write an ApplicationExpert to map 
+    # the symbol used in the task to the symbol for that button. 
+    # The ApplicationExpert would only need to know what page it 
+    # was on to find a mappings class (or yml file) for the fields on that page.
+  end
+
+  def look_at_the_display
+    find_field('display').value.to_i
+  end
+
+  def is_the_calculator_ready?
+    page.body.should =~ /Calculator is Ready!/
+  end
+end

data/examples/Calculator/features/lib/default/roles/calculating_individual.rb

@@ -0,0 +1,32 @@
+require 'calculator'
+
+module CalculatingIndividual
+
+  def switch_on_the_calculator
+    @calculator = Calculator.new
+    @operate_with = {
+      plus: :+,
+     minus: :-
+    }
+  end
+
+  def enter value
+    @calculator.enter value.to_i
+  end
+
+  def press next_operator
+    if next_operator == :equals
+      equals
+    else
+      @calculator.get_ready_to @operate_with[next_operator]
+    end
+  end
+
+  def equals
+    @calculator.equals
+  end
+
+  def look_at_the_display
+    @calculator.display
+  end
+end

data/examples/Calculator/features/lib/default/tasks/add.rb

@@ -0,0 +1,13 @@
+# This demonstrates how to use an attribute mapping 
+#  to make the interactions within the task read more naturally
+# In the scenario it might say "add: the number '5', to the number '10'
+# The form illustrated below simply maps the elements the_number and to_the_number
+#  to alternative symbols that make the interactions read more like real instructions
+# See subtract.rb for a way of writing tasks that reuses the common interactions 
+# required to perform calculations.
+in_order_to 'add', the_number: :first_number, to_the_number: :second_number do
+    enter the :first_number 
+    press :plus
+    enter the :second_number 
+    press :equals
+end

data/examples/Calculator/features/lib/default/tasks/calculate.rb

@@ -0,0 +1,4 @@
+in_order_to "Calculate", with_the_following: :calculation do
+  see_how_to_do Calculations  
+  follow_the_steps_for the( :calculation ).split(" ")
+end

data/examples/Calculator/features/lib/default/tasks/calculations.rb

@@ -0,0 +1,15 @@
+module Calculations
+  
+  def follow_the_steps_for sum
+    enter_numbers_and_operators_for sum
+  end
+  
+  def enter_numbers_and_operators_for sum
+    operator = {"+" => :plus, "-" => :minus, "=" => :equals}
+    sum.each do | token |
+      enter token.to_i if token =~ /\d+/
+      press operator[token] if operator.include? token
+    end
+  end
+end
+

data/examples/Calculator/features/lib/default/tasks/see_the_answer.rb

@@ -0,0 +1,3 @@
+in_order_to "see the answer" do
+  look_at_the_display
+end

data/examples/Calculator/features/lib/default/tasks/subtract.rb

@@ -0,0 +1,4 @@
+in_order_to "Subtract", the_number: :subtractor, from_the_number: :subtractee do
+  see_how_to_do Calculations
+  follow_the_steps_for [the(:subtractee), "-", the(:subtractor), "="] 
+end

data/examples/Calculator/features/lib/default/tasks/switch_on_the_calculator.rb

@@ -0,0 +1,9 @@
+in_order_to "switch on the calculator" do
+  require 'rspec/expectations'
+  extend RSpec::Matchers
+  
+  @calc = switch_on_the_calculator
+  self.should respond_to :enter
+  self.should respond_to :press
+  self.should respond_to :look_at_the_display
+end

data/examples/Calculator/features/support/env.rb

@@ -0,0 +1,6 @@
+$:.unshift(File.dirname(__FILE__) + '/../../lib') #where to find the calculator implementation
+$:.unshift(File.dirname(__FILE__) + '/../../../../lib') #where to find CukeSalad
+
+require 'cukesalad'
+
+begin require 'rspec/expectations'; rescue LoadError; require 'spec/expectations'; end