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.

Placeholders stand out inside the step text, and an Examples table’s header cells are coloured apart from its data.

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

Invoke Code Completion in a step, the same as in any other file. The IDE shows the steps that the tests for this spec file can call. It does not show steps from other spec files. Thus the list stays short.

You do not have to know the first words of a step. Type any word from the step to make the list shorter. Type a second word to make the list shorter again. The words can be in any order. When you select a step, it replaces the text that you typed. If the step has values, the IDE adds a placeholder for each one.

The typed words are matched anywhere in a step, not just at its start — and each suggestion shows the parameters it takes.

A second word narrows the list further, and the order you type them in does not matter — here “quantity add” finds steps that read “add … with quantity”.

Choosing a step replaces everything you typed and leaves a placeholder wherever a value belongs.

Start completion at the beginning of a line to get keywords instead. The IDE shows only the keywords that are correct at that position. For example, it shows Feature: at the start of a file, and Given in a scenario. Thus you can write the structure of a spec file without knowledge of the order of the keywords.

<The completion popup at the start of an empty line inside a Scenario, listing the step keywords — showing that what is offered depends on where the caret sits.>

Element folding

You can fold a scenario, a background or an examples table to one line. Thus you can work on one part of a long spec file, and the other parts stay out of the way. You can also fold a rule, but first you must enable this option in the settings.

Folding a scenario takes everything attached to it — the doc string, the data table and the Examples — leaving just the heading line.

You can also select which elements are folded when a file opens. Rules, scenarios and doc strings each have their own setting, and doc strings have one setting for each content type. Thus a step with a large JSON doc string can open folded, and a short doc string can stay open.

<The Editor page under Settings → Tools → SpecBinder, showing the collapse-on-open checkboxes — rules and scenarios, and one per doc-string content type — so it is clear where these are set and how granular the choice is.>

Two buttons on the editor toolbar fold or unfold all the scenarios and backgrounds in the file at the same time. Rules and doc strings do not change. The toolbar is visible by default. You can also assign a keyboard shortcut to each button in the Keymap.

Formatting

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

<A before-and-after pair of the same spec: on the left a file with ragged indentation and a misaligned table, on the right the same file after Reformat Code, with the table's pipes lined up into columns.>

The IDE does not format the text inside a doc string, unless you ask for this. 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 or HTML, 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.

<A before-and-after pair of a step with a """json doc string: on the left the JSON as pasted, on one long line or unevenly indented, with the content between the two """ selected; on the right the same doc string after Reformat Code, laid out over several lines and indented under its opening """.>

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 → File handling.

<A step or scenario title with a typo underlined, in a file that also contains tags, a placeholder and a table — none of which are flagged. The contrast between the flagged prose and the unflagged technical tokens is the point.>

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 Structure tool window open beside a spec file, showing the Feature → Rule → Scenario tree for a file long enough that the outline is genuinely easier to navigate than the file.>

The Project tool window can show the same elements. Enable Show file members in Project view in Settings → Tools → SpecBinder → File handling. 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 Project tool window with a spec file expanded, showing its Rules and Scenarios as child nodes below the file, each in the colour of its element type.>