Gherkin Language Support for Python Behave

Full-featured VS-Code language server support for Behave BDD projects written in Python. Run, debug, and navigate Gherkin feature files and Python step definitions using the native VS Code Test API — no separate test runner or config needed. Built for day-to-day use at scale: multi-workspace, parallel runs, step libraries, and more.

Features

• Run or debug tests from the gutter, test panel, or sidebar — individual scenario, folder, or all features
• Scenario Outline rows each get their own run/debug button in the gutter
• F12 / Ctrl+Click two-way navigation between feature files and step definitions
• Shift+F12 / hover to find all usages and see reference counts for step definitions
• Autocomplete with cross-type suggestions — type Given and also see matching @when / @then steps
• Syntax highlighting, autoformatting, and snippets for Gherkin feature files
• Step Database panel: searchable browser of all step definitions with reference count badges
• Missing step diagnostics: warning badges in the Explorer and Problems panel for unresolved steps
• Step library support (behave 1.4.0+)
• Stage support (--stage) with a status bar quick-picker
• Multi-workspace support for both test execution and step database
• Parallel feature test execution (runParallel)
• Auto-detects paths from your behave config (behave.ini, .behaverc, setup.cfg, tox.ini, pyproject.toml)

Run & Debug Tests

Click the ▶ or 🐞 gutter icon next to any scenario, or use the Test Explorer sidebar. Results appear inline in the feature file; full output is in the "Gherkin Behave" output window. Smart -i regex minimises behave instances for multi-selection runs.

Step Navigation

F12 / Ctrl+Click on a step in a feature file jumps to the Python step definition. Ctrl+Click on a @given(...) pattern in a Python step file shows all feature file usages. Shift+F12 opens the native "Find All References" panel. Hover over a step pattern to see its reference count.

Autocomplete & Syntax

Typing a step keyword shows matching suggestions from all step files, including cross-type steps (e.g. typing Given also surfaces @when and @then steps, labelled accordingly). Includes Gherkin syntax highlighting, autoformatting (Ctrl+K, Ctrl+F), and smart parameter recognition.

Step Database

The Step Database panel (Activity Bar) shows all parsed step definitions across all workspaces, grouped by file. Use the search field to filter by text. Each step shows a reference count badge — ×0 in orange means the step is unreferenced, useful for auditing dead steps. Click any step to jump to its definition.

Missing Step Diagnostics

Feature files with unresolved step references show a yellow warning badge on the file and its parent folders in the Explorer. Missing steps also appear in the Problems panel (Ctrl+Shift+M).

Getting Started

Workspace requirements

• No conflicting behave/gherkin/cucumber extension is enabled
• Extension activation requires at least one *.feature file somewhere in the workspace
• ms-python.python extension
• behave
• python

Required project directory structure

A single features folder (lowercase by default), which either contains a steps folder or has a sibling steps folder at the same level. Multiple features folders are allowed in a multi-root workspace, but only one per project.

Example 1:

  . my-project
  .    +-- features/
  .    |   |   +-- my.feature
  .    |   |   +-- steps/
  .    |   |   |   +-- steps.py

Example 2:

  . my-project
  .    +-- features/
  .    |   |   +-- my.feature
  .    +-- steps/
  .    |   |   +-- steps.py

Example 3:

  . my-project
  .    +-- behave.ini
  .    +-- features/
  .       +-- environment.py
  .       +-- steps/
  .       |   |   +-- __init__.py
  .       |   |   +-- steps.py
  .       +-- storage_tests/
  .       |   +-- *.feature
  .       +-- web_tests/
  .       |   +-- *.feature
  .       |   +-- steps/
  .       |   |   +-- __init__.py
  .       |   |   +-- steps.py

Configuration

If your features folder is not called features, or is not in your project root, the extension reads paths from your behave config file (behave.ini, .behaverc, setup.cfg, tox.ini, pyproject.toml) automatically. You only need to set gherkin-behave.featuresPath explicitly if you want to override it:

# behave.ini
[behave]
paths=my_tests/behave_features

// .vscode/settings.json — only needed to override auto-detection
{
  "gherkin-behave.featuresPath": "my_tests/behave_features"
}

Extension settings

• This extension has various options to customise your test run via settings.json, e.g. runParallel, featuresPath, and envVarOverrides.
• You can also disable/enable justMyCode for debug (via settings.json not launch.json).
• If you are using a multi-root workspace with multiple projects that contain feature files, you can set up default settings in your *.code-workspace file, then optionally override these as required in the settings.json in each workspace folder.
• For more information on available options, go to the extension settings in vscode.

Stage support

Behave v1.2.5+ supports a --stage flag that loads step definitions from two directories: the common steps/ folder (always) and a stage-specific {stage}_steps/ folder (when the stage is active). Typical use: different backend implementations for smoke, develop, or product stages.

The extension auto-discovers *_steps/ directories in the workspace and shows a status bar quick-picker (click $(beaker) Stage: …) to switch the active stage. Selecting a stage:

• Reloads step definitions from steps/ + {stage}_steps/
• Updates F12, Shift+F12, autocomplete, and semantic highlighting
• Passes --stage {stage} to behave when running or debugging tests

Selecting [default] in the picker clears the stage — only steps/ is used and no --stage flag is passed.

The selected stage is persisted to gherkin-behave.stage in your .vscode/settings.json:

{
  "gherkin-behave.stage": "smoke"
}

The status bar item is only shown for workspaces that have at least one *_steps/ directory.

How it works

How test runs work

• The python path is obtained from the ms-python.python extension (exported settings) i.e. your python.defaultInterpreterPath or selected python interpreter override. This is read before each run, so it is kept in sync with your project.

• For each run, the behave command to run the test manually appears in the Gherkin Behave output window.

• The behave process is spawned, and behave output is written to the Gherkin Behave output window for the associated workspace.

• The extension parses the junit file output and updates the test result in the UI, and any assertion failures and python exceptions are shown in the test run detail accessible in the feature file.

• You can adjust the run behaviour via extension settings in your settings.json file (e.g. runParallel and envVarOverrides).

• Tests runs are smart, so for example if you select to run three feature nodes it will build a behave -i regex to run them in a single behave instance rather than separate instances (unless you are using runParallel). If you choose a nested folder it will run that folder in a behave instance, etc.

How debug works

• It dynamically builds a debug launch config with the behave command and runs that. (This is a programmatic equivalent to creating your own debug launch.json and enables the ms-python.python extension to do the work of debugging.)
• You can control whether debug steps into external code via the extension setting gherkin-behave.justMyCode (i.e. in your settings.json not your launch.json).
• Behave stderr output (only) is shown in the debug console window. (This is to reduce noise when debugging. Run the test instead if you want to see the full behave output.)
• The extension parses the junit file output and updates the test result in the UI, and any assertion failures and python exceptions are shown in the test run detail accessible in the feature file.
• Debug is not affected by runParallel.

Q&A

• How can I see all effective settings for the extension? On starting vscode, look in the Gherkin Behave output window.

• How can I see the active behave configuration being used for behave execution? In your behave config file, set verbose=true.

• How do I clear previous test results? This isn't that obvious in vscode. Click the ellipsis ... at the top of the test side bar and then click "Clear all results".

• Why does the behave command output contain --show-skipped? This flag must be enabled for junit files (which the extension depends on) to be produced for skipped tests. It is enabled by default, so this override is there just in case your behave.ini/.behaverc file specifies show_skipped=False.

• How can I only execute a specific set of tests while using the extension? There are a lot of options here, but there are some examples:

  • (simple but inflexible) use the default_tags= setting in your behave.ini file (or a [behave.userdata] setting for a custom setup)
  • (highly flexible) consider if you can group them into folders, not just by tag, then you can select to run any folder/subfolder from the test tree in the UI instead.
  • (highly flexible) consider if you can use a feature/scenario/folder naming scheme that will allow you to leverage the filtering above the test tree to enable you to run just those tests.
  • (custom) use the envVarOverrides extension setting to set an environment variable that is only set when running from the extension. This adds endless possibilities, but the most obvious approaches are probably: (a) setting the BEHAVE_STAGE environment variable, (b) to control a behave active_tag_value_provider, (c) to control scenario.skip(), or (d) to control a behave before_all for a completely custom setup.

• How do I enable automatic feature file formatting on save? You can do this via a standard vscode setting: "[gherkin]": { "editor.formatOnSave": true }

• How do I disable feature file snippets? You can do this via a standard vscode setting: "[gherkin]": { "editor.suggest.showSnippets": false }

• How do I disable autocomplete for feature file steps? You can do this via a standard vscode setting: "[gherkin]": { "editor.suggest.showFunctions": false }

• Why can't I see print statements in the Gherkin Behave output window even though I have stdout_capture=False in my behave config file? Because the extension depends on the --junit behave argument. As per the behave docs, with this flag set, all stdout and stderr will be redirected and dumped to the junit report, regardless of the capture/no-capture options. If you want to see print statements, copy/paste the outputted command and run it manually (or run python -m behave for all test output).

• Where is the behave junit output stored? In a temp folder that is deleted (recycled) each time the extension is started. The path is displayed on startup in the Gherkin Behave output window. (Note that if your test run uses runParallel, then multiple files are created for the same feature via a separate folder for each scenario. This is a workaround to stop the same junit file being written multiple times for the same feature, which in runParallel mode would stop us from being able to know the result of the test because each parallel behave execution would rewrite the file and mark scenarios not included in that execution as "skipped".)

Troubleshooting

If you have used a previous version of this extension

• Please read through the release notes for breaking changes. If that does not resolve your issue, then please rollback to the previous working version via the vscode uninstall dropdown and raise an issue.

Otherwise

• Does your project meet the workspace requirements and have the required project directory structure?
• If you have set the featuresPath in extension settings, make sure it matches the paths setting in your behave configuration file.
• Did you set extension settings in your user settings instead of your workspace settings?
• Have you tried manually running the behave command that is logged in the Gherkin Behave output window?
• If you are getting different results running all tests vs running a test separately, then it is probably due to lack of test isolation.
• If you are not seeing exceptions while debugging a test, do you have the appropriate breakpoint settings in vscode, e.g. do you have "Raised Exceptions" etc. turned off?
• Do you have the correct extension settings for your project? (See Q&A for information on how to see your effective settings.)
• Does restarting vscode solve your issue?
• Do you have runParallel turned on? Try turning it off.
• Do you have the latest version of the extension installed? The problem may have been fixed in a newer release. (Please note that the latest version you can install is determined by your vscode version, so you may need to update vscode first.)
• Check if the problem is in Known Issues below
• Check if the issue has already been reported in gitlab issues.
• Try temporarily disabling other extensions.
• Have you recently upgraded vscode, and does your python/behave environment match the one tested for this release? You can check the environment tested for each release in gitlab and downgrade as required.
• Any extension errors should pop up in a notification window, but you can also look at debug logs and error stacks by enabling xRay in the extension settings and using vscode command "Developer: Toggle Developer Tools".
• The extension is only tested with a few example projects. It's possible that something specific to your project/setup/environment is not accounted for. See Contributing for instructions on debugging the extension with your own project. (If you debug with your own project, you may also wish to check whether the same issue occurs with one of the example project workspaces.)

Known issues and limitations

• Test durations are taken from behave junit xml files, not an actual execution time.
• vscode always adds up test durations. For runParallel runs this means the parent test node reports a longer time than the test run actually took.
• Behave 1.3.0+ features with currently partial or no support:
  • Scenario Outline examples loaded from an external CSV file (Examples: @file=data.csv) will not appear as separate test nodes until after a test run.

Contributing

If you would like to submit a merge request, please see the contributing doc.