How-to guide

Write machines as features

A team that describes what happens in Gherkin can have Trax derive the machines from it: the states, the moves, the guards, the timers, the policies between machines, the views, and who may do what. Nothing is written in C# but the trains the machines invoke. Why this is a source of machines, and what it refuses, is ADR 0058, and why the words are written as a lexicon that Trax turns into the glossary is ADR 0059. The CheckIn sample is this page, built, and How features become machines follows each lexicon line and step to the IR, host.json, GraphQL and the C# builder.

Write the lexicon

The lexicon names the words the features use: the actors and the roles they carry, each machine with its states, triggers and guards, and the views. It is one file beside the features, features/<name>.lexicon, holding every machine, and each line starts with a keyword. A user's machine is owned by an actor; a system machine lives at a fixed key.

Version: 1
 
Actor: passenger "a passenger"
  Roles: passenger
 
Machine: booking
  Owned by: passenger
  Started by: "has a booking"
 
  State: Booked  "is booked"
  State: Open    "is open for check-in"
 
  Trigger: GivePassport "gives passport {passport} for {subject}"
    Input: passport is a string
    Sets: passport

The machine's noun is its id (booking, as Ada's booking says it), it starts in its first state, and its context holds passport because Sets: writes it. Every keyword, and what is filled in when a line leaves it out, is in the lexicon reference. trax lexicon format lines up its columns.

Trax elaborates the lexicon to the glossary, the JSON every engine reads, and from-gherkin writes it as glossary.json beside the machines (below). Its keys are in the feature files reference. An app whose features still have a hand-written glossary.json passes it with --glossary; a lexicon and a glossary.json in one features directory are refused.

Write the features

Each scenario names its people in the third person, sets up what it needs with Givens, acts with Whens, and says what happened with Thens:

Feature: Checking in for a flight
  Scenario: A passenger gives a passport number
    Given Ada is a passenger
    And Ada has a booking
    And Ada's booking is open for check-in
    When Ada gives passport "X1234567" for her booking
    Then Ada's booking is open for check-in

An actor's own act grants that actor the trigger. A trigger no scenario shows anyone firing is not served at all. The steps derivation reads are in the reference; a Then it does not read is about the UI, and is left alone.

Add guards, trains, timers, policies and views

Each of these is a few lexicon lines plus the scenarios that show it. The examples are the CheckIn sample's.

A guard is a pair of phrases and the rule they stand for. A scenario where it holds and one where it fails, with the message, make a guarded move:

  Guard: hasPassport when passport is not empty
    Holds: "has a passport number"
    Fails: "has no passport number"
Scenario: Checking in with no passport number is refused
  Given Ada's booking is open for check-in
  And Ada's booking has no passport number
  When Ada checks in for her booking in seat "14C"
  Then Ada is told "Add your passport number first."
  And Ada's booking is still open for check-in

A train runs when an instance enters a state. The lexicon names its interface and the state, its input from context fields (Takes:), its output (Returns:), and a phrase for each outcome. A done outcome's when is also the output an in-memory run answers with:

  Runs: Trax.Samples.CheckIn.Trains.IIssueBoardingPassTrain in Issuing
    Takes: passport
    Returns: accepted is a boolean
    Outcome: "the boarding pass is issued"              when accepted is true
    Outcome: "the passport is turned down"              when accepted is false
    Outcome: "the boarding pass cannot be issued"       when it fails
    Outcome: "issuing the boarding pass is called off"  when it is called off

Given the trains' assemblies (from-gherkin --trains bin/Trains.dll), Takes: and Returns: may be left out: they are read from the train's input and output records, as the host reads them, and a Returns: line that disagrees with the record is a problem at its line.

When Ada checks in for her booking in seat "14C"
Then Ada's booking is getting a boarding pass
When the boarding pass is issued
Then Ada's booking is checked in

Every invoking state needs a scenario for each of done, failed and cancelled. An outcome may not go to the state the machine starts in (unless that state invokes a train itself): an outcome's state is reserved for what the train produced, so no instance could be started there. Send it to a state of its own, with a move back if the flow returns. The initial state may invoke a train: starting an instance queues its run. The train is the one piece of C# behind the machine, written as in Invoke a train from a state. Its input and output records' properties are the lexicon's field names in camelCase (Accepted is accepted).

A done outcome keeps what the train produced with a Stores: line under Runs:, which reads fields of the train's output into the context, renamed with as:

    Stores: result as lastShot

On a machine a person owns, an outcome may not go to another state that invokes a train. The server would queue that run with nobody there to run it as, so derivation refuses it, as it refuses a timer or a policy that enters one. Stop in a state of the outcome's own and let a trigger the person fires go on from there, or have one train do both steps. Only a system machine chains runs through outcomes.

A timer is time passing in a scenario. There is no lexicon line:

Scenario: A gate agent steps away once the gate is closed
  Given Kit is a gate agent
  And Kit has a desk
  And Kit's desk is closing the gate
  And the flight is closed
  When 2 seconds pass
  Then Kit's desk is done
  And the flight is still closed

A policy is a Then about another instance moving after a When. A system machine has a fixed key and a name, and only the server moves it:

Machine: flight "the flight"
  System at: flight/tx101
  State: Scheduled  "is scheduled"
  State: Open       "is open for check-in"
  State: Closed     "is closed"
  State: Departed   "has departed"
  Trigger: OpenCheckIn  "check-in opens for the flight"
  Trigger: CloseGate    "the flight closes its gate"
Scenario: A gate agent opens check-in for everyone booked
  Given Ada is a passenger
  And Ada has a booking
  And Kit is a gate agent
  And Kit has a desk
  And the flight is scheduled
  When Kit opens his desk
  Then Kit's desk is open
  And the flight is open for check-in
  And Ada's booking is open for check-in

That derives a toSystem policy: when a desk enters Open, the server fires OpenCheckIn on flight/tx101. The flight entering Open then moves every booking still Booked, which is a broadcast. A broadcast moves the instances in exactly one state: a Then that shows instances moving out of two states from one transition is refused, so give them one state to wait in. Each machine's OpenCheckIn also needs a scenario of its own showing it as a plain move (When check-in opens for the flight, When Ada's booking opens for check-in). Two machines of the same owner need a link.

A view is what a reader sees across machines, with labels for states. A scenario that reads it makes its actor a reader, and a view no scenario reads is not served:

View: "bookings"
  Reads: booking
  Field: status from booking's state
    Label: CheckedIn   "Checked in"
    Label: TurnedDown  "Passport not accepted"
  Field: seat from booking's seat
Then Ada's bookings show status "Passport not accepted"

Derive the machines

trax machine from-gherkin --features features --out machines

It reads the lexicon in features, and writes one <machine>.ir.json per machine, host.json with what only the server reads, access.txt, one line per grant, and glossary.json, the lexicon elaborated, so a reviewer sees what was filled in. It replays every scenario on what it derived, and refuses features that contradict each other, or that would derive a machine the host refuses, naming the file and line. Commit machines/, and review access.txt in every pull request: a new grant shows there. trax machine from-gherkin --check in CI fails when a committed file is stale.

trax machine missing --features features lists what the lexicon names and no scenario shows, each with a scenario to paste that is checked green first. trax machine explain --features features prints each scenario with what derivation read from it, a policy in full among them: run it when a scenario does not derive what you meant, and read how a scenario is read.

Serve them

services.AddTrax(trax => trax
    .AddEffects(e => e.UsePostgres(connectionString).AddJunctionProgress())
    .AddStateMachines(o => o.ServeFeatures("machines", typeof(IssueBoardingPassTrain).Assembly))
    .AddMediator(typeof(IssueBoardingPassTrain).Assembly)
    .AddScheduler());

ServeFeatures serves the directory as committed: each machine with its access, the policies between them, the views and the system instances. A directory whose files disagree refuses the host at startup. Copy machines/ into the build output, register an ISnapshotPrincipal, which says whose instances a request reaches and which Trax does not register for you, and export the client manifest and run trax client as for any machine. Serve features from the hub template takes a trax-hub project through each step, persisted operations and the timer and policy intervals included.

A state that invokes a train only queues its run. AddScheduler(), on this host or another sharing the database, runs it, and without one the instance waits in that state. See Meet the host's requirements.

Run the features

  • In memory, on the committed machines: trax machine run --features features --machines machines, or FeatureMachines.Run from a test. Each answer is the host's, access included.
  • Against the host, with Reqnroll: reference Trax.StateMachine.Gherkin.Reqnroll, include the feature files, and configure the bindings with the host in the test process, the glossary the lexicon gives (Lexicon.ReadDirectory), and a credential per person per scenario. A machine feature needs no step code. What the machines do not cover goes in specs under specs/, which derivation does not read, with the few steps the lexicon's phrases do not read registered beside the bindings.

Nothing runs a feature through a page yet. A page's browser tests are written by hand, as the CheckIn sample's CheckInPageTests are: a gate agent and three passengers on pages of their own, telling the same story as the features. Nothing checks that they still do when a scenario changes.

What features cannot say yet

Some designs need something the lexicon has no word for. Each of these is a limit of what is served today:

  • A policy carries no data. A policy fires a trigger with no input on the instances it reaches, so a value in the moving instance's context does not travel with it. Put the value where the target can read it, or have a train write it.
  • A view does not show a timer's dueAt. A view's field is a state or a context field. A user's own instance carries dueAt on its machine's get and push (Machines root), but a system machine read through a view does not, so a page cannot count down to its timer on the server's clock.
  • The server has no supported read of other users' instances. A view shows the caller's own instances and the system's. IMachineInstances starts and moves system instances, and the operations service lists instances by machine and state without their context or owner. A train that needs every user's instances (to score every answer, say) reads the snapshot table through IDataContext.SnapshotDrafts itself, and is then tied to how the features name machines, states and fields: renaming one in the lexicon breaks the train, and derivation does not notice.

SDK Reference

Lexicon | Feature machines | Feature bindings | AddStateMachines