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 files._  
[Homepage](https://github.com/famished-tiger/cukedep)

### 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 in your feature files
* Generates dependency reports (in CSV format)
* Generates dependency diagram (in GraphViz's DOT format),
* Generates a Rake file.


### Installation ###
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.


### 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
and type the command-line:
```bash  
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:  
```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.  
* 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:
```bash  
cukedep --project ../../../sample
```

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
* 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  
```

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
```

#### 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-2018, Dimitri Geshef. 
__Cukedep__ is released under the MIT License see [LICENSE.txt](https://github.com/famished-tiger/Cukedep/blob/master/LICENSE.txt) for details.