Référence › Référence du langage › Scenarios, verification & traceability

Référence › Référence du langage

Cette page n’est pas encore traduite : voici la version anglaise.

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, inside when
  • 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, inside when
  • 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, inside system
  • 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
}