Running a Subset of Scenarios

As the number of features and scenarios grows, we’ll frequently run into situations where we want to run only a single (or maybe a couple) of scenarios to get faster feedback. This can be if we are working on a new scenario or if we have broken an existing one. Let’s take a closer look at how this works.

Filtering with Tag Expressions

The simplest way to use the --tags option is to give it a single tag to run, for example:

This would cause Cucumber to run just the scenarios tagged with @focus. It’s quite common to temporarily tag a scenario or feature with a unique tag like this to filter what to run.

In some situations, we may want a little more control over the tag filtering. Imagine that we have made some changes to a piece of our application that sends out emails. What if we want to run all scenarios tagged with @focus or @email? Here is how:

The comma is interpreted as a logical OR statement. It’s not uncommon to have scenarios that run fast and others that run slowly. If we have tagged the fast scenarios or features with a tag, for example @fast, we can apply a logical AND to say we want to run scenarios that are tagged as @fast and either @focus or @email:

Here we are using --tags twice. Each of them will be logically ANDed together. Ideally, most of our scenarios are fast, and only a few are slow. So, instead of tagging most of our scenarios with @fast, it makes more sense to tag the few that are slow with @slow. If we want to run the scenarios that are not slow (and at the same time @focus or @email), we can use negation (tilde):

Let’s look at another way to run a subset of scenarios—line numbers.

Filtering on Lines

You don’t need to tag your scenarios or features to run just a subset of them. Cucumber also provides a convenient way to specify the line number of the scenario you want to run. Here is an example:

If the feature file has more than one scenario, it will run only the one on line 45. The line number can be anywhere in the feature, ranging from a comment line to the last step (including a step table or doc string).

You have probably noticed that Cucumber prints out the location of a feature file with the line number in error messages.

If you want to rerun the scenario that failed, just select the text and paste it:

This is equivalent to using the --line option. The colon notation also allows you to specify several line numbers, allowing you to specify several scenarios to run:

If you prefer, you can also do this using the --lines argument. Cucumber doesn’t mind whether you say --line or --lines.

Filtering on Names

If tag and line filtering still doesn’t meet your needs, you can filter scenarios based on name. Say, for example, that you want to run all scenarios that have the text logout in their name and that they are scattered around several feature files without a particular tag to identify them. Running them is just a matter of the following:

In a similar fashion, you can also --exclude scenarios with a certain name.