Gherkin pytest-bdd Navigator

A VS Code extension that provides navigation from Gherkin steps in .feature files to their pytest-bdd step definitions in Python files.

Features

Navigation

• ⚡ Fast Navigation: Instant lookups using an indexed cache of step definitions
• Go to Definition: Ctrl+Click (or Cmd+Click on Mac) on any Gherkin step to jump to its pytest-bdd step definition
• F12 Support: Press F12 on a step to navigate to its definition
• Multiple Matches: Shows all matching definitions when multiple exist

Gherkin Support

• Custom File Icon: Distinctive cucumber icon for .feature files in the explorer
• Syntax Highlighting: Full syntax highlighting for .feature files
• Full Keyword Support: Works with all step keywords: Given, When, Then, And, But, and *
• Parameter Highlighting: Special highlighting for <parameters> in steps
• Comments & Tags: Proper highlighting for # comments and @tags
• Tables & Doc Strings: Highlighting for data tables and doc strings

pytest-bdd Integration

• pytest-bdd Support: Works with @given, @when, @then, and @step decorators
• Parameter Matching: Handles steps with parameters like {param} and <param>
• Parser Support: Works with parsers.parse() and parsers.re() patterns

Performance

• Auto-Indexing: Automatically indexes step definitions on startup for fast lookups
• Smart File Watching: Automatically detects when you add, modify, or delete step definitions
• Live Updates: Cache updates in real-time as you work - no need to reload
• Status Bar Integration: Shows step count in status bar (click for details)

Usage

1. Open a .feature file with Gherkin scenarios
2. Place your cursor on any step (Given, When, Then, And, But, *)
3. Use one of the following methods to navigate to the definition:
   • Cmd+Click (or Ctrl+Click on Windows/Linux) - Click on any step text
   • Press F12 - Standard "Go to Definition"
   • Right-click and select "Go to Definition"
   • Press Cmd+Shift+P and run "Gherkin pytest-bdd: Go to Definition"

Supported pytest-bdd Syntax

The extension recognizes the following pytest-bdd patterns:

from pytest_bdd import given, when, then, parsers, step

# Simple string match
@given('I have a product')
def step_impl():
    pass

# With parameters using {param} syntax
@when('I add {quantity} items to cart')
def step_impl(quantity):
    pass

# Using parsers.parse
@then(parsers.parse('the total should be {amount:d}'))
def step_impl(amount):
    pass

# Using parsers.re
@given(parsers.re(r'I have (?P<count>\d+) products'))
def step_impl(count):
    pass

# Using @step decorator (matches any keyword)
@step(parsers.parse("the client should have '{audience_type}' successfully configured"))
def step_impl(audience_type):
    pass

Parameter Matching

The extension automatically converts between Gherkin's <param> syntax and pytest-bdd's {param} syntax:

Feature file:

Then the client should have '<audience_type>' successfully configured

Step definition (any of these will match):

@step("the client should have '{audience_type}' successfully configured")
@step("the client should have '{audience_type}' successfully configured")
@then(parsers.parse("the client should have '{audience_type}' successfully configured"))

Example

Feature file (features/shopping.feature):

Feature: Shopping Cart
  Scenario: Add items to cart
    Given I have a product
    When I add 5 items to cart
    Then the total should be 50
    And the cart is not empty
    But the discount is not applied
    * the user is logged in

Step definitions (tests/test_shopping.py):

from pytest_bdd import given, when, then, parsers

@given('I have a product')
def setup_product():
    pass

@when(parsers.parse('I add {quantity} items to cart'))
def add_to_cart(quantity):
    pass

@then(parsers.parse('the total should be {amount}'))
def verify_total(amount):
    pass

Installation

From Source

1. Clone this repository
2. Install dependencies:

   npm install
   

3. Compile the extension:

   npm run compile
   

4. Press F5 in VS Code to launch Extension Development Host

From VSIX

1. Package the extension:

   npm install -g @vscode/vsce
   vsce package
   

2. Install the .vsix file in VS Code:
   • Open VS Code
   • Go to Extensions view
   • Click on "..." menu
   • Select "Install from VSIX..."
   • Choose the generated .vsix file

Requirements

• VS Code 1.85.0 or higher
• Python files with pytest-bdd step definitions in your workspace

Extension Settings

This extension provides the following configuration options:

Commands

• Gherkin pytest-bdd: Reindex Step Definitions - Manually reindex all step definitions
• Gherkin pytest-bdd: Show Cache Statistics - Display cache statistics (number of indexed files and definitions)

File Watching

The extension automatically watches for changes to your step definition files:

• ✅ New files: When you create a new *_steps.py file, it's automatically indexed
• ✅ File changes: When you modify a step definition, the cache updates immediately
• ✅ File deletions: Removed files are automatically removed from the cache
• ✅ Status bar: Shows current step count (e.g., ✓ 150 steps) - click to see details

You don't need to reload VS Code when adding or modifying step definitions!

Performance Tips

For large projects with many test files:

1. Customize the include pattern to only scan relevant directories:

   "gherkinPytestBdd.includePattern": "tests/**/*test*.py"
   

2. Exclude unnecessary directories:

   "gherkinPytestBdd.excludePattern": "{**/node_modules/**,**/venv/**,**/build/**}"
   

3. Initial indexing happens on startup - you'll see a notification with the progress

4. Subsequent lookups are instant (< 10ms) thanks to the cache

5. File watching keeps the cache updated automatically

Known Limitations

• Only searches .py files in the current workspace
• Does not support custom step decorator names
• Requires exact or pattern-based matches between feature steps and step definitions

Development

To contribute or modify this extension:

1. Clone the repository
2. Run npm install
3. Open in VS Code
4. Press F5 to launch the Extension Development Host
5. Make changes and reload the Extension Development Host to test

Project Structure

gherkin-plugin/
├── src/
│   ├── extension.ts              # Extension entry point & cache initialization
│   ├── stepDefinitionCache.ts    # High-performance caching system
│   ├── gherkinParser.ts          # Gherkin step parsing
│   ├── pytestBddFinder.ts        # Step definition finder (cache-based)
│   └── definitionProvider.ts     # VS Code definition provider
├── package.json                  # Extension manifest
├── tsconfig.json                # TypeScript configuration
└── README.md                    # This file

How the Optimization Works

1. Indexing Phase (startup): The extension scans all Python test files and builds an in-memory index of step definitions with pre-compiled regex patterns.

2. Lookup Phase (on F12/Ctrl+Click): Instead of searching through files, the extension performs an instant lookup in the indexed cache.

3. Update Phase (file changes): File watchers detect changes and update only the affected files in the cache.

This approach provides 100-1000x faster lookups compared to searching files on every request.

License

MIT

Feedback

Please report issues or suggest features by opening an issue in the repository.