All Docs
Gherkin Test Cases

Gherkin Test Cases

Gherkin is one of the three test case Formats in Lathe Studio, beside Standard and Flow (see Test Case Formats). A Gherkin case is written as plain Given/When/Then text, and the text is the source of truth: Lathe derives the executable steps from it on every save, so runs, reports, and bug pushes work exactly as they do for Standard cases.

Choose the Format in the Format field when you create a test case.

Writing a Gherkin case#

The editor has Write and Preview tabs. The Write tab validates as you type and shows Valid once the text parses; problems are shown as Line {line}: {message}, so you always know which line to fix.

Feature: Login

  Background:
    Given a registered user exists

  Scenario: Successful login
    When the user logs in with valid credentials
    Then the dashboard is shown

  Scenario Outline: Login with <username>
    When the user logs in as <username>
    Then the dashboard is shown

    Examples:
      | username |
      | alice    |
      | bob      |

Supported syntax:

  • Feature: — every case starts with one. The feature name becomes the case's title on import.
  • Scenario: — a single path through the feature.
  • Scenario Outline: + Examples: — a parameterized scenario. Each example row runs as its own block of steps, with <placeholders> substituted into the step text. Two rows above mean the tester executes the outline twice — once as alice, once as bob.
  • Background: — steps prepended to every scenario in the feature.
  • @tags — mapped onto the case's coverage tags, so filters and reports keep working. In the editor, an @tag must already exist as a coverage tag on the project; an unknown tag is refused with its line number.
  • Data tables (pipe rows under a step) and Doc Strings (""" blocks) attach to the step they follow. For a Doc String with a content type, write """json — a full media type like """application/json is not supported.

Limits: a case expands to at most 100 steps and one step's text (including its heading) stays under 2,000 characters. An outline that expands past either limit is refused at save, with the line number.

Quick hints under the editor list the same rules in place.

Running a Gherkin case#

A Gherkin case gets one result per case, like every other format — the pass/fail buttons belong to the case, not to individual lines. When a line fails, name it in the note: the example row is the useful detail for outlines ("Example 2 of 2 — Then the dashboard is shown (username=bob)").

Derived steps (keywords emphasized, one block per scenario or example row) are shown in the run exactly as written. Once a case has a result in a run, that run keeps the steps as they were when they ran; a case with no result in an open run follows later edits to the text.

Pushing a failed case to Jira or Azure DevOps sends the steps as plain text — no markup reaches the ticket.

Importing Gherkin#

Three routes land in the same import wizard (choose Import Test Cases on a section or the test case list):

  1. A .feature file. One Feature becomes one case holding all its scenarios; the file's name (without .extension) becomes the section. TestRail's own .feature export — which can repeat Feature: lines — is read with the first as the case and later ones as group headings. A file with no scenarios is refused honestly ("no scenarios"), never imported empty.
  2. TestRail XML. Cases from TestRail's Behaviour Driven Development template carry their scenario blocks natively and import as Gherkin cases. One TestRail BDD case becomes one Lathe case holding all its scenarios. See Migrating to Lathe.
  3. CSV or Excel with a BDD column. Columns named Test Script (BDD) or gherkin definition (or a generic Gherkin Content) map to the Gherkin text; a non-empty cell makes the row a Gherkin case.

Invalid text is refused with the line number, in the dry-run report, before anything is written — fix the file and upload it again.

Unknown tags on import: when a file carries @tags that don't exist as coverage tags yet, the dry-run report lists them with a Create these N tags checkbox, ticked by default. Ticked, the tags are created and attached; unticked, the cases import without them and the result names every dropped tag. (The hand-written editor keeps its stricter rule: unknown @tags are refused there.)

Exporting Gherkin#

  • Export .feature on the test case list downloads a zip with one .feature file per Gherkin case — the stored text, verbatim. The button appears for a project or a single section and is enabled only when Gherkin cases exist.
  • CSV export includes a Gherkin Content column, so a CSV round-trips through the import wizard.

Because the export is verbatim, exporting and re-importing a case gives an equivalent case — same scenarios, same steps.

← All DocsSettings →