BDD Guardian 🛡️

Guard and navigate your BDD steps across Reqnroll, SpecFlow, and Cucumber!

🖥️ Compatibility

A VS Code extension that provides intelligent navigation, visual feedback, and diagnostics for BDD projects using Reqnroll, SpecFlow, Cucumber, and more.

✨ What's improved (0.5.0)

• Reqnroll & SpecFlow — same binding engine — Shared C# parser; SpecFlow-only projects index and navigate like Reqnroll. Reqnroll is the current open-source line; SpecFlow projects keep the same UX.
• Ambiguity aligned with runtime — When multiple bindings match, Guardian shows ⚠️ ambiguous (Reqnroll-like), not a silent “best score” bound. Optional bddGuardian.matching.preferSpecificBinding restores legacy behavior.
• Scenario Outline precision — Examples on plain Scenario; expanded candidates from table rows; matching-corpus regression suite.
• Guardian ↔ Pilot workflow — Navigate and validate bindings here; run tests with BDD Pilot. If Pilot reports PENDING_STEPS or AMBIGUOUS_STEPS, refine bindings and re-check in Guardian.
• 164 tests — Includes precision corpus and SpecFlow provider coverage.

✨ What's improved (0.4.x)

• C# verbatim patterns with quotes — Bindings like [When(@"they click on ""(.*)"" in the menu")] now correctly match steps such as When they click on "Projects" in the menu.
• Pattern whitespace — Binding patterns are normalized like step text (fewer false “unbound”). See docs/BINDING_MATCHING.md.
• Index while you edit — Open .feature files reindex from the editor buffer (debounced); binding files replace per-file entries on save (no duplicate index entries).
• Single architecture — One indexing and resolution path (IndexManager + binding providers + core resolver); one regex compiler in core.
• Unified Gherkin parsing — Coach and navigation/diagnostics share the same core parser for .feature files.
• UI language — Optional English/Spanish via bddGuardian.displayLanguage.
• 197 tests — Matching, parsing, index, references, Coach, and multi-provider coverage.

📊 CodeLens

See binding status directly above each step:

• ✅ Bound: Shows ClassName.MethodName - click to navigate
• ⚠️ Unbound: Warning when no binding is found
• ⚡ Ambiguous: Multiple bindings match - click to select

🎯 Visual Feedback

BDD Guardian provides subtle, non-intrusive visual feedback:

Gutter Icons

Small icons in the editor gutter show step status at a glance:

• ✓ Green checkmark — bound step
• ✗ Red X — unbound step
• ! Orange warning — ambiguous step

Left Border

A subtle colored border on step lines reinforces status.

Overview Ruler

Status markers appear in the minimap/overview ruler for quick file scanning.

💡 Tip: All visual feedback can be disabled via settings.

💬 Enriched Hover

Hover over any step for detailed information:

For Bound steps:

• Binding class and method
• Regex pattern
• File location (clickable)
• Captured parameters
• Code preview (expandable)

For Unbound steps:

• Suggested binding pattern

For Ambiguous steps:

• Top 3 matching bindings
• Best match highlighted
• Link to show all matches

🔎 Find All References (Shift+F12)

Same resolver and index as CodeLens and Go to Definition — not generated Reqnroll code under obj/.

🧭 Navigation History

Navigate back and forward between steps and bindings:

📍 From bindings to steps (usages)

In step definition files (.cs, .ts, .py, etc.), CodeLens above each binding shows how many steps use it:

• → 1 usage (Scenario name) — click to open the step in the feature file
• → N usages (M scenarios) — click to pick a usage from a list and jump to it
  Works with any indexed framework (Reqnroll, SpecFlow, and future Cucumber.js, Behave, etc.).

🏥 BDD Coach (optional)

Best-practice hints for .feature files (duplicate steps, GWT structure, vague Then, step length, UI leakage, etc.).

Commands: BDD Guardian: Toggle Coach Mode, Show Coach Rules, Show Health Score.

🔍 Diagnostics

Warnings in the Problems panel for:

• Unbound steps (no matching binding)
• Ambiguous steps (multiple bindings match)

Updates while typing in .feature files (debounced), aligned with the workspace index.

📋 Scenario Outline Support

Full support for Scenario Outlines with Examples tables:

• Automatically expands <placeholders> with Example values
• Accurate binding resolution for parameterized steps

🔌 Multi-Framework Support

Automatic detection of BDD frameworks:

• ✅ C# Reqnroll — Full navigation (current open-source stack)
• ✅ C# SpecFlow — Same attribute-based bindings as Reqnroll; shared parser, separate NuGet detection
• ✅ JavaScript Cucumber.js (v0.6.1+)
• ✅ Go Godog (v0.7.0+)
• 🔜 Python Behave / Java Cucumber (planned)
• 🔜 Python Behave (planned)

C# step bindings (Reqnroll & SpecFlow)

Reqnroll and SpecFlow share the same binding model ([Binding], [Given(@"...")], etc.). BDD Guardian indexes both with one C# parser — Reqnroll is the active open-source line; legacy SpecFlow projects get the same CodeLens, Go to Definition, and diagnostics.

Recommended flow: Guardian (navigate & validate) → BDD Pilot (run dotnet test) → if PENDING_STEPS or AMBIGUOUS_STEPS, fix bindings and re-open in Guardian. Sample pair: samples/binding-demo/ + Pilot samples/minimal-bdd.

📦 Installation

From VSIX (Current)

1. Download the .vsix file
2. In VS Code: Cmd+Shift+P → "Install from VSIX"
3. Select the downloaded file

From Marketplace

Search for "BDD Guardian" in VS Code Extensions, or install from:
Marketplace

⚙️ Configuration

Language

Visual Feedback

Matching

Core Features

Indexing

🐛 Known Issues

• Large projects may experience initial indexing delay (status bar shows “Indexing…” while running)
• Advanced regex in bindings (lookaheads, complex nested groups) may not match as in the test runner; standard alternation (a|b) is covered by tests (details)

Sample workspace

samples/binding-demo/ is a minimal Reqnroll workspace for manual verification: install VSIX → open that folder → CodeLens + Go to Definition on Features/sample.feature. For test execution, use BDD Pilot samples/minimal-bdd.

Maintainers: npm run verify:local runs lint, tests, and packages bdd-guardian.vsix (Capa A); see CONTRIBUTING.md.

Roadmap

See ROADMAP.md. Current release is v0.5.0. Works alongside BDD Pilot (test execution).

📚 Documentation

📝 Changelog

See CHANGELOG.md for version history.

🤝 Contributing

Contributions are welcome! Please open an issue first to discuss proposed changes.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Inspired by the Reqnroll, SpecFlow, and Cucumber communities
• Built with ❤️ for BDD practitioners

🏢 Enterprise Features

BDD Guardian is designed for enterprise-scale projects:

Performance Guardrails

• Max Files Limit: Configurable limit (default: 5,000) prevents memory issues in large monorepos
• Batch Processing: Files are indexed in batches to keep VS Code responsive
• Async Operations: All indexing is non-blocking

Resilience

• Safe Fallbacks: Extension never crashes - all operations are wrapped in try/catch
• Graceful Degradation: If provider detection fails, falls back to manual configuration
• Detailed Logging: Output channel shows all operations for troubleshooting

Configuration for Large Projects

{
  "reqnrollNavigator.maxFilesIndexed": 10000,
  "reqnrollNavigator.excludePatterns": [
    "**/bin/**",
    "**/obj/**",
    "**/node_modules/**",
    "**/TestResults/**"
  ]
}