cucumber-in-the-yard 1.6.1 → 1.6.3

data/History.txt

@@ -1,3 +1,16 @@
+=== 1.6.3 / 2010-11-08
+
+* FIX Step Definitions and Step Transforms incorrectly cached the YARD Constants
+
+=== 1.6.2 / 2010-11-07
+
+* Undefined Steps are displayed on the Step Transformer page
+* Defined and Undefined steps are better linked to the Transformer page
+
+* FIX Requirements tags were conflicting with YARD tags and being displayed
+  in multiple locations
+* FIX Scenario Outlines Examples failed to show their tables or text
+
 === 1.6.1 / 2010-11-04
 
 * FIX - Feature Directries with sub-directories aborted serialization

data/README.md

@@ -4,59 +4,35 @@ Cucumber-In-The-YARD (CITY): A Requirements Documentation Tool
 Synopsis
 --------
 
-Cucumber-In-The-Yard is a YARD extension that processes Cucumber Features, Scenarios, Steps,
-Step Definitions, Transforms, and Tags and provides a documentation interface that allows you
-easily view and investigate the test suite.  This tools hopes to bridge the gap of being able
-to provide your feature descriptions to your Product Owners and Stakeholders.
+Cucumber-In-The-Yard is a YARD extension that processes Cucumber features, scenarios, steps,
+tags, step definitions, and even transforms to provide documentation similar to what you expect
+to how YARD displays classes, methods and constants.  This tools bridges the gap of having 
+feature files found in your source code and true documentation that your team, product owners
+and stakeholders can use.
 
-Example
--------
-
-An example, particularly the example features included with the project, of CITY can be viewed at
-
-   [http://recursivegames.com/cukes/](http://recursivegames.com/cukes/)    
-
-**1. Users are able to search by Feature, Tags, and Scenario.**
-
-Appended to the traditional search areas is the ability to now search by Feature, Tag, and Scenario.
-The user is able to search by steps, though I have not placed those links on the page, in step_list.html
-found in the root of the output directory.
-
-**2. Feature pages are displayed in a decently formatted HTML representation**
-
-As opposed to pointing team members, stakeholders, and product owners to feature files which require 
-an editor with syntax highlighting.  As well as providing the ability to quickly follow tags and steps 
-for more information.
-
-**3. Tag pages display all the Features and scenarios that currently employ the tag.**
-
-Providing quick access to the important tag divisions that have been created in a project.  
-On the top of the page there are some quick calculations of the number of features and scenarios that
-share the specified tag. 
+Examples
+--------
 
-**4. Steps link to Step definitions.  Step definitions show all uses.**
+I have created a trivial, example project to help provide a quick visualization of the resulting
+documentation.  I encourage you to look at it as an example and see if it would assist your 
+project from a multitude of perspectives: as the project's core developer; another developer or 
+a new developer; quality assurance engineer; or product owner/stakeholder.
 
-Step definitions are displayed in their own index page and for each step definition a list of implemented
-steps for this step definition.  This is useful for providing example documentation and quickly understanding
-which scenarios are affected by a change to a step definition.
+The implemented example has been deployed at [http://recursivegames.com/cukes/](http://recursivegames.com/cukes/).
 
-**5. Step Transforms are displayed as links in the step definitions**
+**1. Formatted Features** [example](http://recursivegames.com/cukes/requirements/example/scenario.html)
 
-After finding the Step to Step Definition link it looks at the match groups within the step and find which
-ones match the step transforms.  Step transform links can be found after following a link from the step to 
-the step definition.
+**2. Search through features, scenarios, and tags** [example](http://recursivegames.com/cukes/feature_list.html) & [example](http://recursivegames.com/cukes/tag_list.html)
 
-**6. Highlight the sections of steps that match in the step definition**
+**4. View features and scenarios by tag** [example](http://recursivegames.com/cukes/requirements/tags/bvt.html)
 
-Steps highlight the match groups in a different color to show which parts of the step are matched in the step
-definition.
+**5. Steps link to their step definitions** [example](http://recursivegames.com/cukes/requirements/example/scenario.html)
 
-**7. Represent instances of scenarios for scenario outlines.**
+**6. Step definitions show implemented steps** [example](http://recursivegames.com/cukes/requirements/step_transformers.html#definition_13-stepdefinition)
 
-Display all the values that would normally be substituted into a scenario for the scenario outline. To 
-make it easier to represent them to product owners.  As well as link the instance of the step definitions
-for developers.
+**7. Step definitions show the step transforms used** [example](http://recursivegames.com/cukes/requirements/step_transformers.html#transform_8-steptransform)
 
+**8. Undefined steps are listed** [example](http://recursivegames.com/cukes/requirements/step_transformers.html#undefined_steps)
 
 Installation
 ------------
@@ -73,10 +49,6 @@ To install CITY use the following command:
     
 (Add `sudo` if you're installing under a POSIX system as root)
 
-Alternatively, if you've checked the source out directly, you can call 
-`rake install` from the root project directory.
-
-
 Usage
 -----
 
@@ -88,7 +60,7 @@ You can do this by adding the following to your `Rakefile`:
     require "city"
 
     YARD::Rake::CitydocTask.new do |t|
-      t.files   = ['features/**/*.feature', 'features/**/*.rb', OTHER_PATHS]   # optional
+      t.files   = ['features/**/*', OTHER_PATHS]   # optional
       t.options = ['--any', '--extra', '--opts'] # optional
     end
 
@@ -98,6 +70,10 @@ to add. Again, a full list of options is available by typing `yardoc --help`
 in a shell. You can also override the options at the Rake command-line with the
 OPTS environment variable:
 
+**2. YARD command-line**
+
+    $ yardoc -e path/to/cucumber-in-the-yard/lib/city.rb -p path/to/cucumber-in-the-yard/lib/templates 'features/**/*.*'
+
 
 Details
 --------
@@ -111,7 +87,9 @@ bringing these requirements to my team, the product owner, and other stakeholder
 
 Initially I tried to expose more of the functionality by providing freshly authored requirements through 
 email, attachments to JIRA tickets, or linked in wiki documents.  None of these methods were very sustainable 
-or successful.  First, I was continually pushing out the documents to those interested.  Second, the documents were displayed to the user in text without the syntax highlighting that was exceedingly helpful for quickly understanding the requirements.
+or successful.  First, I was continually pushing out the documents to those interested.  Second, the documents 
+were displayed to the user in text without the syntax highlighting that was exceedingly 
+helpful for quickly understanding the requirements.
 
 I also found it hard to share the test framework that I had put together with another developer that joined 
 the team.  It was difficult to direct them around the features, tags, step definitions, and transforms.  
@@ -160,7 +138,6 @@ hooks that are tied to tags (unions and intersections) on the tag pages.
 
 More work could be done to make this page more searchable, sortable, and usable.
 
-
 **6. Table Step Transforms**
 
 The table step transform matching would be nice to show which tables are affected by table transforms

data/example/child_feature/grandchild_feature/scenario.feature

@@ -0,0 +1,52 @@
+@scenarios
+Feature: Scenario
+  As a reader of the documentation I expect that scenario are documented correctly
+
+  Background:
+    Given this background step
+
+  @first
+  Scenario: No Step Scenario
+
+  @second
+  Scenario: Scenario With Steps
+    Given this first step
+	When this second step
+	Then this third step
+	
+  @third @optional_parameters
+  Scenario: Optional Parameter Step Definition
+    # This step definition has some optional parameters
+    Given a project
+    And an inactive project
+    And a project with the name 'optional', start date 10/26/2010, nicknamed 'norman'
+
+  @fourth @highlight
+  Scenario: Matched Term Highlighting
+    Given a duck that has a bill
+    Then I expect the duck to quack
+
+  @fifth @table
+  Scenario: Scenario With Table
+    Given the following table:
+      | column 1 | column 2 | column 3 |
+      | value 1  | value 2  | value 3  |
+
+  @sixth @text
+  Scenario: Scenario With Text
+    Given the following text:
+    """
+      Oh what a bother!
+    """
+
+  @seventh @comments
+  Scenario: Scenario with comments and 
+    with multiple lines for the name
+    # First Comment
+    Given this first step
+    # Second Comment
+    And this second step
+    # Third Comment
+    And this third step
+    # Comments after the last step, where do they go?
+

data/example/child_feature/scenario.feature

@@ -0,0 +1,52 @@
+@scenarios
+Feature: Scenario
+  As a reader of the documentation I expect that scenario are documented correctly
+
+  Background:
+    Given this background step
+
+  @first
+  Scenario: No Step Scenario
+
+  @second
+  Scenario: Scenario With Steps
+    Given this first step
+	When this second step
+	Then this third step
+	
+  @third @optional_parameters
+  Scenario: Optional Parameter Step Definition
+    # This step definition has some optional parameters
+    Given a project
+    And an inactive project
+    And a project with the name 'optional', start date 10/26/2010, nicknamed 'norman'
+
+  @fourth @highlight
+  Scenario: Matched Term Highlighting
+    Given a duck that has a bill
+    Then I expect the duck to quack
+
+  @fifth @table
+  Scenario: Scenario With Table
+    Given the following table:
+      | column 1 | column 2 | column 3 |
+      | value 1  | value 2  | value 3  |
+
+  @sixth @text
+  Scenario: Scenario With Text
+    Given the following text:
+    """
+      Oh what a bother!
+    """
+
+  @seventh @comments
+  Scenario: Scenario with comments and 
+    with multiple lines for the name
+    # First Comment
+    Given this first step
+    # Second Comment
+    And this second step
+    # Third Comment
+    And this third step
+    # Comments after the last step, where do they go?
+

data/example/scenario.feature

@@ -0,0 +1,51 @@
+@scenarios @bvt
+Feature: Scenario
+  As a reader of the documentation I expect that scenario are documented correctly
+
+  Background:
+    Given this background step
+
+  @first
+  Scenario: No Step Scenario
+
+  @second
+  Scenario: Scenario With Steps
+    Given this first step
+    When this second step
+    Then this third step
+
+  @third @optional_parameters
+  Scenario: Optional Parameter Step Definition
+    # This step definition has some optional parameters
+    Given a project
+    And an inactive project
+    And a project with the name 'optional', start date 10/26/2010, nicknamed 'norman'
+
+  @fourth @highlight
+  Scenario: Matched Term Highlighting
+    Given a duck that has a bill
+    Then I expect the duck to quack
+
+  @fifth @table
+  Scenario: Scenario With Table
+    Given the following table:
+      | column 1 | column 2 | column 3 |
+      | value 1  | value 2  | value 3  |
+
+  @sixth @text
+  Scenario: Scenario With Text
+    Given the following text:
+      """
+        Oh what a bother!
+      """
+
+  @seventh @comments
+  Scenario: Scenario with comments and
+    with multiple lines for the name
+
+    # First Comment
+    Given this first step
+    # Second Comment
+    And this second step
+    # Third Comment
+    And this third step

data/example/scenario_outline.feature

@@ -0,0 +1,60 @@
+@scenario_outlines @bvt
+Feature: Scenario Outline
+  As a reader of the documentation I expect that scenario outlines are documented correctly
+
+  @first
+  Scenario Outline: Three Examples
+    Given that <Customer> is a valid customer
+    And that the product, named '<Product>', is a valid product
+    When the customer has purchased the product
+    Then I expect the customer to be a member of the '<Product>' group
+
+    Examples:
+     | Customer   | Product   |
+     | Customer A | Product A |
+     | Customer A | Product B |
+     | Customer A | Product C |
+
+  @second
+  Scenario Outline: Step contains a text block
+    Given the following text:
+    """
+    The <noun> jumped over the <place>
+    """
+    When I click on an example row
+ 	Then I expect <noun> to be replaced by the example noun
+    And I expect <place> to be replaced by the example place
+    
+    Examples:
+     | noun  | place |
+     | cow   | moon  |
+     | horse | spoon |
+
+  @third
+  Scenario Outline: Step contains a table
+    Given the following table:
+      | name   | price   | quantity |
+      | <name> | <price> | 100000   |
+    When I click on an example row
+ 	Then I expect <name> to be replaced by the example name
+    And I expect <price> to be replaced by the example price
+
+    Examples:
+     | name | price |
+     | toy  | $99   |
+     | game | $49   |
+
+  @fourth
+  Scenario Outline: Step contains a table; table header uses an example
+    Given the following table:
+      | name   | <denomination> | quantity |
+      | <name> | <price>        | 100000   |
+	When I click on an example row
+ 	Then I expect <name> to be replaced by the example name
+    And I expect <price> to be replaced by the example price
+    And I expect <denomination> to be replaced by the example denomination
+
+    Examples:
+     | name | price | denomination    |
+     | toy  | 99    | cost in euros   |
+     | game | 49    | cost in dollars |

data/example/step_definitions/example.step.rb

@@ -1,6 +1,7 @@
-CUSTOMER = /(?:(?:an?|the) customer|#{TEDDY_BEAR})/
 
-TEDDY_BEAR = /teddy bear/
+Transform /^#{CUSTOMER}$/ do |customer|
+  "a transformed customer"
+end
 
 Transform /^an? customer$/ do |customer|
   "a transformed customer"
@@ -10,6 +11,10 @@ Transform /^the customer$/ do |customer|
   "the transformed customer"
 end
 
+Transform /^(#{ORDER}) customer$/ do |order|
+  "#{order} customer"
+end
+
 Transform /^#{TEDDY_BEAR}$/ do |teddy|
   "the tranformed teddy bear"
 end

data/example/step_definitions/first.step.rb

@@ -0,0 +1,15 @@
+Transform /^#{ORDER}$/ do |order|
+  order
+end
+
+Transform /^background$/ do |background|
+  "background"
+end
+
+Transform /^scenario$/ do |scenario|
+  "scenario"
+end
+
+Given /^this (scenario|background|#{ORDER}) step$/ do |step|
+  pending "step #{order}"
+end

data/example/step_definitions/support/support.rb

@@ -0,0 +1,6 @@
+
+ORDER = /(?:first|second|third)/
+
+TEDDY_BEAR = /teddy bear/
+
+CUSTOMER = /(?:(?:an?|the|#{ORDER}) customer|#{TEDDY_BEAR})/

data/example/transform.feature

@@ -0,0 +1,13 @@
+@scenarios @bvt
+Feature: Step Transforms
+  As a developer of the test suite I expect that step transforms are documented correctly
+
+  @first
+  Scenario: Step with step transformation
+    Given this scenario step
+    Then I expect that the step, on the step transformer page, will link to the step transform
+
+  @second
+  Scenario: Step Transform uses a constant
+    Given this first step
+    Then I expect that the step, on the step transformer page, will link to the step transform

data/lib/city.rb

@@ -6,7 +6,7 @@ require 'gherkin/formatter/tag_count_formatter'
 require 'yard'
 
 module CucumberInTheYARD
-  VERSION = '1.6.1' unless defined?(CucumberInTheYARD::VERSION)
+  VERSION = '1.6.3' unless defined?(CucumberInTheYARD::VERSION)
 end
 
 
@@ -20,6 +20,7 @@ require File.dirname(__FILE__) + "/yard/code_objects/cucumber/tag.rb"
 
 require File.dirname(__FILE__) + "/cucumber/city_builder.rb"
 
+require File.dirname(__FILE__) + "/yard/code_objects/step_transformer.rb"
 require File.dirname(__FILE__) + "/yard/code_objects/step_definition.rb"
 require File.dirname(__FILE__) + "/yard/code_objects/step_transform.rb"
 require File.dirname(__FILE__) + "/yard/code_objects/namespace_object.rb"

data/lib/cucumber/city_builder.rb

@@ -125,10 +125,15 @@ module Cucumber
               s.keyword = step.keyword.dup
               s.value = step.value.dup
               s.add_file(@file,step.line_number)
+
+              s.text = step.text.dup if step.has_text?
+              s.table = clone_table(step.table) if step.has_table?
             end
 
             @step_container.example_values_for_row(row_index).each do |key,text|
               step_instance.value.gsub!("<#{key}>",text)
+              step_instance.text.gsub!("<#{key}>",text) if step_instance.has_text?
+              step_instance.table.each{|row| row.each{|col| col.gsub!("<#{key}>",text)}} if step_instance.has_table?
             end
 
             step_instance.scenario = scenario
@@ -159,6 +164,7 @@ module Cucumber
         when Gherkin::Formatter::Model::PyString
           @table_owner.text = multiline_arg.value
         when Array
+          #log.info "Matrix: #{matrix(multiline_arg).collect{|row| row.collect{|cell| cell.class } }.flatten.join("\n")}"
           @table_owner.table = matrix(multiline_arg)
         end
         
@@ -184,6 +190,10 @@ module Cucumber
           row
         end
       end
+
+      def clone_table(base)
+        base.map {|row| row.map {|cell| cell.dup }}
+      end
     end
   end
 end

data/lib/templates/default/feature/html/no_steps_defined.erb

@@ -1 +1 @@
-<span>No Steps Defined</span>
+<span class="none">No Steps Defined</span>

data/lib/templates/default/feature/html/outline.erb

@@ -1,31 +1,38 @@
 <% @scenario.scenarios.each_with_index do |scenario,example_index| %>
-  <div id="<%= "#{@id}Example#{example_index + 1}Steps" %>" style="display: none;" class="steps">
-    <% scenario.steps.each_with_index do |step,index| %>
-      <% @step = step %>
-
-
-      <div <%= "id='#{@id}Example#{example_index + 1}Step#{index}'" %> class="step <%= (index + 1) % 2 == 0 ? 'even' : 'odd' %>">
-        <span class="predicate"><%= step.keyword %></span>
-
-        <% if step.definition %>
-          <span class="defined">
-            <%=  highlight_matches(step) %>
-            <div class="details">
-              <a href="<%= url_for step.definition %>">?</a>
-            </div>
-          </span>
-        <% else %>
-          <span class="undefined"><%= h step.value %></span>
-        <% end %>
-
-      </div>
+<div id="<%= "#{@id}Example#{example_index + 1}Steps" %>" style="display: none;" class="steps">
+  <% scenario.steps.each_with_index do |step,index| %>
+  <% @step = step %>
 
-      <%= erb(:table) if step.has_table? %>
-      <%= erb(:pystring) if step.has_text? %>
 
+  <div <%= "id='#{@id}Example#{example_index + 1}Step#{index}'" %> class="step <%= (index + 1) % 2 == 0 ? 'even' : 'odd' %>">
+    <span class="predicate"><%= step.keyword %></span>
 
+    <% if step.definition %>
+    <span class="defined">
+      <%=  highlight_matches(step) %>
+      <div class="details">
+        <a href="<%= url_for step.definition %>"><div class="valid">&nbsp;</div></a>
+      </div>
+    </span>
+    <% else %>
+    <span class="undefined">
+      <%= h step.value %>
+      <div class="details">
+        <a href="<%= url_for YARD::CodeObjects::Cucumber::CUCUMBER_STEPTRANSFORM_NAMESPACE %>#undefined_steps">
+          <div class="invalid">&nbsp;</div>
+        </a>  
+      </div>
+    </span>
     <% end %>
+
   </div>
+
+  <%= erb(:table) if step.has_table? %>
+  <%= erb(:pystring) if step.has_text? %>
+
+
+  <% end %>
+</div>
 <% end %>
 
 
@@ -35,17 +42,17 @@
     <thead>
       <tr>
         <% @scenario.example_headers.each_with_index do |header,header_index| %>
-          <th><%= h(header) %></th>
+        <th><%= h(header) %></th>
         <% end %>
       </tr>
     </thead>
     <% @scenario.example_data.each_with_index do |row,row_index| %>
-      <tr class="<%= (row_index + 1) % 2 == 0 ? 'even' : 'odd' %>"
-          onclick="<%= "toggleScenarioExample('#{@id}',#{row_index + 1});" %>">
-            <% row.each_with_index do |column,column_index| %>
-          <td><%= h(column.to_s.strip) %></td>
-        <% end %>
-      </tr>
+    <tr class="<%= (row_index + 1) % 2 == 0 ? 'even' : 'odd' %>"
+      onclick="<%= "toggleScenarioExample('#{@id}',#{row_index + 1});" %>">
+      <% row.each_with_index do |column,column_index| %>
+      <td><%= h(column.to_s.strip) %></td>
+      <% end %>
+    </tr>
     <% end %>
   </table>
 </div>

data/lib/templates/default/feature/html/scenario.erb

@@ -34,7 +34,7 @@ $(function() {
 	<% end %>
 
         <div id="<%= @id %>Steps" class="steps">
-          <%= @scenario.steps ? erb(:steps) : erb(:no_steps_defined) %>
+          <%= @scenario.steps.empty? ? erb(:no_steps_defined) : erb(:steps) %>
         </div>
   
         <%= erb(:outline) if @scenario.outline? %>

data/lib/templates/default/feature/html/steps.erb

@@ -5,21 +5,33 @@
   <div <%= "id='#{@id}Step#{index}'" %> class="step <%= (index + 1) % 2 == 0 ? 'even' : 'odd' %>">
     <span class="predicate"><%= step.keyword %></span>
 
+    <% if @scenario.outline? %>
+      <%= step.value %>
+    <% else %>
+
     <% if step.definition %>
-      <span class="defined">
-        <%=  highlight_matches(step) %>
-        <div class="details">
-          <a href="<%= url_for step.definition %>">?</a>
-        </div>
-      </span>
+    <span class="defined">
+      <%=  highlight_matches(step) %>
+      <div class="details">
+        <a href="<%= url_for step.definition %>"><div class="valid">&nbsp;</div></a>
+      </div>
+    </span>
     <% else %>
-      <span class="undefined"><%= h step.value %></span>
+    <span class="undefined">
+      <%= h step.value %>
+      <div class="details">
+        <a href="<%= url_for YARD::CodeObjects::Cucumber::CUCUMBER_STEPTRANSFORM_NAMESPACE %>#undefined_steps">
+          <div class="invalid">&nbsp;</div>
+        </a>  
+      </div>
+    </span>
     <% end %>
 
+    <% end %>
   </div>
 
   <%= erb(:table) if step.has_table? %>
   <%= erb(:pystring) if step.has_text? %>
 
 
-<% end %>
+  <% end %>

data/lib/templates/default/feature/html/table.erb

@@ -1,20 +1,20 @@
 <div class="multiline">
-	<table style="">
+  <table style="">
 
-		<thead>
-			<tr>
-				<% @step.table.first.each_with_index do |column,column_index| %>
-				<th class="<%= (column_index + 1) % 2 == 0 ? 'even' : 'odd' %>"><%= h(column.strip) %></th>
-				<% end %>
-			</tr>
-		</thead>
+    <thead>
+      <tr>
+        <% @step.table.first.each_with_index do |column,column_index| %>
+          <th class="<%= (column_index + 1) % 2 == 0 ? 'even' : 'odd' %>"><%= h(column.strip) %></th>
+        <% end %>
+      </tr>
+    </thead>
 
-		<% @step.table[1..-1].each_with_index do |row,row_index| %>
-		<tr class="<%= (row_index + 1) % 2 == 0 ? 'even' : 'odd' %>">
-			<% row.each_with_index do |column,column_index| %>
-			<td><%= h(column.strip) %></td>
-			<% end %>
-		</tr>
-		<% end %>
-	</table>
+    <% @step.table[1..-1].each_with_index do |row,row_index| %>
+      <tr class="<%= (row_index + 1) % 2 == 0 ? 'even' : 'odd' %>">
+        <% row.each_with_index do |column,column_index| %>
+          <td><%= h(column.strip) %></td>
+        <% end %>
+      </tr>
+    <% end %>
+  </table>
 </div>

data/lib/templates/default/feature/setup.rb

@@ -33,7 +33,7 @@ def highlight_matches(step)
   value = h(step.value)
   
   if step.definition
-    matches = step.value.match(%r{#{step.definition.compare_value}})
+    matches = step.value.match(step.definition.regex)
     
     if matches
       matches[1..-1].reverse.each_with_index do |match,index|