Gherkin PowerTools

Format, lint and navigate Gherkin .feature files in VS Code.

Install from VS Code Marketplace

Why Gherkin PowerTools?

Writing Behavior-Driven Development (BDD) specifications often leads to misaligned tables, inconsistent indentation, and syntax typos caught only during test execution.

This extension runs natively in VS Code to format your files, detect structural errors in real-time, and provide navigation capabilities directly to your code.

Before / After

The formatter uses the Gherkin AST to apply consistent keyword casing, indentation and table alignment.

Before

feature: user authentication

@smoke @regression
scenario: successful login
given i am on the login page
when i enter "admin" as username
and i enter "secret" as password
then i should be redirected to dashboard
  |field  |value |
  |user   |admin |

After

Feature: User Authentication

    @smoke @regression
    Scenario: Successful login
        Given I am on the login page
        When  I enter "admin" as username
        And   I enter "secret" as password
        Then  I should be redirected to dashboard
              | field | value |
              | user  | admin |

Compatibility

Features are divided into two tiers based on your project stack:

Generic .feature files

Core formatting and syntax features operate directly on standard Gherkin .feature files and do not depend on a specific test runner (e.g., Cucumber, SpecFlow, Karate).

• Formatter
• Linter
• Quick Fixes
• Workspace Statistics Dashboard
• Syntax Highlighting

Python / Behave Specific

When working in a Python/Behave project, the extension parses your @given, @when, and @then decorators to enable:

• Go To Definition (Cmd+Click on macOS or Ctrl+Click on Windows and Linux)
• Autocomplete (Step suggestions based on Python definitions)
• Hover (Displays the Python Docstring of the step)

Note: Behave tooling is designed for conventional step decorators and steps/ directory layouts. Dynamically generated decorators or complex multiline patterns may not be detected.

Gherkin PowerTools vs Official Cucumber Extension

Gherkin PowerTools focuses on configurable formatting, structural diagnostics and Python/Behave tooling. The official Cucumber extension provides broader step-definition language support, localisation and Cucumber Language Server integration.

Features

1. Formatter

Auto-indentation, dynamic data table alignment to the preceding step keyword, auto-casing for Gherkin keywords (given -> Given), and configurable tag wrapping.

2. Live Diagnostics Linter

Real-time syntax error detection. Flags missing colons after block keywords, invalid structural nesting (e.g., Examples without Scenario Outline), and unclosed data tables.

3. Quick Fixes (Code Actions)

Apply auto-corrections (Cmd+. / Ctrl+.) over diagnostic warnings:

• Correct misspelled keywords based on Levenshtein distance.
• Append missing colons.
• Convert Scenario to Scenario Outline when an Examples table is added.
• Close malformed data table rows.

4. Behave Navigation (Go To Definition)

Use Cmd+Click on macOS or Ctrl+Click on Windows and Linux on any step to jump to its Python @given, @when, or @then implementation.

5. Autocomplete

Suggests steps as you type based on your Python step definitions. Converts Behave placeholders into VS Code tab-stops.

6. Hover

• Steps: Hover over any step to view the underlying Python function signature and its associated Docstring.
• Tags: Hover over any Gherkin tag (@tag) to view its "Blast Radius" (the exact number of scenarios and outline examples across the entire workspace affected by that tag).

7. Dashboard

An HTML webview displaying heuristic workspace metrics, including a Gherkin quality indicator, scenario complexity signals and tag distribution.

8. Workspace Analytics

Estimates executable permutations and provides a heuristic comparison between automated and manual execution effort.

Configuration

Available via your VS Code settings.json:

Format on Save:

"[feature]": {
  "editor.defaultFormatter": "carloscamara.vscode-gherkin-powertools",
  "editor.formatOnSave": true
}

Documentation

For architecture overviews and feature deep-dives, see the Documentation Website.

Contributing

Bug reports, feature requests, and code contributions are welcome. See CONTRIBUTING.md to get started.

License

Licensed under the MIT License - © Carlos Camara.