Gherkin Lint

Common errors

• glob.sync missing absolute: true causes MODULE_NOT_FOUND on Windows with glob v11+

  cause 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

  cause 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)

  cause 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.

Warnings

• breaking 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.
  Fix: Review the project's GitHub release notes for specific breaking changes. Update your `.gherkin-lintrc` configuration and any programmatic usages accordingly.
• gotcha 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.
  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`.
• gotcha 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).
  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.
• deprecated 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.
  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.

Install

• npm install gherkin-lint npm
• yarn add gherkin-lint yarn
• pnpm add gherkin-lint pnpm

Imports

• Linter
  wrong:

  const Linter = require('gherkin-lint').Linter;

  correct:

  import { Linter } from 'gherkin-lint';

  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.

Quickstart

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);