IntelliJ Plugin

The SpecBinder IntelliJ plugin is the IDE companion to the SpecBinder annotation processor. It provides full Gherkin language support for .feature and .specb files and ties feature files tightly to the JUnit 5 test classes the processor generates from them — so navigation, running, debugging, refactoring, and execution feedback all happen directly inside the spec.

Installation

Install from the JetBrains Marketplace:

1. Open Settings → Plugins → Marketplace.
2. Search for SpecBinder.
3. Click Install and restart the IDE.

Requirements: IntelliJ IDEA 2024.2 or later (Community or Ultimate). The Java and JUnit features below are available automatically when the matching IntelliJ modules are present in your project.

File extensions

By default the plugin handles both .feature and .specb files. The choice of extension is up to you:

• .feature — the standard Gherkin extension. Use it for interoperability with existing feature files and external tooling.
• .specb — a SpecBinder-specific extension. Use it when you want the SpecBinder plugin to coexist with the Cucumber/Gherkin plugin in the same IDE without one stealing .feature files from the other.

You can switch between handling both, only .feature, or only .specb under Settings → Tools → SpecBinder → File extensions.

Auto-recompile on feature-file save

One of the plugin's biggest day-to-day wins: editing a step in a feature file and re-running its test just works, with no manual rebuild step in between. By default, saving a feature file marks its @Gherkin2JUnit marker classes for rebuild on the next build, so the generated tests stay in sync with the spec.

Under Settings → Tools → SpecBinder → On feature file save you can choose:

• Off — do nothing when a feature file is saved.
• Touch marker classes (default) — mark the matching marker classes as needing a rebuild, so the next build regenerates the tests.
• Recompile marker classes — rebuild the matching marker classes immediately, without waiting for the next build. This is the option to pick when you're iterating quickly on a .feature / .specb file: edit a step, save, re-run the test, and the generated code is already up to date — no separate "Build" action required. It turns the spec file into the only thing you need to touch, with the run/debug flow staying one shortcut away.

Editor support

Syntax highlighting

Full Gherkin syntax highlighting with per-keyword granularity, including:

• Feature / Rule / Scenario / Scenario Outline / Scenario Template / Example / Background / Examples keywords
• Feature aliases: Ability, Business Need, Narrative
• Step keywords: Given, When, Then, And, But, *
• Tags, comments, descriptions, doc strings, and data tables
• Inline highlighting for step parameters ("…", '…', numbers, and <placeholder> Outline variables), even when no backing Java step method exists yet

Colours are customizable under Settings → Editor → Color Scheme → Gherkin (SpecBinder) and ship with tuned defaults for both light and Darcula themes.

Code completion

• Keyword completion — Ctrl+Space after the indent of a new line proposes context-appropriate Gherkin keywords (Feature, Rule, Background, Scenario, Scenario Outline, Examples, Given/When/Then/And/But).
• Step completion — inside a step line, suggestions are drawn from the step phrases declared by your Cucumber-style annotations (@Given, @When, @Then, @And, @But) and from matching method names in the project. Matching is fuzzy: typing any word will suggest every step whose text contains that word at any position, and multi-word input requires every word to appear (in any order). The suggestion popup is always shown — even when only a single step matches — so you can review the inserted text (including parameter placeholders) before accepting.

Code folding

Fold markers and the standard collapse/expand gutter affordance are provided for:

• Scenario, Scenario Outline, Scenario Template, Example, Background, and Examples blocks
• Rules (opt-in — enable Make Rules foldable under Settings → Tools → SpecBinder → Code folding)
• Typed doc strings — """html, """json, """xml, and """yaml / """yml blocks each have their own fold marker and collapse into a single line showing only the opening fence with a placeholder (e.g. """html…)

The same settings page also lets you configure which blocks are collapsed automatically when a feature file is opened.

Formatting

Reformat Code (Cmd+Alt+L / Ctrl+Alt+L) applies the standard 2-space Gherkin indentation, aligns data-table columns, and tidies doc-string indentation. Defaults live under Settings → Editor → Code Style → Gherkin (SpecBinder), where you can override tabs, indents, blank-line policy, and commenting style.

Commenting

Cmd+/ / Ctrl+/ toggles # line comments on the selected lines, the same as any other supported language.

Structure view

Press Cmd+7 (macOS) / Alt+7 (Windows/Linux) to open the Structure tool window. It shows the Feature → Rule → Scenario → Step outline of the current file with quick keyboard navigation to any node.

Project view

By default, feature files in the Project tool window expand to reveal their Feature, Rule, Scenario, and Background elements as children, so you can jump straight to a scenario without opening the file first. Toggle this under Settings → Tools → SpecBinder → Project view.

Spell checking

Spell-check inspections are applied to step text, Feature / Rule / Scenario titles, free-text descriptions (the user-story As a / I want / So that block), comments, and doc strings. The IDE's standard spell-checker contributors handle the suggestions and "Save to dictionary" actions. Disable globally under Settings → Tools → SpecBinder → Spell checking if you don't want feature-file spell warnings.

Doc strings with typed fences

Doc strings can be tagged with a language fence so the IDE treats the body as the matching language rather than plain text:

Given the response body:
  """json
  { "id": 42, "status": "ok" }
  """

Supported fences: """html, """json, """xml, """yaml (and the alias """yml).

Inside a typed doc string you get:

• Syntax highlighting for the contained language
• Fold markers on multi-line structures (HTML elements, JSON objects/arrays, etc.)
• Completion proposals from the IDE's language services for that language

The fence identifier (html, json, …) and the surrounding Gherkin keep their normal Gherkin colours, and the doc-string indentation is ignored when parsing the body, so embedded markup is treated as if it were written at column zero.

Inline HTML preview

"""html doc strings render a small preview icon in the editor gutter on the opening-fence line. Clicking the icon shows an inline preview of the rendered HTML below the closing fence; clicking again removes it. Open previews update live as you edit the markup, and the icon switches to a coloured "eye" while the preview is visible so it's easy to see at a glance which doc strings are rendered.

To always render every """html doc string when a feature file is opened, enable Auto-open HTML previews under Settings → Tools → SpecBinder → Doc string previews.

Navigation

The plugin links every feature-file element to its SpecBinder-generated Java counterpart in both directions.

• Gherkin → Java — Cmd/Ctrl+Click on a Feature / Rule / Scenario / Example title jumps to the matching generated class, @Nested Rule class, or @Test method. Cmd/Ctrl+Click on a step jumps to the generated call site inside the scenario method.
• Java → Gherkin — Cmd/Ctrl+Click (or Cmd+B / Go To Declaration) on a generated test class, nested Rule class, or @Test method jumps back to the originating element in the feature file. From a step call site inside a generated scenario method, use Cmd/Ctrl+Shift+Click (or Cmd/Ctrl+Shift+B / Go To Type Declaration) instead to jump to the matching step in the feature file.
• Keyword aliases — navigation also resolves the Gherkin aliases recognized by SpecBinder: Ability, Business Need, and Narrative (Feature), Example (Scenario), and Scenario Template (Scenario Outline).

Run and debug

Gutter run icons

Green run-triangle icons appear in the gutter next to every Feature:, Rule:, and Scenario: keyword. Click the icon (or right-click for Run / Debug) to run that Feature, Rule, or Scenario as a JUnit test. Run configurations are named after the Scenario / Rule / Feature title rather than the underlying Java method name, so the runner view stays readable.

When you use abstract markers with a separate concrete subclass that actually executes the tests, the plugin runs the right subclass automatically — both for the gutter icon and for re-running an individual scenario from the test results tree.

Breakpoints on Gherkin steps

You can place a line breakpoint directly on a step line in a feature file. Running the test in Debug mode pauses execution at that step, with the feature file (not the generated Java source) staying in view. Standard breakpoint actions (suspend policy, condition, log message) are available from the gutter's right-click menu.

Inline execution feedback

When a project uses the SpecBinder execution reporter, the plugin reads its JSON output (under target/specbinder-reports/ for Maven or build/specbinder-reports/ for Gradle) and renders the result directly in the editor. Enable this under Settings → Tools → SpecBinder → JSON-report results.

Pass / fail gutter icons

After a run, the gutter run icon on each Feature, Rule, Scenario, and Scenario Outline row shows the latest outcome:

• A green check for passed
• A red mark for failed (with a tooltip naming the failing step)
• The neutral run icon when no report is available, or when the recorded outcome is stale

Failed steps also get a red error icon anchored on the step keyword, with a tooltip carrying the recorded error type and message. Passed and skipped steps are left undecorated.

Staleness handling

If you've edited a scenario since the last run, its recorded pass/fail result no longer reflects the current spec. The plugin treats those results as stale so a green checkmark cannot mislead you: by default, a stale scenario falls back to the neutral run icon, and any failed-step error icons on it are hidden.

Inline error panel

When a failed step has additional detail in the report, the plugin displays an inline error panel as an editor inlay beneath the failing step. The panel is laid out as a stack of expandable rows:

• Message — the assertion or exception message
• Expected — the expected value (when present)
• Actual — the actual runtime value
• Stack trace — the first line acts as the row header (typically the exception class plus message); the remaining frames are revealed when the row is expanded

Long multi-line Message / Expected / Actual values fold to their first line with an … indicator and expand on click. Single-line values always render in full. The initial fold state is configurable under Settings → Tools → SpecBinder → Inline error panel — Message / Expected / Actual folding: never collapse, always collapse, or only collapse when the value is longer than a threshold (the default — 10 lines).

Clickable stack traces

Stack-trace frames render the same way they do in the run/debug console: each (FileName.java:line) reference is a hyperlink that opens the source file at the matching line. Frames with no navigable source (Native Method, Unknown Source) stay as plain text.

Frames pointing at your own project's source are styled differently from JDK / library frames so user-code lines stand out at a glance. The colour and font style used for in-module frames are configurable under Settings → Tools → SpecBinder → Inline error panel — in-module stack trace styling.

Diff viewers

When the failing step carries both Expected and Actual values, two extra actions appear under those rows:

• Show diff opens IntelliJ's standalone diff viewer on the two values. The Expected pane is editable while Actual stays as a read-only runtime snapshot, so the standard chunk-arrows in the gutter can copy differing pieces from Actual into Expected. When the failing parameter is a typed doc string ("""html, """json, """xml, """yaml, …), the viewer applies language-aware syntax highlighting and folding to both panes.
• Visual diff is offered when the failing parameter is an HTML-tagged doc string. It opens a side-by-side rendered-HTML diff in a separate window, outlining differing elements (green = modified, red = only in Actual, orange = only in Expected). Indicators can be toggled from the toolbar; up/down arrow buttons step through the differences and highlight the current element on both sides. Zoom is supported via Ctrl/Cmd + = / - / 0 and Ctrl/Cmd + mouse-wheel, between 50% and 300%.

The diff viewer's toolbar also offers two write-back actions:

• Copy Actual to Expected overwrites the Expected pane with the runtime Actual value (equivalent to pressing every chunk-arrow at once), without touching the spec file or closing the viewer.
• Apply Expected to Step writes the current Expected pane contents back into the failing step's matching parameter ("…" literal or """…""" doc string) and closes the viewer. If the value cannot be safely applied (for example, the step has no unambiguous matching parameter), the action is disabled and a tooltip explains why.

One-click Approve

For routine snapshot-style failures the panel also exposes an Approve link, which performs the same rewrite as Apply Expected to Step but in one click and without opening the diff window. After a successful Approve (or Apply Expected), the editor caret is placed at the end of the replaced value and focus returns to the spec file so you can keep typing.

If the rewrite cannot be applied, the reason is surfaced as an editor hint so the failure is visible rather than silent.

Embedded HTML previews

When the failing parameter is an HTML-tagged doc string, the inline error panel also renders live HTML previews directly below the Expected and Actual values, so you can see the rendered output alongside the source.

Refactoring

Find Usages

Alt+F7 on a Java step method lists every Gherkin step in the project that matches its annotation pattern, with the file, line, and surrounding scenario in the standard Find Usages tool window.

Rename

Shift+F6 is wired up for the three step-related rename targets:

• Cucumber-style annotation patterns — rename a step pattern on @Given / @When / @Then / @And / @But and the plugin propagates the change to every matching step text across every feature file in the project. Patterns with regex capture groups are supported: the values captured at each call site are preserved when the surrounding template is rewritten.
• Step methods — rename the underlying Java method and matching step phrases are kept in sync.
• Scenario Outline parameters — invoke rename on a <parameter> placeholder inside a Scenario Outline or on the corresponding Examples-table column header to rename every occurrence within that Scenario Outline.

Settings reference

All plugin-specific options live under Settings → Tools → SpecBinder:

Section	Settings
File extensions	Handle .feature, .specb, or both.
On feature file save	Auto-recompile mode and debounce delay.
Code folding	Make Rules foldable; collapse Rules / Scenarios / """html / """json / """xml / """yaml doc strings by default.
Doc string previews	Auto-open HTML previews when a feature file is opened.
Project view	Show Feature / Rule / Scenario / Background as expandable children of feature files.
Spell checking	Enable spell checking inside feature files.
JSON-report results	Read execution-reporter JSON for gutter pass/fail icons; hide stale icons.
Inline error panel — folding	Initial fold state of multi-line Message / Expected / Actual values.
Inline error panel — stack trace styling	Colour and font style for in-module stack-trace frames.

Colour customisation for Gherkin tokens lives on a separate page under Settings → Editor → Color Scheme → Gherkin (SpecBinder), and formatting defaults live under Settings → Editor → Code Style → Gherkin (SpecBinder).

See also

• Getting Started — adding SpecBinder to a project, writing your first feature, and running the generated tests.
• Configuration — the @Gherkin2JUnitOptions annotation that controls how features are generated into JUnit code.