Tutorial

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-features
wrote access.txt
wrote glossary.json
wrote host.json
wrote order-return.ir.json

The 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 Customer is who counts as a customer.
  • start is there because Ada has a return, Describe and Send because Ada fills in and sends her own return, and read because a customer reads the returns they own.
  • view returns is there because Ada'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 Customer

SDK Reference

Write machines as features | Feature files | Feature machines | Feature bindings | AddStateMachines | Views root | trax CLI


Next: 14.5 The check