macros4cuke 0.2.00 → 0.2.01

data/HISTORY.md

@@ -1,13 +1,14 @@
 ## [0.2.00] Version number was bumped
 ### Changes:
-* Replaced the Mustache template engine by own lightweight TemplateEngine
-* Macro-step arguments have a syntax that is closer to Gherkin's scenario outlines.
-* Upgraded TemplateEngine class to become a simple templating system.
-* Remove dependency to mustache gem.
+* Regexp in the step definitions are more robust: they accept escape character sequence. 
+
+### Fixes:
+* Corrected remnant of Mustache template in travelling_demo.feature file.
+
 
 ### Documentation:
-* All demos updated to new syntax.
-* Updated the examples in README.md
+* Expanded the README.md file.
+
 
 
 ## [0.1.07]

data/README.md

@@ -1,87 +1,165 @@
-Macros4Cuke
-===========
-
-_Add macros to your Cucumber scenarios._  
-[Homepage](https://github.com/famished-tiger/Macros4Cuke)
-
-__Macros4Cuke__ gives you the opportunity to factor out repeated steps
- in your Cucumber scenarios. You can create (macro-)steps directly in feature files.   
-To each macro-step, it is possible to associate a sequence of sub-steps
- that will be executed every time a macro-step occurs in a scenario.
-
-### Highlights ###
-* Works with out-of-the-box Cucumber
-* Simple installation and setup (no programming required),
-* Substep sequence can be of arbitrary length,
-* Macro-steps may have data arguments,
-* Data values can be passed to the sub-steps.
-
-## Synopsis ##
-Here is an example taken from our demo files:  
-```cucumber
-  Given I define the step "When I [enter my userid <userid> and password <password>]" to mean:  
-  """  
-  Given I landed in the homepage  
-  When I click "Sign in"  
-  And I fill in "Username" with "<userid>"  
-  And I fill in "Password" with "<password>"  
-  And I click "Submit"  
-  """  
-```
-
-Notice how the arguments _userid_ and _password_ are enclosed between chevrons (angle brackets) <...>.
-
-
-That macro-step can then be used in a scenario like this:  
-```cucumber
-  When I [enter my userid "jdoe" and password "hello-world"]
-```
-
-When it is executed, the last macro-step (invokation) as the same effect as:
-```cucumber 
-  Given I landed in the homepage  
-  When I click "Sign in"  
-  And I fill in "Username" with "jdoe"  
-  And I fill in "Password" with "hello-world"  
-  And I click "Submit"  
-  """  
-```
-
-In other words, this sequence of 5 steps can be replaced by just one.
-Macros4Cuke not only helps in getting rid of the repeated step sequences,
- it allows the feature writers to create themselves higher-level steps
- that are closer to the business logic.  
-
-See also the working examples in the features folder.
-
-## Install and setup ##
-* Step 1: Install the macros4cuke gem:
-```bash  
-[sudo] gem install macros4cuke
-```
-
-  
-* Step 2: Add support for macros in your Cucumber project  
-In your /features/support/ folder:    
-  - Create a Ruby file (e.g. 'macro\_support.rb') with the following contents:  
-  
-```ruby
-require 'macros4cuke'  
-World(Macros4Cuke::MacroStepSupport)
-```  
-  
-* Step 3: Import the macro-management steps  
-In your /features/step_definitions/ folder:  
-  - Create a Ruby file (say, 'use\_macro\_steps.rb') with the following line:  
-  
-```ruby  
-require 'macros4cuke/../macro_steps'
-```  
-  
-Now, you can start writing macros in your Cucumber project.
-
----
-
-Copyright
----------
+Macros4Cuke
+===========
+
+_Add macros to your Cucumber scenarios._  
+[Homepage](https://github.com/famished-tiger/Macros4Cuke)
+
+__Macros4Cuke__ gives you the opportunity to factor out repeated steps
+ in your Cucumber scenarios. You can create (macro-)steps directly in feature files.   
+To each macro-step, it is possible to associate a sequence of sub-steps
+ that will be executed every time a macro-step occurs in a scenario.
+
+### Highlights ###
+* Works with out-of-the-box Cucumber
+* Simple installation and setup (no programming required),
+* Substep sequence can be of arbitrary length,
+* Macro-steps may have data arguments,
+* Data values can be passed to the sub-steps.
+
+## A quick example ##
+Here is an example taken from our demo files:  
+```cucumber
+  Given I define the step "When I [enter my userid <userid> and password <password>]" to mean:  
+  """  
+  Given I landed in the homepage  
+  When I click "Sign in"  
+  And I fill in "Username" with "<userid>"  
+  And I fill in "Password" with "<password>"  
+  And I click "Submit"  
+  """  
+```
+
+Notice how the arguments _userid_ and _password_ are enclosed between chevrons (angle brackets) <...>.
+
+
+That macro-step can then be used in a scenario like this:  
+```cucumber 
+  When I [enter my userid "jdoe" and password "hello-world"]
+```
+
+When it is executed, the last macro-step (invokation) as the same effect as:  
+```cucumber 
+  Given I landed in the homepage  
+  When I click "Sign in"  
+  And I fill in "Username" with "jdoe"  
+  And I fill in "Password" with "hello-world"  
+  And I click "Submit"  
+  """  
+```
+
+In other words, this sequence of 5 steps can be replaced by just one.
+Macros4Cuke not only helps in getting rid of the repeated step sequences,
+ it allows the feature writers to create themselves higher-level steps
+ that are closer to the business logic.  
+
+See also the working examples in the features folder.
+
+## Setup ##
+### Installation ###
+To install the macros4cuke gem:
+```bash  
+$[sudo] gem install macros4cuke
+```
+
+### Setting up your Cucumber project ####
+  
+* Step 1: Add support for macros in your Cucumber project  
+In your `/features/support/` folder:    
+  - Create a Ruby file (e.g. 'macro\_support.rb') with the following contents:  
+  
+```ruby
+require 'macros4cuke'  
+World(Macros4Cuke::MacroStepSupport)
+```  
+  
+* Step 2: Import the macro-management steps  
+In your `/features/step_definitions/` folder:  
+  - Create a Ruby file (say, 'use\_macro\_steps.rb') with the following line:  
+  
+```ruby  
+require 'macros4cuke/../macro_steps'
+```  
+  
+That's it! Now you can start writing macros in your Cucumber project.
+
+
+## Getting started ##
+Working with a macro-step is a two-stages process:  
+1. First, the definition of a new macro-step  
+2. Second, the use of that macro-step in a scenario.
+
+Let's begin by taking a closer look at the definition step.
+### Defining a macro-step ###
+There are three questions to keep in mind when creating a new macro-step:  
+1. What is its syntax?  
+2. What are its substeps?     
+3. Does it need arguments?  
+
+#### Specifying the syntax of a macro-step ####
+Let's begin with a simple example: 
+```cucumber
+  Given I define the step "When I [enter my credentials]" to mean:  
+  """  
+  Given I landed in the homepage   
+  And I fill in "Username" with "tweedledum"  
+  And I fill in "Password" with "tweedledee"  
+  And I click "Sign in"  
+  """  
+```
+
+The first line in the snippet is a step that helps to define macro-step.
+It is a perfectly valid step once your Cucumber project was configured to use __Macros4Cuke__
+ as explained in the Setup section above.  
+The syntax of a macro-step sentence is defined by its __phrase__, that is, the text on the first line that appears
+ between square brackets [...].
+In the example at hand, the _phrase_ is the text:  
+```cucumber
+  [enter my credentials] 
+``` 
+
+A few remarks about the __phrase__ part:  
+- It must be unique. In other words, it is not possible to create another
+  macro-step with the same phrase. In fact, Macros4Cuke uses the phrase internally as a mean to identify/name
+  a macro-step.  
+- It may have one or more arguments. The example above illustrates the simplest case where no argument
+is placed inside the phrase.  
+Besides that, the text inside the phrase can be arbitrary (well, almost).
+
+The next phrase takes two arguments:  
+```cucumber
+  [travel from <origin> to <destination>] 
+```  
+
+Each argument (variable), is enclosed between <...> chevrons. In our last example,
+the argument names are: _origin_ and _destination_. Notice that _origin_ and _destination_ are
+ variable names that will take a value (if any) when the step is invoked _(more on this later)_.
+
+#### Specifying the sub-steps of a macro-step ####
+The sub-steps are placed in a Gherkin multiline text, that is, a text that is enclosed between 
+ triple quotes ("""). In the earlier example, the text 
+```cucumber  
+  """  
+  Given I landed in the homepage   
+  And I fill in "Username" with "tweedledum"  
+  And I fill in "Password" with "tweedledee"  
+  And I click "Sign in"  
+  """  
+```  
+enumerates the sub-steps associated with the macro-step. A pleasing aspect is the familiar syntax 
+ the sub-steps have: they closely look to steps in a genuine scenario. Sub-steps can also have macro arguments.  
+ For instance, the previous step sequence may have two arguments called _userid_ and _password_:
+```cucumber  
+  """  
+  Given I landed in the homepage   
+  And I fill in "Username" with "<userid>"  
+  And I fill in "Password" with "<password>"  
+  And I click "Sign in"  
+  """  
+``` 
+
+ 
+---
+
+Copyright
+---------
 Copyright (c) 2013, Dimitri Geshef. See [LICENSE.txt](https://github.com/famished-tiger/Macros4Cuke/blob/master/LICENSE.txt) for details.

data/features/demo02.feature

@@ -1,34 +1,34 @@
-# File: demo02.feature
-
-Feature: Show the use of a basic macro with one argument
-  As a Cuke user
-  So that I enjoy writing scenario.
-
-
-Scenario: Creating a basic scenario with one argument
-  # The next step creates a macro(-step)
-  # The syntax of the new macro-step is specified between the double quotes.
-  # The steps to execute when the macro is used/invoked are listed in the multiline triple quotes arguments.
-  # The macro argument is put between chevrons <...>.
-  Given I define the step "When I [log in as <userid>]" to mean:
-  """
-  Given I landed in the homepage
-  When I click "Sign in"
-  And I fill in "Username" with "<userid>"
-  And I fill in "Password" with "unguessable"
-  And I click "Submit"
-  """
-
-Scenario: Let's use the macro we created above
-  # Here the macro is invoked. Actual value for the argument is put between double quotes.
-  When I [log in as "guest"]
-
-  # The next step verifies that the steps from the macro were effectively executed.
-  Then I expect the following step trace:
-  """
-Invoked step: ... I landed in the homepage
-Invoked step: ... I click "Sign in"
-Invoked step: ... I fill in "Username" with "guest"
-Invoked step: ... I fill in "Password" with "unguessable"
-Invoked step: ... I click "Submit"
+# File: demo02.feature
+
+Feature: Show the use of a basic macro with one argument
+  As a Cuke user
+  So that I enjoy writing scenario.
+
+
+Scenario: Creating a basic scenario with one argument
+  # The next step creates a macro(-step)
+  # The syntax of the new macro-step is specified between the double quotes.
+  # The steps to execute when the macro is used/invoked are listed in the multiline triple quotes arguments.
+  # The macro argument is put between chevrons <...>.
+  Given I define the step "When I [log in\[\] as <userid>]" to mean:
+  """
+  Given I landed in the homepage
+  When I click "Sign in"
+  And I fill in "Username" with "<userid>"
+  And I fill in "Password" with "unguessable"
+  And I click "Submit"
+  """
+
+Scenario: Let's use the macro we created above
+  # Here the macro is invoked. Actual value for the argument is put between double quotes.
+  When I [log in\[\] as "guest"]
+
+  # The next step verifies that the steps from the macro were effectively executed.
+  Then I expect the following step trace:
+  """
+Invoked step: ... I landed in the homepage
+Invoked step: ... I click "Sign in"
+Invoked step: ... I fill in "Username" with "guest"
+Invoked step: ... I fill in "Password" with "unguessable"
+Invoked step: ... I click "Submit"
   """

data/features/travelling-demo.feature

@@ -1,113 +1,113 @@
-# File: travelling-demo.feature
-
-Feature: Show -visually- the several ways to use macros
-  As a Cuke user
-  So that I enjoy writing scenario.
-
-
-Scenario: Definition of a simple macro-step with two arguments
-  Given I define the step "When I [travel from <origin> to <destination>]" to mean:
-  """
-  When I leave <origin>
-  And I arrive in <destination>
-  """
-
-Scenario: Do a simple travel
-  # Call a macro-step defined earlier
-  When I [travel from "Brussels" to "Rome"]
-
-  # You should see the output:
-  # I leave Brussels
-  # I arrive in Rome
-  
-  # Actual values can have embedded double quotes provided they are escaped.
-  When I [travel from "Tampa" to "\"Little Italy\""]  
-  
-
-
-
-Scenario: Defining a macro calling other macro(s)
-  Given I define the step "When I [travel from <origin> to <destination> and back]" to mean:
-  """
-  # The next two steps are, in fact, macro-step invokations
-  When I [travel from "<origin>" to "<destination>"]
-  When I [travel from "{{destination}}" to "<origin>"]
-  """
-
-Scenario: Do a travel back and forth
-    When I [travel from "Paris" to "London" and back]
-
-  # You should see the output:
-  # I leave Paris
-  # I arrive in London
-  # I leave London
-  # I arrive in Paris
-
-
-Scenario: Defining a macro that requires a data table
-  Given I define the step "When I [fill in the form with]:" to mean:
-  """
-  When I type "<firstname>"
-  And I type "<lastname>"
-  And I type "<street_address>"
-  And I type "<postcode>"
-  And I type "<city>"
-  And I type "<country>"
-  """
-
-Scenario: Using a macro-step with a data table
-  When I [fill in the form with]:
-  |firstname| Sherlock|
-  |lastname | Holmes  |
-  |street_address| 221B, Baker Street|
-  |city    |London   |
-  |postcode|NW1 6XE  |
-  |country | U.K.    |
-
-  # You should see the output:
-  # Sherlock
-  # Holmes
-  # 221B, Baker Street
-  # London
-  # U.K.
-  
-  
-  When I [fill in the form with]:
-  |firstname| Albert  |
-  |lastname | Einstein|
-  |street_address| 22, Mercer Street|
-  |city   |Princeton|  
-  |country| U.S.A   |
-  
-  # You should see the output:  
-  # Albert
-  # Einstein
-  # 22, Mercer Street
-
-  # Princeton
-  # U.S.A
-
-  # Did you notice the empty line in the previous output.
-  # Guess what? We forgot to specify a value for the postcode argument.
-  
-  
-Scenario: Demonstrate that it is possible to use a sub-step with a data table
-  Given I define the step "When I [fill in, as a Londonian, the form with]:" to mean:
-  """
-  When I [fill in the form with]:
-  |firstname| <firstname>|
-  |lastname | <lastname> |
-  |street_address| <street_address>|
-  |postcode|<postcode> |
-  # The next two lines have hard-coded values
-  |city    |London   |  
-  |country | U.K.    |
-  """
-  
-  # Let's try...
-  When I [fill in, as a Londonian, the form with]:
-  |firstname| Prime|
-  |lastname | Minister  |
-  |street_address| 10, Downing Street|
-
-
+# File: travelling-demo.feature
+
+Feature: Show -visually- the several ways to use macros
+  As a Cuke user
+  So that I enjoy writing scenario.
+
+
+Scenario: Definition of a simple macro-step with two arguments
+  Given I define the step "When I [travel from <origin> to <destination>]" to mean:
+  """
+  When I leave <origin>
+  And I arrive in <destination>
+  """
+
+Scenario: Do a simple travel
+  # Call a macro-step defined earlier
+  When I [travel from "Brussels" to "Rome"]
+
+  # You should see the output:
+  # I leave Brussels
+  # I arrive in Rome
+  
+  # Actual values can have embedded double quotes provided they are escaped.
+  When I [travel from "Tampa" to "\"Little Italy\""]  
+  
+
+
+
+Scenario: Defining a macro calling other macro(s)
+  Given I define the step "When I [travel from <origin> to <destination> and back]" to mean:
+  """
+  # The next two steps are, in fact, macro-step invokations
+  When I [travel from "<origin>" to "<destination>"]
+  When I [travel from "<destination>" to "<origin>"]
+  """
+
+Scenario: Do a travel back and forth
+    When I [travel from "Paris" to "London" and back]
+
+  # You should see the output:
+  # I leave Paris
+  # I arrive in London
+  # I leave London
+  # I arrive in Paris
+
+
+Scenario: Defining a macro that requires a data table
+  Given I define the step "When I [fill in the form with]:" to mean:
+  """
+  When I type "<firstname>"
+  And I type "<lastname>"
+  And I type "<street_address>"
+  And I type "<postcode>"
+  And I type "<city>"
+  And I type "<country>"
+  """
+
+Scenario: Using a macro-step with a data table
+  When I [fill in the form with]:
+  |firstname| Sherlock|
+  |lastname | Holmes  |
+  |street_address| 221B, Baker Street|
+  |city    |London   |
+  |postcode|NW1 6XE  |
+  |country | U.K.    |
+
+  # You should see the output:
+  # Sherlock
+  # Holmes
+  # 221B, Baker Street
+  # London
+  # U.K.
+  
+  
+  When I [fill in the form with]:
+  |firstname| Albert  |
+  |lastname | Einstein|
+  |street_address| 22, Mercer Street|
+  |city   |Princeton|  
+  |country| U.S.A   |
+  
+  # You should see the output:  
+  # Albert
+  # Einstein
+  # 22, Mercer Street
+
+  # Princeton
+  # U.S.A
+
+  # Did you notice the empty line in the previous output.
+  # Guess what? We forgot to specify a value for the postcode argument.
+  
+  
+Scenario: Demonstrate that it is possible to use a sub-step with a data table
+  Given I define the step "When I [fill in, as a Londonian, the form with]:" to mean:
+  """
+  When I [fill in the form with]:
+  |firstname| <firstname>|
+  |lastname | <lastname> |
+  |street_address| <street_address>|
+  |postcode|<postcode> |
+  # The next two lines have hard-coded values
+  |city    |London   |  
+  |country | U.K.    |
+  """
+  
+  # Let's try...
+  When I [fill in, as a Londonian, the form with]:
+  |firstname| Prime|
+  |lastname | Minister  |
+  |street_address| 10, Downing Street|
+
+

data/lib/macro_steps.rb

@@ -1,47 +1,47 @@
-# File: macro_steps.rb
-# Purpose: step definitions that help to build macro-steps (i.e. a step that is equivalent to a sequence of steps)
-
-
-
-# This step is used to define a macro-step
-# Example:
-#  Given I define the step "When I [log in as <userid>]" to mean:
-#  """
-#  Given I landed in the homepage
-#  When I click "Sign in"
-#  And I fill in "Username" with "<userid>"
-#  And I fill in "Password" with "unguessable"
-#  And I click "Submit"
-#  """
-
-Given(/^I define the step "When I \[([^\]]+\]:?)" to mean:$/) do |macro_phrase, template|
-  add_macro(macro_phrase, template)
-end
-
-# This step is used to invoke a simple macro-step
-# Example:
-#  When I [log in as "guest"]
-#
-When(/^I \[([^\]]+\])$/) do |macro_phrase|
-  invoke_macro(macro_phrase)  # This will call the macro with the given phrase
-end
-
-
-# This step is used to invoke a macro-step with a table argument.
-# Example:
-#  When I [enter my credentials as]:
-#  |userid  |guest      |
-#  |password|unguessable|
-When(/^I \[([^\]]+\]:)$/) do |macro_phrase, table_argument|
-  # Ensure that the second argument is of the correct type
-  unless table_argument.kind_of?(Cucumber::Ast::Table)
-     raise StandardError, "This step must have a data table as an argument."
-  end
-  
-  # This will call the macro with the given phrase.
-  # The second argument consists of a hash with pairs of the kind: argument name => actual value
-  invoke_macro(macro_phrase, table_argument.rows_hash())
-end
-
-
+# File: macro_steps.rb
+# Purpose: step definitions that help to build macro-steps (i.e. a step that is equivalent to a sequence of steps)
+
+
+
+# This step is used to define a macro-step
+# Example:
+#  Given I define the step "When I [log in as {{userid}}]" to mean:
+#  """
+#  Given I landed in the homepage
+#  When I click "Sign in"
+#  And I fill in "Username" with "{{userid}}"
+#  And I fill in "Password" with "unguessable"
+#  And I click "Submit"
+#  """
+
+Given(/^I define the step "When I \[((?:[^\\\]]|\\.)+\]:?)" to mean:$/) do |macro_phrase, template|
+  add_macro(macro_phrase, template)
+end
+
+# This step is used to invoke a simple macro-step
+# Example:
+#  When I [log in as "guest"]
+#
+When(/^I \[((?:[^\\\]]|\\.)+\])$/) do |macro_phrase|
+  invoke_macro(macro_phrase)  # This will call the macro with the given phrase
+end
+
+
+# This step is used to invoke a macro-step with a table argument.
+# Example:
+#  When I [enter my credentials as]:
+#  |userid  |guest      |
+#  |password|unguessable|
+When(/^I \[([^\]]+\]:)$/) do |macro_phrase, table_argument|
+  # Ensure that the second argument is of the correct type
+  unless table_argument.kind_of?(Cucumber::Ast::Table)
+     raise StandardError, "This step must have a data table as an argument."
+  end
+  
+  # This will call the macro with the given phrase.
+  # The second argument consists of a hash with pairs of the kind: argument name => actual value
+  invoke_macro(macro_phrase, table_argument.rows_hash())
+end
+
+
 # End of file

data/lib/macros4cuke/constants.rb

@@ -3,7 +3,7 @@
 
 module Macros4Cuke # Module used as a namespace
 	# This constant keeps the current version of the gem.
-	Version = '0.2.00'
+	Version = '0.2.01'
   
   Description = "Macros for Cucumber"
 	

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: macros4cuke
 version: !ruby/object:Gem::Version
-  version: 0.2.00
+  version: 0.2.01
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-25 00:00:00.000000000 Z
+date: 2013-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -43,6 +43,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.00'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.00'
 description: ! "\tMacros4Cuke is a lightweight library that adds a macro facility
   your Cucumber scenarios.\n  In short, you can create any new step that replaces
   a sequence of lower-level steps.\n  All this can be done directly in your feature