BDD Guardian 🛡️

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

🖥️ Compatibility

A VS Code extension that provides intelligent navigation, visual feedback, and diagnostics for BDD projects across five binding stacks.

BDD extension family

Guardian answers “where is this step implemented?” — Pilot answers “run this and what failed?”

ForgeOne: navigation & map (Guardian) → execution (Pilot).

✨ What's new (1.0.0)

• Stable multi-framework release — C# (Reqnroll/SpecFlow), JavaScript Cucumber.js, Go Godog, Python Behave, Java Cucumber-JVM.
• Communication polish — Unified Spanish status labels (Enlazado / Sin enlazar); i18n for navigation and Coach UI.
• Visual language — CodeLens icons aligned with gutter semantics; see docs/VISUAL_LANGUAGE.md.
• First-run hint — One-time toast when .feature files exist but no bindings are indexed (bddGuardian.onboarding.enabled).
• Guardian ↔ Pilot — Navigate bindings here; run tests with BDD Pilot.

🎬 Quick demo

Open samples/binding-demo/ after installing the VSIX: wait for Ready in the status bar → CodeLens above a step → Go to Definition to the binding.

Maintainer: if the GIF is missing locally, record per docs/assets/README.md before Marketplace publish.

✨ Highlights (0.5.x–0.9.x)

• 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: No binding found
• ⚠️ Ambiguous: Multiple bindings match — click to select

🗺️ Suite map

The BDD Map view in Explorer lists workspace holes in the step↔binding map (unbound steps, ambiguous steps, unused/orphan bindings) with the same resolution as CodeLens. Holes are grouped by .feature (orphans by binding file). Click a row to open the file. Unbound rows offer Generate binding (or Copy snippet if generate does not apply). Bound steps are counted in the summary, not listed (less noise).

Command: BDD Guardian: Show suite map. Disable with bddGuardian.suiteMap.enabled: false. Independent of feedbackLevel.

🎯 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. Full matrix: docs/VISUAL_LANGUAGE.md.

Iconography

BDD Guardian uses VS Code codicons for CodeLens and chrome, plus two brand assets that share the same silhouette (shield + linked nodes + map pin — Opción B, ForgeOne navy tile):

ForgeOne family: Guardian = navigation & step bindings · BDD Pilot = execution — same navy Opción B shelf; Guardian glyph = map/link/shield (not Pilot radar).

💬 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, dominant Then, redundant Feature→Scenario tags, step length, UI leakage, etc.).

Quick Fix: remove redundant scenario tags that already exist on Feature.

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 (v0.7.1+)
• ✅ Java Cucumber-JVM (v0.9.0+)

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

Autocomplete

While typing a Gherkin step (Given / When / Then / And / But), IntelliSense suggests steps from the same index used by CodeLens and diagnostics (keyword + prefix filter; patterns are humanized for insert). Autocomplete does not invent steps and does not run tests — use BDD Pilot to execute.

Disable with bddGuardian.autocomplete.enabled: false.

Orphan bindings

Bindings that no indexed feature step resolves to appear in the Problems panel as Information diagnostics on the binding file (dual of unbound steps). CodeLens “No usages” on step definitions remains unchanged.

Disable with bddGuardian.orphanBindings.enabled: false. Workspaces with more than 2000 indexed bindings skip the orphan scan (see Output channel).

Author actions

On unbound steps (Problems panel or lightbulb), BDD Guardian offers:

• Copy binding snippet — framework-aware step definition text (same as hover v1.0.1)
• Copy suggested pattern — regex/Cucumber pattern only
• Generate binding (insert) — inserts scaffold into an indexed step-definition file, or creates a conventional new file:
  • C#: StepDefinitions/GuardianGeneratedSteps.cs
  • JS/TS: features/step_definitions/guardian-generated.steps.ts
  • Behave: features/steps/guardian_generated_steps.py
  • Godog: features/guardian_generated_steps_test.go (or insert into existing InitializeScenario)
  • Java: src/test/java/generated/GuardianGeneratedSteps.java

After generate, reindex the workspace to verify the step is bound. When BDD Pilot is installed, the toast also offers Run with BDD Pilot (opens Pilot’s dashboard — Pilot runs tests; Guardian does not). On unbound steps, the lightbulb includes Open BDD Pilot or Install BDD Pilot if Pilot is missing.

Disable author actions with bddGuardian.authorActions.enabled: false. Disable Pilot CTAs with bddGuardian.pilotHandoff.enabled: false.

Settings reference

Keys under reqnrollNavigator.* are legacy IDs kept for backward compatibility — do not rename in settings JSON. New UX settings use bddGuardian.*.

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 v1.9.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/**"
  ]
}