cukesalad 0.7.0 → 0.8.0

data/features/a_simple_tutorial/README.markdown

@@ -0,0 +1,277 @@
+## Goals->Tasks->Actions
+The terms *"actions"* and *"tasks"* 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 called Calculator:
+
+    cukesalad Calculator
+
+Or, if you have an existing cucumber project that you want to configure to use cukesalad, you can type:
+
+    cukesalad
+
+## 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. Instead, we describe tasks...
+
+## 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 "switch on the calculator" do
+      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 "see the answer" 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' and 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... See below. Notice the ':' (colon) after `<do something>` followed by the name-value pairs:
+
+    When I attempt to <do something>: <name> '<value>' <name> '<value>'
+
+You can also use a ',' (comma) in situations where a colon wouldn't quite work:
+
+    When I attempt to <do something>, <name> '<value>' <name> '<value>'
+
+`<do something>` can be as many words as you like. You can have as many name-value pairs as you like.
+
+For this to work 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(:and_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 (using Ruby 1.9.x syntax):
+
+    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` and `:to_the_number` to `:second_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 create the corresponding methods in `calculating_individual.rb`.
+
+    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
+
+Of course you'll have to [implement the calculator too](https://github.com/RiverGlide/CukeSalad/blob/master/Examples/Calculator/lib/calculator.rb)
+
+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.
+
+If we want to know what things we can say, instead of trawling through a step-def ruby file, we can look in our tasks folder:
+
+    features/lib/default/tasks/
+    ├── add.rb
+    ├── calculate.rb
+    ├── calculations.rb
+    ├── see_the_answer.rb
+    ├── subtract.rb
+    └── switch_on_the_calculator.rb
+
+You can structure your tasks as you see fit. For example, as the project grows, it might end up looking like this:
+
+    features/lib/default/tasks/
+    ├── all_purpose
+    |   └── calculate.rb
+    ├── arithmetic
+    |   ├── add.rb
+    |   ├── divide.rb
+    |   ├── multiply.rb
+    |   └── subtract.rb
+    ├── extras
+    |   ├── recall_from_memory.rb
+    |   ├── store_in_memory.rb
+    |   └── switch_on_the_calculator.rb
+    ├── questions
+    |   ├── see_the_answer.rb
+    |   ├── see_the_following_indicators.rb
+    |   └── switch_on_the_calculator.rb
+    ├── trigonometry
+    |   ├── sine.rb
+    |   ├── cosine.rb
+    |   └── tangent.rb
+    └── reference_material
+        └── calculations.rb
+
+## 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.
+
+After adding some more scenarios and tasks and an alternative "Calculating Individual" (see below for why), our Calculator directory structure currently looks like this...
+
+    ├── cucumber.yml
+    ├── features
+    │   ├── A_PlaceToStart.feature
+    │   ├── Addition.feature
+    │   ├── Complex_calculations.feature
+    │   ├── 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.

data/features/creating_a_new_project.feature

@@ -1,34 +1,36 @@
 Feature: Creating a New Project
   As a Step Free Cuker
-  You want to set up your project to use use Cuke Salad 
-  So that you can start writing scenarios without step definitions 
+  You want to set up your project to use use Cuke Salad
+  So that you can start writing scenarios without step definitions
 
   Scenario: Set up your project and verify that you can use CukeSalad
     Given you are a Step Free Cuker
-    And   you were able to create directories: as follows
-    """
-    features
-    features/lib
-    features/lib/roles
-    features/lib/tasks
-    features/support
-    """
-    And you were able to create a file: at 'features/support/env.rb' containing
-      """
-      $:.unshift(File.dirname(__FILE__) + "/../../../../lib") #where to find CukeSalad
-             
-      require "cukesalad"
-      """
+    And   you were able to interactively run, the command 'cukesalad' and type 'y'
     And you were able to create a file: at 'features/hello_cukesalad.feature' containing
       """
       Feature: Hello CukeSalad
-  
+
         Scenario: Greetings
-          When I say hello CukeSalad
-      """ 
-    When you attempt to run: the command 'cucumber'  
+          Given I am a Newbie
+          When I say hello world
+      """
+    And you were able to create a file: at 'features/role/newbie.rb' containing
+    """
+      module Newbie
+        def say_hello
+          puts 'CukeSalad says: Hello World!'
+        end
+      end
+    """
+    And you were able to create a file: at 'features/lib/hello_world.rb' containing
+    """
+      in_order_to 'say hello world' do
+        say_hello
+      end
+    """
+    When you attempt to run: the command 'cucumber'
     Then  you should see a reply that includes:
     """
-    CukeSalad says: Hello!!
+    CukeSalad says: Hello World!
     """
-   And  you should see it has 'passed'
+    And  you should see it has 'passed'

data/features/defining_roles/README.md

@@ -0,0 +1,29 @@
+Your first step in your scenarios or in your background names a role relevant to your feature.
+Cukesalad has an actor that adopts this role at run-time.
+
+For example:
+
+    Given I am a Calculating Individual
+
+This will find a role called `CalculatingIndividual`. 
+This role will have the methods that you call from within the tasks.
+
+You would define this role as follows:
+
+    module CalculatingIndividual
+      def some_method_you_want_to_call
+        # some stuff the method does
+      end
+      ...
+    end
+
+That's all there is to it. You can simply wrap another module if you want to.
+We've done this in our scenarios for cukesalad as follows:
+
+    module StepFreeCuker
+      include Aruba::Api
+    end
+
+There are other things you can do, like initialise your 'role' by defining a `role_preparation` method.
+
+Take a look through the examples in this folder.

data/features/{define_a_role.feature → defining_roles/define_a_role.feature}

@@ -28,3 +28,11 @@ Feature: Define the Role
     Given I am a New Customer
     """
     Then you should see it has 'passed'
+
+  Scenario: Roles which grammatically required an 'an'
+    Given you did create a role: called 'UnregisteredCustomer'
+    When  you attempt to run a scenario: containing
+    """
+    Given I am an Unregistered Customer
+    """
+    Then you should see it has 'passed'

data/features/defining_tasks/README.md

@@ -0,0 +1,12 @@
+In your scenario, once you've named you role, you can write tasks that use methods on that role.
+For example:
+
+    Given I was able to switch on the calculator
+
+Needs a task called 'switch on the calculator'. You do this by creating a file, usually in `features/tasks`, called `switch_on_the_calculator.rb` with the following:
+
+    in_order_to "switch on the calculator" do
+      switch_on_the_calculator
+    end
+
+This is the most basic example. Look through the other examples to see how to pass arguments into your task.

data/features/{define_a_task.feature → defining_tasks/define_a_task.feature}

@@ -1,4 +1,4 @@
-Feature: Define the Task
+Feature: Define a Task
   As a Step Free Cuker
   You want to describe a task
   So that your steps that use that role are executed 
@@ -8,6 +8,23 @@ Feature: Define the Task
     Given you are a Step Free Cuker
     And   you were able to create a role: called 'NewCustomer'
 
+  Scenario: We'll tell you what you need to do to describe the task
+    Given you did not create a task: called 'do something'
+    When  you attempt to run a scenario: containing
+      """
+      Given I am a New Customer
+      And I was able to do something
+      """
+    Then you should see it has 'failed'
+    And  you should see a reply that includes:
+      """
+            I can't find a task called 'do something'. Have you created it?
+            e.g.
+              in_order_to 'do something' do
+                # the actions
+              end
+      """
+
   Scenario Outline: Once you've created the task, you see the step pass
     Given you were able to create a task: called 'do something'
     When  you attempt to run a scenario: containing
@@ -35,20 +52,44 @@ Feature: Define the Task
       | And   I should do something         |
       | Then  you should do something       |
       | And   you should do something       |
-    
-  Scenario: We'll tell you what you need to do to describe the task
-    Given you did not create a task: called 'do something'
+
+  Scenario Outline: Once you've created the task, you see the step pass
+    Given you were able to create a task: called 'do something for 123Company'
     When  you attempt to run a scenario: containing
-      """
-      Given I am a New Customer
-      And I was able to do something
-      """
-    Then you should see it has 'failed'
-    And  you should see a reply that includes:
-      """
-            I can't find a task called 'do something'. Have you created it?
-            e.g.
-              in_order_to 'do something' do
-                # the actions
-              end
-      """
+    """
+    Given I am a New Customer
+    <step using the task>
+    """
+    Then you should see it has 'passed'
+
+    Examples:
+      | step using the task                                |
+      | Given I was able to do something for 123Company    |
+      | And   I was able to do something for 123Company    |
+      | But   I did do something for 123Company            |
+      | Given you were able to do something for 123Company |
+      | And   you were able to do something for 123Company |
+      | But   you did do something for 123Company          |
+      | When  I attempt to do something for 123Company     |
+      | And   I attempt to do something for 123Company     |
+      | And   I did do something for 123Company            |
+      | When  you attempt to do something for 123Company   |
+      | And   you attempt to do something for 123Company   |
+      | And   you did do something for 123Company          |
+      | Then  I should do something for 123Company         |
+      | And   I should do something for 123Company         |
+      | Then  you should do something for 123Company       |
+      | And   you should do something for 123Company       |
+
+  Scenario Outline: Once you've created the task, you see the step pass
+    Given you were able to create a task: called 'have something'
+    When  you attempt to run a scenario: containing
+    """
+    Given I am a New Customer
+    <step using the task>
+    """
+    Then you should see it has 'passed'
+
+    Examples:
+      | step using the task                 |
+      | Given I have something              |