macros4cuke 0.3.24 → 0.3.25

data/CHANGELOG.md

@@ -1,29 +1,37 @@
-## 0.3.24 / 2013-05-28
+### 0.3.25 / 2013-05-30
+* [NEW] File `exceptions.rb`: New exception class AmbiguousArgumentValue.
+* [CHANGE] Method `MacroStep#validate_params`: an AmbiguousArgumentValue is raised when a macro argument get its value from phrase and data table at the same time.
+* [CHANGE] File `macro-step_spec.rb`: Added specific test for new exception.
+* [CHANGE] File `README.md`: Added a pre-requisites section and a FAQ section.
+* [CHANGE] File `demo_steps.rb`: Removed one Rubocop's complain 'Line is too long'.
+* [CHANGE] File `CHANGELOG.md`: change in headings style.
+
+### 0.3.24 / 2013-05-28
 * [CHANGE] File `.rubocop.yml`: A few new Rubocop 0.8.0 checks are disabled.
 * [CHANGE] Many source files refactored to satisfy new "cops" from Rubocop 0.8.0
 
-## 0.3.23 / 2013-05-26
+### 0.3.23 / 2013-05-26
 * [CHANGE] Demo file `table.feature`: Added one scenario combining argument passing via the phrase and table.
 
-## 0.3.22 / 2013-05-25
+### 0.3.22 / 2013-05-25
 * [CHANGE] File `macro-collection_spec.rb`: Added one test for the `MacroCollection#render_steps` method.
 
-## 0.3.21 / 2013-05-24
+### 0.3.21 / 2013-05-24
 * [CHANGE] File `.rubocop.yml`: StringLiterals cop is now enabled.
 * [CHANGE] Many file: replaced double quotes by single quotes in order to pass the StringLiterals Robocop rule.
 
-## 0.3.20 / 2013-05-23
+### 0.3.20 / 2013-05-23
 * [CHANGE] File `.travis.yml`: Added more CI environments: ruby-head and jruby-head.
 * [CHANGE] File `Rakefile`: Added task to push gem to Rubygems.
 
-## 0.3.19 / 2013-05-22
+### 0.3.19 / 2013-05-22
 * [CHANGE] File `.rubocop.yml`: Reduced MethodLength to 30 (lines in a method).
 * [CHANGE] Method `Engine#compile_line refactored: Extract Method pattern => new method line_rep_ending added.
 * [CHANGE] Method `Engine#compile_sections refactored: Extract Method pattern => new method validate_section_end added.
 * [FIX] File `exceptions.rb`: Removal of useless assignment (detected by Rubocop). No runtime impact.
 
 
-## 0.3.18 / 2013-05-21
+### 0.3.18 / 2013-05-21
 * [FEATURE] Support for sub-steps having multiline text arguments (docstring).
 * [CHANGE] Method `MacroStep#expand passes` also built-in arguments to template engine.
 * [CHANGE] Method `MacroStep#validate_phrase_args` does not apply validations on built-in arguments.
@@ -31,66 +39,66 @@
 * [NEW] File `multiline.feature` added in examples/features/ folder.
 * [CHANGE] File `README.md`: Added section 'Sub-steps with multiline text argument'
 
-## 0.3.17 / 2013-05-20
+### 0.3.17 / 2013-05-20
 * [CHANGE] File `README.md`: Added dynamic dependencies badge (Gemnasium).
 
-## 0.3.16 / 2013-05-20
+### 0.3.16 / 2013-05-20
 * [CHANGE] File `demo06.feature`: Added a scenario that causes a specific exception to be raised.
 * [CHANGE] File `demo_steps.rb`: Added a specific step that raises a TableNotException. It is captured and compared to expectations. 
 * [CHANGE] File `engine.rb`: Removed two lines that were never executed.
 
-## 0.3.15 / 2013-05-20
+### 0.3.15 / 2013-05-20
 * [FIX] File `.CHANGELOG.md` Date entries weren't incremented.
 * [CHANGE] File `.rubocop.yml`: Added more configuration entries.
 * [CHANGE] Spec files updated to better please Rubocop.
 
-## 0.3.14 / 2013-05-18
+### 0.3.14 / 2013-05-18
 * [FIX] lib/ folder in secondary local repository was messed up. Gem was OK.
 
-## 0.3.13 / 2013-05-18
+### 0.3.13 / 2013-05-18
 * [NEW] File `.rubocop.yml` Added.
 * [CHANGE] Many source files changed to please Rubocop.
 
-## 0.3.12 / 2013-05-17
+### 0.3.12 / 2013-05-17
 * [NEW] File `.ruby-gemset` Added (for RVM users).
 * [NEW] File `.ruby-version` Added (for RVM users).
 
-## 0.3.11 / 2013-05-16
+### 0.3.11 / 2013-05-16
 * [CHANGE] File `README.md`: Minor reformating.
 * [CHANGE] File `basic.feature` (in examples/): Added one more macro-step example.
 
-## 0.3.10 / 2013-05-15
+### 0.3.10 / 2013-05-15
 * [CHANGE] File `README.md`: Expanded section on conditional section.
 * [CHANGE] Method `Templating::Engine::parse` slightly refactored in order to decrease its complexity.
 
-## 0.3.09 / 2013-05-14
+### 0.3.09 / 2013-05-14
 * [CHANGE] File `.travis.yml`: Added jruby as a target Ruby
 
-## 0.3.08 / 2013-05-13
+### 0.3.08 / 2013-05-13
 * [CHANGE] File `README.md`: Added Gem Version badge
 
-## 0.3.07 / 2013-05-12
+### 0.3.07 / 2013-05-12
 * [CHANGE] File `README.md`: Added Codeclimate badge
 
-## 0.3.06 / 2013-05-12
+### 0.3.06 / 2013-05-12
 * [FIX] File `README.md`: Fixed formatting issue of Travis CI status badge
 
-## 0.3.05 / 2013-05-12 Unreleased
+### 0.3.05 / 2013-05-12 Unreleased
 * [CHANGE] File `README.md`: Added Travis CI status badge
 
-## 0.3.04 / 2013-05-12 Unreleased
+### 0.3.04 / 2013-05-12 Unreleased
 * [NEW] File `.travis.yml`: Added for integration with Travis CI
 * [NEW] File `Gemfile`: Added for integration with Bundler
 * [NEW] File `Rakefile`: Added with test tasks
 * [CHANGE] File `macros4cuke.gemspec`: added development dependency on rake. 
 
-## 0.3.03 / 2013-05-11
+### 0.3.03 / 2013-05-11
 * [CHANGE] File `README.md`: added section on conditional section.
 
-## 0.3.02 / 2013-05-11
+### 0.3.02 / 2013-05-11
 * [FIX] File `macro_steps.rb`: Recovered. Was missing in the 0.3.01 gem!
 
-## 0.3.01 / 2013-05-10
+### 0.3.01 / 2013-05-10
 * [NEW] features/ folder: added `demo06.feature` file showing the new conditional section.
 * [NEW] File `placeholder_spec.rb`: Added a RSpec file to test the Placeholder class.
 * [CHANGE] File `macro_steps.rb` Macro-step definition accepts the '*' Gherkin keyword.
@@ -102,15 +110,15 @@
 * [CHANGE] examples/ folder expanded and reorganized
 * [FIX] Method `Section#render` fixed typo in call to __method__
 
-## 0.3.00 / 2013-05-09 Version number bumped
+### 0.3.00 / 2013-05-09 Version number bumped
 * [CHANGE] Class `Templating::Engine` can handle conditional tags (TODO: document).
 * [CHANGE] File `engine_spec.rb`: Added a RSpec examples to test the conditional tags.
 
 
-## 0.2.22 / 2013-05-08
+### 0.2.22 / 2013-05-08
  [CHANGE] File `README.md`: expanded the section on macro arguments.
 
-## 0.2.21 / 2013-05-08
+### 0.2.21 / 2013-05-08
 * [NEW] Added new class `Templating::UnaryElement`.
 * [CHANGE] Made `Placeholder` class inherit from `UnaryElement`.
 * [NEW] Added new class `Templating::Section`, a subclass of `UnaryElement`.
@@ -118,52 +126,52 @@
 * [CHANGE] Method Engine#parse_tag modified in prevision of conditional tags.
 * [NEW] File `section_spec.rb`: Added a RSpec file to test the Conditional class.
 
-## 0.2.20 / 2013-05-07
+### 0.2.20 / 2013-05-07
 * [NEW] Added `examples` folder with a first example of an internationalized customisation of __Macros4Cuke__.
 
-## 0.2.19 / 2013-05-07
+### 0.2.19 / 2013-05-07
 * [CHANGE] Added validation of macro argument names in new `Engine::parse_tag` method.
 * [CHANGE] InvalidCharError exception added.
 * [CHANGE] File `engine_spec.rb`: Added one RSpec example for an invalid argument name.
 * [CHANGE] File `README.md`: added a new section on naming macro arguments.
 
-## 0.2.18 / 2013-05-06
+### 0.2.18 / 2013-05-06
 * [CHANGE] Amended spec files and added a new demo feature. SimpleCov code coverage raised to more than 97%.
 * [CHANGE] Macro-step arguments can be multivalued (experimental)
 
-## 0.2.17 / 2013-05-05
+### 0.2.17 / 2013-05-05
 * [CHANGE] File `engine_spec.rb`: Added more RSpec examples. SimpleCov code coverage raised to more than 96%.
 * [CHANGE] Added section in README.md
 
 
-## 0.2.16 / 2013-05-04
+### 0.2.16 / 2013-05-04
 * [FEATURE] Added dependency to SimpleCov. It is used to measure test code coverage (the combination of Cucumber and RSpec result in 95.9% code coverage).
 * [CHANGE] File `macro-step-support_spec.rb`: Added one RSpec example
 
-## 0.2.15 / 2013-05-03
+### 0.2.15 / 2013-05-03
 * [CHANGE] File `macro-step-support_spec.rb`: Added one RSpec example.
 * [FIX] Updated gemspec.
 
 
-## 0.2.14 / 2013-05-03
+### 0.2.14 / 2013-05-03
 * [CHANGE] Code comments reformatted to YARD. The command line `yard stats`display a 100% documented score!
 * [CHANGE] Moved all classes related to the template engine to the new module Templating.
 * [CHANGE] Classes `StaticRep, EOLRep, VariableRep, TemplateEngine` renamed to `StaticText, EOLine, Placeholder, Engine` respectively.
 * [CHANGE] Added spec file for `MacroStepSupport` module.
 * [CHANGE] Initialization of `MacroStepSupport` singleton changed (no dependency on `extended` hook).
 
-## 0.2.13 / 2013-05-02
+### 0.2.13 / 2013-05-02
 * [NEW] File `macro-collection_spec.rb`: partial spec file for the `MacroCollection` class.
 * [FIX] `DuplicateMacroError#initialize`: Removed superfluous [ in error message.
 
-## 0.2.12 / 2013-05-01
+### 0.2.12 / 2013-05-01
 * [CHANGE] Method `Macros4Cuke#compile` raise an `EmptyArgumentError` exception when a line contains an empty or blank argument.
 * [CHANGE] File `template-engine_spec.rb`: Added an example for error case mentioned in previous line.
 
-## 0.2.11 / 2013-05-01
+### 0.2.11 / 2013-05-01
 * [CHANGE] File `macros4cuke.gemspec`: Removed dependency on Rake.
 
-## 0.2.10 / 2013-04-30
+### 0.2.10 / 2013-04-30
 
 * [CHANGE] `CHANGELOG.md` replaces `HISTORY.md` file. Partial reformatting of historical entries to [Changelogs Convention](tech-angels.github.com/vandamme/#changelogs-convention)
 * [CHANGE] Method `MacroStep#initialize`: added the detection of two inconsistencies in macro arguments.
@@ -173,13 +181,13 @@
 * [CHANGE] File `macro-step_spec.rb`: Added examples covering the new validation rules in `MacroStep#initialize` method.
 * [FIX] `UnknownArgumentError#initialize` Typo in error message.
 
-## 0.2.09 / 2013-04-29
+### 0.2.09 / 2013-04-29
 
 * [CHANGE] Added one capturing group in regexp of macro defining step to detect data passing via table.
 * [CHANGE] Class `MacroStep`: added an explicit argument for data passing via table mode.
 
 
-## 0.2.08 / 2013-04-29
+### 0.2.08 / 2013-04-29
 
 * [CHANGE] Signature of `MacroStep#expand` changed.
 * [CHANGE] `MacroStep#validate_params` method is now private
@@ -188,45 +196,45 @@
 * [CHANGE] File `macro-step_spec.rb`: added test case when a macro is called with unknown argument.
 * [FIX] macro-step.rb: added a missing `require 'exceptions'`.
 
-## 0.2.07 / 2013-04-29
+### 0.2.07 / 2013-04-29
 
 * [FIX] Editorial improvements in `README.md`, corrected one inaccurate sentence.
 
 
-## 0.2.06 / 2013-04-28
+### 0.2.06 / 2013-04-28
 
 * [CHANGE] Formatting improvements in `README.md`.
 
 
-## 0.2.05 / 2013-04-28
+### 0.2.05 / 2013-04-28
 
 * [CHANGE] Expanded `README.md` with macro-step invokation, passing data value via a table.
 
 
-## 0.2.04 / 2013-4-27
+### 0.2.04 / 2013-4-27
 
 * [FIX] `MacroCollection#add_macro method`: typo correction.
 
 
-## 0.2.03 / Unreleased
+### 0.2.03 / Unreleased
 
 * [CHANGE] Regexp of defining step is more general: it accepts the Gherkin adverbs `Given, When, Then, And`.
 
 
-## 0.2.02 / 2013-4-26
+### 0.2.02 / 2013-4-26
 
 * [CHANGE] Added an example in `template-engine_spec.rb` file.
 * [CHANGE] Expanded `README.md` file.
 
 
-## 0.2.01 / 2013-4-26
+### 0.2.01 / 2013-4-26
 
 * [CHANGE] Regexps in step definitions accept escape character sequence. 
 * [CHANGE] Expanded `README.md` file.
 * [FIX] Corrected remnant of Mustache template in `travelling_demo.feature` file.
 
 
-## 0.2.00  / 2013-4-25  Version number was bumped
+### 0.2.00  / 2013-4-25  Version number was bumped
 
 * [CHANGE] Replaced the Mustache template engine by own lightweight TemplateEngine
 * [CHANGE] Macro-step arguments have a syntax that is closer to Gherkin's scenario outlines.
@@ -236,42 +244,42 @@
 * [CHANGE] examples in `README.md` updated.
 
 
-## 0.1.07 / 2013-4-24
+### 0.1.07 / 2013-4-24
 
 * [CHANGE] Added new class `TemplateEngine`.
 
 
-## 0.1.06 / 2013-4-24
+### 0.1.06 / 2013-4-24
 
 * [FIX] Format fix in README.md
 * [FIX] `HISTORY.md` file updated with missing entries/
 
 
-## 0.1.05 / Unreleased
+### 0.1.05 / Unreleased
 
 * [CHANGE] `demo_steps.rb`. Added few step definitions that emit output to the screen (so that at least something is shown in the demo).  
 * [CHANGE] `MacroStep` class: regexp slightly reworked to accept escaped double quotes in actual values. 
 * [CHANGE] `travelling_demo.feature`: Added one example with escaped quotes in actual value.
 
 
-## 0.1.04 / 2013-4-23
+### 0.1.04 / 2013-4-23
 
 * [ENHANCEMENT] Gherkin comments are allowed in sub-steps sequence. Previous version supported only Mustache comments.
 * [CHANGE] Added a few more examples in the `travelling-demo.feature` file.
 
 
-## 0.1.03 / 2013-4-23
+### 0.1.03 / 2013-4-23
 
 * [CHANGE] `README.md` slightly reworked and added link to Mustache.
 * [CHANGE] File `env.rb`: moved all dependencies on Macros4Cuke to the file `macro_support.rb`
 * [CHANGE] File `travelling-demo.feature`: Demo feature file with output on the screen (the other demos don't display any result).
 
 
-## 0.0.02 / 2013-04-21
+### 0.0.02 / 2013-04-21
 
 * [CHANGE] `README.md`: added a reference to the features folder.
 
 
-## 0.0.01 / 2013-04-21
+### 0.0.01 / 2013-04-21
 
 * [FEATURE] Initial public working version

data/README.md

@@ -59,6 +59,11 @@ Macros4Cuke not only helps in getting rid of the repeated step sequences,
 See also the working examples in the ```features/``` folder.
 
 ## Setup ##
+### Pre-requisites ###
+Macros4Cuke works with:  
+- MRI Ruby 1.9.x and 2.0.x.  
+- JRuby (was tested with version 1.7.3 and above).
+
 ### Installation ###
 To install the macros4cuke gem:
 ```bash  
@@ -406,6 +411,35 @@ Think of specific UI-events that can trigger some special system response.
 
 
 
+## FAQ ##
+__Q__: Can I define a macro in one scenario and invoke it in another scenario in the same feature file?  
+__A__: Yes. Once a macro is defined in a feature file it can be invoked in any scenario that follows the definition.  
+In fact, the macro can be invoked in any scenario from any feature file, provided the invokation takes place _after_ the 
+macro definition.  
+
+__Q__: So, a macro can be shared between multiple files.  
+__A__: Indeed. This is similar to genuine step definitions which are global (accessible to every feature files).
+For macro-steps, again, they can be used anywhere after their definition.  
+
+__Q__: How should I pass arguments: via the phrase or a data table?  
+__A__: Both data passing mechanisms can be used at the same time. Favour data value passing
+via the phrase when the number of macro arguments is small (say, <= 2).   
+
+__Q__: Can I define a macro-step in a Background section?  
+__A__: No. Here is why: Every step from the Background section is executed in each scenario (outline).
+If a macro were defined in the Background, then the macro definition will occur multiple times, which is
+ flagged as an error by Macros4Cuke.  
+ 
+__Q__: Can I define a macro-step in a Scenario Outline?  
+__A__: No, if the scenario outline has multiple rows then an error will occur. Bear in mind,
+that steps in a scenario outline are repeating n times, n being the number of rows in the example table.
+Since a macro can only be defined once, placing a macro definition in a scenario outline will
+most likely cause an error.  
+
+__Q__: Can I invoke/call a macro-step in a Background or Scenario Outline?  
+__A__: Yes. A macro-step can be invoked many times.
+
+
 
 ## With great power comes great responsibility. ##
 _Stan Lee_  

data/features/step_definitions/demo_steps.rb

@@ -32,7 +32,8 @@ SNIPPET
   begin
     steps(wrong)
   rescue Macros4Cuke::DataTableNotFound => exc
-    msg = 'The step with phrase [fill in the form with]: requires a data table.'
+    phrase = '[fill in the form with]:'
+    msg = "The step with phrase #{phrase} requires a data table."
     exc.message.should == msg
   end
 end

data/lib/macros4cuke/constants.rb

@@ -4,7 +4,7 @@
 
 module Macros4Cuke # Module used as a namespace
   # The version number of the gem.
-  Version = '0.3.24'
+  Version = '0.3.25'
 
   # Brief description of the gem.
   Description = 'Macros for Cucumber'

data/lib/macros4cuke/exceptions.rb

@@ -36,6 +36,17 @@ class UnreachableSubstepArgument < Macros4CukeError
 end # class
 
 
+# Raised when one passes one value for an argument via the macro-step's phrase
+# and a value for that same argument via the the data table.
+# and that argument name does not appear in any sub-step.
+class AmbiguousArgumentValue < Macros4CukeError
+  def initialize(anArgName, valuePhrase, valueTable)
+    msg = "The macro argument '#{anArgName}' has value '#{valuePhrase}' and 'valueTable'."
+    super(msg)
+  end
+end # class
+
+
 
 # Raised when a sub-step has an empty or blank argument name.
 class EmptyArgumentError < Macros4CukeError

data/lib/macros4cuke/macro-step.rb

@@ -136,14 +136,17 @@ private
     macro_parameters = {}
 
     # Retrieve the value(s) per variable in the phrase.
-    quoted_values = scan_arguments(aPhrase, :invokation)   
+    quoted_values = scan_arguments(aPhrase, :invokation)  
     quoted_values.each_with_index do |val, index|
       macro_parameters[phrase_args[index]] = val
     end
-
+    
     unless rawData.nil?
       rawData.each do |(a_key, value)|
         raise UnknownArgumentError.new(a_key) unless @args.include? a_key
+        if (phrase_args.include? a_key) && (macro_parameters[a_key] != value)
+          raise AmbiguousArgumentValue.new(a_key, macro_parameters[a_key], value)        
+        end
         if macro_parameters.include? a_key
           if macro_parameters[a_key].kind_of?(Array)
              macro_parameters[a_key] << value

data/spec/macros4cuke/macro-step_spec.rb

@@ -67,7 +67,6 @@ end
   context 'Provided services:' do
 
     let(:phrase_instance) { %Q|enter my credentials as "nobody"| }
-
     it 'should render the substeps' do
       text = subject.expand(phrase_instance, [ %w(password no-secret) ])
       expectation = <<-SNIPPET
@@ -117,6 +116,16 @@ SNIPPET
       ->(){ subject.expand(phrase_instance, args) }.should raise_error(
         UnknownArgumentError, error_message)
     end
+ 
+    
+    it 'should complain when argument gets a value from phrase and table' do
+      # Error case: there is no macro argument called <unknown>
+      phrase = %Q|enter my credentials as "nobody"|
+      msg = "The macro argument 'userid' has value 'nobody' and 'valueTable'."
+      args = [ %w(userid someone), %w(password no-secret) ]
+      ->(){ subject.expand(phrase, args) }.should raise_error(
+        AmbiguousArgumentValue, msg)
+    end
 
 
     it 'should expand built-in variables' do
@@ -135,7 +144,7 @@ SNIPPET
       expected = substeps.gsub(/<quotes>/, '"""')
       actual.should == expected
     end
-   
+  
 
   end # context
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: macros4cuke
 version: !ruby/object:Gem::Version
-  version: 0.3.24
+  version: 0.3.25
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-28 00:00:00.000000000 Z
+date: 2013-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cucumber