14.4 Derive the machine
trax machine from-gherkin reads the feature and the lexicon and writes the machine. It came with
the tool installed in chapter 12. From the solution folder:
dotnet trax machine from-gherkin --features features --out machines/from-featureswrote access.txt
wrote glossary.json
wrote host.json
wrote order-return.ir.jsonThe tool owns the folder it writes to and removes a machine that no longer derives, so it gets one
of its own beside checkout's machines/checkout. Before it writes anything it replays every
scenario on what it derived and fails on one that does not pass. Two scenarios that disagree, a
Given or When it cannot read, or a feature that would derive a machine the hub refuses, are
reported with the file and the line, and nothing is written.
glossary.json is the lexicon elaborated: every word it gave, and what it left to a rule written
out, such as the context fields Sets: implied and each outcome's example. It is derived like the
rest of the folder, never edited.
machines/from-features/glossary.json:
{
"version": 1,
"actors": {
"customer": {
"noun": "a customer",
"roles": [
"Customer"
]
}
},
"machines": {
"order-return": {
"ownedBy": "customer",
"noun": "return",
"start": "has a return",
"initial": "Draft",
"context": [
{
"name": "orderId",
"type": "string",
"nullable": false,
"constraints": []
},
{
"name": "reason",
"type": "string",
"nullable": false,
"constraints": []
}
],
"states": {
"Draft": "is a draft",
"Checking": "is being checked",
"Accepted": "is accepted",
"Refused": "was refused",
"Unchecked": "could not be checked"
},
"triggers": {
"Describe": {
"phrase": "fills in {subject} for order {orderId} because {reason}",
"input": [
{
"name": "orderId",
"type": "string",
"nullable": false,
"constraints": []
},
{
"name": "reason",
"type": "string",
"nullable": false,
"constraints": []
}
],
"reduce": {
"reduce": "set",
"steps": [
{
"field": "orderId",
"value": {
"input": "orderId"
}
},
{
"field": "reason",
"value": {
"input": "reason"
}
}
]
}
},
"Send": {
"phrase": "sends {subject}"
}
},
"guards": {
"hasReason": {
"holds": "has a reason",
"fails": "has no reason",
"rule": {
"rule": "nonEmpty",
"source": "context",
"field": "reason"
}
}
},
"invokes": {
"Checking": {
"train": "Shopfront.Trains.ReturnOrder.IReturnOrderTrain",
"input": {
"orderId": "orderId",
"customerId": "$owner"
},
"output": [
{
"name": "accepted",
"type": "boolean",
"nullable": false,
"constraints": []
}
],
"outcomes": {
"the return is accepted": {
"outcome": "done",
"when": {
"rule": "boolEquals",
"source": "input",
"field": "accepted",
"value": true
}
},
"the return is refused": {
"outcome": "done",
"when": {
"rule": "boolEquals",
"source": "input",
"field": "accepted",
"value": false
}
},
"the return cannot be checked": {
"outcome": "failed"
},
"the return is called off": {
"outcome": "cancelled"
}
},
"examples": {
"the return is accepted": {
"accepted": true
},
"the return is refused": {
"accepted": false
}
}
}
}
}
},
"views": {
"returns": {
"reads": [
{
"machine": "order-return"
}
],
"fields": {
"status": {
"from": "order-return.state",
"labels": {
"Draft": "Not sent",
"Checking": "Being checked",
"Accepted": "Accepted",
"Refused": "Refused",
"Unchecked": "Not checked yet"
}
},
"reason": {
"from": "order-return.reason"
}
}
}
}
}Commit the folder. access.txt is the part to read in review:
@customer: roles Customer
order-return Describe: customer
order-return Send: customer
order-return read: customer
order-return start: customer
view returns: customer@customer: roles Customeris who counts as a customer.startis there becauseAda has a return,DescribeandSendbecause Ada fills in and sends her own return, andreadbecause a customer reads the returns they own.view returnsis there becauseAda's returns show ....
Each line is a grant a scenario showed. A grant added to a feature is a new line in this file in
the same pull request, and a word changed in the lexicon is a change to glossary.json. dotnet trax machine from-gherkin --features features --out machines/from-features --check writes nothing and fails when a committed file is stale, and is the
step to run in CI.
When a scenario does not derive what was meant, explain prints what derivation read from it:
dotnet trax machine explain --features features --scenario "no reason"returns.feature:20 A return with no reason is refused
grant: order-return Send is served to Customer
guard: order-return Send from Draft moves when its guard holds and is refused when it fails
start: order-return is started by CustomerSDK Reference
Write machines as features | Feature files | Feature machines | Feature bindings | AddStateMachines | Views root | trax CLI
Next: 14.5 The check