slicetest 0.2.0 → 0.4.0

package/dist/trace.d.ts

@@ -0,0 +1,43 @@
+import type { Changes } from "./db.js";
+import type { HttpResponse } from "./http.js";
+import type { Mailbox } from "./mail.js";
+import type { Stub } from "./stub.js";
+/**
+ * Everything one scenario did at the three boundaries: the requests it made to
+ * the app, the calls the app made to stubs, and the rows it changed. Meant for
+ * `expect(await trace()).toMatchSnapshot()`: resets make ids deterministic,
+ * and `mask` replaces the values that aren't (timestamps, UUIDs).
+ */
+export interface Trace {
+    http: {
+        request: string;
+        status: number;
+        body?: unknown;
+    }[];
+    stubs: Record<string, {
+        request: string;
+        body?: unknown;
+        status?: number;
+    }[]>;
+    db: Changes;
+    /** Mail the app sent, when the `mail` option is on. */
+    mail?: {
+        from: string;
+        to: string[];
+        subject: string;
+        text: string;
+    }[];
+}
+export interface MaskOptions {
+    /** Keys whose values are always replaced, e.g. `["token", "password_hash"]`. Matched at any depth. */
+    keys?: string[];
+    /** Also mask strings matching these patterns, e.g. `[/^tok_\w+$/]`. */
+    patterns?: RegExp[];
+}
+/**
+ * A copy of `value` with the parts that change from run to run replaced by
+ * placeholders: dates (`Date` objects and ISO strings) by `[date]`, UUIDs by
+ * `[uuid]`, and the values of `keys` / strings matching `patterns` by `[masked]`.
+ */
+export declare function mask<T>(value: T, opts?: MaskOptions): T;
+export declare function buildTrace(history: readonly HttpResponse[], stubs: Iterable<Stub>, db: Changes, mailbox?: Mailbox): Trace;

package/dist/trace.js

@@ -0,0 +1,59 @@
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * A copy of `value` with the parts that change from run to run replaced by
+ * placeholders: dates (`Date` objects and ISO strings) by `[date]`, UUIDs by
+ * `[uuid]`, and the values of `keys` / strings matching `patterns` by `[masked]`.
+ */
+export function mask(value, opts = {}) {
+    const keys = new Set(opts.keys ?? []);
+    const walk = (v) => {
+        if (v instanceof Date)
+            return "[date]";
+        if (typeof v === "bigint")
+            return v.toString();
+        if (typeof v === "string") {
+            if (UUID.test(v))
+                return "[uuid]";
+            if (ISO_DATE.test(v))
+                return "[date]";
+            if (opts.patterns?.some((p) => ((p.lastIndex = 0), p.test(v))))
+                return "[masked]";
+            return v;
+        }
+        if (Array.isArray(v))
+            return v.map(walk);
+        if (v && typeof v === "object") {
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, keys.has(k) && x != null ? "[masked]" : walk(x)]));
+        }
+        return v;
+    };
+    return walk(value);
+}
+export function buildTrace(history, stubs, db, mailbox) {
+    const trace = {
+        http: history.map((r) => {
+            const url = new URL(r.url, "http://app");
+            const body = r.json !== undefined ? r.json : r.text || undefined;
+            return { request: `${r.method} ${url.pathname}${url.search}`, status: r.status, ...(body !== undefined ? { body } : {}) };
+        }),
+        stubs: {},
+        db,
+    };
+    for (const stub of stubs) {
+        const calls = stub.calls();
+        if (calls.length === 0)
+            continue;
+        trace.stubs[stub.name] = calls.map((c) => {
+            const body = c.json !== undefined ? c.json : c.body || undefined;
+            return {
+                request: `${c.method} ${c.path}${c.query.size ? `?${c.query}` : ""}`,
+                ...(body !== undefined ? { body } : {}),
+                ...(c.response ? { status: c.response.status } : {}),
+            };
+        });
+    }
+    if (mailbox)
+        trace.mail = mailbox.messages().map((m) => ({ from: m.from, to: m.to, subject: m.subject, text: m.text }));
+    return trace;
+}

package/dist/vitest.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { configDefaults } from "vitest/config";
 import { resolveOptions } from "./config.js";
+import { SESSION_ENV } from "./record.js";
 import { parseScenarioFile } from "./yaml.js";
 /** YAML scenario files are picked up next to the regular test files. */
 export const YAML_SCENARIOS = "**/*.scenario.{yaml,yml}";
@@ -17,7 +18,9 @@ export function slicetest(options) {
             const root = path.resolve(config.root ?? process.cwd());
             // Mutated rather than returned: a returned list would replace Vitest's default include instead of extending it.
             const test = (config.test ??= {});
-            test.include = [...(test.include ?? configDefaults.include), YAML_SCENARIOS];
+            // `slicetest record` runs only its session file.
+            if (!process.env[SESSION_ENV])
+                test.include = [...(test.include ?? configDefaults.include), YAML_SCENARIOS];
             return {
                 test: {
                     globalSetup: [path.join(here, `global-setup${ext}`)],
@@ -31,7 +34,7 @@ export function slicetest(options) {
             const file = id.split("?")[0];
             if (!YAML_ID.test(file))
                 return;
-            const doc = parseScenarioFile(code, path.relative(root ?? process.cwd(), file) || file);
+            const doc = { ...parseScenarioFile(code, path.relative(root ?? process.cwd(), file) || file), path: file };
             const runtime = JSON.stringify(path.join(here, `yaml-runtime${ext}`));
             return { code: `import { defineYamlScenarios } from ${runtime};\ndefineYamlScenarios(${JSON.stringify(doc)});\n`, map: null };
         },

package/dist/yaml-runtime.d.ts

@@ -1,3 +1,4 @@
+import "./provided.js";
 import "./matchers.js";
 import type { YamlFile } from "./yaml.js";
 type Vars = Record<string, unknown>;

package/dist/yaml-runtime.js

@@ -1,4 +1,6 @@
-import { expect } from "vitest";
+import { expect, inject } from "vitest";
+import { recordYamlFailure } from "./ci.js";
+import "./provided.js";
 import { formatChanges } from "./db.js";
 import "./matchers.js";
 import { scenario } from "./scenario.js";
@@ -17,11 +19,17 @@ async function runSteps(doc, sc, steps, ctx, vars) {
     for (const [i, step] of steps.entries()) {
         try {
             // A log step waits by itself; `within` is its timeout.
-            await retry("within" in step && !("log" in step) ? step.within : undefined, () => runStep(step, ctx, vars));
+            // Log and mail steps wait by themselves; `within` is their timeout.
+            await retry("within" in step && !("log" in step) && !("mail" in step) ? step.within : undefined, () => runStep(step, ctx, vars));
         }
         catch (e) {
             const label = step.name ?? describeStep(step);
             const where = `${doc.file}:${step.line} (${sc.name}, step ${i + 1}: ${label})`;
+            const ciDir = inject("slicetestDb")?.ciDir;
+            if (ciDir && doc.path) {
+                const message = (e instanceof Error ? e.message : String(e)).replace(/\x1b\[[0-9;]*m/g, "");
+                await recordYamlFailure(ciDir, { file: doc.path, line: step.line, scenario: sc.name, step: `step ${i + 1}: ${label}`, message }).catch(() => { });
+            }
             if (e instanceof Error) {
                 e.message = `${where}\n${e.message}`;
                 throw e;
@@ -32,7 +40,7 @@ async function runSteps(doc, sc, steps, ctx, vars) {
 }
 function describeStep(step) {
     if ("request" in step)
-        return step.request;
+        return step.concurrency ? `${step.request} ×${step.concurrency}` : step.request;
     if ("stub" in step)
         return `stub ${step.stub} ${step.on}`;
     if ("received" in step)
@@ -45,6 +53,10 @@ function describeStep(step) {
         return "changes";
     if ("checkpoint" in step)
         return "checkpoint";
+    if ("snapshot" in step)
+        return "snapshot";
+    if ("mail" in step)
+        return `mail${Object.entries(step.mail).map(([k, v]) => ` ${k}: ${JSON.stringify(v)}`).join(",")}`;
     if ("log" in step)
         return `log ${step.from ? `from ${step.from} ` : ""}/${step.log}/`;
     return "sql";
@@ -73,11 +85,33 @@ async function runStep(step, ctx, vars) {
         await ctx.db.checkpoint();
         return;
     }
+    if ("snapshot" in step) {
+        expect(await ctx.trace({ keys: step.mask })).toMatchSnapshot();
+        return;
+    }
     if ("log" in step) {
         const target = step.from ? ctx.service(step.from) : ctx.app;
         await target.waitForLog(new RegExp(interpolate(step.log, vars)), step.within ?? 5000);
         return;
     }
+    if ("mail" in step) {
+        const filter = Object.fromEntries(Object.entries(interpolate(step.mail, vars)).map(([k, v]) => {
+            const re = v && typeof v === "object" && "$regex" in v ? new RegExp(String(v.$regex)) : undefined;
+            return [k, re ?? String(v)];
+        }));
+        const box = ctx.mail;
+        await retry(step.within ?? 5000, async () => {
+            const found = box.messages(filter);
+            if (step.times === undefined ? found.length === 0 : found.length !== step.times) {
+                const want = step.times === undefined ? "at least one message" : `${step.times} message(s)`;
+                throw new Error(`expected ${want} matching ${JSON.stringify(step.mail)}, got ${found.length}\n${box.describe()}`);
+            }
+        });
+        const last = box.last(filter);
+        if (last)
+            capture(step.capture, last, vars);
+        return;
+    }
     if ("changes" in step) {
         const actual = await ctx.db.changes();
         const expected = interpolate(step.changes, vars);
@@ -135,18 +169,29 @@ async function runStep(step, ctx, vars) {
             : step.form !== undefined
                 ? ctx.http.form(interpolate(step.form, vars))
                 : interpolate(step.body, vars);
-        const res = await ctx.http.request(method, path, body, opts);
         const e = step.expect;
-        if (e?.status !== undefined)
-            expect(res).toHaveStatus(interpolate(e.status, vars));
-        if (e?.headers !== undefined) {
-            const expected = Object.fromEntries(Object.entries(e.headers).map(([k, v]) => [k.toLowerCase(), v]));
-            check(Object.fromEntries(res.headers), expected, vars, "response headers");
+        const verify = (res) => {
+            if (e?.status !== undefined)
+                expect(res).toHaveStatus(interpolate(e.status, vars));
+            if (e?.headers !== undefined) {
+                const expected = Object.fromEntries(Object.entries(e.headers).map(([k, v]) => [k.toLowerCase(), v]));
+                check(Object.fromEntries(res.headers), expected, vars, "response headers");
+            }
+            if (e?.json !== undefined)
+                check(res.json, e.json, vars, "response JSON");
+            if (e?.text !== undefined)
+                check(res.text, e.text, vars, "response text");
+        };
+        if (step.concurrency !== undefined) {
+            // Each request gets its own body: a URLSearchParams body can only be read once.
+            const all = await ctx.http.concurrently(step.concurrency, () => ctx.http.request(method, path, body instanceof URLSearchParams ? new URLSearchParams(body) : body, opts));
+            if (e?.statuses !== undefined)
+                expect(all).toHaveStatuses(interpolate(e.statuses, vars));
+            all.forEach(verify);
+            return;
         }
-        if (e?.json !== undefined)
-            check(res.json, e.json, vars, "response JSON");
-        if (e?.text !== undefined)
-            check(res.text, e.text, vars, "response text");
+        const res = await ctx.http.request(method, path, body, opts);
+        verify(res);
         capture(step.capture, { status: res.status, json: res.json, text: res.text, headers: Object.fromEntries(res.headers) }, vars);
         return;
     }

package/dist/yaml.d.ts

@@ -6,6 +6,8 @@
  */
 export interface YamlFile {
     file: string;
+    /** Absolute path, for CI annotations. */
+    path?: string;
     /** Steps run at the start of every scenario in the file. */
     setup: Step[];
     scenarios: YamlScenario[];
@@ -19,7 +21,7 @@ export interface YamlScenario {
     timeout?: number;
     steps: Step[];
 }
-export type Step = (StubStep | RequestStep | InsertStep | SqlStep | DbStep | ReceivedStep | ChangesStep | CheckpointStep | LogStep) & {
+export type Step = (StubStep | RequestStep | InsertStep | SqlStep | DbStep | ReceivedStep | ChangesStep | CheckpointStep | LogStep | SnapshotStep | MailStep) & {
     line: number;
     name?: string;
 };
@@ -55,8 +57,11 @@ export interface RequestStep {
     form?: Record<string, unknown>;
     body?: string;
     follow?: boolean;
+    /** Send the request this many times at once. `expect` applies to every response; `statuses` counts them. */
+    concurrency?: number;
     expect?: {
         status?: number;
+        statuses?: Record<string, number>;
         headers?: Record<string, unknown>;
         json?: unknown;
         text?: unknown;
@@ -123,6 +128,30 @@ export interface LogStep {
 export interface CheckpointStep {
     checkpoint: true;
 }
+/** Compare the scenario's trace (requests, stub calls, database changes) with its stored snapshot. */
+export interface SnapshotStep {
+    snapshot: true;
+    /** Keys whose values are masked in addition to dates and UUIDs. */
+    mask?: string[];
+}
+/**
+ * The app sent mail matching `mail:` (strings are exact addresses for to/from and substrings
+ * otherwise; `{ $regex }` also works). Waits up to `within` ms (default 5000). `capture` reads
+ * the last match: `subject`, `text`, `links.0`.
+ */
+export interface MailStep {
+    mail: {
+        to?: unknown;
+        from?: unknown;
+        subject?: unknown;
+        text?: unknown;
+        html?: unknown;
+    };
+    /** Exact number of matching messages. Default: at least one. */
+    times?: number;
+    within?: number;
+    capture?: Record<string, string>;
+}
 export declare class YamlScenarioError extends Error {
 }
 export declare function parseScenarioFile(text: string, file: string): YamlFile;

package/dist/yaml.js

@@ -1,7 +1,7 @@
 import { isMap, isSeq, LineCounter, parseDocument } from "yaml";
 const KINDS = {
     stub: ["on", "when", "reply", "sequence", "networkError", "times", "delay"],
-    request: ["headers", "query", "json", "form", "body", "follow", "expect", "capture"],
+    request: ["headers", "query", "json", "form", "body", "follow", "concurrency", "expect", "capture"],
     insert: ["rows", "capture"],
     sql: ["params", "expect", "capture", "within"],
     db: ["where", "orderBy", "expect", "capture", "within"],
@@ -9,17 +9,22 @@ const KINDS = {
     changes: ["within"],
     log: ["from", "within"],
     checkpoint: [],
+    snapshot: ["mask"],
+    mail: ["times", "within", "capture"],
 };
 const EXPECT_KEYS = {
-    request: ["status", "headers", "json", "text"],
+    request: ["status", "statuses", "headers", "json", "text"],
     sql: ["rows", "count"],
     db: ["rows", "count"],
 };
 const CONDITION_KEYS = ["query", "headers", "json", "body"];
+const MAIL_KEYS = ["to", "from", "subject", "text", "html"];
 const CHANGE_KEYS = ["inserted", "updated", "deleted"];
 const RESPONSE_KEYS = ["status", "headers", "body"];
 const SCENARIO_KEYS = ["name", "steps", "each", "skip", "only", "timeout"];
 const CALL = /^([A-Za-z]+|\*)\s+(\/\S*)$/;
+/** A request may also go to a captured URL of the app, e.g. a link from a mail: `GET {{link}}`. */
+const REQUEST = /^[A-Za-z]+\s+(\/\S*|\{\{[^}]+\}\}\S*)$/;
 export class YamlScenarioError extends Error {
 }
 export function parseScenarioFile(text, file) {
@@ -107,10 +112,24 @@ function parseStep(node, fail, lineOf) {
             }
         }
     }
+    else if (kind === "mail") {
+        const filter = raw.mail;
+        if (!filter || typeof filter !== "object" || Array.isArray(filter))
+            fail(at(kind), "`mail:` must be a mapping such as { to: alice@example.com, subject: Welcome } ({} for any)");
+        for (const k of Object.keys(filter))
+            if (!MAIL_KEYS.includes(k))
+                fail(at(kind), `unknown key "${k}" in mail (allowed: ${MAIL_KEYS.join(", ")})`);
+    }
     else if (kind === "checkpoint") {
         if (raw.checkpoint !== true)
             fail(at(kind), "use `checkpoint: true`");
     }
+    else if (kind === "snapshot") {
+        if (raw.snapshot !== true)
+            fail(at(kind), "use `snapshot: true`");
+        if (raw.mask !== undefined && !(Array.isArray(raw.mask) && raw.mask.every((k) => typeof k === "string")))
+            fail(at("mask"), "`mask:` must be a list of keys, e.g. [token]");
+    }
     else if (typeof raw[kind] !== "string" || !raw[kind])
         fail(at(kind), `\`${kind}:\` must be a non-empty string`);
     const keysOf = (key, allowedKeys) => {
@@ -124,8 +143,8 @@ function parseStep(node, fail, lineOf) {
                 fail(at(key), `unknown key "${k}" in ${key} (allowed: ${allowedKeys.join(", ")})`);
         }
     };
-    const call = (key) => {
-        if (raw[key] !== undefined && !CALL.test(String(raw[key])))
+    const call = (key, pattern = CALL) => {
+        if (raw[key] !== undefined && !pattern.test(String(raw[key])))
             fail(at(key), `\`${key}\` must look like "POST /path", got "${raw[key]}"`);
     };
     if (raw.within !== undefined && (typeof raw.within !== "number" || raw.within <= 0))
@@ -159,9 +178,23 @@ function parseStep(node, fail, lineOf) {
             break;
         }
         case "request":
-            call("request");
+            call("request", REQUEST);
             if (["json", "form", "body"].filter((k) => raw[k] !== undefined).length > 1)
                 fail(node, "use only one of json / form / body");
+            if (raw.concurrency !== undefined && !(Number.isInteger(raw.concurrency) && raw.concurrency >= 1))
+                fail(at("concurrency"), "`concurrency` must be a positive whole number");
+            if (raw.concurrency !== undefined && raw.capture !== undefined)
+                fail(at("capture"), "`capture` can't be used with `concurrency`: there is more than one response");
+            {
+                const statuses = raw.expect?.statuses;
+                if (statuses !== undefined) {
+                    if (raw.concurrency === undefined)
+                        fail(at("expect"), "`expect.statuses` needs `concurrency`");
+                    if (!statuses || typeof statuses !== "object" || Object.entries(statuses).some(([k, v]) => !/^\d{3}$/.test(k) || !Number.isInteger(v))) {
+                        fail(at("expect"), "`expect.statuses` maps status codes to counts, e.g. { 201: 1, 409: 9 }");
+                    }
+                }
+            }
             break;
         case "insert":
             if (!raw.rows || typeof raw.rows !== "object")
@@ -181,6 +214,9 @@ function parseStep(node, fail, lineOf) {
             call("call");
             number("times");
             break;
+        case "mail":
+            number("times");
+            break;
     }
     return { ...raw, line: lineOf(node) };
 }

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "slicetest",
-  "version": "0.2.0",
-  "description": "Framework-agnostic slice tests: drive a real app process over HTTP with a real Postgres and stubbed outbound APIs, checked against OpenAPI contracts.",
+  "version": "0.4.0",
+  "description": "Framework-agnostic slice tests: drive a real app process over HTTP with a real Postgres, MySQL or SQLite and stubbed outbound APIs, checked against OpenAPI contracts.",
   "keywords": [
     "testing",
     "integration-testing",
     "slice-test",
     "api-testing",
     "postgres",
+    "mysql",
+    "sqlite",
     "stub",
     "mock-server",
     "vitest",
@@ -54,11 +56,13 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:dist": "npm run build && tsc -p examples/tsconfig.dist.json && vitest run --config examples/vitest.dist.config.ts && node dist/cli.js --config examples/slicetest.config.yaml",
+    "test:dist": "npm run build && tsc -p examples/tsconfig.dist.json && vitest run --config examples/vitest.dist.config.ts && node dist/cli.js --config examples/slicetest.config.yaml && node test/record-dist.mjs",
     "prepublishOnly": "npm run typecheck && npm run build"
   },
   "peerDependencies": {
-    "vitest": ">=5"
+    "vitest": ">=5",
+    "mysql2": ">=3",
+    "@testcontainers/mysql": ">=11"
   },
   "dependencies": {
     "@testcontainers/postgresql": "^12.2.0",
@@ -69,12 +73,22 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
+    "@testcontainers/mysql": "^12.2.0",
     "@types/node": "^26.6.3",
     "@types/pg": "^8.23.1",
+    "mysql2": "^3.24.5",
     "typescript": "^7.0.2",
     "vitest": "^5.0.2"
   },
   "bin": {
     "slicetest": "dist/cli.js"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
+    },
+    "@testcontainers/mysql": {
+      "optional": true
+    }
   }
 }

package/schema/scenario.schema.json

@@ -180,6 +180,11 @@
             "follow": {
               "type": "boolean"
             },
+            "concurrency": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Send the request this many times at once, to provoke races. `expect` applies to every response"
+            },
             "expect": {
               "type": "object",
               "additionalProperties": false,
@@ -196,7 +201,18 @@
                 "json": {
                   "description": "Subset of the response JSON"
                 },
-                "text": {}
+                "text": {},
+                "statuses": {
+                  "type": "object",
+                  "propertyNames": {
+                    "pattern": "^\\d{3}$"
+                  },
+                  "additionalProperties": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "description": "With `concurrency`: how many responses have each status, e.g. { 201: 1, 409: 9 }"
+                }
               }
             },
             "capture": {
@@ -501,6 +517,162 @@
               "description": "Label shown when this step fails"
             }
           }
+        },
+        {
+          "type": "object",
+          "required": [
+            "snapshot"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "snapshot": {
+              "const": true,
+              "description": "Compare this scenario's trace so far (requests to the app, calls to stubs, database changes; dates and UUIDs masked) with its stored snapshot. Update with vitest -u"
+            },
+            "mask": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Keys whose values are masked too, e.g. [token]"
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "mail"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "mail": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "The app sent mail matching these fields (needs `mail: true` in the config). to/from are exact addresses; subject/text/html are substrings. {} matches any message",
+              "properties": {
+                "to": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "$regex"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "$regex": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "from": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "$regex"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "$regex": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "subject": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "$regex"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "$regex": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "text": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "$regex"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "$regex": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "html": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "$regex"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "$regex": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            },
+            "times": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Exact number of matching messages. Default: at least one"
+            },
+            "within": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Milliseconds to wait. Default 5000"
+            },
+            "capture": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "description": "Values of the last matching message: subject, text, html, from, to.0, links.0"
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            }
+          }
         }
       ]
     },