Editing spec files

Syntax highlighting

Each type of element in a spec file has a different colour. Thus you can find a scenario quickly, and you can see the parameter values in a step easily.

Every element type carries its own colour — headings, step keywords, tags and the quoted values inside a step all stay apart at a glance.

Examples table placeholders stand out inside the step text, and an Examples table’s header cells can be styled apart from its data rows.

A Background carries its own colour, and a data table attached to a step is coloured apart from an Examples table.

You can adjust the colours in detail. The keyword, the title and the description of an element are three separate settings. The header cells and the data cells of a table are also separate. Thus you can make the important parts more visible, and the other parts less visible.

To change a colour, go to Settings → Editor → Color Scheme → Gherkin (SpecBinder). Default colours are available for light themes and for dark themes.

Each heading is three separate entries — keyword, title and description — so you can make the important parts stand out and mute the rest.

A table's header cells and data cells are separate entries too, each with its own colour, weight and effects.

Completion

Completing a keyword

Invoked at the beginning of a line, completion offers keywords instead of steps — only the keywords that are correct at that position. For example, the list offers Feature: at the start of a file, and Given inside a scenario. A spec file's structure can therefore be written without knowing the order of the keywords by heart.

At the left margin: the block keywords

One indent in: the step keywords instead

The same shortcut on the same line: at the left margin it offers the block keywords, and one indent further in it offers the step keywords instead.

Before the first scenario: the block keywords

Inside a Scenario Outline the list gains Examples:

It follows the structure too: inside a Scenario Outline the list gains “Examples:” alongside the step keywords, because that is what may legally come next.

Completing an existing step

When writing a step, any step already available to this spec file — one that the spec file's tests can call — can be inserted instead of typed out again. Invoke Code Completion (Ctrl+Space) on a step line, the same as in any other file. The list holds only the steps available to this spec file, not the steps of other spec files, so the list stays short.

There is no need to know how a step begins. Typing any word from the step narrows the list, and a second word narrows the list again; the words can be in any order. Choosing a step from the list replaces the typed text with the whole step. Where the step takes values, the IDE inserts a placeholder for each value, ready to be filled in.

‘add’ matches in the middle of the step, not only at its start

Each parameter is left as a placeholder

Type any word from a step rather than its opening words, then accept: the suggestion replaces what you typed and leaves a placeholder wherever a step parameter belongs.

Every suggestion here comes from ShoppingCartScenarios

Another file, another list — CheckoutSpec

The same gesture in another module's Checkout.feature offers an entirely different list — you are only offered steps this file can actually use, which are the step methods reachable from the test class generated for it.

Element folding

You can fold a rule, a scenario, a background or a doc string to one line. Thus you can work on one part of a long spec file, and the other parts stay out of the way.

The doc string folds on its own

The scenario takes its attachments with it

A doc string folds on its own; folding the scenario around it then takes the doc string, the data table and the Examples with it.

A Rule folds to its heading line

Every scenario inside it goes with it

A Rule folds like a scenario does: it collapses to its heading line with every scenario nested inside it.

You can also select which elements are folded when a file opens: rules, scenarios and doc strings each have one setting, under Settings → Tools → SpecBinder → Editor → Fold on open. Thus a file with long payloads can open with every doc string folded.

Fold on open has one checkbox each for rules, scenarios and doc strings.

Two buttons on the toolbar above the spec file fold or unfold all the scenarios and backgrounds in the file at the same time — see Expand and collapse everything. Rules and doc strings do not change. Each button can also be given a keyboard shortcut under Settings → Keymap.

Expand and collapse everything

Two buttons on the spec file's toolbar collapse and expand every Scenario and Background in the file at once. Collapsing leaves only the title lines, so a long spec file becomes a short outline of titles, and each scenario can then be opened on its own.

Collapse All Scenarios

Every scenario folded to its title line

Expand All Scenarios — the left of the pair

One press, and a feature that overflowed the screen becomes a list of its own titles — every Scenario, the Scenario Outline and the Rule's scenarios folded together. The other button expands everything again.

Formatting

Reformat Code sets the indentation of each line to the correct level. It also aligns the columns of your tables.

Every table padded so its pipes line up

One Reformat Code: levels corrected throughout, and every table padded so its pipes form columns.

The IDE does not reformat the text inside a doc string unless you ask for this, though an ordinary reformat does move the fences to their correct level and pulls any body line left of them across. If a doc string has a content type, the IDE can format that text with the rules of the content type. Select the text between the two """ and then use Reformat Code. The IDE adjusts the indentation and the line breaks of the JSON, YAML, XML, HTML or SVG, and puts the text below the first """. Thus you can make a large payload easy to read, and you do not have to align it line by line.

The JSON laid out by its own rules; the step is untouched

Select the content between the fences and Reformat Code lays the JSON out by its own rules — the step around it is untouched.

Spell checking

The IDE checks the spelling of the text that you write: step text, titles, descriptions, comments and doc strings. It does not check the technical parts, such as keywords, tags, placeholder names and table values. Thus you get only the warnings that are useful.

You can enable or disable the spelling checks in Settings → Tools → SpecBinder → General.

Put the caret on a marked word and the IDE offers a correction, the same as in any other file.

The marked word offers its correction in place

Tags, placeholders and table values are never checked

Only the prose is checked — @cart, <qty> and every table value are left alone — and the marking is actionable: put the caret on the marked word and the IDE offers the correction.

Switched on under Tools → SpecBinder → General

The marking style lives in the colour scheme: a crimson dotted line

Switching it on lives under Tools → SpecBinder → General. How the marks look is somewhere else entirely — search for Gherkin and the colour scheme's typo token carries the effect, a dotted crimson underline, with a preview of it underneath.

Structure view

Open the Structure tool window to see the outline of the file. It shows the features, the rules and the scenarios. Click an item to go to it.

The outline stops at scenario level — features, rules, scenarios and outlines, but not their steps — which is what makes it a usable table of contents.

The Project tool window can show the same elements. Enable Show file members in Project view in Settings → Tools → SpecBinder → Project view. Each spec file then becomes an expandable node, and its rules, scenarios and examples are the children. Click a child to open the file at that element. Thus you can go directly to a scenario from the project tree. Each child has the colour of its element type, from the colour scheme that you use.

The file becomes a branch: rules and scenarios hang below it, nested as they are in the file and coloured by element type.