Facet
DeutschInstall

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.

A Gherkin scenario, one keyword per line
  1. Feature: Discount codesFeatureNames the capability the examples below describe.
  2. Scenario: An expired code is rejectedScenarioOne concrete example of one rule, with a name a person would say.
  3. Given a code that expired yesterdayGivenThe state before anything happens.
  4. When the customer applies the codeWhenThe one action the example is about.
  5. Then the total is unchangedThenAn outcome someone can observe.
  6. 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.

GHERKINdiscount-codes.feature
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
RECORDdocs/facets/features/checkout/pricing/discount-codes.yaml
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
Where each Gherkin construct lives in a FACET record
#GherkinFACET recordWhat changes
1Feature:id: checkout/pricing/discount-codesThe record is the feature. Its id says where it sits in the product.
2Scenario:contract.scenarios[].idA stable id instead of a title, so tests and other records can name it.
3Given / When / Then / Andcontract.scenarios[].statementThe steps, unchanged. Each step on its own line; a second step of the same kind begins with And.
4Scenario Outline + Examplesstatement with <placeholders> + examplesNamed example blocks, one rule per block, and still one scenario however many rows it has.
5Step definitionsverification … 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.

The scenario lives in the record. Under verification the record names the tests that prove it, and facet test runs them in the runners you already use. A scenario with no linked test is a lint warning.

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.