DEV Community

Hamza Hamidi
Hamza Hamidi

Posted on Edited on Originally published at hamidihamza.com

Add Gherkin linting to a Node.js project

#gherkin #node #testing #cucumber

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/
Enter fullscreen mode Exit fullscreen mode

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. The Getting started guide includes a complete GitHub Actions workflow:

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/
Enter fullscreen mode Exit fullscreen mode

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 gherkin-lint setup

If the repository already uses gherkin-lint, replace the dependency:

npm uninstall gherkin-lint
npm install --save-dev gherkin-refine
Enter fullscreen mode Exit fullscreen mode

Gherkin Refine installs a gherkin-lint command and reads the existing .gherkin-lintrc and .gherkin-lintignore, so scripts and CI keep working. It supports every gherkin-lint 4.2.4 rule. A few findings differ where gherkin-lint bugs were fixed, and the migration guide lists them.

To move to a native configuration instead, preview the conversion before writing it:

npx gherkin-refine migrate .gherkin-lintrc --dry-run
Enter fullscreen mode Exit fullscreen mode

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. Add --strict to fail instead of writing a configuration that drops a rule.

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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

The clip 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. Formatting rules such as indentation and use-and also have safe fixes.

Gherkin Refine previews whitespace findings, applies safe fixes, and checks the feature file again

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

Top comments (0)