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.

Vortex installs Gherkin Lint together with Behat. If you deselect Behat in the Development tools prompt, the installer removes Gherkin Lint, gherkinlint.json and the Gherkin Lint CI step.

Usage

To lint the feature files in tests/behat/features, run 1 of the following commands:

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 by default. The file changes only the rules it lists.

The shipped file sets the indentation rule to 2 spaces per level. It also 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 checks only those lines and 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

Ignore violations

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

The second rule name in the example is a placeholder. The shipped file already turns keyword-order off. Replace both names with the rules you need, separated by commas. The annotation also works from any other comment line, and it always covers the whole file.

Per-file rule suppression is the only inline mechanism. Gherkin Lint has no comment that ignores every rule in a file, a block or a single line.

Continuous integration

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

Ignore 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