cucumber feature organisation

A few months ago I asked around to find out how (or whether) people organised the Cucumber feature files in their project’s features folder. Nothing in particular turned up. But yesterday the good folks at Thoughtbot posted their own very interesting convention: They have a sub-folder of features/ for each Actor served by the application. For example:


I like this a lot, and I’ll be re-organising Reek’s features soon along the same lines. In fact, thinking about this has made me realise that there’s a whole class of user (API clients) not represented by Reek‘s current set of Cucumber features.

And here’s an interesting thought experiment I’ll also be trying out: How about adding another folder level for the Actor’s goal? So the folders would be organised according to the commonalities among the feature descriptions: features/<as_a>/<in_order_to>/feature. For example:


Will that be useful, or just create more clutter? In general I dislike hierarchical classification, so I was keen to keep the sub-folder names as verbs. I’ll try it for Reek and report my feelings back here. Please let us know if you try it first…

4 thoughts on “cucumber feature organisation

  1. Hi Kevin,

    It’s an interesting idea, but I think the abstraction would quickly break down. There isn’t a 1-1 mapping between a feature and a role or outcome. (Which is the same reason why it’s often hard to write good narratives).

    I think organising by tags could be more useful.

    • Agreed, not 1-1; but every feature does expressly nominate an Actor and a Goal, so there’s an implied 1-many relationship from Actors to features.

      I did consider using tags as folders, but I think Cucumber’s –tags options renders this pointless.

      Maybe there is no single “best” answer…

  2. I would counsel against trying too hard to organise features into folders.

    We started out with folders-per-user, and also considered sub-folders per outcome / goal but recently we flattened them out (using a strict naming convention for the file that prefixes each with the user type) into a single folder.

    We’ve found it much easier to see at a glance what’s going on, as feature files can’t hide away in little corners. Cucumber’s tags feature means you can have several different axes of organisation for your features without having to move files into folders.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s