Gherkin PowerTools: Workspace Intelligence for Python Behave
Visual execution, AST-powered linting, and real-time impact analysis for enterprise BDD teams.
A premium VS Code testing environment that transforms plain-text Gherkin specifications into an interactive, debuggable, and strictly validated codebase.
Visually run, debug, and track your Python Behave scenarios directly from the VS Code Test Explorer.
⚡ Quick Start
- Install from the VS Code Marketplace.
- Open any
.feature file to rapidly activate formatting and linting.
- (Behave only) Gherkin PowerTools automatically discovers your project and offers a guided Walkthrough.
A premium testing environment that eliminates the friction between plain-text .feature files and your Python backend logic:
- Visual Testing Integration: Run, debug, and trace Python Behave scenarios visually directly from the VS Code sidebar.
- Workspace Intelligence: Context-aware IntelliSense and Cmd+Click navigation with O(1) in-memory indexing.
- Safe Step Refactoring: View the exact blast radius of a step before refactoring, and rename it globally with 1-click.
- Catch Errors Before CI: Dialect-aware real-time AST linting catches malformed syntax as you type.
🌟 Feature Highlights
See all features in the Full Documentation →
1. Missing Python Step Generation
Press Ctrl+. (Cmd+. on macOS) to instantly generate a valid Python stub—complete with extracted regex parameters—from any undefined Gherkin step.
- Workspace-Aware: Intelligently infers the optimal destination based on your
stepGlobs configuration, resolving ambiguity safely via QuickPick.
2. Gherkin Health Dashboard & Anti-pattern Engine
Powered by the new BDD Anti-pattern Detection Engine, you can now visually identify unused, duplicated, ambiguous, or highly complex step definitions and scenarios. Gherkin PowerTools calculates Technical Debt and Maintainability, persisting branch-isolated historical snapshots to securely visualize your project's evolution over time in a premium, interactive dashboard.
- Finding Suppression: Safely suppress deliberate anti-patterns using Quick Fixes, with all suppressions persisted to a centralized ledger (
.gherkin-pt-suppressions.json).
- Batch Fix Workflow: Run the
Fix All Safe Auto-Fixable Problems command to automatically correct semantics-preserving errors across a whole document.
3. Real-Time Impact Analysis
A Blast Radius CodeLens appears above every Python step definition. View exactly how many scenarios will be impacted before refactoring, and jump to them with a single click.
🛠 Capabilities
Gherkin PowerTools acts in two tiers depending on your project:
Generic BDD Frameworks (Cucumber, SpecFlow, Playwright)
- AST-Powered Formatting: Rapidly align tables, tags, and indentation (
Shift+Alt+F or Editor Context Menu).
- Structural Linting: Catch malformed scenarios across 70+ spoken languages in real-time.
- Document Outline: Navigate complex
.feature structures from the VS Code sidebar.
- Gherkin Health Dashboard: Interactive modern webview to analyze oversized features, tag usage, and architectural anti-patterns with built-in DOM node limits for massive workspaces.
Exclusive to Python Behave
- Context-Aware IntelliSense: Autocomplete powered by recent-usage ranking and tag affinity.
- Step Refactoring: Safely extract steps or natively rename them across your entire workspace (F2 or Context Menu).
- Test Explorer Integration: Run and debug features with line-by-line execution tracking and pristine Markdown-formatted error traces, ordered strictly chronologically as written in your code.
- BDD Anti-pattern Detection Engine: Instant technical debt diagnostics for unused, ambiguous, or duplicated step definitions. Features Object-based Configuration to dynamically scale heuristic severities (e.g. adjust max sizes per rule).
- Standalone CLI (
@carlos-camara/gherkin-pt): Enforce formatting, run the Anti-pattern Engine, and calculate project health metrics natively in your CI/CD pipelines.
The CLI uses the exact same parsing, formatting, and BDD Anti-pattern engine as the VS Code extension. View the Capability Contract. (Note: In Remote Development environments like WSL or SSH, run the CLI from the VS Code Integrated Terminal, not your local OS terminal).
⚙️ Essential Configuration
Share team formatting and diagnostic rules by committing a .gherkin-powertoolsrc.json to your project root.
| Setting |
Default |
Description |
gherkinPowerTools.profile |
"custom" |
Formatting baseline: strict, team, minimal, legacy, or custom. |
gherkinPowerTools.rules |
{...} |
Diagnostic rule overrides. Accepts string severities ("error") or configuration objects ({ "severity": "warning", "maxSteps": 20 }). |
gherkinPowerTools.behave.stepGlobs |
["**/steps/**/*.py", ...] |
Paths to Python step definitions. |
gherkinPowerTools.behave.execution |
{"executable": "behave", "arguments": []} |
Secure Test Explorer execution command (e.g., {"executable": "poetry", "arguments": ["run", "behave"]}). |
gherkinPowerTools.behave.localExecutable |
None |
Machine-specific override for the Behave executable absolute path. |
Visit the Configuration Reference for all available settings.
Support & Contributions
Contributions are welcome! Please read the Contributing Guide.
