Smart Cucumber-Behave

A complete, high-performance Visual Studio Code extension integrating the official Cucumber Language Server with the advanced Smart Behave Runner test execution engine and fine-grained Custom Gherkin Formatter.

🌟 What is Smart Cucumber-Behave?

Smart Cucumber-Behave combines two complete BDD toolsets into a single extension:

1. Official Cucumber Language Server (@cucumber/language-server):

   • Backed by tree-sitter WebAssembly (WASM) grammars.
   • Cross-language step definition indexing (cucumber.glue) supporting Python, TypeScript/JavaScript, Java, C#, Ruby, PHP, Rust, and Go.
   • Full support for Cucumber Expressions and Regular Expressions.
   • Support for Custom Parameter Types (cucumber.parameterTypes).
   • Autocomplete for Given/When/Then steps across all glue languages.
   • Go to Step Definition (F12) across all glue languages.
   • Diagnostics for undefined steps and Gherkin syntax errors.
   • Quick Fix action to generate step definition snippets.
   • Document structure and semantic tokens.

2. Smart Behave Test Runner & Execution Platform:

   • Native VS Code Test Explorer (TestController): Instant zero-latency discovery of Features, Scenarios, and Examples with pass/fail hierarchy propagation (when a scenario fails, the scenario and whole feature are marked failed; when all pass, both pass).
   • Cucumber-Behave Live Run Panel: Dedicated bottom panel tab (Cucumber-Behave → Live Run) with streaming logs, status indicators, elapsed timers, a Cancel Run button (with warning/confirmation modal to terminate lingering processes), and a Rerun Last Run button.
   • Multi-Language Interactive Configuration Screen: Multi-runtime diagnostic prober (Python, Node.js, Java, .NET, Ruby, PHP, Rust, Go), live Gherkin formatter preview, Cucumber settings, and Behave test runner settings.
   • In-Editor CodeLens: ▶ Run and 🐞 Debug buttons directly above Features, Scenarios, and Example rows.
   • Full Debugging (debugpy): Breakpoint debugging inside step functions, hooks, and environment fixtures with justMyCode stepping.

3. Custom Gherkin Keyword Formatter:

   • Fully customizable, keyword-specific indentation levels for Feature, Scenario, Background, Given, When, Then, And, But.
   • Default Stepped Ladder preset: Feature has 0 tabs, Scenario has 1 tab, Given has 2 tabs, When has 2 tabs, Then has 3 tabs, And has 4 tabs, But has 4 tabs.
   • Formats via standard VS Code document formatting (Shift+Alt+F), format-on-save, and on-type table pipe formatting (|).

🚀 Key Features

📐 Custom Gherkin Formatter

Customize exact indentation levels (tabs or spaces) per Gherkin keyword:

Feature: User Authentication & Dashboard
	Background: Database initialization
		Given database connection is open

	Scenario: Successful login with multi-factor authentication
		Given user is on login page
		When user enters valid credentials
			Then user receives one-time passcode
				And security dashboard is displayed
				But lockout warning is not triggered

• Interactive Presets: Switch instantly in the Configuration Screen between Stepped Ladder (0, 1, 2, 2, 3, 4, 4), Standard BDD (0, 1, 2, 2, 2, 2, 2), or Strict Cascade.
• Indentation Character: Choose "tab" (force \t), "spaces", or "auto" (respecting editor tab settings).
• Relative And/But: Option to dynamically indent And/But +1 tab after the preceding step.

🌐 Multi-Language Interactive Configuration Screen

Open anytime via Smart Behave: Open Configuration Screen (smartBehave.openConfiguration):

• Multi-Language Runtime Probe: One-click probe detecting active versions for Python, JavaScript/TypeScript (Node.js), Java (JDK), C# (.NET), Ruby, PHP, Rust, and Go.
• Interactive Formatter Controls: Slider/number inputs with an instant live Gherkin preview box updating in real-time as you tweak tab values.
• Cucumber Global Settings: Direct editing of cucumber.features, cucumber.glue, and cucumber.parameterTypes.
• Python Behave Runner Settings: Probes Behave CLI version, manages CLI arguments, config directory, and capability files (caps_file).
• Dual Target Saving: Save configuration changes directly to your Workspace Settings (.vscode/settings.json) or User Settings (global).

🥒 Official Cucumber Language Server Integration

• Multilingual Step Definitions: Index step implementations in Python (*.py), JavaScript/TypeScript (*.js, *.ts, *.jsx, *.tsx), Java (*.java), C# (*.cs), Ruby (*.rb), PHP (*.php), Rust (*.rs), and Go (*_test.go).
• Cucumber Expressions: Native matching for {int}, {float}, {word}, {string}, {anonymous}, and custom parameter types.
• Cross-language Autocomplete & Navigation: Jump between .feature files and glue source code with Go to Definition (F12).

🧪 Native VS Code Test Explorer (vscode.TestController)

• Instant Discovery: Fast pure-TypeScript AST parsing discovers features, scenarios, scenario outlines, and example tables instantly.
• Pass/Fail Propagation:
  • If any scenario fails, both the scenario and the parent Feature are marked as failed.
  • If all scenarios pass, both the scenarios and the parent Feature are marked as passed.
• Side-by-Side Diffs: Failed assertions matching smartBehave.diffRegex display expected vs. actual side-by-side in VS Code's native diff viewer.

⚡ Cucumber-Behave Live Run Panel

Located in the bottom panel under the Cucumber-Behave tab:

• Real-time streaming logs from test execution.
• Stop Button: Cancel executing test suites with a warning/confirmation prompt that terminates child test processes cleanly.
• Rerun Button: Quickly rerun the exact same test selection with a single click.

🐍 Deep Python Behave Support & Ecosystem

Fully aligned with the official Behave Documentation:

• Universal Step Matchers:
  • parse (Default Matcher): Supports typed placeholders like {param:d} (integer), {param:f} (float), {param:w} (word), {param:s} (string), named variables {param}, and anonymous {} / "{}".
  • cfparse (Cardinality Field Parse): Full support for cardinality suffixes like {param:Type?} (optional), {param:Type*} (0..), and {param:Type+} (1..).
  • re (Regular Expressions): Named capture groups (?P<name>...), standard regex expressions, and re.compile(...).
  • Quoted Placeholders & Punctuation: Full support for quoted parameters '{param}', "{param}", anonymous "{}", and trailing periods/punctuation (e.g. @given("I sleep for '{seconds}' seconds.")). Flexibly matches single-quoted, double-quoted, or unquoted steps in .feature files without undefined-step warnings.
  • Stacked Decorators: Supports multiple @given, @when, @then, and @step decorators stacked over the same step definition function.
  • Supports @behave.given, @behave.when, @behave.then, @behave.step as well as standard @given, @when, @then, @step.
  • Robust handling of raw strings (r"...", ur"...", ru"...") and multiline triple quotes (""" / ''').
• Behave Configuration Files:
  • Auto-discovers and parses project configuration files: behave.ini, .behaverc, setup.cfg, tox.ini.
  • Reads default_tags, formatters, and [behave.userdata] parameters (-D key=value).
• Environment & Lifecycle (features/environment.py):
  • Built-in command and UI button to open or generate features/environment.py with standard hooks (before_all, after_all, before_feature, after_feature, before_scenario, after_scenario, before_step, after_step, before_tag, after_tag).
  • Scoped @fixture definitions with yield and use_fixture(fixture_func, context).
• Rich Python Snippets:
  • Native Python snippets for steps (@given, @when, @then, @step), table processing (context.table), docstring payloads (context.text), fixtures, and userdata.
• Tag Filtering & Specialized CLI Workflows:
  • Run with tag expressions (--tags): e.g. @smoke and not @slow.
  • Dry run mode (--dry-run): validate step definitions without executing test logic.
  • Work-in-progress mode (--wip): run scenarios tagged @wip and stop on first failure.

🛠️ Configuration Settings

Custom Gherkin Formatter Settings

Cucumber Settings

Behave Runner Settings

⌨️ Commands

🙏 Acknowledgements & Open-Source Credits

Smart Cucumber-Behave stands on the shoulders of these outstanding open-source projects, communities, and authors:

• Cucumber for Visual Studio Code (cucumber/vscode):

  • Official Cucumber extension developed by SmartBear and the Cucumber Open Source Community.
  • Source for the official @cucumber/language-server, @cucumber/language-service, @cucumber/cucumber-expressions, and tree-sitter WebAssembly (WASM) grammars powering multilingual step indexing, diagnostics, autocompletion, and semantic tokens.
  • Licensed under the MIT License.

• Behave (behave/behave):

  • Behavior-driven development test framework for Python by Jens Engel, Benno Rice, and contributors.
  • Architectural specifications and documentation for Behave step matchers (parse, cfparse, re), configuration discovery (behave.ini, .behaverc, setup.cfg, tox.ini), and lifecycle hooks (features/environment.py).
  • Licensed under the BSD 2-Clause License.

• behave-vsc (simplytest/behave-vsc):

  • Copyright (c) Curve & SimplyTest.
  • Original VS Code Behave integration foundation and command inspiration.
  • Licensed under the MIT License.

• behave-runner (RemoYukoff/behave-runner):

  • Copyright (c) Remo Yukoff.
  • Behave test discovery and execution concepts.
  • Licensed under the MIT License.

• Tree-Sitter (tree-sitter/tree-sitter):

  • Fast, incremental parser generator by Max Brunsfeld and the Tree-Sitter community.
  • Powers syntax parsing and AST queries across Python, JavaScript, TypeScript, Java, C#, Ruby, PHP, Rust, and Go.
  • Licensed under the MIT License.

• parse (r1chardj0n3s/parse):

  • Fast Python string parsing library by Richard Jones, powering Behave's format expression matching.
  • Licensed under the MIT License.

• debugpy (microsoft/debugpy):

  • Microsoft's Python debugger implementation for VS Code, enabling breakpoint debugging in Behave step definitions and hooks.
  • Licensed under the MIT License.

📄 License

This project is licensed under the MIT License.