Executable Specifications
Executable specifications encode requirements as running tests in shared language — Given-When-Then scenarios bound to real automation — making specification and verification the same artifact.
Definition
An executable specification is a requirement expressed in a structured, runnable form: BDD scenarios in Given-When-Then bound by step definitions to real system operations, or acceptance criteria wired into automated checks. The document and the test coincide: changing behavior means changing the spec, and stale specifications fail rather than mislead.
Context and scope
Implemented with Cucumber-family tools, specification by example workshops, and living documentation generators that publish suites as readable reports.
Common misconceptions
- It is a test format — the format is a communication device; the value is shared understanding between product, dev, and QA before code
- Every test should be written this way — unit and algorithmic tests stay conventional; executable specs suit behavior-facing scenarios
- Gherkin syntax makes specifications good — syntax is trivial; good specifications come from concrete examples elicited with domain experts
Anti-patterns
- Writing scenarios after implementation as decorated test reports rather than before as agreements
- Chaining technical steps — clicking buttons and waiting for selectors — instead of business language
- Maintaining step definition libraries with combinatorial explosion and unreadable scenarios
Related concepts
Related examples
Authoritative source
What it is
Specifications drift from implementations because nothing enforces the match. Executable specifications weld them: the scenario text is bound to automation, so the spec cannot silently age — it fails.
How it works
Workshops surface concrete examples — real inputs and expected outcomes — and encode them as scenarios. Step definitions map each business phrase to system operations via the same APIs production uses. Suites run in CI and publish as living documentation anyone non-technical can read.
When to use it
Business-facing behavior where misunderstanding is expensive: billing rules, workflow transitions, regulatory calculations. Skip it for pure technical units where the audience is the author.
Pitfalls
Post-hoc Gherkin is test theater — the collaboration happened or it did not; the artifact cannot fake it. Over-parameterized step libraries produce scenarios nobody can parse. Specifications encoding UI mechanics break on every redesign; bind to behavior through stable interfaces.