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. 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. **4. Steps link to Step definitions. Step definitions show all uses.** 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. 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 cucumber-in-the-yard (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 ----- **1. Rake Task** You can do this by adding the following to your `Rakefile`: require "yard" require "city" YARD::Rake::CitydocTask.new do |t| t.files = ['features/**/*.feature', 'features/**/*.rb', OTHER_PATHS] # optional t.options = ['--any', '--extra', '--opts'] # optional end both the `files` and `options` settings are optional. `files` will default to `lib/**/*.rb` and `options` will represents any options you might want 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: 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. Roadmap ------- **Version 1** Current feature set is all that I had planned for this first release. **1. Users are able to search by Feature, Tags, and Scenario.** **2. Feature pages are displayed in a decently formatted HTML representation** **3. Tag pages display all the Features and scenarios that currently employ the tag.** **4. Steps link to Step definitions. Step definitions show all uses.** Subsequent updates are fixes or enhancements to the fundamental structure behind the scenes. Lsegal, has been extremely helpful in assisting me with the re-organization and refinement of this first release. **Future Feature Ideas** **1. Users are able to search Features, Scenarios, and Tags in a unified search box.** I want to rid the three added search fields and provide one unified search field that will use YARD's namespace structure (similar to how Class List works). **2. Tag pages provide the ability to exclude other tags that intersect.** Adding a list of tags currently used by the features and scenarios in the below list (that are not the current tag). Allowing the visualization of what the execution of the requirements pass would look like. Output of a sample generated tag command-line would be displayed to assist with execution. On selection update of the total features and scenarios affected by the changes in the filtering. I would like to also address some layout and formatting on the page. Scenarios will also link to the scenarios feature page, show their descriptions, and of course all their other tags. **3. Step Trasnforms would be displayed where they are used** These tricky pieces of code tend to trip me up and others on the project. I want to be able to show which steps that have mapped to step definitions are being affected by step transforms. **4. Highlight the sections of steps that match in the step definition** Similar to the great output that Cucumber uses to show what is the variable part of the step definition, I would like to have the steps displayed differently to illustrate that they are the variable in the statement. LICENSE ------- (The MIT License) Copyright (c) 2010 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.