slicetest 0.6.1 → 0.8.0

package/dist/yaml.d.ts

@@ -10,6 +10,11 @@ export interface YamlFile {
     path?: string;
     /** Steps run at the start of every scenario in the file. */
     setup: Step[];
+    /** Named step lists that `use:` steps run, with `with:` values for their `params`. */
+    define: Record<string, {
+        params: string[];
+        steps: Step[];
+    }>;
     scenarios: YamlScenario[];
 }
 export interface YamlScenario {
@@ -19,46 +24,71 @@ export interface YamlScenario {
     skip?: boolean;
     only?: boolean;
     timeout?: number;
+    /** Labels to select scenarios by (`npx slicetest --tag smoke`). */
+    tags?: string[];
     steps: Step[];
 }
-export type Step = (StubStep | RequestStep | SubmitStep | InsertStep | MakeStep | ChaosStep | SqlStep | DbStep | ReceivedStep | ChangesStep | CheckpointStep | LogStep | SnapshotStep | MailStep) & {
+export type Step = (StubStep | RequestStep | SubmitStep | InsertStep | MakeStep | ChaosStep | SqlStep | DbStep | ReceivedStep | ChangesStep | CheckpointStep | SetStep | OrderStep | LogStep | SnapshotStep | MailStep | UseStep) & {
     line: number;
     name?: string;
 };
+type GraphQLReply = {
+    data?: unknown;
+    errors?: (string | {
+        message: string;
+    })[];
+};
+/** Run the steps of a `define:` entry. Values in `with` become variables inside it; what it captures is visible afterwards. */
+export interface UseStep {
+    use: string;
+    with?: Record<string, unknown>;
+}
 export interface StubStep {
     stub: string;
-    on: string;
+    /** METHOD /path; or `graphql` instead. */
+    on?: string;
+    /** A GraphQL operation name, answered at any path. */
+    graphql?: string;
     when?: Conditions;
     /** `sse`: a streamed reply, a list of { event, data, id } (instead of `body`). */
+    /** `file`: the body from a file relative to the scenario (.json / .yaml as JSON, with `{{call.*}}`; others as they are). */
     reply?: {
         status?: number;
         headers?: Record<string, string>;
         body?: unknown;
+        file?: string;
         sse?: {
             event?: string;
             data: unknown;
             id?: string;
         }[];
-    };
-    sequence?: {
+    } & GraphQLReply;
+    sequence?: ({
         status?: number;
         headers?: Record<string, string>;
         body?: unknown;
+        file?: string;
         sse?: {
             event?: string;
             data: unknown;
             id?: string;
         }[];
-    }[];
+    } & GraphQLReply)[];
     networkError?: boolean;
     times?: number;
     delay?: number;
+    /** The app may not call this route; `strictStubs` doesn't report it. */
+    optional?: boolean;
 }
 export interface Conditions {
     query?: Record<string, unknown>;
     headers?: Record<string, unknown>;
     json?: unknown;
+    /** Subset of a form-encoded body's fields, bracket keys nested (`metadata[order]` → `metadata: { order }`). */
+    form?: Record<string, unknown>;
     body?: unknown;
+    /** Subset of a GraphQL request's variables (with `graphql`). */
+    variables?: unknown;
 }
 export interface RequestStep {
     request: string;
@@ -66,7 +96,15 @@ export interface RequestStep {
     query?: Record<string, unknown>;
     json?: unknown;
     form?: Record<string, unknown>;
+    /** A `multipart/form-data` body: values are fields, `{ file, type, filename }` uploads a file relative to the scenario, `{ content, filename, type }` an inline one. */
+    multipart?: Record<string, unknown>;
     body?: string;
+    /** A GraphQL operation sent as the JSON body. */
+    graphql?: string | {
+        query: string;
+        variables?: Record<string, unknown>;
+        operationName?: string;
+    };
     follow?: boolean;
     /** Send `Authorization: Bearer` with a token from the `auth` issuer: `true`, or the claims, e.g. { sub: u1, roles: [admin] }. */
     auth?: true | Record<string, unknown>;
@@ -85,7 +123,14 @@ export interface RequestStep {
     };
     /** Send the request this many times at once. `expect` applies to every response; `statuses` counts them. */
     concurrency?: number;
+    /** Repeat the request until `expect` passes, for up to this many ms: polling a job the app finishes later. */
+    within?: number;
+    /** With `within`: ms between attempts. Default 200. */
+    every?: number;
+    /** Fail when the app hasn't answered within this many ms (overrides `http.timeout`). */
+    timeout?: number;
     /** `queries`: at most this many SQL statements (not counting BEGIN/COMMIT), with `db.queries` on. */
+    /** `schema`: a JSON Schema for the response JSON, inline or `file#/pointer` relative to the scenario file. */
     expect?: {
         status?: number;
         statuses?: Record<string, number>;
@@ -93,6 +138,7 @@ export interface RequestStep {
         json?: unknown;
         text?: unknown;
         queries?: number;
+        schema?: string | object;
     };
     capture?: Record<string, string>;
 }
@@ -105,7 +151,8 @@ export interface SubmitStep {
     /** The form by id, name or 0-based position, when the page has several. */
     form?: string | number;
     /** Values typed into the form by field name; true / false / a list check checkboxes and radios. */
-    fields?: Record<string, string | number | boolean | (string | number)[]>;
+    /** `{ file: path }` (relative to the scenario) or `{ content, filename, type }` for a file input. */
+    fields?: Record<string, string | number | boolean | (string | number)[] | FilePart>;
     headers?: Record<string, string>;
     follow?: boolean;
     expect?: {
@@ -113,6 +160,7 @@ export interface SubmitStep {
         headers?: Record<string, unknown>;
         json?: unknown;
         text?: unknown;
+        schema?: string | object;
     };
     capture?: Record<string, string>;
 }
@@ -164,6 +212,8 @@ export interface DbStep {
 export interface ReceivedStep {
     received: string;
     call?: string;
+    /** A GraphQL operation name, instead of `call`. */
+    graphql?: string;
     when?: Conditions;
     /** Exact number of matching calls. Default: at least one. */
     times?: number;
@@ -182,6 +232,8 @@ export type ChangeSpec = {
 export interface ChangesStep {
     changes: Record<string, ChangeSpec>;
     within?: number;
+    /** Columns or tables to leave out: `updated_at`, `orders.synced_at`, `sessions.*`. */
+    ignore?: string[];
 }
 /** Wait until the app (or `from:` a service) prints a line matching `log` (a regex) during the scenario. */
 export interface LogStep {
@@ -190,6 +242,29 @@ export interface LogStep {
     /** Milliseconds to wait. Default 5000. */
     within?: number;
 }
+/**
+ * Calls to stubs happened in this order (others may come in between):
+ * `order: ["stripe POST /v1/charges", { stub: mail, call: POST /send, when: { json: { to: a@b.test } } }]`.
+ */
+export interface OrderStep {
+    order: (string | {
+        stub: string;
+        call: string;
+        when?: Conditions;
+    })[];
+    within?: number;
+}
+/** A file to upload: read from `file` (relative to the scenario file), or `content` given inline. */
+export interface FilePart {
+    file?: string;
+    content?: unknown;
+    filename?: string;
+    type?: string;
+}
+/** Define variables for later steps: `set: { orderId: "{{$uuid}}" }`. */
+export interface SetStep {
+    set: Record<string, unknown>;
+}
 /** Later `changes` steps only see what happens after this step. */
 export interface CheckpointStep {
     checkpoint: true;
@@ -221,3 +296,4 @@ export interface MailStep {
 export declare class YamlScenarioError extends Error {
 }
 export declare function parseScenarioFile(text: string, file: string): YamlFile;
+export {};

package/dist/yaml.js

@@ -1,33 +1,37 @@
 import { isMap, isSeq, LineCounter, parseDocument } from "yaml";
+import { WEBHOOK_PROVIDERS as PROVIDERS } from "./webhook.js";
 const KINDS = {
-    stub: ["on", "when", "reply", "sequence", "networkError", "times", "delay"],
-    request: ["headers", "query", "json", "form", "body", "follow", "auth", "webhook", "concurrency", "expect", "capture"],
+    stub: ["on", "graphql", "when", "reply", "sequence", "networkError", "times", "delay", "optional"],
+    request: ["headers", "query", "json", "form", "multipart", "body", "graphql", "follow", "auth", "webhook", "concurrency", "expect", "capture", "within", "every", "timeout"],
     submit: ["form", "fields", "headers", "follow", "expect", "capture"],
     insert: ["rows", "capture"],
     sql: ["params", "expect", "capture", "within"],
     db: ["where", "orderBy", "expect", "capture", "within"],
-    received: ["call", "when", "times", "within"],
-    changes: ["within"],
+    received: ["call", "graphql", "when", "times", "within"],
+    changes: ["within", "ignore"],
     log: ["from", "within"],
     checkpoint: [],
+    set: [],
+    order: ["within"],
     snapshot: ["mask"],
     mail: ["times", "within", "capture"],
     make: ["rows", "count", "capture"],
     chaos: ["failFirst", "errorRate", "statuses", "networkErrorRate", "latency", "seed"],
+    use: ["with"],
 };
 const EXPECT_KEYS = {
-    request: ["status", "statuses", "headers", "json", "text", "queries"],
-    submit: ["status", "headers", "json", "text"],
+    request: ["status", "statuses", "headers", "json", "text", "queries", "schema"],
+    submit: ["status", "headers", "json", "text", "schema"],
     sql: ["rows", "count"],
     db: ["rows", "count"],
 };
-const CONDITION_KEYS = ["query", "headers", "json", "body"];
-const WEBHOOK_KEYS = ["provider", "secret", "event", "stale", "invalidSignature"];
-const WEBHOOK_PROVIDERS = ["stripe", "github", "slack", "shopify", "standard"];
+const CONDITION_KEYS = ["query", "headers", "json", "form", "body", "variables"];
+const WEBHOOK_KEYS = ["provider", "secret", "event", "stale", "invalidSignature", "url"];
+const WEBHOOK_PROVIDERS = PROVIDERS;
 const MAIL_KEYS = ["to", "from", "subject", "text", "html"];
 const CHANGE_KEYS = ["inserted", "updated", "deleted"];
-const RESPONSE_KEYS = ["status", "headers", "body", "sse"];
-const SCENARIO_KEYS = ["name", "steps", "each", "skip", "only", "timeout"];
+const RESPONSE_KEYS = ["status", "headers", "body", "file", "sse", "data", "errors"];
+const SCENARIO_KEYS = ["name", "steps", "each", "skip", "only", "timeout", "tags"];
 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*)$/;
@@ -48,8 +52,8 @@ export function parseScenarioFile(text, file) {
         return fail(root, "expected a mapping with a `scenarios:` list");
     const top = doc.toJS();
     for (const key of Object.keys(top))
-        if (key !== "scenarios" && key !== "setup")
-            fail(root, `unknown top-level key "${key}" (expected scenarios, setup)`);
+        if (!["scenarios", "setup", "define"].includes(key))
+            fail(root, `unknown top-level key "${key}" (expected scenarios, setup, define)`);
     const stepsOf = (seqNode, what) => {
         if (!isSeq(seqNode))
             return fail(seqNode, `${what} must be a list of steps`);
@@ -59,9 +63,56 @@ export function parseScenarioFile(text, file) {
     if (!isSeq(scenariosNode) || scenariosNode.items.length === 0)
         return fail(scenariosNode ?? root, "`scenarios:` must be a non-empty list");
     const setupNode = root.get("setup", true);
-    return {
+    const define = {};
+    const defineNode = root.get("define", true);
+    if (defineNode !== undefined) {
+        if (!isMap(defineNode))
+            return fail(defineNode, "`define:` maps names to step lists, e.g. `define: { login: [ ...steps ] }`");
+        for (const pair of defineNode.items) {
+            const name = String(pair.key?.value ?? pair.key);
+            const value = pair.value;
+            if (isSeq(value)) {
+                define[name] = { params: [], steps: stepsOf(value, `define "${name}"`) };
+                continue;
+            }
+            if (!isMap(value))
+                return fail(value ?? pair.key, `define "${name}" must be a list of steps, or { params, steps }`);
+            const raw = value.toJSON();
+            for (const k of Object.keys(raw))
+                if (k !== "params" && k !== "steps")
+                    fail(value, `unknown key "${k}" in define "${name}" (allowed: params, steps)`);
+            if (raw.params !== undefined && !(Array.isArray(raw.params) && raw.params.every((p) => typeof p === "string" && p)))
+                fail(value.get("params", true) ?? value, "`params` must be a list of names, e.g. [email, password]");
+            define[name] = { params: raw.params ?? [], steps: stepsOf(value.get("steps", true), `define "${name}": steps`) };
+        }
+    }
+    // `use:` must name a definition and give it exactly its params; definitions can't use themselves.
+    const checkUses = (steps, chain) => {
+        for (const step of steps) {
+            if (!("use" in step))
+                continue;
+            const def = define[step.use];
+            const at = `${file}:${step.line}`;
+            if (!def)
+                throw new YamlScenarioError(`${at}: no definition "${step.use}" (defined: ${Object.keys(define).join(", ") || "none; add a top-level \`define:\`"})`);
+            if (chain.includes(step.use))
+                throw new YamlScenarioError(`${at}: "${step.use}" uses itself (${[...chain, step.use].join(" → ")})`);
+            const given = Object.keys(step.with ?? {});
+            const missing = def.params.filter((p) => !given.includes(p));
+            const extra = given.filter((g) => !def.params.includes(g));
+            if (missing.length)
+                throw new YamlScenarioError(`${at}: use ${step.use} needs \`with: { ${missing.join(", ")} }\``);
+            if (extra.length)
+                throw new YamlScenarioError(`${at}: "${extra.join('", "')}" ${extra.length > 1 ? "aren't params" : "isn't a param"} of ${step.use} (params: ${def.params.join(", ") || "none"})`);
+            checkUses(def.steps, [...chain, step.use]);
+        }
+    };
+    for (const [name, def] of Object.entries(define))
+        checkUses(def.steps, [name]);
+    const parsed = {
         file,
         setup: setupNode ? stepsOf(setupNode, "setup") : [],
+        define,
         scenarios: scenariosNode.items.map((node) => {
             if (!isMap(node))
                 return fail(node, "each scenario must be a mapping with `name` and `steps`");
@@ -76,6 +127,9 @@ export function parseScenarioFile(text, file) {
             }
             if (raw.timeout !== undefined && typeof raw.timeout !== "number")
                 fail(node, "`timeout` must be a number of milliseconds");
+            if (raw.tags !== undefined && !(Array.isArray(raw.tags) && raw.tags.every((t) => typeof t === "string" && /^[^\s,!]+$/.test(t)))) {
+                fail(node.get("tags", true), "`tags` must be a list of words without spaces, commas or `!`, e.g. [smoke, payments]");
+            }
             return {
                 name: raw.name,
                 line: lineOf(node),
@@ -83,10 +137,15 @@ export function parseScenarioFile(text, file) {
                 skip: raw.skip === true,
                 only: raw.only === true,
                 timeout: raw.timeout,
+                tags: raw.tags,
                 steps: stepsOf(node.get("steps", true), `scenario "${raw.name}": steps`),
             };
         }),
     };
+    checkUses(parsed.setup, []);
+    for (const sc of parsed.scenarios)
+        checkUses(sc.steps, []);
+    return parsed;
 }
 function parseStep(node, fail, lineOf) {
     if (!isMap(node))
@@ -104,6 +163,8 @@ function parseStep(node, fail, lineOf) {
             fail(at(key), `unknown key "${key}" in a ${kind} step (allowed: ${[...allowed].join(", ")})`);
     }
     if (kind === "changes") {
+        if (raw.ignore !== undefined && !(Array.isArray(raw.ignore) && raw.ignore.every((c) => typeof c === "string" && c)))
+            fail(at("ignore"), "`ignore` must be a list of columns or tables, e.g. [updated_at, sessions.*]");
         const tables = raw.changes;
         if (!tables || typeof tables !== "object" || Array.isArray(tables))
             fail(at(kind), "`changes:` must map table names to { inserted, updated, deleted }");
@@ -137,11 +198,54 @@ function parseStep(node, fail, lineOf) {
                 fail(at("fields"), "`fields` must map field names to values, e.g. { email: a@b.test }");
             for (const [k, v] of Object.entries(fields)) {
                 const scalar = (x) => typeof x === "string" || typeof x === "number";
-                if (!(scalar(v) || typeof v === "boolean" || (Array.isArray(v) && v.every(scalar))))
-                    fail(at("fields"), `field "${k}" must be a string, number, true / false or a list`);
+                const isFile = !!v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).every((x) => ["file", "content", "filename", "type"].includes(x)) && ("file" in v) !== ("content" in v);
+                if (!(scalar(v) || typeof v === "boolean" || (Array.isArray(v) && v.every(scalar)) || isFile))
+                    fail(at("fields"), `field "${k}" must be a string, number, true / false, a list, or a file ({ file: path } or { content, filename })`);
+            }
+        }
+    }
+    else if (kind === "use") {
+        if (typeof raw.use !== "string" || !raw.use)
+            fail(at(kind), "`use:` names a step list from `define:`");
+        if (raw.with !== undefined && (!raw.with || typeof raw.with !== "object" || Array.isArray(raw.with)))
+            fail(at("with"), "`with` maps params to values, e.g. { email: a@b.test }");
+    }
+    else if (kind === "order") {
+        const list = raw.order;
+        if (!Array.isArray(list) || list.length < 2)
+            fail(at(kind), "`order:` lists at least two calls, e.g. [\"stripe POST /v1/charges\", \"mail POST /send\"]");
+        for (const item of list) {
+            if (typeof item === "string") {
+                if (!/^\S+\s+([A-Za-z]+|\*)\s+\/\S*$/.test(item))
+                    fail(at(kind), `"${item}" should be "<stub> METHOD /path", e.g. "mail POST /send"`);
+                continue;
+            }
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                fail(at(kind), "each `order` entry is \"<stub> METHOD /path\" or { stub, call, when }");
+            const o = item;
+            for (const k of Object.keys(o))
+                if (!["stub", "call", "when"].includes(k))
+                    fail(at(kind), `unknown key "${k}" in an order entry (allowed: stub, call, when)`);
+            if (typeof o.stub !== "string" || !o.stub)
+                fail(at(kind), "an order entry needs `stub`");
+            if (typeof o.call !== "string" || !CALL.test(o.call))
+                fail(at(kind), `an order entry's \`call\` must look like "POST /path", got ${JSON.stringify(o.call)}`);
+            if (o.when !== undefined) {
+                if (!o.when || typeof o.when !== "object" || Array.isArray(o.when))
+                    fail(at(kind), "`when` in an order entry must be a mapping");
+                for (const k of Object.keys(o.when))
+                    if (!CONDITION_KEYS.includes(k))
+                        fail(at(kind), `unknown key "${k}" in when (allowed: ${CONDITION_KEYS.join(", ")})`);
             }
         }
     }
+    else if (kind === "set") {
+        if (!raw.set || typeof raw.set !== "object" || Array.isArray(raw.set) || Object.keys(raw.set).length === 0)
+            fail(at(kind), "`set:` maps variable names to values, e.g. { orderId: \"{{$uuid}}\" }");
+        for (const k of Object.keys(raw.set))
+            if (!/^[A-Za-z_][\w]*$/.test(k))
+                fail(at(kind), `"${k}" isn't a variable name (letters, digits and _)`);
+    }
     else if (kind === "checkpoint") {
         if (raw.checkpoint !== true)
             fail(at(kind), "use `checkpoint: true`");
@@ -183,11 +287,21 @@ function parseStep(node, fail, lineOf) {
     }
     if (kind in EXPECT_KEYS)
         keysOf("expect", EXPECT_KEYS[kind]);
+    {
+        const schema = raw.expect?.schema;
+        if (schema !== undefined && !((typeof schema === "string" && schema) || (schema && typeof schema === "object" && !Array.isArray(schema)))) {
+            fail(at("expect"), "`expect.schema` is a JSON Schema, or a file such as openapi.yaml#/components/schemas/Poll");
+        }
+    }
     keysOf("when", CONDITION_KEYS);
+    if (raw.graphql !== undefined && kind !== "request" && (typeof raw.graphql !== "string" || !raw.graphql))
+        fail(at("graphql"), "`graphql` is the operation's name, e.g. `graphql: GetUser`");
+    if (raw.when?.variables !== undefined && raw.graphql === undefined)
+        fail(at("when"), "`when.variables` needs `graphql: <operation>`");
     switch (kind) {
         case "stub": {
-            if (raw.on === undefined)
-                fail(node, "a stub step needs `on`, e.g. `on: POST /hook`");
+            if ((raw.on === undefined) === (raw.graphql === undefined))
+                fail(node, "a stub step needs one of `on` (e.g. `on: POST /hook`) or `graphql` (e.g. `graphql: GetUser`)");
             call("on");
             const answers = ["reply", "sequence", "networkError"].filter((k) => raw[k] !== undefined);
             if (answers.length !== 1)
@@ -196,7 +310,22 @@ function parseStep(node, fail, lineOf) {
             for (const [where, r] of [["reply", raw.reply], ...(Array.isArray(raw.sequence) ? raw.sequence : []).map((r) => ["sequence", r])]) {
                 if (!r || typeof r !== "object")
                     continue;
-                const { body, sse } = r;
+                const { body, sse, data, errors, file } = r;
+                if (file !== undefined) {
+                    if (typeof file !== "string" || !file)
+                        fail(at(where), "`file` is a path relative to the scenario file, e.g. fixtures/charge.json");
+                    if (body !== undefined || sse !== undefined || data !== undefined || errors !== undefined)
+                        fail(at(where), "a reply has `file` instead of `body`, `sse`, `data` or `errors`");
+                }
+                if (data !== undefined || errors !== undefined) {
+                    if (raw.graphql === undefined)
+                        fail(at(where), "`data` and `errors` answer a GraphQL operation: use them with `graphql: <operation>`, or send `body`");
+                    if (body !== undefined || sse !== undefined)
+                        fail(at(where), "a GraphQL reply has `data` / `errors`, not `body` or `sse`");
+                    if (errors !== undefined && !(Array.isArray(errors) && errors.every((e) => typeof e === "string" || (e && typeof e === "object" && typeof e.message === "string")))) {
+                        fail(at(where), "`errors` must be a list of messages or { message, path, extensions }");
+                    }
+                }
                 if (sse === undefined)
                     continue;
                 if (body !== undefined)
@@ -209,12 +338,39 @@ function parseStep(node, fail, lineOf) {
                 fail(at("sequence"), "`sequence` must be a non-empty list of responses");
             number("times");
             number("delay");
+            if (raw.optional !== undefined && typeof raw.optional !== "boolean")
+                fail(at("optional"), "`optional` must be true or false");
             break;
         }
         case "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 (["json", "form", "multipart", "body", "graphql"].filter((k) => raw[k] !== undefined).length > 1)
+                fail(node, "use only one of json / form / multipart / body / graphql");
+            if (raw.multipart !== undefined) {
+                const m = raw.multipart;
+                if (!m || typeof m !== "object" || Array.isArray(m))
+                    fail(at("multipart"), "`multipart` maps field names to values, e.g. { name: ada, avatar: { file: ada.png } }");
+                for (const [k, v] of Object.entries(m)) {
+                    for (const part of Array.isArray(v) ? v : [v]) {
+                        if (part && typeof part === "object") {
+                            const keys = Object.keys(part);
+                            const bad = keys.find((x) => !["file", "content", "filename", "type"].includes(x));
+                            if (bad)
+                                fail(at("multipart"), `unknown key "${bad}" in multipart field "${k}" (allowed: file, content, filename, type)`);
+                            if (("file" in part) === ("content" in part))
+                                fail(at("multipart"), `multipart field "${k}" needs one of \`file\` (a path relative to the scenario file) or \`content\``);
+                        }
+                        else if (part === null)
+                            fail(at("multipart"), `multipart field "${k}" has no value`);
+                    }
+                }
+            }
+            if (raw.graphql !== undefined) {
+                const g = raw.graphql;
+                const ok = (typeof g === "string" && g.trim()) || (g && typeof g === "object" && !Array.isArray(g) && typeof g.query === "string" && Object.keys(g).every((k) => ["query", "variables", "operationName"].includes(k)));
+                if (!ok)
+                    fail(at("graphql"), "`graphql` is the query, or { query, variables, operationName }");
+            }
             if (raw.webhook !== undefined) {
                 const w = raw.webhook;
                 if (!w || typeof w !== "object" || Array.isArray(w))
@@ -233,6 +389,14 @@ function parseStep(node, fail, lineOf) {
                 fail(at("auth"), "`auth` must be true or the token's claims, e.g. { sub: u1, roles: [admin] }");
             if (raw.concurrency !== undefined && !(Number.isInteger(raw.concurrency) && raw.concurrency >= 1))
                 fail(at("concurrency"), "`concurrency` must be a positive whole number");
+            if (raw.timeout !== undefined && !(typeof raw.timeout === "number" && raw.timeout > 0))
+                fail(at("timeout"), "`timeout` must be a positive number of milliseconds");
+            if (raw.every !== undefined && !(typeof raw.every === "number" && raw.every > 0))
+                fail(at("every"), "`every` must be a positive number of milliseconds");
+            if (raw.every !== undefined && raw.within === undefined)
+                fail(at("every"), "`every` sets the pause between attempts of a `within` step; add `within: <ms>`");
+            if (raw.within !== undefined && raw.concurrency !== undefined)
+                fail(at("within"), "`within` repeats one request until it passes; it can't be combined with `concurrency`");
             {
                 const q = raw.expect?.queries;
                 if (q !== undefined && !(Number.isInteger(q) && q >= 0))
@@ -296,6 +460,8 @@ function parseStep(node, fail, lineOf) {
             break;
         case "received":
             call("call");
+            if (raw.call !== undefined && raw.graphql !== undefined)
+                fail(node, "a received step takes `call` or `graphql`, not both");
             number("times");
             break;
         case "mail":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slicetest",
-  "version": "0.6.1",
+  "version": "0.8.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",
@@ -19,6 +19,7 @@
     "language-agnostic",
     "openapi",
     "contract-testing",
+    "graphql",
     "jwt",
     "oidc",
     "webhooks",