STANDARDS · GHERKIN
Given, When, Then: behaviour as examples anyone can read.
Gherkin is the plain-text format Cucumber uses to describe what software does through concrete examples. FACET uses the same format for a record’s acceptance criteria.
One keyword per line says what the line is for.
A scenario is one concrete example of one rule. Read the keywords alone and you already know its structure: where it starts, what happens, what must be true afterwards.
Feature: Discount codesFeatureNames the capability the examples below describe.Scenario: An expired code is rejectedScenarioOne concrete example of one rule, with a name a person would say.Given a code that expired yesterdayGivenThe state before anything happens.When the customer applies the codeWhenThe one action the example is about.Then the total is unchangedThenAn outcome someone can observe.And the customer sees that the code has expiredAndAnother step of the same kind as the one above it, here a second outcome.
The same scenario, inside a FACET record.
FACET keeps the sentences and puts them where the rest of the feature lives: next to its intent, its anchors and the tests that prove it.
Feature: Discount codes # 1 Scenario: An expired code is rejected # 2 Given a code that expired yesterday When the customer applies the code Then the total is unchanged And the customer sees that the code has expired
id: checkout/pricing/discount-codes # 1contract: scenarios: - id: expired-code-rejected # 2 statement: | # 3 Given a code that expired yesterday When the customer applies the code Then the total is unchanged And the customer sees that the code has expiredverification: unit_tests: - id: checkout::discount::test_expired_code_rejected proves: [expired-code-rejected] # 5
| # | Gherkin | FACET record | What changes |
|---|---|---|---|
| 1 | Feature: | id: checkout/pricing/discount-codes | The record is the feature. Its id says where it sits in the product. |
| 2 | Scenario: | contract.scenarios[].id | A stable id instead of a title, so tests and other records can name it. |
| 3 | Given / When / Then / And | contract.scenarios[].statement | The steps, unchanged. Each step on its own line; a second step of the same kind begins with And. |
| 4 | Scenario Outline + Examples | statement with <placeholders> + examples | Named example blocks, one rule per block, and still one scenario however many rows it has. |
| 5 | Step definitions | verification … proves: [scenario-id] | The record names the tests that prove the scenario. They stay in the test runner you already use. |
boundary
FACET uses the shape of Gherkin, not a .feature file.
Why FACET writes features this way.
Documentation that describes code drifts from it. A scenario describes behaviour, which is what people ask about and what tests can check.
One language for product, development and support
A scenario is written to be read by engineers and product managers alike, and the help articles support works from can be generated from the same record. Nobody needs the code to say whether the sentence is right.
Shaped like a test
Given is the state before, When the action, Then what can be observed. That is the shape of a test, so each scenario can be claimed by one, and the record says which.
One scenario, one acceptance criterion
One scenario per distinct rule or edge case. Two consequences are two lines, because a test cannot prove half of a joined sentence.
Focused on the feature
Scenarios sit under the feature they describe, not under a file or a class. A feature has between two and nine of them, at least one a failure path.
Source: FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]
View on GitHub FACET §2.1.1Original excerpt from the English source.[…] It has between two and nine observable scenarios, including at least one failure path. […]
View on GitHub, FACET §3.2Original excerpt from the English source.[…] The normative behavior of the feature — the rules that MUST hold. […]
View on GitHub, FACET §3.2.3Original excerpt from the English source.[…] MUST NOT flatten them into set notation or a list inside one Given/When/Then. […]
View on GitHub, FACET §3.4Original excerpt from the English source.[…] The tests and property checks that prove the contract holds. […]
View on GitHub and FACET §8.5Original excerpt from the English source.[…] The Knowledge facet exists precisely to feed this pipeline. […]
View on GitHub.
The official reference
Gherkin's keywords, its grammar and its translations into many spoken languages are documented by Cucumber.