Skip to content

Commit 9261483

Browse files
jgelukclaude
jgeluk
and
claude
committed
docs(story): add StoryTestScenario concept and test scenarios page
Add a new concept page explaining how stories are tested using BDD-style Given-When-Then test scenarios, with audience tabs for business and technical readers plus an Ontology tab with facts for StoryTestScenario, State, and Expectation. Add StoryTestScenario to the main story UML diagram and create a dedicated detail diagram. Expand the continuous-testing page with sections on functional health and coverage. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 8c39b3a commit 9261483

File tree

6 files changed

+306
-0
lines changed

6 files changed

+306
-0
lines changed

‎docs/concept/story/.pages.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ nav:
44
- What is a story?: what-is-a-story.md
55
- Story structure: story-structure.md
66
- Why stories matter: why-stories-matter.md
7+
- Test scenarios: test-scenarios.md
78
- Continuous testing: continuous-testing.md
89
- Relationships: relationships.md
910
- Implementation: implementation.md

‎docs/concept/story/continuous-testing.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,45 @@ This means that Stories are not just requirements
1818
documents — they are **living, executable specifications**
1919
that the EKG monitors and validates throughout their entire
2020
lifecycle.
21+
22+
## How it works
23+
24+
Every story has one or more
25+
[test scenarios](test-scenarios.md) — concrete
26+
Given-When-Then checks that verify the story delivers
27+
what it promises.
28+
The EKG runs these test scenarios continuously, not
29+
just before deployment but also in production.
30+
31+
When a test scenario fails, the EKG knows exactly
32+
which story is affected, which
33+
[use case](../use-case/index.md) it belongs to, and
34+
which [personas](../persona/index.md) are impacted.
35+
This turns a technical failure into a business-level
36+
signal.
37+
38+
## Functional health
39+
40+
**Functional health** is the degree to which the EKG
41+
is delivering on its promises.
42+
It is measured by the ratio of passing test scenarios
43+
to total test scenarios across all stories.
44+
45+
Because the EKG tracks this continuously, stakeholders
46+
can answer questions like:
47+
48+
- Are all stories still delivering after last night's
49+
data load?
50+
- Which use cases are affected by the ontology change
51+
we just deployed?
52+
- What is the overall health of the EKG right now?
53+
54+
## Coverage as a first-class metric
55+
56+
Stories without [test scenarios](test-scenarios.md) are
57+
immediately visible as gaps.
58+
The goal is 100% story coverage — every story should
59+
have at least one test scenario verifying its behavior.
60+
61+
This makes testing a **structural property** of the
62+
EKG, not an afterthought.

‎docs/concept/story/test-scenarios.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
---
2+
title: Test scenarios
3+
description: >-
4+
How stories are tested using BDD-style test scenarios
5+
with Given-When-Then, making them executable
6+
specifications that verify the EKG delivers what it
7+
promises.
8+
keywords:
9+
- story test scenario
10+
- given-when-then
11+
- BDD
12+
- test coverage
13+
- functional health
14+
- EKG method
15+
- enterprise knowledge graph
16+
schema_type: "Article"
17+
---
18+
19+
# Test scenarios
20+
21+
<!--summary-start-->
22+
23+
_A concrete verification of a Story, following a
24+
Given-When-Then pattern that defines an initial state,
25+
input values, and the expected result_
26+
27+
<!--summary-end-->
28+
29+
=== "Business & Management Audience"
30+
31+
## Stories are testable
32+
33+
Stories are not just documentation — they are
34+
**testable, executable specifications**.
35+
Each story has one or more test scenarios that verify
36+
the story delivers what it promises.
37+
38+
This is what separates the Use Case Tree Method from
39+
traditional requirements management: every story can
40+
be automatically checked, not just reviewed by a
41+
human.
42+
43+
## How testing works
44+
45+
Each test scenario follows a simple three-step
46+
pattern:
47+
48+
1. **Set up the situation** — Define the data that
49+
should already exist before the story runs
50+
2. **Run the story** — Provide the inputs the story
51+
needs
52+
3. **Check the result** — Verify that the output
53+
matches what was expected
54+
55+
This pattern is repeated for each scenario, covering
56+
different situations the story might encounter:
57+
normal cases, edge cases, and error conditions.
58+
59+
## Why this matters
60+
61+
Because every story has test scenarios, the EKG can
62+
continuously verify that all stories still deliver
63+
what was promised.
64+
When anything changes — code, ontologies, data
65+
pipelines, policies — the EKG can immediately detect
66+
whether all stories still work.
67+
68+
This is how you achieve **functional health** of
69+
the EKG: the system knows whether it is delivering
70+
on its promises, at all times.
71+
72+
Stories without test scenarios are immediately
73+
visible as gaps, making it clear where coverage
74+
needs to improve.
75+
The goal is 100% story coverage.
76+
77+
See [Continuous testing](continuous-testing.md) for
78+
more on how the EKG monitors its own health.
79+
80+
=== "Data & Tech Audience"
81+
82+
## Given-When-Then
83+
84+
Each story has one or more **test scenarios** that
85+
follow the
86+
[BDD](https://en.wikipedia.org/wiki/Behavior-driven_development)-style
87+
Given-When-Then pattern:
88+
89+
- **Given** — An input graph: a dataset that sets up
90+
the initial state (the world as it exists before
91+
the story runs)
92+
- **When** — Invoke the story with input values for
93+
each input [concept](../concept/index.md) (the
94+
parameters the story needs)
95+
- **Then** — The expected result, which takes one of
96+
two forms depending on the story type:
97+
- For **query stories**: output data matching
98+
the defined output concepts
99+
- For **update stories / transform rules**: an
100+
expected output graph representing the new
101+
state
102+
103+
## Example
104+
105+
Consider a story _"As the Chief Risk Officer, I need
106+
to know our current Risk Position against party B."_
107+
108+
A test scenario might look like:
109+
110+
- **Given** — A graph containing party B, its
111+
contracts, and known exposures
112+
- **When** — Invoke the story with `party = B`
113+
- **Then** — The result contains the aggregated risk
114+
position matching the expected output
115+
116+
Multiple scenarios cover different situations: a
117+
party with no exposures, a party with multiple
118+
contract types, missing data, and so on.
119+
120+
## Living specifications
121+
122+
This is what makes stories **living specifications**
123+
rather than throwaway tasks.
124+
Every story is continuously tested across its entire
125+
lifecycle.
126+
When anything changes — code, ontologies, data
127+
pipelines, policies — the EKG can immediately detect
128+
whether all stories still deliver.
129+
130+
Because the EKG knows about both
131+
[Stories](index.md) and their
132+
[Implementations](implementation.md), it can run
133+
test scenarios against each implementation and
134+
report on which stories are passing, failing, or
135+
untested.
136+
137+
## Test coverage
138+
139+
The goal is **100% story coverage**: every story
140+
should have at least one test scenario.
141+
Stories without test scenarios are immediately
142+
visible as gaps in the system's coverage report.
143+
144+
This visibility is deliberate — it turns testing
145+
from an afterthought into a first-class concern
146+
that is tracked alongside the stories themselves.
147+
148+
See [Continuous testing](continuous-testing.md) for
149+
how test scenarios fit into the EKG's ongoing
150+
health monitoring.
151+
152+
=== "Ontology"
153+
154+
--8<-- "fragment/uctm-diagram-story-test-scenario.md"
155+
156+
<span id="ontology"></span>
157+
## Facts
158+
159+
!!! info "About these facts"
160+
161+
We're not prescribing a full OWL ontology here.
162+
These are minimal facts you can use to build your
163+
own ontology, schema, or graph model.
164+
165+
### StoryTestScenario
166+
167+
- **Opaque universally unique identifier**
168+
- A StoryTestScenario must have an **opaque**,
169+
**universally unique** identifier.
170+
- Prefer a random identifier such as
171+
**UUIDv4**.
172+
173+
- **Belongs to exactly one Story**
174+
- A StoryTestScenario must reference exactly one
175+
[Story](index.md) via a `:testScenario`
176+
relationship.
177+
- A Story can have **0..\*** StoryTestScenarios.
178+
179+
- **Description**
180+
- A StoryTestScenario should have a
181+
human-readable description of the situation
182+
it verifies.
183+
184+
- **Given (initial state)**
185+
- A StoryTestScenario must reference a
186+
**State** — a set of datasets that define the
187+
initial graph before the story runs.
188+
189+
- **When (input values)**
190+
- A StoryTestScenario must specify input values
191+
for each input
192+
[Concept](../concept/index.md) that the
193+
Story requires.
194+
195+
- **Then (expected result)**
196+
- A StoryTestScenario must reference an
197+
**Expectation**, which takes one of two
198+
forms:
199+
- **State** — an expected output graph
200+
(for update stories / transform rules)
201+
- **StoryOutputs** — expected output
202+
values matching the defined output
203+
concepts (for query stories)
204+
205+
### State
206+
207+
- A **State** is a set of named datasets (graphs)
208+
representing a snapshot of the world.
209+
- Used as both the **given** (initial state) and,
210+
for update stories, as the **then** (expected
211+
output state).
212+
213+
### Expectation
214+
215+
- **Expectation** is the base type for the expected
216+
result of a test scenario.
217+
- It has two specializations:
218+
- **State** — the expected output graph
219+
- **StoryOutputs** — the expected output values
220+
221+
### Cardinality
222+
223+
- A Story can have **0..\*** StoryTestScenarios
224+
- A StoryTestScenario belongs to exactly **1** Story
225+
226+
## See also
227+
228+
- [Story](index.md) — The business requirement that
229+
test scenarios verify
230+
- [Story Implementation](implementation.md) — The
231+
technical realization tested by scenarios
232+
- [Continuous testing](continuous-testing.md) — How
233+
test scenarios fit into ongoing health monitoring

‎docs/diagrams/src/uctm-story-test-scenario.puml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
@startuml
2+
!include ../include/themes/light.puml
3+
top to bottom direction
4+
hide members
5+
6+
class "Story" as Story [[/concept/story/#ontology]]
7+
class "StoryTestScenario" as StoryTestScenario [[/concept/story/test-scenarios/#ontology]]
8+
class "State" as State
9+
class "Expectation" as Expectation
10+
11+
' Scenario ownership
12+
Story "1" --> "0..*" StoryTestScenario : :testScenario
13+
14+
' Given-When-Then
15+
StoryTestScenario --> State : :given
16+
StoryTestScenario --> Expectation : :then
17+
18+
' Expectation specializations
19+
Expectation <|-- State
20+
21+
@enduml

‎docs/diagrams/src/uctm-story.puml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ class "TechnicalTerm" as TechnicalTerm [[/concept/term/technical-term/#ontology]
1616
class "WorkflowDefinition" as WorkflowDefinition [[/concept/workflow/#ontology]]
1717
class "StoryConceptRelationship" as StoryConceptRelationship [[/concept/concept/story-concept-relationship/#ontology]]
1818
class "StoryImplementation" as StoryImplementation [[/concept/story/implementation/#ontology]]
19+
class "StoryTestScenario" as StoryTestScenario [[/concept/story/test-scenarios/#ontology]]
1920

2021
' Term specializations
2122
Term <|-- BusinessTerm
@@ -48,6 +49,9 @@ Concept "0..1" --> "1" BusinessTerm : :labelTerm
4849
' Implementation
4950
Story "1" --> "0..*" StoryImplementation : :implementation
5051

52+
' Test scenarios
53+
Story "1" --> "0..*" StoryTestScenario : :testScenario
54+
5155
' Workflow participation
5256
WorkflowDefinition --> Story : :steps
5357

‎docs/fragment/uctm-diagram-story-test-scenario.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<!-- markdownlint-disable MD041 MD012 -->
2+
3+
<figure markdown>
4+
<object data="/diagrams/out/uctm-story-test-scenario.svg#darkable" type="image/svg+xml"></object>
5+
</figure>

0 commit comments

Comments
 (0)