Feature machines
Package Trax.StateMachine.GherkinNamespace Trax.StateMachine.GherkinSource FeatureMachines.cs, Lexicon.cs
Trax.StateMachine.Gherkin reads a features directory's lexicon into its glossary, and
derives state machines from Gherkin features and that glossary: each machine's IR, the host file that says who may use
it, and the access report. trax machine from-gherkin, run, missing and diagram are
these calls (trax machine usage and explain are the CLI's own, with no call here), and a host serves what they write with
ServeFeatures. The files are in the
feature files reference, the how-to is
Write machines as features, and why it is so is
ADR 0058.
Members
| Member | Description |
|---|---|
Lexicon.ReadDirectory(directory, trains) | Reads the one lexicon in a features directory and returns its LexiconReading, or null when the directory has none. Two lexicons in one directory are a problem in the reading. See Lexicon. |
Lexicon.Read(path, text), Lexicon.Read(path, text, trains) | Reads a lexicon's text; path is what every problem names. Returns LexiconReading. |
LexiconReading | Glossary, the FeatureGlossary the lexicon elaborates to; Json, that glossary's canonical JSON, the glossary.json trax machine from-gherkin writes; Problems, each a FeatureProblem at its lexicon line. Succeeded is true when there is a glossary, and only then are Glossary and Json set. GlossaryOrThrow() returns the glossary, or throws a FormatException listing each problem at its line. |
FeatureGlossary.Read(string json) | Reads a glossary's JSON, for features not yet written with a lexicon. A text that is not one throws a FormatException naming the key. |
FeatureFile | One feature file: its Path, as provenance and every problem names it, and its Text. |
FeatureMachines.Derive(glossary, features) | Derives every machine the features use, then replays every scenario on what it derived, access included. Returns DerivedMachines. |
DerivedMachines | Irs, one IR per machine by id; Host, the host file; Access, the access report; Problems, what stopped it, each a FeatureProblem; UiSteps, the Thens about the UI that derivation does not read; Warnings, designs that derive and may still not hold on the host, such as a policy that waits for another policy's result, each a FeatureProblem. A warning stops nothing. Succeeded is true when there is no problem, and only then are the files set. |
FeatureProblem | A File, a Line and a Message. |
FeatureMachines.Run(glossary, features, irs, host, options) | Runs the features in memory on machines, given as their IRs by id and their host file. Each answer is the host's, access included: a trigger the host does not serve the caller is not served, another owner's instance is NOT_FOUND, and a caller the rule does not admit is FORBIDDEN. Each scenario runs on fresh instances. The IRs and the host file are checked as a host checks them before any scenario runs: an IR that is not JSON, a machine of one missing from the other, a name the host file gives that its IR lacks, or an IR the host file was not derived from throws a FormatException, as does a tag expression that is not one; a name pattern that is not a regular expression throws an ArgumentException. An overload takes the DerivedMachines of Derive and throws an ArgumentException when it did not succeed. Returns FeatureRunReport. |
FeatureRunOptions | Tags, a Cucumber tag expression (@smoke and not @slow); Names, regular expressions any of which a scenario's name matches; Locations, file and line pairs; DryRun, read every step and run none; FailFast, stop at the first scenario that does not pass. |
FeatureRunReport | Scenarios, in file and line order, each a FeatureScenarioResult, and Problems, files that could not be read. Passed is true when there is no problem and every scenario passed, or was skipped as one only the host runs (@host). |
FeatureScenarioResult | A scenario's File, Line, Name, Tags, Status and Steps, each a FeatureStepResult with its Line, Keyword, Text, Status and Message, why it failed or was skipped. |
FeatureStatus | Passed, Failed, Undefined (a Given or When derivation cannot read) and Skipped (after a failure, in a dry run, a step about the UI, or a scenario tagged @host). |
FeatureMachines.Missing(glossary, features) | What the glossary names and no scenario shows, each a FeatureGap: its Kind (machine, trigger, state, guard, refusal, outcome, view or grant), the Machine, What it is, a Message, and a Stub, a scenario to paste, or null when none can be written. A stub is offered only if the features with it pasted derive with no problem and change only what it claims. |
FeatureMachines.Board(irs, host) | The event-storming board, from the IRs and the host file alone: a FeatureBoard of Stickies and Links. A FeatureSticky has an Id, a Kind (actor, command, event, policy, aggregate or view), its Machine, a Label, and the Scenarios behind it, each a FeatureScenarioRef (File, Line, Scenario) when the host file has provenance. A FeatureLink goes From one sticky's id To another's. The files are checked as Run checks them, and refused with the same FormatException. |
Lexicon
Lexicon reads the file people write to say what their features' words mean
(the lexicon reference) and elaborates it to the glossary the calls below take.
| Member | Description |
|---|---|
Extension | ".lexicon". |
Read(string path, string text) | Reads a lexicon. Each train's output fields come from its Returns: line, and its input fields from its Takes: and Input: lines. |
Read(string path, string text, IEnumerable<Assembly> trains) | Reads a lexicon, finding each train it runs in trains by its full name and reading its input and output records as the host does. Returns: and Takes: lines are then optional, and one that disagrees with the record is a problem at its line. |
ReadDirectory(string directory, IEnumerable<Assembly>? trains = null) | The one *.lexicon in directory, read, with the trains when they are given; null when there is none. A second lexicon is a problem. |
Nothing is read in part: a lexicon with any problem gives no glossary, and every problem, including those the glossary reader finds in what the lexicon elaborated to, names the lexicon line that wrote the key.
The C# a host binds
A lexicon names the C# behind a machine by its full name, and derivation writes those names to the host file, never
to the IR (see the feature files reference). A host serving the
directory finds each type in the assemblies given to ServeFeatures, as it finds the trains, and refuses the host
when one is missing, of the wrong kind, or does not pair one for one with what the IR names. The three handler kinds
are interfaces of Trax.StateMachine, each created once with its public parameterless constructor, so each answers
from its arguments alone:
| Interface | Member | Bound as |
|---|---|---|
ICustomRule | bool Holds(JsonObject context, JsonNode? input) | the handler of a custom rule, as CustomGuard binds one |
ICustomReduction | JsonObject Reduce(JsonObject context, JsonNode? input) | the handler of a custom reduction, as CustomReducer binds one |
IMachineMigration | MigrationResult Migrate(string state, JsonObject context) | the step from one version to the next, as MigrateFrom registers one |
A run-once effect is an interface extending ISnapshotEffect, resolved from the host's services when a send runs it,
as RunsOnce<TEffect> binds one.
Example
var lexicon = Lexicon.ReadDirectory("features", [typeof(ITakePaymentTrain).Assembly])!;
var glossary = lexicon.GlossaryOrThrow();
FeatureFile[] features = [new("ordering.feature", File.ReadAllText("features/ordering.feature"))];
var derived = FeatureMachines.Derive(glossary, features);
if (!derived.Succeeded)
foreach (var problem in derived.Problems)
Console.Error.WriteLine(problem);
var report = FeatureMachines.Run(glossary, features, derived, new FeatureRunOptions { Tags = "@smoke" });