@reventlessdev/reventless-gwt 1.0.0-alpha.247 → 1.0.0-alpha.248

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 1.0.0-alpha.248 (2026-10-19)
+
+### Features
+
+* **gwt:** record behaviour scenarios as they run, for suites whose source names none ([256b253](https://github.com/ReventlessDev/reventless-core/commit/256b253153ec043105c38ac742a1a3efbde48c87))
+
+
 # 1.0.0-alpha.247 (2026-10-17)
 
 **Note:** Version bump only for package @reventlessdev/reventless-gwt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-gwt",
-  "version": "1.0.0-alpha.247",
+  "version": "1.0.0-alpha.248",
   "description": "Given-When-Then DSLs and test harness for Reventless slice testing",
   "license": "Apache-2.0",
   "jest": {
@@ -15,11 +15,11 @@
   "dependencies": {
     "sury": "11.0.0",
     "@reventlessdev/rescript-effect": "1.0.0-alpha.0",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.22",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.299",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.196",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.300",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.12",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.168"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.197",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.22",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.169"
   },
   "devDependencies": {
     "rescript": "12.3.1",

package/src/Behavior_GWT.res

@@ -443,7 +443,10 @@ module Make = (Spec: BehaviorSpec, Behavior: Behavior with module Spec := Spec):
 
   let describe = JestBind.describe
   let todo = JestBind.todo
-  let test = (name, body) => JestBind.test(~slice=Spec.name, name, body)
+  let test = (name, body) =>
+    JestBind.test(~slice=Spec.name, name, () =>
+      ScenarioRecorder.around(~spec=Spec.name, name, body)
+    )
 
   let currentState = consumed => consumed->Array.reduce(Behavior.initialState, Behavior.evolve)
 
@@ -614,7 +617,27 @@ module Make = (Spec: BehaviorSpec, Behavior: Behavior with module Spec := Spec):
   }
 
   let givenEvents = consumed => consumed
-  let whenCmd = (history, cmd) => history->exec(cmd)
+  let whenCmd = (history, cmd) => {
+    if ScenarioRecorder.recording() {
+      ScenarioRecorder.given(
+        history->Array.map(e =>
+          e->Message.encode(Spec.consumedEventSchema)->Message.variantNameOfJson
+        ),
+      )
+      ScenarioRecorder.whenCommand(Guard.commandName(cmd))
+    }
+    history->exec(cmd)
+  }
+  // What a test expects, named for the recorded sidecar.
+  let expects = (~events=[], ~error=?) =>
+    if ScenarioRecorder.recording() {
+      ScenarioRecorder.thenEvents(
+        events->Array.map(e => e->Core.encEvent->Message.variantNameOfJson),
+      )
+      error->Option.forEach(err =>
+        ScenarioRecorder.thenError(err->Core.encError->Message.variantNameOfJson)
+      )
+    }
 
   let checkAppendCondition = (): option<Outcome.outcome> =>
     switch appendConditionFailure.contents {
@@ -631,37 +654,49 @@ module Make = (Spec: BehaviorSpec, Behavior: Behavior with module Spec := Spec):
 
   // The append-condition footgun is surfaced before the shared comparison core
   // runs; `thenAppends*` below bypass it deliberately.
-  let thenEvents = (events, expectedEvents) =>
+  let thenEvents = (events, expectedEvents) => {
+    expects(~events=expectedEvents)
     switch checkAppendCondition() {
     | Some(o) => o
     | None => Core.compareEvents(events, expectedEvents)
     }
+  }
 
   let thenEvent = (events, expectedEvent) => thenEvents(events, [expectedEvent])
 
-  let thenNoEvent = events =>
+  let thenNoEvent = events => {
+    if ScenarioRecorder.recording() {
+      ScenarioRecorder.thenNoEvent()
+    }
     switch checkAppendCondition() {
     | Some(o) => o
     | None => Core.compareNoEvent(events)
     }
+  }
 
-  let thenError = (events, expectedError) =>
+  let thenError = (events, expectedError) => {
+    expects(~error=expectedError)
     switch checkAppendCondition() {
     | Some(o) => o
     | None => Core.matchesError(events, [], expectedError)
     }
+  }
 
-  let thenEventWithError = (events, expectedEvent, expectedError) =>
+  let thenEventWithError = (events, expectedEvent, expectedError) => {
+    expects(~events=[expectedEvent], ~error=expectedError)
     switch checkAppendCondition() {
     | Some(o) => o
     | None => Core.matchesError(events, [expectedEvent], expectedError)
     }
+  }
 
-  let thenEventsWithError = (events, expectedEvents, expectedError) =>
+  let thenEventsWithError = (events, expectedEvents, expectedError) => {
+    expects(~events=expectedEvents, ~error=expectedError)
     switch checkAppendCondition() {
     | Some(o) => o
     | None => Core.matchesError(events, expectedEvents, expectedError)
     }
+  }
 
   let thenAppendsConditionedOn = (_events, expectedQuery: Reventless.DcbTag.query) =>
     switch derivedCondition.contents {
@@ -773,7 +808,10 @@ module MakeFromAggregate = (Spec: AggregateSpec, Behavior: Behavior.T with modul
   module Spec = Spec
 
   let describe = JestBind.describe
-  let test = (name, body) => JestBind.test(~slice=Spec.name, name, body)
+  let test = (name, body) =>
+    JestBind.test(~slice=Spec.name, name, () =>
+      ScenarioRecorder.around(~spec=Spec.name, name, body)
+    )
 
   let currentState = events => events->Array.reduce(Behavior.initialState, Behavior.evolve)
 
@@ -809,7 +847,23 @@ module MakeFromAggregate = (Spec: AggregateSpec, Behavior: Behavior.T with modul
   }
 
   let givenEvents = events => events
-  let whenCmd = (history, cmd) => history->exec(cmd)
+  let whenCmd = (history, cmd) => {
+    if ScenarioRecorder.recording() {
+      ScenarioRecorder.given(history->Array.map(e => e->Core.encEvent->Message.variantNameOfJson))
+      ScenarioRecorder.whenCommand(Guard.commandName(cmd))
+    }
+    history->exec(cmd)
+  }
+  // What a test expects, named for the recorded sidecar.
+  let expects = (~events=[], ~error=?) =>
+    if ScenarioRecorder.recording() {
+      ScenarioRecorder.thenEvents(
+        events->Array.map(e => e->Core.encEvent->Message.variantNameOfJson),
+      )
+      error->Option.forEach(err =>
+        ScenarioRecorder.thenError(err->Core.encError->Message.variantNameOfJson)
+      )
+    }
 
   // The aggregate flavour has no append-condition footgun, so the shared core's
   // comparisons are exposed directly once a refusal has been ruled out; only
@@ -819,22 +873,38 @@ module MakeFromAggregate = (Spec: AggregateSpec, Behavior: Behavior.T with modul
     | Some(o) => o
     | None => compare(events)
     }
-  let thenEvents = (events, expected) => events->unlessRefused(Core.compareEvents(_, expected))
-  let thenCompareEvents = (events, expected, cmp) =>
+  let thenEvents = (events, expected) => {
+    expects(~events=expected)
+    events->unlessRefused(Core.compareEvents(_, expected))
+  }
+  let thenCompareEvents = (events, expected, cmp) => {
+    expects(~events=expected)
     events->unlessRefused(Core.compareEventsWith(_, expected, cmp))
+  }
   let thenEvent = (events, expectedEvent) => thenEvents(events, [expectedEvent])
   let thenCompareEvent = (events, expectedEvent, cmp) =>
     thenCompareEvents(events, [expectedEvent], cmp)
-  let thenNoEvent = events => events->unlessRefused(Core.compareNoEvent)
+  let thenNoEvent = events => {
+    if ScenarioRecorder.recording() {
+      ScenarioRecorder.thenNoEvent()
+    }
+    events->unlessRefused(Core.compareNoEvent)
+  }
 
-  let thenError = (events, expectedError) =>
+  let thenError = (events, expectedError) => {
+    expects(~error=expectedError)
     events->unlessRefused(Core.matchesError(_, [], expectedError))
+  }
 
-  let thenEventWithError = (events, expectedEvent, expectedError) =>
+  let thenEventWithError = (events, expectedEvent, expectedError) => {
+    expects(~events=[expectedEvent], ~error=expectedError)
     events->unlessRefused(Core.matchesError(_, [expectedEvent], expectedError))
+  }
 
-  let thenEventsWithError = (events, expectedEvents, expectedError) =>
+  let thenEventsWithError = (events, expectedEvents, expectedError) => {
+    expects(~events=expectedEvents, ~error=expectedError)
     events->unlessRefused(Core.matchesError(_, expectedEvents, expectedError))
+  }
 
   let thenRefused = events =>
     Guard.thenRefused(

package/src/Behavior_GWT.res.mjs

@@ -15,6 +15,7 @@ import * as JestBind$ReventlessGwt from "./JestBind.res.mjs";
 import * as Message$ReventlessCore from "@reventlessdev/reventless-core/src/Message.res.mjs";
 import * as Authorization$Reventless from "@reventlessdev/reventless-spec/src/types/Authorization.res.mjs";
 import * as DcbScopeInference$Reventless from "@reventlessdev/reventless-spec/src/components/DcbScopeInference.res.mjs";
+import * as ScenarioRecorder$ReventlessGwt from "./ScenarioRecorder.res.mjs";
 import * as CommandTopic_Helpers$ReventlessCore from "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic_Helpers.res.mjs";
 
 function roleNames(roles) {
@@ -317,7 +318,7 @@ function AssertionCore(Spec) {
 
 function Make(Spec) {
   return Behavior => {
-    let test = (name, body) => JestBind$ReventlessGwt.test(Spec.name, name, body);
+    let test = (name, body) => JestBind$ReventlessGwt.test(Spec.name, name, () => ScenarioRecorder$ReventlessGwt.around(Spec.name, name, body));
     let errors = {
       contents: []
     };
@@ -494,6 +495,10 @@ function Make(Spec) {
     let queryTagsTotal = q => Stdlib_Array.reduce(q, 0, (acc, qi) => acc + Stdlib_Option.mapOr(qi.tags, 0, t => t.length) | 0);
     let givenEvents = consumed => consumed;
     let whenCmd = (history, cmd) => {
+      if (ScenarioRecorder$ReventlessGwt.recording()) {
+        ScenarioRecorder$ReventlessGwt.given(history.map(e => Message$ReventlessCore.variantNameOfJson(Message$ReventlessCore.encode(e, Spec.consumedEventSchema))));
+        ScenarioRecorder$ReventlessGwt.whenCommand(Message$ReventlessCore.variantNameOfJson(Message$ReventlessCore.encode(cmd, commandSchema)));
+      }
       errors.contents = [];
       appendConditionFailure.contents = undefined;
       let query = DcbTag$Reventless.buildQueryFromCommand(consumedEventTypes, Spec.commandSchema, cmd, tagKeysByEventType, crossPartitionTagKeys, payloadTagKeys);
@@ -529,6 +534,13 @@ function Make(Spec) {
       errors.contents = [events._0];
       return [];
     };
+    let expects = (eventsOpt, error) => {
+      let events = eventsOpt !== undefined ? eventsOpt : [];
+      if (ScenarioRecorder$ReventlessGwt.recording()) {
+        ScenarioRecorder$ReventlessGwt.thenEvents(events.map(e => Message$ReventlessCore.variantNameOfJson(Message$ReventlessCore.encode(e, Spec.eventSchema))));
+        return Stdlib_Option.forEach(error, err => ScenarioRecorder$ReventlessGwt.thenError(Message$ReventlessCore.variantNameOfJson(Message$ReventlessCore.encode(err, Spec.errorSchema))));
+      }
+    };
     let checkAppendCondition = () => {
       let m = appendConditionFailure.contents;
       if (m !== undefined) {
@@ -555,6 +567,7 @@ function Make(Spec) {
       }
     };
     let thenEvents = (events, expectedEvents) => {
+      expects(expectedEvents, undefined);
       let o = checkAppendCondition();
       if (o !== undefined) {
         return o;
@@ -572,6 +585,9 @@ function Make(Spec) {
     };
     let thenEvent = (events, expectedEvent) => thenEvents(events, [expectedEvent]);
     let thenNoEvent = events => {
+      if (ScenarioRecorder$ReventlessGwt.recording()) {
+        ScenarioRecorder$ReventlessGwt.thenNoEvent();
+      }
       let o = checkAppendCondition();
       if (o !== undefined) {
         return o;
@@ -587,6 +603,7 @@ function Make(Spec) {
       }
     };
     let thenError = (events, expectedError) => {
+      expects(undefined, Primitive_option.some(expectedError));
       let o = checkAppendCondition();
       if (o !== undefined) {
         return o;
@@ -595,6 +612,7 @@ function Make(Spec) {
       }
     };
     let thenEventWithError = (events, expectedEvent, expectedError) => {
+      expects([expectedEvent], Primitive_option.some(expectedError));
       let o = checkAppendCondition();
       if (o !== undefined) {
         return o;
@@ -603,6 +621,7 @@ function Make(Spec) {
       }
     };
     let thenEventsWithError = (events, expectedEvents, expectedError) => {
+      expects(expectedEvents, Primitive_option.some(expectedError));
       let o = checkAppendCondition();
       if (o !== undefined) {
         return o;
@@ -676,7 +695,7 @@ function Make(Spec) {
 
 function MakeFromAggregate(Spec) {
   return Behavior => {
-    let test = (name, body) => JestBind$ReventlessGwt.test(Spec.name, name, body);
+    let test = (name, body) => JestBind$ReventlessGwt.test(Spec.name, name, () => ScenarioRecorder$ReventlessGwt.around(Spec.name, name, body));
     let errors = {
       contents: []
     };
@@ -810,6 +829,10 @@ function MakeFromAggregate(Spec) {
     }));
     let givenEvents = events => events;
     let whenCmd = (history, cmd) => {
+      if (ScenarioRecorder$ReventlessGwt.recording()) {
+        ScenarioRecorder$ReventlessGwt.given(history.map(e => Message$ReventlessCore.variantNameOfJson(Message$ReventlessCore.encode(e, Spec.eventSchema))));
+        ScenarioRecorder$ReventlessGwt.whenCommand(Message$ReventlessCore.variantNameOfJson(Message$ReventlessCore.encode(cmd, commandSchema)));
+      }
       errors.contents = [];
       if (refuses(history, cmd)) {
         return [];
@@ -821,6 +844,13 @@ function MakeFromAggregate(Spec) {
       errors.contents = [events._0];
       return [];
     };
+    let expects = (eventsOpt, error) => {
+      let events = eventsOpt !== undefined ? eventsOpt : [];
+      if (ScenarioRecorder$ReventlessGwt.recording()) {
+        ScenarioRecorder$ReventlessGwt.thenEvents(events.map(e => Message$ReventlessCore.variantNameOfJson(Message$ReventlessCore.encode(e, Spec.eventSchema))));
+        return Stdlib_Option.forEach(error, err => ScenarioRecorder$ReventlessGwt.thenError(Message$ReventlessCore.variantNameOfJson(Message$ReventlessCore.encode(err, Spec.errorSchema))));
+      }
+    };
     let unlessRefused = (events, compare) => {
       let o = unexpectedRefusal();
       if (o !== undefined) {
@@ -829,38 +859,58 @@ function MakeFromAggregate(Spec) {
         return compare(events);
       }
     };
-    let thenEvents = (events, expected) => unlessRefused(events, __x => {
-      if (errors.contents.length !== 0) {
-        return unexpectedError(__x);
-      } else if (Primitive_object.equal(__x.map(encEvent), expected.map(encEvent))) {
-        return Outcome$ReventlessGwt.pass;
-      } else {
-        return Outcome$ReventlessGwt.fail({
-          TAG: "EventsMismatch",
-          expected: expected.map(encEvent),
-          actual: __x.map(encEvent)
-        });
-      }
-    });
-    let thenCompareEvents = (events, expected, cmp) => unlessRefused(events, __x => {
-      if (errors.contents.length !== 0) {
-        return unexpectedError(__x);
-      } else if (__x.length === expected.length && Stdlib_Array.zip(__x, expected).every(param => cmp(param[0], param[1]))) {
-        return Outcome$ReventlessGwt.pass;
-      } else {
-        return Outcome$ReventlessGwt.fail({
-          TAG: "EventsMismatch",
-          expected: expected.map(encEvent),
-          actual: __x.map(encEvent)
-        });
-      }
-    });
+    let thenEvents = (events, expected) => {
+      expects(expected, undefined);
+      return unlessRefused(events, __x => {
+        if (errors.contents.length !== 0) {
+          return unexpectedError(__x);
+        } else if (Primitive_object.equal(__x.map(encEvent), expected.map(encEvent))) {
+          return Outcome$ReventlessGwt.pass;
+        } else {
+          return Outcome$ReventlessGwt.fail({
+            TAG: "EventsMismatch",
+            expected: expected.map(encEvent),
+            actual: __x.map(encEvent)
+          });
+        }
+      });
+    };
+    let thenCompareEvents = (events, expected, cmp) => {
+      expects(expected, undefined);
+      return unlessRefused(events, __x => {
+        if (errors.contents.length !== 0) {
+          return unexpectedError(__x);
+        } else if (__x.length === expected.length && Stdlib_Array.zip(__x, expected).every(param => cmp(param[0], param[1]))) {
+          return Outcome$ReventlessGwt.pass;
+        } else {
+          return Outcome$ReventlessGwt.fail({
+            TAG: "EventsMismatch",
+            expected: expected.map(encEvent),
+            actual: __x.map(encEvent)
+          });
+        }
+      });
+    };
     let thenEvent = (events, expectedEvent) => thenEvents(events, [expectedEvent]);
     let thenCompareEvent = (events, expectedEvent, cmp) => thenCompareEvents(events, [expectedEvent], cmp);
-    let thenNoEvent = events => unlessRefused(events, compareNoEvent);
-    let thenError = (events, expectedError) => unlessRefused(events, __x => matchesError(__x, [], expectedError));
-    let thenEventWithError = (events, expectedEvent, expectedError) => unlessRefused(events, __x => matchesError(__x, [expectedEvent], expectedError));
-    let thenEventsWithError = (events, expectedEvents, expectedError) => unlessRefused(events, __x => matchesError(__x, expectedEvents, expectedError));
+    let thenNoEvent = events => {
+      if (ScenarioRecorder$ReventlessGwt.recording()) {
+        ScenarioRecorder$ReventlessGwt.thenNoEvent();
+      }
+      return unlessRefused(events, compareNoEvent);
+    };
+    let thenError = (events, expectedError) => {
+      expects(undefined, Primitive_option.some(expectedError));
+      return unlessRefused(events, __x => matchesError(__x, [], expectedError));
+    };
+    let thenEventWithError = (events, expectedEvent, expectedError) => {
+      expects([expectedEvent], Primitive_option.some(expectedError));
+      return unlessRefused(events, __x => matchesError(__x, [expectedEvent], expectedError));
+    };
+    let thenEventsWithError = (events, expectedEvents, expectedError) => {
+      expects(expectedEvents, Primitive_option.some(expectedError));
+      return unlessRefused(events, __x => matchesError(__x, expectedEvents, expectedError));
+    };
     let thenRefused = events => {
       let decided = Stdlib_Option.map(errors.contents[0], encError);
       let match = refusal.contents;

package/src/ScenarioRecorder.res

@@ -0,0 +1,182 @@
+// Behaviour scenarios as they run, written as sidecars `check-lifecycle` reads.
+//
+// The PPX writes a `.gwt.json` sidecar from a `_GWT.res` file's source, so it can only name what
+// the source spells out: a literal constructor in a step. A suite written against a binding (a
+// trait's conformance suite, whose `B.request(…)` is whatever the host's binding builds) names
+// nothing in its source, and the host's file that registers it has no `describe` of its own, so
+// no sidecar is written and `check-lifecycle` sees none of its scenarios. The run has the values,
+// and the spec's schemas name them; this records them.
+//
+// Only with `REVENTLESS_EMIT_SIDECAR` set in the test process, the switch the PPX reads at build
+// time; otherwise every call is a no-op. A test file whose sidecar the PPX wrote is left alone:
+// read from source, it carries values and ids a run cannot.
+
+type entry = {kind: string, element: string}
+
+type scenario = {
+  title: string,
+  given: array<entry>,
+  when_: array<entry>,
+  then_: array<entry>,
+}
+
+let enabled = () =>
+  switch NodeProcess.env->Dict.get("REVENTLESS_EMIT_SIDECAR") {
+  | Some("1" | "true" | "TRUE") => true
+  | _ => false
+  }
+
+// The scenario of the test running now, if one is being recorded.
+let current: ref<option<scenario>> = ref(None)
+
+// The test file an external runner says it is running; Jest says it itself.
+let fileOverride: ref<option<string>> = ref(None)
+
+/** Names the test file an external runner (registered through `RunnerHook`) is about to run, so
+    what its tests record lands beside it. */
+let setFile = (path: string) => fileOverride := Some(path)
+
+// The running test's file under Jest, while a test runs.
+let jestTestPath: unit => option<string> = %raw(`function () {
+  try {
+    const state = globalThis.expect && globalThis.expect.getState && globalThis.expect.getState();
+    return state && typeof state.testPath === "string" ? state.testPath : undefined;
+  } catch (_) { return undefined; }
+}`)
+
+let testFile = () =>
+  switch fileOverride.contents {
+  | Some(f) => Some(f)
+  | None => jestTestPath()
+  }
+
+// What has been recorded in this process, per sidecar path: the spec it names and its scenarios.
+let recorded: Map.t<string, (string, array<scenario>)> = Map.make()
+
+// Per test file, the specs recorded from it in order, the first owning `<File>_GWT.gwt.json`.
+let specsOf: Map.t<string, array<string>> = Map.make()
+
+// Sidecar paths found written by the PPX: never written over.
+let foreign: Set.t<string> = Set.make()
+
+// `…/X_GWT.res.mjs` (or `.res`, `.mjs`, `.js`) → `…/X_GWT`.
+let baseOf = (file: string) =>
+  [".res.mjs", ".res.js", ".res", ".mjs", ".js"]->Array.reduce(file, (f, ext) =>
+    f->String.endsWith(ext)
+      ? f->String.slice(~start=0, ~end=String.length(f) - String.length(ext))
+      : f
+  )
+
+let sidecarFor = (~file: string, ~spec: string) => {
+  let specs = specsOf->Map.get(file)->Option.getOr([])
+  if !(specs->Array.includes(spec)) {
+    specs->Array.push(spec)
+    specsOf->Map.set(file, specs)
+  }
+  specs->Array.indexOf(spec) == 0 ? `${baseOf(file)}.gwt.json` : `${baseOf(file)}.${spec}.gwt.json`
+}
+
+// Whether a sidecar at `path` is the PPX's: present and not marked recorded.
+let writtenByPpx = (path: string) =>
+  switch NodeFs.existsSync(path) {
+  | false => false
+  | true =>
+    switch NodeFs.readFileSync(path)->JSON.parseOrThrow {
+    | Object(d) => d->Dict.get("recorded") != Some(Boolean(true))
+    | _ => true
+    | exception _ => true
+    }
+  }
+
+let entryJson = (e: entry) => JSON.Object(
+  Dict.fromArray([
+    ("kind", JSON.String(e.kind)),
+    ("element", JSON.String(e.element)),
+    ("values", JSON.Array([])),
+  ]),
+)
+
+let write = (~path: string, ~file: string, ~spec: string, scenarios: array<scenario>) => {
+  let json = JSON.Object(
+    Dict.fromArray([
+      ("specName", JSON.String(`${spec} (recorded)`)),
+      // What `check-lifecycle` takes the file's component from.
+      ("stem", JSON.String(spec)),
+      ("file", JSON.String(file)),
+      ("componentKind", JSON.String("Behavior")),
+      ("recorded", JSON.Boolean(true)),
+      (
+        "scenarios",
+        JSON.Array(
+          scenarios->Array.map(s => JSON.Object(
+            Dict.fromArray([
+              ("title", JSON.String(s.title)),
+              ("given", JSON.Array(s.given->Array.map(entryJson))),
+              ("when", JSON.Array(s.when_->Array.map(entryJson))),
+              ("then", JSON.Array(s.then_->Array.map(entryJson))),
+            ]),
+          )),
+        ),
+      ),
+    ]),
+  )
+  NodeFs.writeFileSync(path, JSON.stringifyAny(json, ~space=2)->Option.getOr("{}") ++ "\n")
+}
+
+/** Runs one test's `body`, recording its steps when recording is on, and adds the scenario to
+    its file's sidecar. `spec` is the spec the test runs against, the component the sidecar names. */
+let around = (~spec: string, title: string, body: unit => 'outcome): 'outcome =>
+  if !enabled() {
+    body()
+  } else {
+    current := Some({title, given: [], when_: [], then_: []})
+    let finish = () => {
+      let scenario = current.contents
+      current := None
+      switch (scenario, testFile()) {
+      | (Some(s), Some(file)) =>
+        let path = sidecarFor(~file, ~spec)
+        if !(foreign->Set.has(path)) && !(recorded->Map.has(path)) && writtenByPpx(path) {
+          foreign->Set.add(path)
+        }
+        if !(foreign->Set.has(path)) {
+          let (_, scenarios) = recorded->Map.get(path)->Option.getOr((spec, []))
+          let scenarios = scenarios->Array.filter(o => o.title != s.title)->Array.concat([s])
+          recorded->Map.set(path, (spec, scenarios))
+          write(~path, ~file, ~spec, scenarios)
+        }
+      | _ => ()
+      }
+    }
+    switch body() {
+    | outcome =>
+      finish()
+      outcome
+    | exception e =>
+      finish()
+      throw(e)
+    }
+  }
+
+/** Whether a test is being recorded now: the steps name what they get only then. */
+let recording = () => current.contents->Option.isSome
+
+let push = (pick: scenario => array<entry>, entries: array<entry>) =>
+  current.contents->Option.forEach(s => entries->Array.forEach(e => pick(s)->Array.push(e)))
+
+/** The history a command is decided on, by event name. */
+let given = (names: array<string>) =>
+  push(s => s.given, names->Array.map(element => {kind: "event", element}))
+
+/** The command a test sends. */
+let whenCommand = (name: string) => push(s => s.when_, [{kind: "command", element: name}])
+
+/** What a test expects: these events. */
+let thenEvents = (names: array<string>) =>
+  push(s => s.then_, names->Array.map(element => {kind: "event", element}))
+
+/** What a test expects: this error. */
+let thenError = (name: string) => push(s => s.then_, [{kind: "error", element: name}])
+
+/** What a test expects: no event. */
+let thenNoEvent = () => push(s => s.then_, [{kind: "noEvent", element: ""}])

package/src/ScenarioRecorder.res.mjs

@@ -0,0 +1,287 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+
+function enabled() {
+  let match = process.env["REVENTLESS_EMIT_SIDECAR"];
+  if (match === undefined) {
+    return false;
+  }
+  switch (match) {
+    case "1" :
+    case "TRUE" :
+    case "true" :
+      return true;
+    default:
+      return false;
+  }
+}
+
+let current = {
+  contents: undefined
+};
+
+let fileOverride = {
+  contents: undefined
+};
+
+function setFile(path) {
+  fileOverride.contents = path;
+}
+
+let jestTestPath = (function () {
+  try {
+    const state = globalThis.expect && globalThis.expect.getState && globalThis.expect.getState();
+    return state && typeof state.testPath === "string" ? state.testPath : undefined;
+  } catch (_) { return undefined; }
+});
+
+function testFile() {
+  let f = fileOverride.contents;
+  if (f !== undefined) {
+    return f;
+  } else {
+    return jestTestPath();
+  }
+}
+
+let recorded = new Map();
+
+let specsOf = new Map();
+
+let foreign = new Set();
+
+function baseOf(file) {
+  return Stdlib_Array.reduce([
+    ".res.mjs",
+    ".res.js",
+    ".res",
+    ".mjs",
+    ".js"
+  ], file, (f, ext) => {
+    if (f.endsWith(ext)) {
+      return f.slice(0, f.length - ext.length | 0);
+    } else {
+      return f;
+    }
+  });
+}
+
+function sidecarFor(file, spec) {
+  let specs = Stdlib_Option.getOr(specsOf.get(file), []);
+  if (!specs.includes(spec)) {
+    specs.push(spec);
+    specsOf.set(file, specs);
+  }
+  if (specs.indexOf(spec) === 0) {
+    return baseOf(file) + `.gwt.json`;
+  } else {
+    return baseOf(file) + `.` + spec + `.gwt.json`;
+  }
+}
+
+function writtenByPpx(path) {
+  if (!Nodefs.existsSync(path)) {
+    return false;
+  }
+  let d;
+  try {
+    d = JSON.parse(Nodefs.readFileSync(path, "utf8"));
+  } catch (exn) {
+    return true;
+  }
+  if (typeof d === "object" && d !== null && !Array.isArray(d)) {
+    return Primitive_object.notequal(d["recorded"], true);
+  } else {
+    return true;
+  }
+}
+
+function entryJson(e) {
+  return Object.fromEntries([
+    [
+      "kind",
+      e.kind
+    ],
+    [
+      "element",
+      e.element
+    ],
+    [
+      "values",
+      []
+    ]
+  ]);
+}
+
+function write(path, file, spec, scenarios) {
+  let json = Object.fromEntries([
+    [
+      "specName",
+      spec + ` (recorded)`
+    ],
+    [
+      "stem",
+      spec
+    ],
+    [
+      "file",
+      file
+    ],
+    [
+      "componentKind",
+      "Behavior"
+    ],
+    [
+      "recorded",
+      true
+    ],
+    [
+      "scenarios",
+      scenarios.map(s => (Object.fromEntries([
+        [
+          "title",
+          s.title
+        ],
+        [
+          "given",
+          s.given.map(entryJson)
+        ],
+        [
+          "when",
+          s.when_.map(entryJson)
+        ],
+        [
+          "then",
+          s.then_.map(entryJson)
+        ]
+      ])))
+    ]
+  ]);
+  Nodefs.writeFileSync(path, Stdlib_Option.getOr(JSON.stringify(json, undefined, 2), "{}") + "\n", "utf8");
+}
+
+function around(spec, title, body) {
+  if (!enabled()) {
+    return body();
+  }
+  current.contents = {
+    title: title,
+    given: [],
+    when_: [],
+    then_: []
+  };
+  let finish = () => {
+    let scenario = current.contents;
+    current.contents = undefined;
+    let match = testFile();
+    if (scenario === undefined) {
+      return;
+    }
+    if (match === undefined) {
+      return;
+    }
+    let path = sidecarFor(match, spec);
+    if (!foreign.has(path) && !recorded.has(path) && writtenByPpx(path)) {
+      foreign.add(path);
+    }
+    if (foreign.has(path)) {
+      return;
+    }
+    let match$1 = Stdlib_Option.getOr(recorded.get(path), [
+      spec,
+      []
+    ]);
+    let scenarios = match$1[1].filter(o => o.title !== scenario.title).concat([scenario]);
+    recorded.set(path, [
+      spec,
+      scenarios
+    ]);
+    write(path, match, spec, scenarios);
+  };
+  let outcome;
+  try {
+    outcome = body();
+  } catch (e) {
+    finish();
+    throw e;
+  }
+  finish();
+  return outcome;
+}
+
+function recording() {
+  return Stdlib_Option.isSome(current.contents);
+}
+
+function push(pick, entries) {
+  Stdlib_Option.forEach(current.contents, s => {
+    entries.forEach(e => {
+      pick(s).push(e);
+    });
+  });
+}
+
+function given(names) {
+  push(s => s.given, names.map(element => ({
+    kind: "event",
+    element: element
+  })));
+}
+
+function whenCommand(name) {
+  push(s => s.when_, [{
+      kind: "command",
+      element: name
+    }]);
+}
+
+function thenEvents(names) {
+  push(s => s.then_, names.map(element => ({
+    kind: "event",
+    element: element
+  })));
+}
+
+function thenError(name) {
+  push(s => s.then_, [{
+      kind: "error",
+      element: name
+    }]);
+}
+
+function thenNoEvent() {
+  push(s => s.then_, [{
+      kind: "noEvent",
+      element: ""
+    }]);
+}
+
+export {
+  enabled,
+  current,
+  fileOverride,
+  setFile,
+  jestTestPath,
+  testFile,
+  recorded,
+  specsOf,
+  foreign,
+  baseOf,
+  sidecarFor,
+  writtenByPpx,
+  entryJson,
+  write,
+  around,
+  recording,
+  push,
+  given,
+  whenCommand,
+  thenEvents,
+  thenError,
+  thenNoEvent,
+}
+/* recorded Not a pure module */

package/tests/ScenarioRecorderTest.res

@@ -0,0 +1,101 @@
+open JestGlobals
+
+// `ScenarioRecorder` writes what a behaviour test runs as a sidecar `check-lifecycle` reads, for
+// a suite whose source names nothing (one written against a binding). Each case records into a
+// file of its own under the OS temp folder, named by `setFile` as an external runner would.
+
+let dir = NodeFs.mkdtempSync(NodePath.join([NodeOs.tmpdir(), "scenario-recorder-"]))
+let testFile = name => NodePath.join([dir, `${name}_GWT.res.mjs`])
+let sidecarOf = name => NodePath.join([dir, `${name}_GWT.gwt.json`])
+
+let read = path => NodeFs.readFileSync(path)->JSON.parseOrThrow
+
+let field = (json: JSON.t, key) =>
+  switch json {
+  | Object(d) => d->Dict.get(key)
+  | _ => None
+  }
+
+// One recorded test: the history, the command, and the event it expects.
+let run = (~spec, ~title, ~expects) =>
+  ScenarioRecorder.around(~spec, title, () => {
+    ScenarioRecorder.given(["CustomerRegistered"])
+    ScenarioRecorder.whenCommand("RequestNotification")
+    ScenarioRecorder.thenEvents([expects])
+  })
+
+let switched = (on, f) => {
+  NodeProcess.env->Dict.set("REVENTLESS_EMIT_SIDECAR", on ? "1" : "0")
+  let out = f()
+  NodeProcess.env->Dict.delete("REVENTLESS_EMIT_SIDECAR")
+  out
+}
+
+describe("ScenarioRecorder", () => {
+  testSync("with the switch off it writes nothing", () => {
+    ScenarioRecorder.setFile(testFile("Off"))
+    switched(false, () => run(~spec="Prefs", ~title="t", ~expects="NotificationRequested"))
+    expect(NodeFs.existsSync(sidecarOf("Off")))->toBe(false)
+  })
+
+  testSync("a test run with the switch on is a sidecar naming its spec as the component", () => {
+    ScenarioRecorder.setFile(testFile("Conformance"))
+    switched(
+      true,
+      () => {
+        run(~spec="Prefs", ~title="undeliverable", ~expects="NotificationUndeliverable")
+        run(~spec="Prefs", ~title="deferred", ~expects="NotificationDeferred")
+      },
+    )
+    let json = read(sidecarOf("Conformance"))
+    let scenarios = switch json->field("scenarios") {
+    | Some(Array(xs)) => xs
+    | _ => []
+    }
+    expect((
+      json->field("stem"),
+      json->field("recorded"),
+      scenarios->Array.map(
+        s =>
+          switch (s->field("when"), s->field("then")) {
+          | (Some(Array([w])), Some(Array([t]))) => (w->field("element"), t->field("element"))
+          | _ => (None, None)
+          },
+      ),
+    ))->toEqual((
+      Some(JSON.String("Prefs")),
+      Some(JSON.Boolean(true)),
+      [
+        (Some(JSON.String("RequestNotification")), Some(JSON.String("NotificationUndeliverable"))),
+        (Some(JSON.String("RequestNotification")), Some(JSON.String("NotificationDeferred"))),
+      ],
+    ))
+  })
+
+  testSync("a sidecar the PPX wrote is left as it is", () => {
+    let ppx = `{"stem":"Mine_GWT","scenarios":[]}`
+    NodeFs.writeFileSync(sidecarOf("Mine"), ppx)
+    ScenarioRecorder.setFile(testFile("Mine"))
+    switched(true, () => run(~spec="Prefs", ~title="t", ~expects="NotificationRequested"))
+    expect(NodeFs.readFileSync(sidecarOf("Mine")))->toBe(ppx)
+  })
+
+  testSync("a second spec in one file gets a sidecar of its own", () => {
+    ScenarioRecorder.setFile(testFile("Two"))
+    switched(
+      true,
+      () => {
+        run(~spec="Prefs", ~title="a", ~expects="NotificationRequested")
+        run(~spec="Claims", ~title="b", ~expects="NotificationSourceClaimed")
+      },
+    )
+    expect((
+      read(sidecarOf("Two"))->field("stem"),
+      read(NodePath.join([dir, "Two_GWT.Claims.gwt.json"]))->field("stem"),
+    ))->toEqual((Some(JSON.String("Prefs")), Some(JSON.String("Claims"))))
+  })
+
+  testSync("steps outside a recorded test record nothing", () =>
+    expect(ScenarioRecorder.recording())->toBe(false)
+  )
+})

package/tests/ScenarioRecorderTest.res.mjs

@@ -0,0 +1,163 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodeos from "node:os";
+import * as Nodepath from "node:path";
+import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
+import * as ScenarioRecorder$ReventlessGwt from "../src/ScenarioRecorder.res.mjs";
+
+let dir = Nodefs.mkdtempSync(Nodepath.join(Nodeos.tmpdir(), "scenario-recorder-"));
+
+function testFile(name) {
+  return Nodepath.join(dir, name + `_GWT.res.mjs`);
+}
+
+function sidecarOf(name) {
+  return Nodepath.join(dir, name + `_GWT.gwt.json`);
+}
+
+function read(path) {
+  return JSON.parse(Nodefs.readFileSync(path, "utf8"));
+}
+
+function field(json, key) {
+  if (typeof json === "object" && json !== null && !Array.isArray(json)) {
+    return json[key];
+  }
+}
+
+function run(spec, title, expects) {
+  ScenarioRecorder$ReventlessGwt.around(spec, title, () => {
+    ScenarioRecorder$ReventlessGwt.given(["CustomerRegistered"]);
+    ScenarioRecorder$ReventlessGwt.whenCommand("RequestNotification");
+    ScenarioRecorder$ReventlessGwt.thenEvents([expects]);
+  });
+}
+
+function switched(on, f) {
+  process.env["REVENTLESS_EMIT_SIDECAR"] = on ? "1" : "0";
+  let out = f();
+  Stdlib_Dict.$$delete(process.env, "REVENTLESS_EMIT_SIDECAR");
+  return out;
+}
+
+globalThis.describe("ScenarioRecorder", () => {
+  globalThis.test("with the switch off it writes nothing", () => {
+    ScenarioRecorder$ReventlessGwt.setFile(testFile("Off"));
+    switched(false, () => run("Prefs", "t", "NotificationRequested"));
+    globalThis.expect(Nodefs.existsSync(sidecarOf("Off"))).toBe(false);
+  });
+  globalThis.test("a test run with the switch on is a sidecar naming its spec as the component", () => {
+    ScenarioRecorder$ReventlessGwt.setFile(testFile("Conformance"));
+    switched(true, () => {
+      run("Prefs", "undeliverable", "NotificationUndeliverable");
+      run("Prefs", "deferred", "NotificationDeferred");
+    });
+    let path = sidecarOf("Conformance");
+    let json = JSON.parse(Nodefs.readFileSync(path, "utf8"));
+    let match = field(json, "scenarios");
+    let scenarios = match !== undefined ? (
+        Array.isArray(match) ? match : []
+      ) : [];
+    globalThis.expect([
+      field(json, "stem"),
+      field(json, "recorded"),
+      scenarios.map(s => {
+        let match = field(s, "when");
+        let match$1 = field(s, "then");
+        if (match === undefined) {
+          return [
+            undefined,
+            undefined
+          ];
+        }
+        if (!Array.isArray(match)) {
+          return [
+            undefined,
+            undefined
+          ];
+        }
+        if (match.length !== 1) {
+          return [
+            undefined,
+            undefined
+          ];
+        }
+        let w = match[0];
+        if (match$1 === undefined) {
+          return [
+            undefined,
+            undefined
+          ];
+        }
+        if (!Array.isArray(match$1)) {
+          return [
+            undefined,
+            undefined
+          ];
+        }
+        if (match$1.length !== 1) {
+          return [
+            undefined,
+            undefined
+          ];
+        }
+        let t = match$1[0];
+        return [
+          field(w, "element"),
+          field(t, "element")
+        ];
+      })
+    ]).toEqual([
+      "Prefs",
+      true,
+      [
+        [
+          "RequestNotification",
+          "NotificationUndeliverable"
+        ],
+        [
+          "RequestNotification",
+          "NotificationDeferred"
+        ]
+      ]
+    ]);
+  });
+  globalThis.test("a sidecar the PPX wrote is left as it is", () => {
+    let ppx = `{"stem":"Mine_GWT","scenarios":[]}`;
+    Nodefs.writeFileSync(sidecarOf("Mine"), ppx, "utf8");
+    ScenarioRecorder$ReventlessGwt.setFile(testFile("Mine"));
+    switched(true, () => run("Prefs", "t", "NotificationRequested"));
+    globalThis.expect(Nodefs.readFileSync(sidecarOf("Mine"), "utf8")).toBe(ppx);
+  });
+  globalThis.test("a second spec in one file gets a sidecar of its own", () => {
+    ScenarioRecorder$ReventlessGwt.setFile(testFile("Two"));
+    switched(true, () => {
+      run("Prefs", "a", "NotificationRequested");
+      run("Claims", "b", "NotificationSourceClaimed");
+    });
+    let path = sidecarOf("Two");
+    let path$1 = Nodepath.join(dir, "Two_GWT.Claims.gwt.json");
+    globalThis.expect([
+      field(JSON.parse(Nodefs.readFileSync(path, "utf8")), "stem"),
+      field(JSON.parse(Nodefs.readFileSync(path$1, "utf8")), "stem")
+    ]).toEqual([
+      "Prefs",
+      "Claims"
+    ]);
+  });
+  globalThis.test("steps outside a recorded test record nothing", () => {
+    globalThis.expect(ScenarioRecorder$ReventlessGwt.recording()).toBe(false);
+  });
+});
+
+export {
+  dir,
+  testFile,
+  sidecarOf,
+  read,
+  field,
+  run,
+  switched,
+}
+/* dir Not a pure module */