Skip to content

Add Gherkin linting to a Node.js project

Published

Gherkin feature files can parse correctly and still contain duplicate tags, repeated names or unused Scenario Outline variables. Gherkin Refine checks those issues in a Node.js project, with optional rules for whitespace cleanup. It statically checks .feature files. It does not execute scenarios or validate Cucumber step definitions.

Install and run it locally

The package requires Node.js 22.18 or later. Install it as a development dependency, then point it at your feature files:

npm install --save-dev gherkin-refine
npx gherkin-refine features/

The recommended rules run without a configuration file. They check duplicate tags, duplicate Feature and Scenario names, and unused or undeclared Scenario Outline variables. Style rules stay off until you choose to enable them.

Run it on pull requests

Add a workflow that installs the locked dependencies and lints the same feature directory used locally. This example follows the workflow in the project README:

name: Gherkin

on:
  push:
  pull_request:

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22.18.0
          cache: npm
      - run: npm ci
      - run: npx gherkin-refine features/

A lint error returns exit status 1, so the job fails. If merges should wait for the result, mark the job as a required check in branch protection.

Bring over an existing config

If the repository has a .gherkin-lintrc, preview its conversion before writing a new config:

npx gherkin-refine migrate .gherkin-lintrc --dry-run

The migration command prints the generated configuration and reports rules it cannot map or behavior that changes. Review that output before running the command without --dry-run to write gherkin-refine.config.json.

Preview safe whitespace fixes

Whitespace rules are opt in. Add the ones that match your team’s style to gherkin-refine.config.json:

{
  "extends": ["recommended"],
  "rules": {
    "no-extra-blank-lines": "error",
    "no-trailing-whitespace": "error"
  }
}

Use a dry run to see which safe fixes are available without writing the feature file:

npx gherkin-refine features/checkout.feature --fix-dry-run

The README safe fix example shows the diagnostics. The dry run reports findings and which ones have safe fixes, but does not show an edited diff. Apply fixes in your working tree and inspect the result:

npx gherkin-refine features/checkout.feature --fix
git diff -- features/checkout.feature
npx gherkin-refine features/checkout.feature

The animation shows a dry run reporting trailing whitespace and repeated blank lines, applies those whitespace fixes, displays the cleaned feature file and checks it again. Findings without a safe automatic fix remain for you to review.

Gherkin Refine previews whitespace findings, applies safe fixes, and checks the feature file again
A dry run reports fixable whitespace findings. The fixer applies them, then the linter checks the file again.

For every built-in rule, see the rules reference. The configuration guide, plugin guide and JavaScript API cover the next steps. Install the package from npm.

All notes