Scenarios, verification & traceability
Scenarios, tests and simulation runs that show the system does what it should.
On this page: scenario · workflow · participant · sequence · alt · when · ref · test-plan · case · cases · step · trace · simulation · stimulus · keyframe
End-to-end cases, test plans, typed relationships and simulation runs.
scenario#
An end-to-end architecture scenario (scenarios.yaml): participants and ordered sequences of calls/messages.
- Keywords:
scenario - Set: functional analysis & scenarios
- Where: top level
- Syntax:
scenario id "Name" { participant Sys.comp { role "…" }; sequence id "…" { a.p -> b.q : fn "note" } }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
verifies |
list of requirement names | Requirements the scenario verifies (traces from it, in traces.yaml); a value may give its trace an id: verifies REQ-1 as t-7. |
fold |
refs | Composites drawn as one lifeline when the editor shows the whole scenario (a sequence's own fold wins when it is shown alone). Only the view. |
scenario emergency-stop "Emergency stop" {
participant Car.lidar { role "Detects the obstacle" }
participant Car.fusion
sequence s1 "Detection to braking" {
Car.lidar.cloud -> Car.fusion.lidar_in : POINT_CLOUD
Car.fusion -> Car.fusion : plan "Private planning step"
}
}
workflow#
A process (a workflow): who does what, in which order, with its branches. Its lanes are the blocks taking part — a person or a team is a block too — and each line is a hand-off (sales -> ops : provision "…") or an activity in one lane (sales: qualify "…"); alt { when "…" { … } when "…" { … } } (and loop, opt, par) branch it as in a sequence. in System lets lanes be written by their name. Written to Arche as a scenario (scenarios.yaml), with one sequence.
- Keywords:
workflow(old spelling:process) - Set: functional analysis & scenarios
- Where: top level
- Syntax:
workflow id "Name" [in System] { lanes a, b; a: activity "…"; a -> b : handoff "…"; alt { when "…" { … } } }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
lanes |
list of element names | The blocks taking part. |
workflow onboarding "Onboard a customer" in Shop {
lanes sales, ops
sales: qualify "Qualify the lead"
sales -> ops : provision "Ask for an account"
ops: create "Create the account"
}
participant#
A component taking part in a scenario, by path System.comp.child.
- Keywords:
participant - Set: functional analysis & scenarios
- Where: inside
scenario - Syntax:
participant System.comp [as alias] { role "…"; ports p, q }
| Property | Value | Meaning |
|---|---|---|
role |
string | What it does in the scenario. |
ports |
refs | Ports the case exercises. |
participant Car.fusion { role "Plans the stop"; ports lidar_in, can0 }
sequence#
An ordered list of steps from[.port] -> to[.port] [: fn|MESSAGE] ["note"].
- Keywords:
sequence - Set: functional analysis & scenarios
- Where: inside
scenario - Syntax:
sequence id "Name" { fold System.comp; a.p -> b.q : fn "note"; ref other "…" }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
fold |
refs | Composites drawn as one lifeline when the editor shows this sequence (their children's exchanges among themselves become ⋯ N internal); a click on one opens it. Only the view. |
sequence boot "Boot" { Car.hmi -> Car.fusion : start }
alt#
A combined fragment of a sequence: alternatives (alt), a loop, an option, parallel parts. Its branches are when "condition" { steps }.
- Keywords:
alt·loop·opt·par·break·critical - Set: functional analysis & scenarios
- Where: inside
sequence, insidewhen - Syntax:
alt { [folded] when "cond" { a -> b : f } when "else" { … } }
| Property | Value | Meaning |
|---|---|---|
folded |
bool | Drawn shut in the editor's sequence view: one row, ▸ par [label] — N steps, that a click opens. Only the view: the Arche project and the exports show it open. |
alt {
when "table valide" en "table valid" { cff -> cff : main "lookup kept" }
when "table absente" { cff -> cff : main "mapped = 0" }
}
when#
A branch of a fragment: its condition (or the loop's), and its steps.
- Keywords:
when - Set: functional analysis & scenarios
- Where: inside
alt - Syntax:
when "condition" { a -> b : f; … }
when "toutes les SENSOR_PERIOD" { timer -> imu : read }
ref#
Another sequence, played here (UML's interaction use): ref nominal names a sequence of the same scenario, ref boot.nominal one of another scenario. Drawn as a box over the lifelines it covers, which opens it; the Arche project, which has no such step, gets its steps written in its place.
- Keywords:
ref - Set: functional analysis & scenarios
- Where: inside
sequence, insidewhen - Syntax:
ref sequence ["label"] | ref scenario.sequence ["label"]
ref pbit-run "PBIT de chaque élément"
test-plan#
A test plan (testplans.yaml): cases of steps with do, wait and expect assertions.
- Keywords:
test-plan(old spellings:testplan,tests) - Set: the model
- Where: top level
- Syntax:
test-plan ID "Name" { scenario s; case TC "…" { at 0ms do python…; at 10ms expect python…; within 30ms expect python… } }
| Property | Value | Meaning |
|---|---|---|
file |
string | The file it is written to (default testplans.yaml; Arche reads every testplans*.yaml). |
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
scenario |
scenario name | Scenario the plan exercises. |
setup |
any | Observer code run before every case: Python to the end of the line, or a ``` block. |
check-sequence |
bool | Check the run against the scenario sequence. |
verifies |
list of requirement names | Requirements verified by every case. |
model |
system name | System the plan runs on (default: the simulation model). |
issue |
string | Its issue in the tracker (Jira, GitHub, GitLab): written by archec issues sync when it opens one for a failing case or an unverified requirement, or by hand to link one. |
test-plan TP-AEB "Automatic emergency braking" {
verifies REQ-BRK-001
case TC-AEB-01 "Obstacle at 30 m" {
at 0ms "Obstacle appears" do send(lidar.cloud, POINT_CLOUD(obstacle=30))
within 100ms expect received(brakes, "BRAKE_CMD") == 1
}
}
case#
A test case. Runs on a fresh simulation.
- Keywords:
case - Set: the model
- Where: inside
test-plan - Syntax:
case ID "Name" { objective "…"; step … }
| Property | Value | Meaning |
|---|---|---|
setup |
code | Python run before the case's steps. |
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
objective |
text | What the case shows. |
preconditions |
text | State before the case. |
verifies |
list of requirement names | Requirements this case verifies. |
timeout |
duration | Case timeout. |
keyframe |
ident | The keyframe of the system it starts from: its variables set before the case's steps (in its setup). |
preview |
ident | The preview of a ui it starts from, written after its title: case TC-7 "Fault at speed" from preview Faulted. The run starts from the preview's keyframe, then what the preview sets: a variable of a part, a message as if received, a part's state, a variable of the ui. It runs on the browser simulator. |
issue |
string | Its issue in the tracker (Jira, GitHub, GitLab): written by archec issues sync when it opens one for a failing case or an unverified requirement, or by hand to link one. |
case TC-01 "Nominal" { objective "Brakes engage" }
cases#
Test cases written as a table: one body, and a rows block with a line per case — id first, then a column per value. {column} anywhere in the label or the body (a text, code, an id) is that row's cell; a cell - leaves out every line that uses it; a cell holding a | is quoted. Each row is an ordinary case.
- Keywords:
cases - Set: the model
- Where: inside
test-plan - Syntax:
cases "Speed {v}" { at 0ms do car.speed = {v}; within 1s expect car.state == "{s}"; rows { id | v | s; TC-1 | 10 | Slow; TC-2 | 30 | Fast } }
cases "Cruise at {v} m/s" {
at 0ms do car.speed = {v}
within 1s expect car.state == "{state}"
rows {
id | v | state
TC-CR-1 | 10 | Slow
TC-CR-2 | 30 | Fast
}
}
step#
Old form, read until edition 0.13: write the case as a timeline instead (at 0ms do …, at 10ms expect …); archec fmt rewrites it. A test step: observer code, a wait, and assertions (within 30ms: …, eventually: …, never: …). do and expect take Python as it is, to the end of the line (or a ;, or the } of a one-line block); the linter checks the messages (MSG(…), sent("MSG")) and states (part.state == "S") it names. On a ui: do press hmi.engage, do change hmi.limit 80, expect hmi.mode.text == "…", expect hmi.engage.enabled, expect hmi.screen == Details — a case with one runs on the browser simulator (docs/ui.md).
- Keywords:
step - Set: the model
- Where: inside
case - Syntax:
step ["Name"] { do python…; wait 10ms; expect python… }
| Property | Value | Meaning |
|---|---|---|
do |
any | Observer code run at the start of the step: Python to the end of the line, or a ``` block. |
wait |
duration | Time to let pass after do. |
expect |
any | One assertion per expect: a Python condition, optionally within 30ms:, eventually: or never:. |
fault |
any | A fault injected at the start of the step (as a moment's fault). |
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
step "Engage" {
do send(hmi.btn, ENGAGE())
wait 50ms
expect car.ctrl.state == "Driving"
}
trace#
A typed relationship between two elements (traces.yaml). A link to a requirement is written on its other end instead, satisfies R / verifies R: trace satisfies and trace verifies are old forms read until 0.13, but for one with a comment.
- Keywords:
trace - Set: the model
- Where: top level, inside
component, insidesystem - Syntax:
trace derives|refines|allocates|realizes|involves|deploys|traces A -> B ["comment"]
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
trace allocates Car.fusion.plan -> Car.fusion.can0 "Planning drives the CAN bus"
simulation#
Behavioural simulation settings (simulation.yaml): which model runs, for how long, and the stimuli replayed. Without one, the first system is simulated.
- Keywords:
simulation - Set: functional analysis & scenarios
- Where: top level
- Syntax:
simulation { model System; horizon 600ms; at 1ms ["Label"] do python… }
| Property | Value | Meaning |
|---|---|---|
model |
system name | The system to simulate. |
horizon |
duration | Simulated duration. |
seed |
number | Random seed. |
scenario |
scenario name | Scenario the run is checked against. |
panel |
ident | Control panel shown beside the run. |
lanes |
any | Chronogram lanes (glob patterns). |
deployment |
deployment name | The deployment the run uses (threads, cores, buses). Default: the only one, when there is one. |
simulation {
model Car
horizon 500ms
seed 42
lanes "adcu.*", "brakes.*"
at 20ms "Obstacle at 30 m" do send(lidar.cloud, POINT_CLOUD(nearest=30.0))
}
stimulus#
Old form, read until edition 0.13: write at 5ms "Label" do … in the simulation instead; archec fmt rewrites it. Something done to the model at a given time during the run.
- Keywords:
stimulus - Set: functional analysis & scenarios
- Where: inside
simulation - Syntax:
stimulus "Label" { at 1ms; do python… }
| Property | Value | Meaning |
|---|---|---|
at |
duration | When. |
do |
any | Observer code: Python to the end of the line (or the }), or a ``` block. |
stimulus "Driver engages" { at 5ms; do send(hmi.bus, ENGAGE_REQ(True)) }
keyframe#
A named start state of the system, as MuJoCo's keyframes: each line sets a part's variable (ctrl.gain = 2, a physical network's state c.v = 1V), the position of a part's joint (arm.upper.joint = 0.5, rad or m; a ball's turn wrist.joint = [0, 0, 30deg]; a free body's drone.joint.at = [0, 0, 2m] and drone.joint.rot; their speeds joint.vel, a free body's joint.spin) or the command an actuator starts with (arm.motor.cmd = 0.2, its in port). archec sim --keyframe, archec physics --keyframe (and --linearize --at <keyframe>) start from it, a test case with keyframe does, and archec gen --target mujoco writes it as a <key>.
- Keywords:
keyframe - Set: functional analysis & scenarios
- Where: inside
system - Syntax:
keyframe name ["Label"] { part.var = value; part.joint = value; actuator.port = value }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
set |
any | One line of it: path = value (written without set). |
keyframe raised "Arm raised" {
arm.upper.joint = 1.2
arm.motor.cmd = 0.4
ctrl.target = 1.2
}