Registry / testing / gherkin-lint

gherkin-lint

JSON →
library4.2.4jsnpmunverified

Gherkin Lint is a JavaScript-based linter and validator for Gherkin feature files, inspired by ESLint. It ensures consistency and adherence to predefined style and structural rules within Behavior-Driven Development (BDD) scenarios. The current stable version is 4.2.4, with recent releases focusing on dependency updates and minor bug fixes. The package helps teams maintain high-quality, readable, and maintainable Gherkin files by catching common pitfalls such as incorrect indentation, duplicate tags, unnamed features or scenarios, and structural inconsistencies. Its primary differentiator is its comprehensive set of configurable rules and its integration capabilities within CI/CD pipelines and development environments, allowing for early detection of issues in Gherkin syntax and style.

npm install gherkin-lint
INSTALL
IMPORT
SIG · GHERKIN-LINT
G
gherkin-lint
testingjavascriptv4.2.4
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Linter
✓ import { Linter } from 'gherkin-lint';
✗ const Linter = require('gherkin-lint').Linter;
The `Linter` class is the primary programmatic interface for Gherkin Lint, allowing direct integration into custom workflows. While CommonJS `require` works, ESM `import` is the recommended modern approach.
runCLI
✓ import { runCLI } from 'gherkin-lint/dist/bin/gherkin-lint';
This import allows programmatically invoking the CLI runner. This is less common than using the `Linter` class directly but can be useful for wrappers or custom scripting environments.
GherkinParser
✓ import { GherkinParser } from 'gherkin-lint/dist/src/gherkin-parser';
For advanced use cases, the internal GherkinParser can be imported to directly interact with the underlying Gherkin parsing logic. This is generally not needed for typical linting tasks.

This quickstart demonstrates programmatic use of the `Linter` class to lint a single Gherkin feature file. It shows how to read file content, instantiate the linter, and process the results. It assumes the presence of a `.gherkin-lintrc` configuration file in the working directory.

import { Linter } from 'gherkin-lint'; import * as fs from 'fs'; import * as path from 'path'; async function lintFeatureFile(filePath: string) { const linter = new Linter(); const featureContent = fs.readFileSync(filePath, 'utf8'); // A .gherkin-lintrc file should be present in the project root // or specified via linter options for rules to be applied. // Example .gherkin-lintrc (JSON format with comments): // { // "no-unnamed-scenarios": "on", // "indentation": ["on", {"Feature": 0, "Background": 2, "Scenario": 2, "Step": 4, "Examples": 2, "example": 4}], // "no-duplicate-tags": "on" // } const result = await linter.lint({ featureFile: featureContent, fileName: path.basename(filePath) }); if (result.length > 0) { console.error(`Linting issues in ${filePath}:`); result.forEach(issue => { console.error(` [${issue.rule}] Line ${issue.line}: ${issue.message}`); }); process.exit(1); } else { console.log(`No linting issues found in ${filePath}.`); } } // To run this, create a dummy.feature file and a .gherkin-lintrc in the same directory // Example dummy.feature: // Feature: My Feature // Scenario: My Scenario // Given a step // When another step // Then a final step const featurePath = path.resolve(__dirname, 'dummy.feature'); if (!fs.existsSync(featurePath)) { fs.writeFileSync(featurePath, 'Feature: Example\n Scenario: Test\n Given a passing step'); console.log('Created dummy.feature. Please create a .gherkin-lintrc file in the same directory.'); } lintFeatureFile(featurePath).catch(console.error);
gherkin-lint --version
Debug
Known issues
breakingMajor version updates (e.g., v2 to v3, v3 to v4) often introduce breaking changes, including changes to rule names, configuration formats, or the programmatic API. Always consult the official GitHub releases and changelog when upgrading major versions.
fix
Review the project's GitHub release notes for specific breaking changes. Update your `.gherkin-lintrc` configuration and any programmatic usages accordingly.
affects: >=3.0.0
gotchaThe `gherkin-lint` package requires Node.js version 10 or higher. Running it with older Node.js versions may lead to unexpected errors or installation failures.
fix
Ensure your Node.js environment is version 10.0.0 or higher. You can manage Node.js versions using tools like `nvm` or `volta`.
affects: <10.0.0
gotchaIncorrectly configured `.gherkin-lintrc` files or misnamed custom rules can lead to the linter not applying expected rules or failing during configuration parsing. Rule configurations are case-sensitive and expect specific formats (e.g., 'on', 'off', or array with options).
fix
Verify your `.gherkin-lintrc` file against the official documentation for correct syntax and rule options. Ensure it's valid JSON (allowing comments) and located in the project root or specified via CLI options.
affects: >=2.0.0
deprecatedUsers may encounter 'Deprecated Packages When Installing gherkin-lint' warnings during `npm install`. This indicates that some of `gherkin-lint`'s internal dependencies might be using deprecated packages, though `gherkin-lint` itself remains active.
fix
While these warnings are generally harmless for `gherkin-lint`'s functionality, they can often be resolved by ensuring your `npm` or `yarn` is up-to-date. If issues persist, report them on the `gherkin-lint` GitHub issue tracker.
affects: >=4.0.0
Errors
Common errors & fixes
glob.sync missing absolute: true causes MODULE_NOT_FOUND on Windows with glob v11+
An incompatibility between `gherkin-lint`'s internal file path resolution and `glob` library versions on Windows systems.
fix
This is an open issue. As a temporary workaround, try using an older version of `glob` if possible, or ensure consistent path separators. Check the `gherkin-lint` GitHub issues for updates and potential patches.
Configuration verification would fail for custom rules
Historically, there was a bug in `gherkin-lint` that caused issues when validating the configuration of custom-defined rules.
fix
This specific bug was fixed in `v2.11.1`. Ensure you are using `gherkin-lint@2.11.1` or newer. If you are on an older version, upgrade. If the error persists with a newer version, double-check your custom rule's configuration format.
Variables were not correctly detected in scenario names or step arguments (DocString or DataTable)
Prior to specific bug fixes, the linter had shortcomings in correctly identifying and processing variables enclosed in `<...>` within Gherkin syntax.
fix
This issue was resolved in `v2.13.2`. Upgrade `gherkin-lint` to version `2.13.2` or later to ensure proper variable detection and avoid false positives or negatives related to variable usage.
Upgrade
Version history
4.2.4latest on npm
Audit
Dependencies
gherkinrequiredUsed for parsing Gherkin feature files into an Abstract Syntax Tree (AST) for linting.
Agent activity
4 hits · last 30 days
node
4
Resources
gherkin-lint — npm install gherkin-lint · libregistry