{"id":15621,"library":"gherkin-lint","title":"Gherkin Lint","description":"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.","status":"active","version":"4.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/vsiakka/gherkin-lint","tags":["javascript","gherkin","linter"],"install":[{"cmd":"npm install gherkin-lint","lang":"bash","label":"npm"},{"cmd":"yarn add gherkin-lint","lang":"bash","label":"yarn"},{"cmd":"pnpm add gherkin-lint","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for parsing Gherkin feature files into an Abstract Syntax Tree (AST) for linting.","package":"gherkin","optional":false}],"imports":[{"note":"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.","wrong":"const Linter = require('gherkin-lint').Linter;","symbol":"Linter","correct":"import { Linter } from 'gherkin-lint';"},{"note":"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.","symbol":"runCLI","correct":"import { runCLI } from 'gherkin-lint/dist/bin/gherkin-lint';"},{"note":"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.","symbol":"GherkinParser","correct":"import { GherkinParser } from 'gherkin-lint/dist/src/gherkin-parser';"}],"quickstart":{"code":"import { Linter } from 'gherkin-lint';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nasync function lintFeatureFile(filePath: string) {\n  const linter = new Linter();\n  const featureContent = fs.readFileSync(filePath, 'utf8');\n\n  // A .gherkin-lintrc file should be present in the project root\n  // or specified via linter options for rules to be applied.\n  // Example .gherkin-lintrc (JSON format with comments):\n  // {\n  //   \"no-unnamed-scenarios\": \"on\",\n  //   \"indentation\": [\"on\", {\"Feature\": 0, \"Background\": 2, \"Scenario\": 2, \"Step\": 4, \"Examples\": 2, \"example\": 4}],\n  //   \"no-duplicate-tags\": \"on\"\n  // }\n\n  const result = await linter.lint({\n    featureFile: featureContent,\n    fileName: path.basename(filePath)\n  });\n\n  if (result.length > 0) {\n    console.error(`Linting issues in ${filePath}:`);\n    result.forEach(issue => {\n      console.error(`  [${issue.rule}] Line ${issue.line}: ${issue.message}`);\n    });\n    process.exit(1);\n  } else {\n    console.log(`No linting issues found in ${filePath}.`);\n  }\n}\n\n// To run this, create a dummy.feature file and a .gherkin-lintrc in the same directory\n// Example dummy.feature:\n// Feature: My Feature\n//   Scenario: My Scenario\n//     Given a step\n//     When another step\n//     Then a final step\n\nconst featurePath = path.resolve(__dirname, 'dummy.feature');\nif (!fs.existsSync(featurePath)) {\n  fs.writeFileSync(featurePath, 'Feature: Example\\n  Scenario: Test\\n    Given a passing step');\n  console.log('Created dummy.feature. Please create a .gherkin-lintrc file in the same directory.');\n}\n\nlintFeatureFile(featurePath).catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"fix":"Review the project's GitHub release notes for specific breaking changes. Update your `.gherkin-lintrc` configuration and any programmatic usages accordingly.","message":"Major 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":"<10.0.0"},{"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.","message":"Incorrectly 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).","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"Users 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.","severity":"deprecated","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"An incompatibility between `gherkin-lint`'s internal file path resolution and `glob` library versions on Windows systems.","error":"glob.sync missing absolute: true causes MODULE_NOT_FOUND on Windows with glob v11+"},{"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.","cause":"Historically, there was a bug in `gherkin-lint` that caused issues when validating the configuration of custom-defined rules.","error":"Configuration verification would fail for custom rules"},{"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.","cause":"Prior to specific bug fixes, the linter had shortcomings in correctly identifying and processing variables enclosed in `<...>` within Gherkin syntax.","error":"Variables were not correctly detected in scenario names or step arguments (DocString or DataTable)"}],"ecosystem":"npm"}