Use cucumber feature folders for functional organization, tags for non-functional classification

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:

  • features
    • online_ordering
      • shopping_cart.feature
      • check_out.feature
      • check_order_status.feature
    • order_fulfillment
      • modify_orders
        • cancel_order.feature
        • edit_order.feature
      • ship_order.feature
    • admin
      • update_catalog.feature

you could run all online ordering features using:

cucumber features/online_ordering

or all modify order features etc.

cucumber features/order_fulfillment/modify_orders

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 

Previous Comments

Author: Alister Scott

Alister is an Excellence Wrangler for Automattic.

2 thoughts on “Use cucumber feature folders for functional organization, tags for non-functional classification”

  1. Hi! Good article! But I have one problem. Could you help me?
    When I run “cucumber” in project folder, without parameters, it run all *.feature files in the alphabetical order. It’s ok. But when I try run smth. like “cucumber features/online_ordering” (in your folder structure) I get error that my scenarios are not undefined. Smth. like next:

    Feature: bla-bla-bla

    Scenario: bla-bla-bla
    Given bla-bla-bla
    When bla-bla-bla
    Then bla-bla-bla
    Scenario: bla-bla-bla
    Given bla-bla-bla
    When bla-bla-bla
    Then bla-bla-bla
    Scenario: bla-bla-bla
    Given bla-bla-bla
    When bla-bla-bla
    Then bla-bla-bla

    3 scenarios (3 undefined)
    9 steps (9 undefined)

    You can implement step definitions for undefined steps with these snippets:


    If you want snippets in a different programming language, just make sure a file
    with the appropriate file extension exists where cucumber looks for step definitions.


  2. Are you definitely using the -r parameter still?


    cucumber -r features features/online_ordering

    (you can put the -r features in a cucumber.yml file to avoid having to type it every time)


Comments are closed.