yard-cucumber 2.0.0

data/.rspec

@@ -0,0 +1,3 @@
+# /.rspec
+--format d
+--color

data/History.txt

@@ -0,0 +1,190 @@
+=== 2.0.0 / 2011-02-08
+
+* Cucumber In The YARD becomes `yard-cucumber` and with that gains the
+  benefits of being a YARD plugin
+
+=== 1.7.9 / 2011-02-05
+
+- FIX links to Scenarios and Transforms in various places
+- FIX Comments on Step Definitions that may blow up
+
+=== 1.7.8 / 2011-01-30
+
+* 'All Features' lands you on the root features directory; 'Requirements'
+  is still accessible through the breadcrumbs.
+* Feature directory pages will display all the features in all subdirectories 
+* Better sorting for features, tags, and step transformers.
+
+- FIX Feature-Scenario links and Cursors
+
+=== 1.7.7 / 2011-01-06
+
+* Feature Directories now support a README.md file that can be used to provide
+  information (with markdown support) about the directory of features.
+
+=== 1.7.6 / 2011-01-06
+
+* Feature descriptions, multi-line strings, and comments will preserve spacing.
+
+=== 1.7.5 / 2010-12-14
+
+* FIX Step Transforms were colliding with Step Definitions in Ruby 1.9.2
+  
+=== 1.7.4 / 2010-12-11
+
+* Ruby 1.9.2 Support
+* Change to YARD Server support:
+   yard server -e /path/to/gem/lib/server.b
+
+=== 1.7.3 / 2010-12-06
+
+* Shortcut Keys (t) for tags and (r) for features (f was taken)
+* Step definitions/transforms consolidate steps for easier viewing
+  and when they have no steps they are colored differently
+* Tag filtering supports inverse (~) of tags  
+
+* FIX Scenario Outlines without examples will not crash the parser
+* FIX Features, Scenarios, and Directories should display in alphabetic order
+* FIX Comments and multiline strings will display correctly
+* FIX Feature comments will show
+
+=== 1.7.2 / 2010-11-30
+
+* Step Definition and Transform page enhancements
+* Step Regex links to Rubular
+* FIX Steps with HTML encoded characters will display correctly
+
+=== 1.7.1 / 2010-11-28
+
+* Feature file with layout enhancements
+* Scenarios are now linked/linkable
+* FIX Scenario Outline error on CentOS, Ruby 1.8.7
+* FIX Requiring Cucumber before Gherkin so that correct gherkin is loaded
+
+=== 1.7.0 / 2010-11-18
+
+* Dynamic Tag Union / Intersection
+
+=== 1.6.4 / 2010-11-16
+
+* `yard server` can now serve up requirements with YARD 0.6.2
+* 'All Tags' page now has a cucumber tag AND filtering tool (beta)
+* Step Defs and Transforms will show comments
+
+* FIX removed warnings by no longer requiring YARD
+
+=== 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
+
+=== 1.6.0 / 2010-11-02
+
+* Feature directories, subdirectories, and Tags breadcrumb pages are present
+* Scenario Outlines now display each example inline when the example is clicked
+* 'All Features' and 'All Tags' links in the search fields
+
+=== 1.5.4 / 2010-10-28
+
+* Optimization - Found that for a large test suite that the processing time was
+  approaching 2 hours (oh boy!).  Reduced that time to a few minutes by optimizing
+  the feature handler to cache all step definitions and step transforms.
+
+* Step Transforms will now attempt to unpack any constants found within them.
+* FIX - Step Transforms were not being parsed because the regex incorrectly included
+  the block.
+* FIX - Features and Scenarios with multiple tags were not being displayed
+
+=== 1.5.3 / 2010-10-26
+
+* FIX - Step Definition YARD handler regex was poorly formed and raised exceptions
+  when it contained a forward-slash (even if escaped).
+* FIX - Step highlighting was causing 'Out Of Memory' issues because
+  gsub could not handle nil values.
+* FIX - Step highlighting failed to replace matches properly causing for corrupted
+  HTML span values to appear in the highlighted step definitions
+
+=== 1.5.2 / 2010-10-26
+
+* FIX - Step Transform YARD handler regex was poorly formed and raised exceptions
+  when a transform contained a forward-slash (even if escaped).
+
+=== 1.5.1 / 2010-10-26
+
+* Unified Feature/Scenario search field that resembles the Namespace-Class field
+* Tag search also displays immediate features/scenarios
+* Removed Scenario searching field
+* Added filename and line number to a number of locations
+* Minor Tag template enhancements
+* FIX - Scenario Outline Reference was being replaced with the first example
+* FIX - Scenario Outlines were not getting counted for tags
+
+=== 1.5 / 2010-10-25
+
+* Steps that have found their step definitions will also attempt to find their
+  step transforms (However step transforms are not unpacked yet like step
+  definitions).
+* Scenario Outlines will expand, behind the scenes, and match like traditional
+  scenarios.
+* FIX - duplication of owners that the tag reports has been removed.
+* INFO level messaging while processing features and scenarios to help assist
+  with feedback during the long processing.
+
+=== 1.4 / 2010-10-17
+
+* Tagusage has been retired
+* Tags are found during parsing by name or created and all uses are appended to the exising or newly created object
+* Tagusage template renamed and fixed up for just a tag and all the references
+* Tags are named tag_TAG (removed the @ as it was encoded during file serialization and I couldn't find an encoder helper)
+* Cleaned up all references in the fulldoc, full list to references tags
+
+* Moved Cucumber CodeObjects, Handlers, and Parsers to a Cucumber sub-directory
+* Moved StepDefinition and StepTransforms form extensions.rb to individual StepObject and Handlers files 
+
+* (lsegal advice) Created Cucumber Namespace and sub namespaces for features, tags, and step transformers.
+* (lsegal advice) Started to break apart the feature.erb into smaller digestable erb sections
+
+* Feature namespace now parallels the directory structure of the feature directory (from where it is parsed)
+* Feature files have simpler names; i.e. featurefile.html instead of featurefile.feature.html
+* Feature page title now states Feature: The Feature ( KEYWORD: FEATURE_TITLE )
+* Moved the templates to lib/templates so I could use yard/templates to override the YARD helpers
+
+* Changed document parsing to mirror the order imposed by Cucumber, this is to stop features being loaded before step definitions.
+  This should hopefully address the issue where steps were not being mapped correctly to step definitions.  This fixed the issue
+  in the small and large test suite I ran it against.
+  
+
+=== 1.3 / 2010-10-13
+
+* (7rans requested) Step definitions to show their source code; required a better source definition to be stored during creation of the CodeObject
+* Fixes to the Feature template which had some unclosed table header elements
+* Scenario Outline helper methods added to Scenarios
+* Scenario Outlines, Tables, and Multiline Strings had other minor CSS changes
+* Step tables and Scenario Example tables are no longer locked to 150px; instead that is the minimum width
+* Tables and Multiline Strings (PyStrings) are no longer displayed in the steps frame which was causing ugliness with the striping of the rows
+* (lsegal strongly recommended) Removed the pervasive use of filename in the CodeObjects
+* Cleaned up the fulldoc setup to remove the redundancy
+* Updated all the templates to support the lack of filename
+
+=== 1.2 / 2010-10-10
+
+* FIX: Empty Step Definitions caused failure during serialization
+* FIX: Empty Step Definitions caused failure during rendering HTML
+
+=== 1.1 / 2010-10-10
+
+* FIX: Feature template had references to old methods for description (when it was an array)
+* FIX: Empty feature files caused the documentation to fail; ignoring emptying feature files
+* FIX: Tags, Step definitions, and other CodeObjects that were not present caused rendering to fail; Checking for nil
+
+=== 1.0 / 2010-10-10
+
+* Initial Release

data/README.md

@@ -0,0 +1,145 @@
+Cucumber-In-The-YARD (CITY): A Requirements Documentation Tool
+====================================
+
+Synopsis
+--------
+
+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.
+
+Examples
+--------
+
+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.
+
+The implemented example has been deployed at [http://recursivegames.com/cukes/](http://recursivegames.com/cukes/).
+
+**1. View Features and Scenarios** [example](http://recursivegames.com/cukes/requirements/)
+
+**2. Search through [features, scenarios](http://recursivegames.com/cukes/feature_list.html), and [tags](http://recursivegames.com/cukes/tag_list.html)**
+
+**3. Dynamic Tag Unions and Intersections** [example](http://recursivegames.com/cukes/requirements/tags.html)
+
+**4. View all features and scenarios by tag** [example](http://recursivegames.com/cukes/requirements/tags/message.html)
+
+**5. View Step Definitions and Transforms** [example](http://recursivegames.com/cukes/requirements/step_transformers.html)
+
+**6. All steps [matched](http://recursivegames.com/cukes/requirements/step_transformers.html#definition_5-stepdefinition) to step definitions**
+
+**7. [Steps](http://recursivegames.com/cukes/requirements/step_transformers.html#transform_3-steptransform) that have transforms applied to them**
+
+**8. [Undefined steps](http://recursivegames.com/cukes/requirements/step_transformers.html#undefined_steps) and even [Rubular](http://rubular.com/) links of your step definitions.**
+
+**9. Feature directories with a README.md will be parsed into the description** [example](http://recursivegames.com/cukes/requirements/features.html)
+
+Installation
+------------
+
+Cucumber-In-The-Yard (CITY) requires the following gems installed:
+
+    Gherkin - http://cukes.info
+    Cucumber - http://cukes.info
+    YARD - http://yardoc.org
+
+To install CITY use the following command:
+
+    $ gem install yard-cucumber
+    
+(Add `sudo` if you're installing under a POSIX system as root)
+
+Usage
+-----
+
+YARD supports for automatically including gems with the prefix `yard-` 
+as a plugin. To enable automatic loading yard-cucumber. 
+
+1. Edit `~/.yard/config` and insert the following line:
+
+    load_plugins: true
+
+2. Run `yardoc`, use the rake task, or run `yard server`, as would [normally](https://github.com/lsegal/yard).
+
+Be sure to update any file patterns so that they do not exclude `feature` 
+files. yard-cucumber will even process your step definitions and transforms.
+
+    $ yardoc 'example/**/*.rb' 'example/**/*.feature'
+
+An example with the rake task:
+
+    require 'yard'
+
+    YARD::Rake::YardocTask.new do |t|
+      t.files   = ['features/**/*.feature', 'features/**/*.rb']
+      t.options = ['--any', '--extra', '--opts'] # optional
+    end
+
+Details
+--------
+
+There are two things that I enjoy: a test framework written in my own Domain
+Specific Language (DSL) that is easily understood by all those on a project
+and the ability for all participants to easily read, search, and view the tests.
+
+Cucumber is an amazing tool that allowed me to define exercisable requirements. 
+My biggest obstacle was bringing these requirements to my team, the product
+owner, and other stakeholders.
+
+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.
+
+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. It was when I started to convey to them the conventions that I had established that I wished I had a
+tool that would allow me to provide documentation like one would find generated 
+by a great tool like YARD.
+
+So I set out to integrate Cucumber objects like features, backgrounds, 
+scenarios, tags, steps, step definitions, and transforms into a YARD template.
+From my quick survey of the landscape I can see that the my needs are
+different than a lot of others that use Cucumber.  The entire project that
+spawned this effort was solely to exercise the functionality of a different,
+large project and so there is a huge dependence on having the requirements
+documented.  This is in contrast to other projects that are using this on a
+small scale to test the functionality of small software component.  Though,
+ultimately, I realized that the functionality may provide a valuable tool for
+many as I feel it helps more solidly bridge the reporting of the documentation
+by putting a coat of paint on it.
+
+
+LICENSE
+-------
+
+(The MIT License)
+
+Copyright (c) 2011 FIX
+
+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/Rakefile

@@ -0,0 +1,17 @@
+require 'rake'
+
+task :default => :yardoc
+
+task :clean do
+  `rm -rf doc`
+  `rm -rf .yardoc`
+end
+
+task :gendoc => :clean do
+  `yardoc -e ./lib/city.rb -p ./lib/templates 'example/**/*' --debug`
+end
+
+task :gem do
+  `gem build city.gemspec`
+  `gem install --local yard-cucumber-2.0.0.gem`
+end

data/city.gemspec

@@ -0,0 +1,66 @@
+require 'YARD'
+require File.dirname(__FILE__) + "/lib/yard-cucumber"
+
+module CucumberInTheYARD
+  def self.show_version_changes(version)
+    date = ""
+    changes = []  
+    grab_changes = false
+
+    File.open("#{File.dirname(__FILE__)}/History.txt",'r') do |file|
+      while (line = file.gets) do
+
+        if line =~ /^===\s*#{version.gsub('.','\.')}\s*\/\s*(.+)\s*$/
+          grab_changes = true
+          date = $1.strip
+        elsif line =~ /^===\s*.+$/
+          grab_changes = false
+        elsif grab_changes
+          changes = changes << line
+        end
+
+      end
+    end
+
+    { :date => date, :changes => changes }
+  end
+end
+
+Gem::Specification.new do |s|
+  s.name        = 'yard-cucumber'
+  s.version     = ::CucumberInTheYARD::VERSION
+  s.authors     = ["Franklin Webber"]
+  s.description = %{ 
+    YARD-Cucumber 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.  }
+  s.summary     = "Cucumber Features in YARD"
+  s.email       = 'franklin.webber@gmail.com'
+  s.homepage    = "http://github.com/burtlo/yard-cucumber"
+
+  s.platform    = Gem::Platform::RUBY
+  
+  changes = CucumberInTheYARD.show_version_changes(::CucumberInTheYARD::VERSION)
+  
+  s.post_install_message = %{
+(::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)
+
+  Thank you for installing yard-cucumber #{::CucumberInTheYARD::VERSION} / #{changes[:date]}.
+  
+  Changes:
+  #{changes[:changes].collect{|change| "  #{change}"}.join("")}
+(::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)
+
+}
+
+  s.add_dependency 'gherkin', '>= 2.2.9'
+  s.add_dependency 'cucumber', '>= 0.7.5'
+  s.add_dependency 'yard', '>= 0.6.3'
+  
+  s.rubygems_version   = "1.3.7"
+  s.files            = `git ls-files`.split("\n")
+  s.extra_rdoc_files = ["README.md", "History.txt"]
+  s.rdoc_options     = ["--charset=UTF-8"]
+  s.require_path     = "lib"
+end

data/example/README.md

@@ -0,0 +1,8 @@
+This collection of features are really just to test some of the varied cases
+that CITY may come in contact with while parsing a series of features.  All
+of the features, tags, and directories displayed here are contained in this 
+directory and all subdirectories.
+
+* First, the features which are broken down alphabetically and displayed
+* Second, the tags, used by all the features and scenarios
+* Third, the subdirectories, contained in this directory and in the subdirectories.

data/example/child_feature/README.md

@@ -0,0 +1,21 @@
+Child Features
+==============
+
+Synopsis
+--------
+
+This collection of features are contained in this folder.  The description README
+allows a user to place a description for entire directory of the features and appears
+in the output to assist with understanding about the collection of features.
+
+Resources
+---------
+
+Links to particular resources like the links to the stories, tasks, or other areas
+can also be represented.
+
+The implemented example has been deployed at [http://recursivegames.com/cukes/](http://recursivegames.com/cukes/).
+
+**1. An Item** [example](http://recursivegames.com/cukes/requirements/)
+
+

data/example/child_feature/child.feature

@@ -0,0 +1,11 @@
+@scenarios
+Feature: Child Feature
+  As a reader of the documentation I expect that scenario are documented correctly
+
+  Background:
+    Given this background step
+
+  Scenario: Child Scenario
+    Given this first step
+	  When this second step
+	  Then this third step

data/example/child_feature/grandchild_feature/grandchild.feature

@@ -0,0 +1,12 @@
+@scenarios
+Feature: Grandchild Feature
+  As a reader of the documentation I expect that scenario are documented correctly
+
+  Background:
+    Given this background step
+
+  @first
+  Scenario: Grandchild Scenario
+    Given this first step
+  	When this second step
+	  Then this third step

data/example/empty.feature

@@ -0,0 +1,2 @@
+# This is a feature that has not been written
+# However, I don't want parser to fail when reaching this file

data/example/scenario.feature

@@ -0,0 +1,63 @@
+# Comments that appear before the feature are associated with the feature
+@scenarios
+Feature: Displaying Scenarios
+  As a reader of the documentation I expect that scenario are documented correctly
+  
+  # Comments after the feature description belong to the background or first scenario
+  Background:
+    Given this background step
+
+  @first @bvt
+  Scenario: No Step Scenario
+
+  @second @bvt
+  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!
+    That this text has to take up two lines
+      This line should be indented 2 spaces
+        This line should be indented 4 spaces      
+    """
+
+  # Comments before the scenario
+  @seventh @comments
+  Scenario: Scenario with comments and a description
+    There once was a need for information to be displayed alongside all the
+    entities that I hoped to test
+    # First Comment
+    Given this first step
+    # Second Comment that
+    # spans a few lines
+    And this second step
+    # Third Comment
+    And this third step
+    # Comments after the last step, where do they go?
+
+  Scenario: Step ending with a match with double-quotes
+    When searching the log for the exact match of the message "Entering application."
+    When the step definition has HTML escaped characters like: "<>&"

data/example/scenario_outline.feature

@@ -0,0 +1,80 @@
+@scenario_outlines @bvt
+Feature: Displaying Scenario Outlines
+  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 |
+     
+  # This is an example of a scenario outline in development.
+  # The example table has not been defined yet
+  Scenario Outline: Example Table Missing
+    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
+      
+    
+  # This is an example of a scenario outline in development.  
+  # The examples table has been defined, but is missing data.
+  Scenario Outline: Empty Example Table
+    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 |