slicetest 0.1.0 → 0.3.0

package/dist/cli.js

@@ -11,21 +11,33 @@ import { parseArgs } from "node:util";
 import { parse } from "yaml";
 const CONFIG_NAMES = ["slicetest.config.yaml", "slicetest.config.yml", "slicetest.config.json"];
 const HELP = `Usage: slicetest [filters...] [options]
+       slicetest init [--force]
+       slicetest gen [--spec <file>] [--out <dir>] [--uncovered] [--force]
 
 Runs *.scenario.yaml files against your app, as configured in slicetest.config.yaml.
+\`slicetest init\` looks at the project and writes a starting config and scenario.
+\`slicetest gen\` writes scenario skeletons for the documented responses of the
+app's OpenAPI spec; with --uncovered, only for those the last run didn't produce.
 
 Options:
   -c, --config <file>  Config file (default: ${CONFIG_NAMES.join(" / ")} in the current directory)
   -w, --watch          Re-run on changes
   -t, --name <pattern> Only run scenarios whose name matches
+      --spec <file>    gen: OpenAPI file (default: \`openapi\` from the config)
+      --out <dir>      gen: where to write scenarios (default: scenarios)
+      --uncovered      gen: only responses the last run didn't cover
+      --force          init, gen: overwrite existing files
   -h, --help           Show this help
 
 Config (paths are relative to the config file):
-  app:     { command, env, cwd, ready: { path } | { log }, readyTimeout }
-  db:      { migrate: { atlas: { dir } } | { sql } | { command }, seed, url, image, schemas, keep }
-  stubs:   [names]
-  http:    { headers, query }
-  include: [globs]   default ["**/*.scenario.{yaml,yml}"]
+  app:      { command, env, cwd, ready: { path } | { log }, readyTimeout }
+  db:       { migrate: { atlas: { dir } } | { sql } | { command, inputs }, engine, seed, url, image, schemas, keep, reuse }
+  stubs:    [name | { name, openapi, autoReply, upstream, recordings }]
+  services: { name: { command, env, cwd, ready } }
+  containers: { name: { image, port, env, command, ready: { log }, reset } }
+  openapi:  file | { spec, minCoverage }
+  http:     { headers, query }
+  include:  [globs]  default ["**/*.scenario.{yaml,yml}"]
 `;
 export async function main(argv = process.argv.slice(2)) {
     const { values, positionals } = parseArgs({
@@ -36,17 +48,43 @@ export async function main(argv = process.argv.slice(2)) {
             watch: { type: "boolean", short: "w" },
             name: { type: "string", short: "t" },
             help: { type: "boolean", short: "h" },
+            force: { type: "boolean" },
+            spec: { type: "string" },
+            out: { type: "string" },
+            uncovered: { type: "boolean" },
         },
     });
     if (values.help) {
         process.stdout.write(HELP);
         return;
     }
+    if (positionals[0] === "init") {
+        const { init } = await import("./init.js");
+        const { files, notes } = await init(process.cwd(), { force: values.force });
+        process.stdout.write(`Created ${files.join(" and ")}.\n\nWhat was detected (check these in the config):\n${notes.map((n) => `  - ${n}`).join("\n")}\n\nNext: npx slicetest\n`);
+        return;
+    }
     const configPath = values.config
         ? path.resolve(values.config)
         : CONFIG_NAMES.map((n) => path.resolve(n)).find((p) => existsSync(p));
+    if (positionals[0] === "gen") {
+        const configOpenapi = configPath && existsSync(configPath) ? (parse(await readFile(configPath, "utf8")) ?? {}).openapi : undefined;
+        const spec = values.spec ?? (typeof configOpenapi === "object" ? configOpenapi.spec : configOpenapi);
+        if (!spec)
+            throw new Error("slicetest gen: no OpenAPI spec. Pass --spec openapi.yaml, or set `openapi` in the config.");
+        const root = values.spec || !configPath ? process.cwd() : path.dirname(configPath);
+        const { gen } = await import("./gen.js");
+        const { written, skipped, count } = await gen(root, { spec, out: values.out, uncovered: values.uncovered, force: values.force });
+        const lines = [
+            count === 0 ? "Every documented response is already covered; nothing to generate." : `${count} scenario(s) for the responses in ${spec}.`,
+            ...written.map((f) => `  wrote   ${f}`),
+            ...skipped.map((f) => `  skipped ${f} (exists; --force to overwrite)`),
+        ];
+        process.stdout.write(`${lines.join("\n")}\n`);
+        return;
+    }
     if (!configPath || !existsSync(configPath)) {
-        process.stderr.write(`slicetest: no config found. Create ${CONFIG_NAMES[0]} (see --help).\n`);
+        process.stderr.write(`slicetest: no config found. Run "npx slicetest init" to create ${CONFIG_NAMES[0]} (see --help).\n`);
         process.exitCode = 1;
         return;
     }

package/dist/config.d.ts

@@ -2,11 +2,85 @@ import type { RequestOptions } from "./http.js";
 export interface SlicetestOptions {
     app: AppOptions;
     db?: DbOptions;
-    /** Names of outbound HTTP services to stub. Each gets its own server, referenced as `{{stub.<name>}}` in `app.env`. */
-    stubs?: string[];
+    /**
+     * Outbound HTTP services to stub. Each gets its own server, referenced as `{{stub.<name>}}` in `app.env`.
+     * With `{ name, openapi }`, the app's calls to it and the stub's replies are checked against that service's spec.
+     * With `autoReply: true` as well, calls no route matches are answered from the spec (its examples, or values
+     * built from its schemas) instead of failing, so you only register the routes a scenario cares about.
+     */
+    stubs?: (string | StubOptions)[];
+    /**
+     * The app's own OpenAPI 3 spec (YAML or JSON, relative to the root). Every
+     * response the app gives during a scenario must be documented and match its
+     * schema, or the scenario fails. At the end of the run, slicetest prints which
+     * documented responses the scenarios produced; with `minCoverage` (percent),
+     * a lower coverage fails the run.
+     */
+    openapi?: string | {
+        spec: string;
+        minCoverage?: number;
+    };
     /** Defaults for every request made with `http`, e.g. `{ headers: { accept: "application/json" } }`. */
     http?: RequestOptions;
+    /**
+     * Other processes the app needs: a queue worker, another microservice, a
+     * mock written in another language. They start before the app, in order, and
+     * are watched like the app: a crash fails the scenario and they're restarted.
+     * Their URL is `{{service.<name>}}` and their port `{{service.<name>.port}}`,
+     * usable in `app.env` and in the env of services declared after them.
+     */
+    services?: Record<string, ServiceOptions>;
+    /**
+     * Containers the app depends on besides the database: Redis, Elasticsearch,
+     * MinIO, LocalStack. Each test file gets its own, reachable at
+     * `{{container.<name>}}` (`host:port`), `{{container.<name>.host}}` and
+     * `{{container.<name>.port}}`. `reset` runs inside it before every scenario.
+     */
+    containers?: Record<string, ContainerOptions>;
 }
+export interface ContainerOptions {
+    image: string;
+    /** The port the service listens on inside the container. */
+    port: number;
+    env?: Record<string, string>;
+    command?: string[];
+    /** Wait for this log line instead of the port accepting connections. */
+    ready?: {
+        log: string;
+    };
+    /** Command run inside the container before each scenario, e.g. `["redis-cli", "FLUSHALL"]`. */
+    reset?: string[];
+}
+export interface StubOptions {
+    name: string;
+    /** The provider's OpenAPI spec: the app's calls and the stub's replies are checked against it. */
+    openapi?: string;
+    /** Answer calls no route matches from the spec's examples or schemas. Needs `openapi`. */
+    autoReply?: boolean;
+    /**
+     * The real service's base URL, e.g. `https://api.github.com`. Calls no route
+     * matches are answered from `recordings`; run with `SLICETEST_RECORD=<name>`
+     * (or `=1` for every stub) to forward the ones without a recording to this
+     * URL and record the answers.
+     */
+    upstream?: string;
+    /** Recordings file, relative to the root. Default `recordings/<name>.yaml`. */
+    recordings?: string;
+}
+export interface ServiceOptions extends Omit<AppOptions, "ready"> {
+    /** Default: no wait (for workers that don't listen). `{ path }` polls the service's own port. */
+    ready?: AppOptions["ready"];
+}
+type ResolvedReady = {
+    path: string;
+} | {
+    log: string;
+    flags: string;
+};
+/** A process to start, with `ready` made JSON-serializable. The app always has `ready`; services may not. */
+export type ResolvedProcess = Omit<AppOptions, "ready"> & {
+    ready?: ResolvedReady;
+};
 export interface AppOptions {
     /** Command that starts the app, run through the shell. */
     command: string;
@@ -27,10 +101,15 @@ export interface AppOptions {
     readyTimeout?: number;
 }
 export interface DbOptions {
-    /** Postgres image used when no `url` is given. Default `postgres:17-alpine`. */
+    /**
+     * `postgres` (default) or `mysql`. Inferred from `url` when it starts with `mysql://`.
+     * MySQL needs the `mysql2` package, and `@testcontainers/mysql` unless `url` is given.
+     */
+    engine?: "postgres" | "mysql";
+    /** Image used when no `url` is given. Default `postgres:17-alpine`, or `mysql:8.4` for MySQL. */
     image?: string;
     /**
-     * Use an existing Postgres server instead of starting a container. Must point at a superuser-capable database.
+     * Use an existing server instead of starting a container. Must point at a superuser (root) connection.
      * Defaults to the `SLICETEST_DATABASE_URL` environment variable, which is handy in CI.
      */
     url?: string;
@@ -41,6 +120,13 @@ export interface DbOptions {
     schemas?: string[];
     /** Extra tables kept across resets, in addition to known migration bookkeeping tables. */
     keep?: string[];
+    /**
+     * Keep the Postgres container running between runs and cache the migrated
+     * template by the contents of the migrations, so a run with unchanged
+     * migrations skips both container start-up and migrating.
+     * Default: on, except when `CI` is set or `url` is given.
+     */
+    reuse?: boolean;
 }
 export type MigrateOptions = {
     atlas: {
@@ -50,20 +136,37 @@ export type MigrateOptions = {
     sql: string;
 } | {
     command: string;
+    /**
+     * Files or directories the command reads (e.g. `["prisma/migrations"]`).
+     * With `reuse`, the migrated template is cached until one of them changes;
+     * without `inputs`, the command runs on every run.
+     */
+    inputs?: string[];
 };
 /** Normalized shape passed from the plugin to globalSetup and workers. Must stay JSON-serializable. */
 export interface ResolvedOptions {
     root: string;
     app: Omit<AppOptions, "ready"> & {
-        ready: {
-            path: string;
-        } | {
-            log: string;
-            flags: string;
-        };
+        ready: ResolvedReady;
     };
-    db: Required<Pick<DbOptions, "image" | "schemas" | "keep">> & Omit<DbOptions, "image" | "schemas" | "keep">;
+    services: Record<string, ResolvedProcess>;
+    containers: Record<string, ContainerOptions>;
+    db: Required<Pick<DbOptions, "engine" | "image" | "schemas" | "keep" | "reuse">> & Omit<DbOptions, "engine" | "image" | "schemas" | "keep" | "reuse">;
     stubs: string[];
+    /** Spec files, resolved against the root: the app's, and per stub name. */
+    openapi: {
+        app?: string;
+        minCoverage?: number;
+        stubs: Record<string, string>;
+        autoReply: string[];
+    };
+    /** Stubs backed by recordings of a real service; `record` when SLICETEST_RECORD selects them. */
+    recordings: Record<string, {
+        file: string;
+        upstream: string;
+        record: boolean;
+    }>;
     http?: RequestOptions;
 }
 export declare function resolveOptions(opts: SlicetestOptions, root: string): ResolvedOptions;
+export {};

package/dist/config.js

@@ -1,27 +1,55 @@
 export function resolveOptions(opts, root) {
     validate(opts);
-    const ready = opts.app.ready ?? { path: "/" };
     return {
         root,
-        app: {
-            ...opts.app,
-            ready: "log" in ready
-                ? typeof ready.log === "string"
-                    ? { log: escapeRegExp(ready.log), flags: "" }
-                    : { log: ready.log.source, flags: ready.log.flags }
-                : ready,
+        app: { ...opts.app, ready: resolveReady(opts.app.ready ?? { path: "/" }) },
+        services: Object.fromEntries(Object.entries(opts.services ?? {}).map(([name, s]) => [name, { ...s, ready: s.ready && resolveReady(s.ready) }])),
+        containers: opts.containers ?? {},
+        db: resolveDb(opts.db ?? {}),
+        stubs: (opts.stubs ?? []).map(stubName),
+        openapi: {
+            app: typeof opts.openapi === "object" ? opts.openapi.spec : opts.openapi,
+            minCoverage: typeof opts.openapi === "object" ? opts.openapi.minCoverage : undefined,
+            stubs: Object.fromEntries((opts.stubs ?? []).flatMap((s) => (typeof s === "object" && s.openapi ? [[s.name, s.openapi]] : []))),
+            autoReply: (opts.stubs ?? []).flatMap((s) => (typeof s === "object" && s.autoReply ? [s.name] : [])),
         },
-        db: {
-            image: "postgres:17-alpine",
-            schemas: ["public"],
-            keep: [],
-            ...opts.db,
-            url: opts.db?.url ?? (process.env.SLICETEST_DATABASE_URL || undefined),
-        },
-        stubs: opts.stubs ?? [],
+        recordings: resolveRecordings(opts.stubs ?? []),
         http: opts.http,
     };
 }
+function resolveRecordings(stubs) {
+    const withUpstream = stubs.filter((s) => typeof s === "object" && !!s.upstream);
+    const env = (process.env.SLICETEST_RECORD ?? "").trim();
+    const all = ["1", "true", "all", "*"].includes(env.toLowerCase());
+    const names = all || !env ? [] : env.split(",").map((n) => n.trim()).filter(Boolean);
+    for (const n of names) {
+        if (!withUpstream.some((s) => s.name === n)) {
+            throw new Error(`slicetest: SLICETEST_RECORD names "${n}", but no stub of that name has an upstream. Stubs with one: ${withUpstream.map((s) => s.name).join(", ") || "(none)"}`);
+        }
+    }
+    return Object.fromEntries(withUpstream.map((s) => [s.name, { file: s.recordings ?? `recordings/${s.name}.yaml`, upstream: s.upstream, record: all || names.includes(s.name) }]));
+}
+function resolveReady(ready) {
+    if (!("log" in ready))
+        return ready;
+    return typeof ready.log === "string" ? { log: escapeRegExp(ready.log), flags: "" } : { log: ready.log.source, flags: ready.log.flags };
+}
+function resolveDb(db) {
+    const isMysql = (u) => /^mysql:/i.test(u);
+    const env = process.env.SLICETEST_DATABASE_URL || undefined;
+    const engine = db.engine ?? (isMysql(db.url ?? env ?? "") ? "mysql" : "postgres");
+    // The environment variable names one server for the whole CI job; a project on the other engine starts its own.
+    const url = db.url ?? (env && isMysql(env) === (engine === "mysql") ? env : undefined);
+    return {
+        image: engine === "mysql" ? "mysql:8.4" : "postgres:17-alpine",
+        schemas: ["public"],
+        keep: [],
+        ...db,
+        engine,
+        url,
+        reuse: db.reuse ?? (!url && !process.env.CI),
+    };
+}
 function validate(opts) {
     const fail = (msg) => {
         throw new Error(`slicetest: invalid config: ${msg}`);
@@ -29,18 +57,62 @@ function validate(opts) {
     if (!opts?.app || typeof opts.app.command !== "string" || !opts.app.command.trim()) {
         fail("app.command is required, e.g. { app: { command: \"node server.js\" } }");
     }
-    const ready = opts.app.ready;
-    if (ready !== undefined && !("path" in ready) && !("log" in ready))
-        fail("app.ready must be { path } or { log }");
-    if (ready && "path" in ready && !ready.path.startsWith("/"))
-        fail(`app.ready.path must start with "/", got "${ready.path}"`);
+    const checkReady = (ready, where) => {
+        if (ready !== undefined && !("path" in ready) && !("log" in ready))
+            fail(`${where}.ready must be { path } or { log }`);
+        if (ready && "path" in ready && !ready.path.startsWith("/"))
+            fail(`${where}.ready.path must start with "/", got "${ready.path}"`);
+    };
+    checkReady(opts.app.ready, "app");
+    for (const [name, s] of Object.entries(opts.services ?? {})) {
+        if (!/^[\w-]+$/.test(name))
+            fail(`service name "${name}" may only contain letters, digits, "_" and "-"`);
+        if (!s || typeof s.command !== "string" || !s.command.trim())
+            fail(`services.${name}.command is required`);
+        checkReady(s.ready, `services.${name}`);
+    }
+    for (const [name, c] of Object.entries(opts.containers ?? {})) {
+        if (!/^[\w-]+$/.test(name))
+            fail(`container name "${name}" may only contain letters, digits, "_" and "-"`);
+        if (!c || typeof c.image !== "string" || !c.image)
+            fail(`containers.${name}.image is required, e.g. "redis:7-alpine"`);
+        if (!Number.isInteger(c.port) || c.port <= 0)
+            fail(`containers.${name}.port must be the port the service listens on inside the container, e.g. 6379`);
+        for (const key of ["command", "reset"]) {
+            const v = c[key];
+            if (v !== undefined && !(Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === "string")))
+                fail(`containers.${name}.${key} must be a list of strings, e.g. ["redis-cli", "FLUSHALL"]`);
+        }
+    }
+    const engine = opts.db?.engine;
+    if (engine !== undefined && engine !== "postgres" && engine !== "mysql")
+        fail(`db.engine must be "postgres" or "mysql", got ${JSON.stringify(engine)}`);
     const migrate = opts.db?.migrate;
     if (migrate) {
         const keys = Object.keys(migrate).filter((k) => ["atlas", "sql", "command"].includes(k));
         if (keys.length !== 1)
             fail(`db.migrate takes exactly one of atlas / sql / command, got ${keys.join(", ") || "none"}`);
     }
-    const stubs = opts.stubs ?? [];
+    const oas = opts.openapi;
+    if (oas !== undefined) {
+        const spec = typeof oas === "object" && oas ? oas.spec : oas;
+        if (typeof spec !== "string" || !spec)
+            fail('openapi must be the path of an OpenAPI file, or { spec, minCoverage }');
+        const min = typeof oas === "object" ? oas.minCoverage : undefined;
+        if (min !== undefined && !(typeof min === "number" && min >= 0 && min <= 100))
+            fail("openapi.minCoverage must be a percentage between 0 and 100");
+    }
+    for (const s of opts.stubs ?? []) {
+        if (typeof s !== "string" && (!s || typeof s.name !== "string"))
+            fail(`each stub must be a name or { name, openapi }, got ${JSON.stringify(s)}`);
+        if (typeof s === "object" && s.autoReply && !s.openapi)
+            fail(`stub "${s.name}": autoReply needs an openapi spec to answer from`);
+        if (typeof s === "object" && s.upstream !== undefined && !/^https?:\/\/[^/]/.test(s.upstream))
+            fail(`stub "${s.name}": upstream must be an http(s) URL, got ${JSON.stringify(s.upstream)}`);
+        if (typeof s === "object" && s.recordings !== undefined && !s.upstream)
+            fail(`stub "${s.name}": recordings needs an upstream to record from`);
+    }
+    const stubs = (opts.stubs ?? []).map(stubName);
     for (const name of stubs) {
         if (!/^[\w-]+$/.test(name))
             fail(`stub name "${name}" may only contain letters, digits, "_" and "-"`);
@@ -49,6 +121,9 @@ function validate(opts) {
     if (dup)
         fail(`stub "${dup}" is declared twice`);
 }
+function stubName(s) {
+    return typeof s === "string" ? s : s.name;
+}
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

package/dist/containers.d.ts

@@ -0,0 +1,22 @@
+import type { ContainerOptions } from "./config.js";
+/**
+ * A container the app depends on (Redis, a search engine, an S3 emulator),
+ * started for one test file and emptied between scenarios with `reset`.
+ */
+export declare class Dependency {
+    readonly name: string;
+    private readonly container;
+    private readonly opts;
+    private constructor();
+    static start(name: string, opts: ContainerOptions): Promise<Dependency>;
+    get host(): string;
+    /** The host port mapped to the container's `port`. */
+    get port(): number;
+    /** `host:port`, to put after a scheme: `redis://{{container.cache}}`. */
+    get address(): string;
+    /** Run a command inside the container; throws with its output unless it exits with 0. */
+    exec(command: string[]): Promise<string>;
+    /** Start of a scenario: run the `reset` command, if any. */
+    reset(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/containers.js

@@ -0,0 +1,59 @@
+import { configureContainerRuntime } from "./container-runtime.js";
+/**
+ * A container the app depends on (Redis, a search engine, an S3 emulator),
+ * started for one test file and emptied between scenarios with `reset`.
+ */
+export class Dependency {
+    name;
+    container;
+    opts;
+    constructor(name, container, opts) {
+        this.name = name;
+        this.container = container;
+        this.opts = opts;
+    }
+    static async start(name, opts) {
+        configureContainerRuntime();
+        const { GenericContainer, Wait } = await import("testcontainers");
+        let definition = new GenericContainer(opts.image).withExposedPorts(opts.port);
+        if (opts.env)
+            definition = definition.withEnvironment(opts.env);
+        if (opts.command)
+            definition = definition.withCommand(opts.command);
+        if (opts.ready)
+            definition = definition.withWaitStrategy(Wait.forLogMessage(opts.ready.log));
+        try {
+            return new Dependency(name, await definition.start(), opts);
+        }
+        catch (e) {
+            throw new Error(`slicetest: container "${name}" (${opts.image}) didn't start: ${e.message}`);
+        }
+    }
+    get host() {
+        return this.container.getHost();
+    }
+    /** The host port mapped to the container's `port`. */
+    get port() {
+        return this.container.getMappedPort(this.opts.port);
+    }
+    /** `host:port`, to put after a scheme: `redis://{{container.cache}}`. */
+    get address() {
+        return `${this.host}:${this.port}`;
+    }
+    /** Run a command inside the container; throws with its output unless it exits with 0. */
+    async exec(command) {
+        const res = await this.container.exec(command);
+        if (res.exitCode !== 0) {
+            throw new Error(`slicetest: \`${command.join(" ")}\` in container "${this.name}" exited with ${res.exitCode}:\n${res.output.trim()}`);
+        }
+        return res.stdout;
+    }
+    /** Start of a scenario: run the `reset` command, if any. */
+    async reset() {
+        if (this.opts.reset)
+            await this.exec(this.opts.reset);
+    }
+    async stop() {
+        await this.container.stop();
+    }
+}

package/dist/db.d.ts

@@ -1,7 +1,5 @@
-export declare function withDatabase(url: string, database: string): string;
-export interface Row {
-    [column: string]: unknown;
-}
+import type { Driver, Row } from "./drivers/driver.js";
+export type { Row } from "./drivers/driver.js";
 /**
  * Column filters. `null` means IS NULL and an array means IN (...);
  * every other value is compared with `=`.
@@ -12,13 +10,30 @@ export interface RowsOptions {
     orderBy?: string | string[];
     limit?: number;
 }
+/** Rows added, changed and removed in one table. */
+export interface TableChanges<T extends Row = Row> {
+    inserted: T[];
+    /**
+     * Matched by primary key (`key`); `changed` lists the columns that differ.
+     * Tables without a primary key only report inserts and deletes.
+     */
+    updated: {
+        key: Row;
+        before: T;
+        after: T;
+        changed: string[];
+    }[];
+    deleted: T[];
+}
+/** Changed tables only, keyed by table name (`schema.table` outside `public`). */
+export type Changes = Record<string, TableChanges>;
 /** Test-side handle to the database the app under test is using. */
 export declare class Db {
     #private;
     readonly url: string;
     private readonly opts;
     private constructor();
-    static connect(url: string, opts: {
+    static connect(driver: Driver, url: string, opts: {
         schemas: string[];
         keep: string[];
         seedFile?: string;
@@ -35,5 +50,22 @@ export declare class Db {
     insert<T extends Row = Row>(table: string, rows: Row | Row[]): Promise<T[]>;
     /** Empty every data table without dropping the app's connections, then re-apply the seed. */
     reset(): Promise<void>;
+    /**
+     * What changed in the database since the scenario started (after the seed),
+     * or since the last `checkpoint()`: inserted, updated and deleted rows per table.
+     *
+     * ```ts
+     * await db.checkpoint();                 // ignore the rows the test arranged
+     * await http.post("/polls", { ... });
+     * expect(await db.changes()).toEqual({ polls: { inserted: [expect.objectContaining({ title: "x" })], updated: [], deleted: [] } });
+     * ```
+     */
+    changes(): Promise<Changes>;
+    /** Make `changes()` report only what happens from now on. */
+    checkpoint(): Promise<void>;
+    /** Changes since the scenario started, regardless of checkpoints. Used for failure output. */
+    changesSinceStart(): Promise<Changes>;
     close(): Promise<void>;
 }
+/** Short summary of `changes()` for failure output. */
+export declare function formatChanges(changes: Changes, maxRows?: number): string;