Gherkin Lint

The Gherkin Lint for PHP repository describes the tool as follows:

PHP Gherkin Linter

Gherkin Lint checks Behat feature files for the slips that make a test suite harder to read and maintain. It flags inconsistent indentation, duplicated feature or scenario names, empty scenarios, duplicate tags, and trailing spaces. Vortex comes with Gherkin Lint configuration for Behat tests.

This page is for developers who write Behat feature files. It shows how to lint them, which rules the shipped configuration changes, and how to turn a rule off.

Gherkin Lint ships with Behat. If you deselect Behat in the Development tools prompt, the installer removes Gherkin Lint, its gherkinlint.json configuration file, and its CI step.

Usage

To lint the feature files in tests/behat/features, run the following command:

Ahoy

ahoy lint-tests

Docker Compose

docker compose exec cli vendor/bin/gherkinlint lint tests/behat/features

Confirm that the check passed: Gherkin Lint prints No problems found in, followed by the number of feature files it checked.

Configuration

See the Gherkin Lint configuration reference and the Gherkin Lint rules.

All global configuration lives in the gherkinlint.json file. Gherkin Lint enables every rule the file doesn't mention, and the values in the file override the defaults of the rules it lists.

The shipped file sets the indentation rule to 2 spaces per level and moves literal blocks, the """ doc strings under a step, from the default level 2 to level 3. The rule checks the following lines:

Line	Level	Spaces
Feature:	0	0
Rule:, Background:, Scenario:, and Scenario Outline:	1	2
Scenario steps and Examples:	2	4
Step table rows, the Examples header row, and the opening """ of a doc string	3	6

A doc string therefore starts 6 spaces in, 2 spaces deeper than its step. The rule doesn't check any other line, so it skips the following:

• Tags
• The steps under Background:
• The rows below an Examples header
• The content and the closing """ of a doc string
• Everything inside a Rule: block

The file also turns off the following rules:

• keyword-order - the order of the Given, When, and Then steps in a scenario
• no-homogenous-tags - a tag on every scenario that belongs at the feature level
• scenario-size - the number of steps in a scenario

To list the rules and whether each one is on, run the following command:

ahoy cli vendor/bin/gherkinlint rules

Ignoring

To turn a rule off globally, set enabled to false for it in the gherkinlint.json file:

{
    "rules": {
        "filename": {
            "enabled": false
        }
    }
}

To ignore specific rules in a file, add this comment before the Feature: line. The comment can sit before or after the feature's tags:

# @gherkinlint-disable-rule keyword-order, someother-rule

In the example, the second name is a placeholder, and the shipped file already turns keyword-order off, so replace both with the rules you need. Separate the rule names with commas. Gherkin Lint reads the annotation from every comment in the file and applies it to the whole file.

Gherkin Lint doesn't support ignoring all rules within a file, ignoring code blocks, or ignoring individual lines. Per-file rule suppression is the only inline mechanism.

Continuous integration

Gherkin Lint runs in the lint job of the continuous integration pipeline and fails the build on violations.

Ignoring failures

To let the build pass anyway, set the VORTEX_CI_GHERKIN_LINT_IGNORE_FAILURE CI variable to 1. Gherkin Lint still runs and prints every violation in the job log, so you can see what you're letting through.

➡️ See Continuous integration > Ignore tool failures