README.md in cukedep-0.0.5 vs README.md in cukedep-0.0.6

- old
+ new

@@ -1,35 +1,62 @@ Cukedep =========== [![Build Status](https://travis-ci.org/famished-tiger/cukedep.png?branch=master)](https://travis-ci.org/famished-tiger/cukedep) [![Gem Version](https://badge.fury.io/rb/cukedep.png)](http://badge.fury.io/rb/cukedep) -_Handle dependencies between feature file._ +_Handle dependencies between feature files._ [Homepage](https://github.com/famished-tiger/cukedep) -__Cukedep__ is a command-line utility that helps to run a set feature files in the proper sequence. +### What is Cukedep? ### +__Cukedep__ is a command-line utility that helps to execute Cucumber feature files +in a sequence that meets their dependencies. +With __Cukedep__ you can: +* Specify that a given feature file has one or other feature files as its pre-requisite. +* Manage the dependencies, thanks to dependency reports and diagram. +* Overcome Cucumber's constraint: file name sort order == execution order + +### Should dependencies between feature files not be banned? ### +The short answer is a "Yes but..." + +In an ideal world, tests and feature files could be run one independently of each other. +However, when the feature file set grows in size and complexity it becomes more and more +difficult to guarantee watertight isolation between feature files. For instance, steps in a feature file may have side effects +that influence the results of scenarios from another feature. +While side effects are often undesirable, that does not means that they should ALWAYS be +avoided: +* Because the removal/reversal of a side effect can be too complicated or tedious, +* Because the results of a feature can be re-used with profit in another feature. + +To illustrate the second point consider the following case: +* You want to test the calculation of invoices but the business of your company +involves many kinds of billable transactions with their own complicated lifecycle +(e.g. a purchase order). It might be more expedient to test the invoicing by +re-using paying transactions generated by other -specialized- features. As a consequence, +most invoice-related features should run after the execution of the paying transaction. +Feature file isolation has been traded off for efficiency. + ### Highlights ### -* Simple syntax to specify dependencies +* Simple syntax to specify dependencies in your feature files * Generates dependency reports (in CSV format) -* Generates dependency diagram (in DOT format), +* Generates dependency diagram (in GraphViz's DOT format), * Generates a Rake file. ### Installation ### -The installation of the cukedep gem is fairly standard: +The installation of the __cukedep__ gem is fairly standard: ```bash $[sudo] gem install cukedep ``` To check the installation, open a shell/command window and type the command-line: ```bash cukedep --version ``` -You should see the version of cukedep gem. +You should see the version of __cukedep__ gem. ### Synopsis ### To get a first taste of how cukedep works, install it first. Then go to the root dir of the cukedep gem, then open a shell/command window @@ -38,21 +65,21 @@ rake ``` You will see tests running and Cucumber executing a number of feature files. -To learn more what's happening, go to the ```rspec/sample_features``` dir -You will notice a number of feature files for a sample application. -Stay in that folder and type the following command-line: +To learn more what's happening, go to the ```rspec/sample_features``` dir. +You will notice a number of feature files for a sample application. +Stay in that folder and type the following command-line: ```bash cukedep --project ../../../sample --dry-run ``` -You told cukedep to do the following: -* Read (parse) all the feature files in the current dir. -* Resolve the dependencies between the feature files (based on Gherkin @tags with a special format). -* Generate a number of dependency reports and drawing. +You told cukedep to do the following: +* Read (parse) all the feature files in the current dir. +* Resolve the dependencies between the feature files (based on Gherkin @tags with a special format). +* Generate a number of dependency reports and drawing. * Generate a rake file that will execute the feature files in the proper sequence for the project located at the relative path ```../../../sample``` To generate all the above files and run the feature files with Cucumber, then retry the command line without the --dry-run option: @@ -61,38 +88,42 @@ ``` Now you see cukedep redoing the same actions as previously but in addition it: * Copies a feature file from the current directive to the Cucumber-based project -* Let Cucumber execute the feature file -* Repeat the two above steps in a sequence that meet the dependencies specified in the feature files. +* Lets Cucumber execute the feature file +* Repeats the two above steps in a sequence that meet the dependencies specified in the feature files. ### How can I define dependencies? ### To define dependencies between feature files, use Gherkin specific tags. Suppose that feature `foo` depends on feature `bar`. Then the feature file `foo` may begin as follows: -```cucumber -# The next line names this feature 'foo' and make dependent on 'bar' -@feature:foo @depends_on:bar -Feature: Check-in - As a video rental employee - I want to register return of rented videos - So that other members can them too +```cucumber + # The next line names this feature 'foo' and make dependent on 'bar' + @feature:foo @depends_on:bar + Feature: Check-in + As a video rental employee + I want to register return of rented videos + So that other members can them too ``` While feature `bar` may start like this: -```cucumber -# The next line names this feature 'bar' -@feature:bar -Feature: Renting videos - As a video rental employee - I want to register rentals made by a member - So I can run my business +```cucumber + # The next line names this feature 'bar' + @feature:bar + Feature: Renting videos + As a video rental employee + I want to register rentals made by a member + So I can run my business ``` +#### Recap: #### +- To identify/name a feature use a tag of the form: `@feature:foo` +- To express a dependency on a feature with identifier `foo`, use the tag syntax: `@depends_on:foo` Copyright --------- -Copyright (c) 2013, Dimitri Geshef. Cukedep is released under the MIT License see [LICENSE.txt](https://github.com/famished-tiger/Cukedep/blob/master/LICENSE.txt) for details. +Copyright (c) 2013, Dimitri Geshef. +__Cukedep__ is released under the MIT License see [LICENSE.txt](https://github.com/famished-tiger/Cukedep/blob/master/LICENSE.txt) for details. \ No newline at end of file