cucumber-sort

cucumber-sort enforces a consistent order of steps across the .feature files in your Cucumber test suite.

Example

Imagine you write an end-to-end test for your robotic kitchen, of course in Cucumber. One of the tests entails the kitchen baking an apple pie from scratch. Here is the (simplified) feature for that.

Feature: apple pie

  Scenario: make the dough
    Given a mixing bowl
    And cinnamon
    And apples
    And butter
    And flour

This scenario works: it produces an apple pie. But it's not well organized. Recipes would be easier to read and compare if they always listed the basic ingredients first and then the optional ones.

That's exactly what cucumber-sort helps with. It enforces a predictable, project-wide order of steps in your Cucumber files.

Step 1: collect all sortable steps

First, collect all Gherkin steps from your test suite into a file you can sort:

cucumber-sort check --record

This creates file named cucumber-sort.json, which defines the expected step order. Currently, it looks like this:

{
  "$schema": "https://raw.githubusercontent.com/kevgo/cucumber-sort/refs/heads/main/docs/schema.json",
  "include": [],
  "exclude": [],
  "record": false,
  "fail-fast": false,
  "steps": [],
  "unknown-steps": [
    "^a mixing bowl$",
    "^apples$",
    "^butter$",
    "^cinnamon$",
    "^flour$"
  ]
}

Everything inside "unknown-steps" are Gherkin steps that cucumber-sort can see but doesn't yet know how to order.

Step 2: arrange the steps in the desired order

Edit cucumber-sort.json to arrange the steps in the order you want them to appear in the recipes. For example:

{
  "$schema": "https://raw.githubusercontent.com/kevgo/cucumber-sort/refs/heads/main/docs/schema.json",
  "include": [],
  "exclude": [],
  "record": false,
  "fail-fast": false,
  "steps": [
    // TOOLS
    "^a mixing bowl$",

    // BASE DOUGH
    "^flour$",
    "^butter$",

    // FRUITS
    "^apples$",

    // SPICES
    "^cinnamon$"
  ]
}

Step 3: apply the new order

Format your feature files according to this new order:

cucumber-sort format

Now all recipes are consistently ordered. Here is how apple_pie.feature looks after sorting:

Feature: apple pie

  Scenario: make the dough
    Given a mixing bowl
    And flour
    And butter
    And apples
    And cinnamon

The behavior is unchanged, but now your .feature files are consistent, readable, and easier to maintain.

Tip

To see a real-world example of using cucumber-sort in production, check out the Git Town codebase.

Step 4: sort repetitive steps

Sometimes multiple steps interleave several times. As an example, creating laminated dough requires to repeatedly add layers of dough and butter:

Feature: laminated dough

  Scenario: make the dough
    Given a mixing bowl
    Then fold the dough
    And add a layer of butter
    And chill in the fridge
    And fold the dough
    And add a layer of butter
    And chill in the fridge
    And fold the dough
    And add a layer of butter
    And sprinkle with cinnamon

A naive approach would be this step order:

{
  "steps": [
    "a mixing bowl",
    "fold the dough",
    "add a layer of butter",
    "chill in the fridge",
    "sprinkle with cinnamon"
  ]
}

However, sorting steps this way would mess up the recipe:

Feature: laminated dough

  Scenario: make the dough
    Given a mixing bowl
    Then fold the dough
    And fold the dough
    And fold the dough
    And add a layer of butter
    And add a layer of butter
    And add a layer of butter
    And chill in the fridge
    And chill in the fridge
    And sprinkle with cinnamon

To sort this recipe properly, we need to tell cucumber-sort to keep the steps fold the dough, add a layer of butter, and chill in the fridge together (in the order they occur) while sorting:

{
  "steps": [
    "a mixing bowl",
    [
      "fold the dough",
      "add a layer of butter",
      "chill in the fridge"
    ],
    "sprinkle with cinnamon"
  ]
}

Now when cucumber-sort formats the recipe for laminated dough, it does not change the content.

Installation

The easiest way to run cucumber-sort is via run-that-app:

rta cucumber-sort

Other options:

• download the latest release and install manually
• Build from source:

  • Install Rust

  • Clone the repo and cd into it

  • Run:

    cargo install --locked --path .

Configuration file

Generate the default configuration with:

cucumber-sort init

This command creates file cucumber-sort.json. JSON-Schema is available.

Tip

See our own cucumber-sort.json file file for a working example.

Commands

Format all .feature files according to your configured step order:

cucumber-sort format

Check whether your .feature files match the configured order:

cucumber-sort check

If you would like to add unknown steps to cucumber-sort.json, run:

cucumber-sort check --record

This appends unknown steps to the order file. Review the file and move them to the right position.

If there are too many unknown steps, stop at the first file with issues:

cucumber-stort check --fail-fast