Originally posted on testingwithvision, moving content here for completeness.
Cucumber allows you to organize your features in a directory structure, as well as label features with tags (keywords). A common question I am asked on projects is what would you use tags for as opposed to a using directory organization.
Use directories for Cucumber feature functional organization
I suggest creating a feature directory structure to organize Cucumber features by functionality, as opposed to using the suggested convention of applying tags for organization. The reason I use directories over tags for functional organization is that I find it’s more efficient to organize features into folders than tagging them, as you don’t have to tag every feature to them to organize them functionally. You also have the benefit of running a subset of scenarios organized into a lower level directory. For example:
Given a folder structure of:
you could run all online ordering features using:
or all modify order features etc.
This allows you maximum flexibility without having to tag each feature as to how it fits functionally with the other features. It also means you don’t end up with a large features directory full of a large number of .feature files that are hard to sort.
The Cucumber feature directory structure you create allows you to see how functionality of your application relates to other functionality through the hierarchial nature of directory organization.
Use tags for non-functional feature classification
I suggest using tags for Cucumber feature and scenario non-functional classification; storing attributes or meta-data about a feature or scenario with it.
Some useful ways you can use Cucumber tags to classify features and scenarios:
- Tagging the status of the feature/scenario: for example, @wip is commonly used to indicate the work in progress status. These can be run in a continuous integration system so the build fails if any @wip scenarios pass (they are after all, work in progress and shouldn’t pass);
- Tagging the size of the feature/scenario. I have recently seen some great examples on the web on how to classify scenarios/tests. Simon Stewart from Google suggests t-shirt styled sizes (Small, Medium, Large), Dave Astels from Engine Yard suggests speed of execution (Fast, Slow, Glacial or Hare, Tortoise, Sloth) which is sort of the same thing;
- Tagging how often a feature or scenario should be run (every build, hourly, daily etc);
- Tagging whether the scenario is destructive or invasive (or indeed non-destructive or non-invasive: good for running in production!); and
- Tagging the feature or scenario with some form of meta-data for requirements traceability, or symbolic link to some other document or system.
Once you have started using certain tags, it is easy to run only scenarios that meet certain characteristics. For example, you could run non-invasive scenarios in production that are fast to run:
cucumber --tags @non-invasive --tags @fast
Or you can combine both functionally organized directories and non-functional tags. For example, you could run all ‘online ordering’ scenarios that are ‘non-invasive’ in production, but only those that are ‘small’ or ‘medium’, so they’re fast to run.
cucumber features/online_ordering --tags @non-invasive --tags @small,@medium
By combining the power of storing your features functionally in directories, and classifying them with non-functional tags, it gives you the power to run scenarios both by functionality, and classification, or both.
Update – 17 Jan 2011
If you’re running directories below the features directory, you should require the features directory so it knows where to look for step definitions. For example:
cucumber -r features features/online_ordering