slicetest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pon-bok
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,296 @@
+# slicetest
+
+[![CI](https://github.com/revo1290/slicetest/actions/workflows/ci.yml/badge.svg)](https://github.com/revo1290/slicetest/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/slicetest)](https://www.npmjs.com/package/slicetest) [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Tests that sit between unit tests and end-to-end tests, for apps written in any language or framework.
+
+slicetest starts your app as a real process, points it at a real Postgres and at stub servers for the services it calls, and lets you check all three sides in one scenario:
+
+```ts
+import { expect } from "vitest";
+import { scenario } from "slicetest";
+
+scenario("creating a poll stores it and notifies Slack", async ({ http, db, stub }) => {
+  stub("slack").on("POST", "/hook").reply(200, "ok");
+
+  const res = await http.post("/polls", { title: "Dogs or cats?", a: "Dogs", b: "Cats" });
+
+  expect(res).toHaveStatus(201);
+  await expect(db).toHaveRow("polls", { title: "Dogs or cats?" });
+  expect(stub("slack")).toHaveReceived("POST", "/hook", { json: { text: "New poll: Dogs or cats?" } });
+});
+```
+
+No browser, no mocked database, no hooks inside your app. The app only has to read its port, database URL and outbound base URLs from environment variables.
+
+## Why
+
+- **Unit tests** mock the database and the network, so broken SQL, migrations and request payloads slip through.
+- **End-to-end tests** drive a browser against a deployed stack. They are slow and hard to make deterministic.
+- **slicetest** keeps the real HTTP server, the real SQL and the real migrations, and replaces only the things you don't own: third-party APIs.
+
+The database is reset between scenarios with a single `TRUNCATE ... RESTART IDENTITY CASCADE` (about 1.5 ms). The app keeps its connections, so this works with any driver or ORM. Resetting by dropping and re-creating the database takes about 130 ms, and it crashed some apps when their pooled connections were cut.
+
+## Install
+
+```sh
+npm i -D slicetest vitest
+```
+
+You also need Docker or Podman. slicetest finds a running Podman machine on its own (on Windows too). Alternatively, pass `db.url` or set `SLICETEST_DATABASE_URL` to use an existing Postgres server, for example a CI service container.
+
+Works on macOS, Linux and Windows. On Windows the app's process tree is stopped with `taskkill /T`, and `app.command` / `db.migrate.command` run through `cmd.exe`.
+
+## Configure
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import { slicetest } from "slicetest/vitest";
+
+export default defineConfig({
+  plugins: [
+    slicetest({
+      app: {
+        command: "python server.py", // any language
+        env: {
+          PORT: "{{app.port}}",
+          DATABASE_URL: "{{db.url}}",
+          SLACK_WEBHOOK_URL: "{{stub.slack}}/hook",
+        },
+        ready: { path: "/health" }, // or { log: "listening" }
+      },
+      db: {
+        migrate: { atlas: { dir: "file://migrations" } }, // or { sql: "schema.sql" } / { command: "npm run migrate" }
+        seed: "seed.sql", // re-applied after every reset
+      },
+      stubs: ["slack"],
+    }),
+  ],
+  test: { include: ["scenarios/**/*.test.ts"] },
+});
+```
+
+### How a run works
+
+1. **Once per run.** slicetest starts `postgres:17-alpine` and migrates a template database.
+2. **Once per worker.** It clones the template into the worker's own database.
+3. **Once per test file.** It starts the stub servers and your app.
+4. **Before each scenario.** It truncates every table except migration bookkeeping tables (`atlas_schema_revisions`, `_prisma_migrations`, `alembic_version`, `django_migrations`, …) and extension-owned tables such as PostGIS's `spatial_ref_sys`, re-runs the seed, and clears the stubs, cookies and request history. If the app crashed in the previous scenario, it is restarted.
+5. **After each scenario.** The scenario fails if the app crashed or called a stub route you didn't register.
+
+Database names are unique per run, so several projects or CI jobs can share one Postgres server via `db.url`.
+
+### When a scenario fails
+
+slicetest prints what happened during that scenario, next to Vitest's own error:
+
+```
+--- slicetest ---
+stub calls with no matching route:
+  mail: POST /send
+    registered on mail: POST /other
+
+requests to the app:
+  POST /signup → 500 (14ms)  {"error":"internal"}
+
+app output during this scenario:
+TypeError: Cannot read properties of undefined (reading 'email')
+-----------------
+```
+
+Only this scenario's app output is shown, not the whole log. Requests that never got a response (for example because the app crashed) appear as `failed`.
+
+## API
+
+Every scenario receives `{ http, db, stub, app }`.
+
+### `http` — talk to the app
+
+```ts
+const res = await http.post("/polls", { title: "x" });   // objects are sent as JSON
+res.status; res.headers; res.text; res.json; res.durationMs;
+
+await http.get("/polls", { query: { page: 2 }, headers: { accept: "text/html" } });
+await http.post("/login", http.form({ user: "a", pass: "b" }));  // urlencoded; FormData, Blob and bytes also work
+await http.get("/old-path", { follow: true });                    // redirects are NOT followed by default
+
+const admin = http.with({ headers: { authorization: `Bearer ${token}` } }); // shares cookies with http
+http.cookies.get("session");                                     // cookies persist within a scenario
+```
+
+Requests may only go to the app under test; absolute URLs to other hosts are rejected. Defaults for every request can be set with `http: { headers }` in the plugin config.
+
+### `db` — arrange and inspect the real database
+
+```ts
+await db.insert("users", [{ name: "a" }, { name: "b" }]);          // returns the stored rows
+const user = await db.one("users", { email: "a@example.com" });    // throws unless exactly one row
+await db.rows("votes", { poll_id: [1, 2], deleted_at: null }, { orderBy: "-id", limit: 10 });
+await db.count("votes", { choice: "a" });
+await db.sql`SELECT * FROM users WHERE id = ${user.id}`;          // values become bind parameters
+await db.query("UPDATE users SET name = $1", ["b"]);
+```
+
+In `where`, `null` means `IS NULL` and an array means `IN (...)`. `bigint` columns (bigserial ids, `count(*)`) come back as numbers when they fit safely.
+
+### `stub(name)` — fake the services the app calls
+
+```ts
+stub("github").on("GET", "/repos/:owner/:repo").reply((call) => ({ body: { name: call.params.repo } }));
+
+stub("stripe")
+  .on("POST", "/v1/charges", {
+    query: { expand: "customer" },
+    headers: { authorization: /^Bearer / },
+    json: { amount: expect.any(Number) },   // subset match; asymmetric matchers and RegExps work anywhere
+  })
+  .reply(200, { id: "ch_1" });
+
+stub("slack").on("POST", "/hook").once().reply(500);          // first call fails, then falls through…
+stub("slack").on("POST", "/hook").reply(200);                 // …to this route: test your retry logic
+stub("pay").on("GET", "/status").replySequence([{ status: 503 }, { status: 200 }]);
+stub("pay").on("POST", "/charge").delay(5_000).reply(200);    // exercise the app's timeouts
+stub("pay").on("POST", "/charge").networkError();             // drop the connection
+
+stub("slack").calls("POST", "/hook");                         // recorded calls: method, path, params, query, headers, body, json
+```
+
+Later routes win. `path` may also be a RegExp, and `method` may be `*`. Unanswered calls get a `501` and fail the scenario.
+
+### Matchers
+
+Registered automatically:
+
+```ts
+expect(res).toHaveStatus(201);                                   // failure shows the response body
+expect(stub("slack")).toHaveReceived("POST", "/hook", { json: { text: "hi" } });
+expect(stub("slack")).toHaveReceivedTimes(1, "POST", "/hook");
+expect(stub("mail")).not.toHaveReceived("POST", "/send");
+await expect(db).toHaveRow("polls", { title: "x" });             // at least one row
+await expect(db).toHaveRow("votes", { poll_id: 1 }, 3);          // exactly three
+```
+
+Failure messages list the calls the stub actually received, or the first rows of the table.
+
+### Scenarios
+
+```ts
+scenario("name", async ({ http, db, stub, app }) => { ... }, timeoutMs?);
+scenario.only / scenario.skip / scenario.todo
+scenario.each([{ choice: "a", status: 204 }, { choice: "x", status: 400 }])(
+  "voting $choice returns $status",
+  async ({ choice, status }, { http }) => { ... },
+);
+```
+
+Scenarios in one file share an app and a database, so they always run one at a time; `.concurrent` is rejected.
+
+### Configuration reference
+
+| Option | Default | |
+|---|---|---|
+| `app.command` | (required) | Shell command. May use `{{app.port}}` and the other placeholders. |
+| `app.env` | `{ PORT, DATABASE_URL }` | Values may use `{{app.port}}`, `{{db.url}}`, `{{stub.<name>}}`. The rest of `process.env` is inherited. |
+| `app.cwd` | vitest root | |
+| `app.ready` | `{ path: "/" }` | Poll a path until it answers below 500, or `{ log: "listening" \| /regex/ }`. |
+| `app.readyTimeout` | `30000` | |
+| `db.migrate` | none | `{ atlas: { dir } }`, `{ sql: "file-or-dir" }` or `{ command }` (gets `DATABASE_URL`). |
+| `db.seed` | none | SQL file re-run after every reset. |
+| `db.schemas` | `["public"]` | Schemas whose tables are reset. |
+| `db.keep` | `[]` | Extra tables (`name` or `schema.name`) never truncated. |
+| `db.url` | `$SLICETEST_DATABASE_URL`, else a container | Use an existing Postgres server (e.g. a CI service container) instead of Testcontainers. |
+| `db.image` | `postgres:17-alpine` | |
+| `stubs` | `[]` | Names of stubbed services. |
+| `http` | `{}` | Default `headers` / `query` for every request. |
+
+The config is validated up front: a missing `app.command`, an ambiguous `db.migrate` or a duplicate stub name fails with a clear message instead of a timeout.
+
+## YAML scenarios
+
+Everything above is also available as data, for teams that don't write JavaScript. Files named `*.scenario.yaml` are picked up automatically, next to your `.test.ts` files, and run with the same app, database and stubs:
+
+```yaml
+# yaml-language-server: $schema=https://unpkg.com/slicetest/schema/scenario.schema.json
+scenarios:
+  - name: creating a poll stores it and notifies Slack
+    steps:
+      - stub: slack
+        on: POST /hook
+        reply: { status: 200, body: ok }
+
+      - request: POST /polls
+        json: { title: Dogs or cats?, a: Dogs, b: Cats }
+        expect:
+          status: 201
+          json: { id: { $type: number } }
+        capture: { pollId: json.id }
+
+      - db: polls
+        where: { title: Dogs or cats? }
+        expect:
+          rows: [{ id: "{{pollId}}", option_a: Dogs }]
+
+      - received: slack
+        call: POST /hook
+        times: 1
+        when:
+          json: { text: "New poll: Dogs or cats?" }
+
+  - name: voting {{choice}} returns {{status}}
+    each:
+      - { choice: a, status: 204 }
+      - { choice: x, status: 400 }
+    steps:
+      - request: POST /polls/1/votes
+        json: { choice: "{{choice}}" }
+        expect: { status: "{{status}}" }
+```
+
+| Step | Keys |
+|---|---|
+| `stub: <name>` | `on: METHOD /path` (`:params` allowed), `when: { query, headers, json, body }`, one of `reply: { status, headers, body }` / `sequence: [...]` / `networkError: true`, plus `times`, `delay`. Replies may echo the call: `{{call.params.id}}`, `{{call.json.name}}`. |
+| `request: METHOD /path` | `headers`, `query`, one of `json` / `form` / `body`, `follow`, `expect: { status, headers, json, text }`, `capture` |
+| `insert: <table>` | `rows`, `capture` (from `row` / `rows`) |
+| `db: <table>` | `where`, `orderBy`, `expect: { rows, count }`, `capture` |
+| `sql: <query>` | `params`, `expect: { rows, count }`, `capture` |
+| `received: <stub>` | `call: METHOD /path`, `when`, `times` (exact; default at least once) |
+
+- `{{name}}` inserts a captured value or an `each` field. A string that is only `{{name}}` keeps the value's type, so `id: "{{pollId}}"` compares as a number.
+- Expected `json`, `rows` and `headers` are subsets: extra keys are fine. `{ $type: number }`, `{ $regex: "^ch_" }`, `{ $contains: "..." }` and `{ $any: true }` match loosely.
+- A file-level `setup:` list runs at the start of every scenario. `skip`, `only` and `timeout` work per scenario.
+- Mistakes are reported with the file and line before anything runs (`polls.scenario.yaml:12: unknown key "stauts" in expect`). A failing step reports its file, line and step number. The JSON Schema in `schema/` gives editors completion and inline errors.
+
+### Without any JavaScript: `npx slicetest`
+
+Put the plugin options in `slicetest.config.yaml` and run the CLI. It needs Node, but no `package.json` scripts, TypeScript or Vitest config:
+
+```yaml
+# slicetest.config.yaml
+app:
+  command: python server.py
+  env: { PORT: "{{app.port}}", DATABASE_URL: "{{db.url}}", SLACK_WEBHOOK_URL: "{{stub.slack}}/hook" }
+  ready: { path: /health }
+db:
+  migrate: { command: alembic upgrade head }
+stubs: [slack]
+```
+
+```sh
+npx slicetest                 # every *.scenario.yaml under the config's directory
+npx slicetest polls -t voting # filter by file and scenario name
+npx slicetest --watch
+```
+
+## Examples
+
+`examples/` has a Node app (`node:http` + `pg`) and a Python app (`http.server` + `psycopg`) with the same API. **The same scenario files (`polls.test.ts` and `polls.scenario.yaml`) run against both**:
+
+```sh
+npm test            # unit tests + both example apps
+npm run test:dist   # the built package, and the CLI with examples/slicetest.config.yaml
+```
+
+## Status
+
+Early prototype. Postgres only. CI runs on Linux and Windows. Planned: container reuse across runs, MySQL.

package/dist/app.d.ts

@@ -0,0 +1,31 @@
+import type { ResolvedOptions } from "./config.js";
+type Exit = {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error;
+};
+/** The app under test, running as a real child process. */
+export declare class App {
+    #private;
+    readonly url: string;
+    private constructor();
+    static start(opts: ResolvedOptions["app"], root: string, vars: Record<string, string>): Promise<App>;
+    get exited(): Exit | undefined;
+    /**
+     * The exit event is delivered asynchronously, so a crash caused by the last
+     * request may not be visible yet. Give it a moment before trusting `exited`.
+     */
+    settle(ms?: number): Promise<Exit | undefined>;
+    /** The app's recent output (last 200 lines), or only what it printed after `since` (a value from `mark()`). */
+    logs(since?: number): string;
+    mark(): number;
+    /**
+     * POSIX: SIGTERM the whole process group, then SIGKILL whatever is left (including orphaned grandchildren).
+     * Windows has no signals to ask politely with, so the tree is terminated at once.
+     */
+    stop(): Promise<void>;
+    /** Synchronous last resort for process exit. */
+    killNow(): void;
+}
+export declare function interpolate(template: string, vars: Record<string, string>, where?: string): string;
+export {};

package/dist/app.js

@@ -0,0 +1,217 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createServer } from "node:net";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+const LOG_LINES = 200;
+/** How long to wait for stdout/stderr to drain after the process exits. */
+const DRAIN_MS = 100;
+const KILL_GRACE_MS = 3000;
+const WINDOWS = process.platform === "win32";
+/** The app under test, running as a real child process. */
+export class App {
+    url;
+    #child;
+    #log = [];
+    /** Lines ever received, so callers can ask for output since a point in time. */
+    #lineCount = 0;
+    #exit;
+    #exited;
+    #onLine;
+    constructor(child, url) {
+        this.url = url;
+        this.#child = child;
+        for (const stream of [child.stdout, child.stderr]) {
+            // Keep partial lines (and split multi-byte characters) until the rest arrives.
+            const decoder = new StringDecoder("utf8");
+            let partial = "";
+            const push = (line) => {
+                if (!line)
+                    return;
+                this.#log.push(line);
+                this.#lineCount++;
+                if (this.#log.length > LOG_LINES)
+                    this.#log.shift();
+                this.#onLine?.(line);
+            };
+            stream.on("data", (chunk) => {
+                const lines = (partial + decoder.write(chunk)).split(/\r?\n/);
+                partial = lines.pop();
+                lines.forEach(push);
+            });
+            stream.on("end", () => push(partial + decoder.end()));
+        }
+        this.#exited = new Promise((resolve) => {
+            const done = (exit) => {
+                this.#exit ??= exit;
+                resolve(this.#exit);
+            };
+            child.on("error", (error) => done({ code: null, signal: null, error }));
+            // 'exit' can fire before the output is read; prefer 'close', but don't wait
+            // forever when a grandchild still holds the pipes open.
+            child.on("exit", (code, signal) => setTimeout(() => done({ code, signal }), DRAIN_MS).unref());
+            child.on("close", (code, signal) => done({ code, signal }));
+        });
+    }
+    static async start(opts, root, vars) {
+        const port = await freePort();
+        vars = { ...vars, "app.port": String(port) };
+        const env = opts.env ?? { PORT: "{{app.port}}", DATABASE_URL: "{{db.url}}" };
+        const child = spawn(interpolate(opts.command, vars, "app.command"), {
+            shell: true,
+            cwd: path.resolve(root, opts.cwd ?? "."),
+            env: { ...process.env, ...mapValues(env, (v) => interpolate(v, vars, "app.env")) },
+            stdio: ["ignore", "pipe", "pipe"],
+            // POSIX: own process group, so stop() also kills whatever the shell spawned.
+            // Windows: detaching would open a console window; taskkill /T walks the tree instead.
+            detached: !WINDOWS,
+            windowsHide: true,
+        });
+        const app = new App(child, `http://127.0.0.1:${port}`);
+        running.add(app);
+        try {
+            await app.#waitReady(opts);
+        }
+        catch (e) {
+            await app.stop();
+            throw e;
+        }
+        return app;
+    }
+    get exited() {
+        return this.#exit;
+    }
+    /**
+     * The exit event is delivered asynchronously, so a crash caused by the last
+     * request may not be visible yet. Give it a moment before trusting `exited`.
+     */
+    async settle(ms = 20) {
+        if (this.#exit)
+            return this.#exit;
+        let timer;
+        await Promise.race([this.#exited, new Promise((r) => (timer = setTimeout(r, ms)))]);
+        clearTimeout(timer);
+        return this.#exit;
+    }
+    /** The app's recent output (last 200 lines), or only what it printed after `since` (a value from `mark()`). */
+    logs(since) {
+        if (since === undefined)
+            return this.#log.join("\n");
+        const n = Math.min(this.#lineCount - since, this.#log.length);
+        return n > 0 ? this.#log.slice(-n).join("\n") : "";
+    }
+    mark() {
+        return this.#lineCount;
+    }
+    /**
+     * POSIX: SIGTERM the whole process group, then SIGKILL whatever is left (including orphaned grandchildren).
+     * Windows has no signals to ask politely with, so the tree is terminated at once.
+     */
+    async stop() {
+        running.delete(this);
+        const pid = this.#child.pid;
+        if (pid === undefined)
+            return;
+        if (WINDOWS) {
+            if (!this.#exit)
+                killTree(pid);
+            await this.settle(KILL_GRACE_MS);
+            return;
+        }
+        if (!this.#exit) {
+            killGroup(pid, "SIGTERM");
+            let timer;
+            await Promise.race([this.#exited, new Promise((r) => (timer = setTimeout(r, KILL_GRACE_MS)))]);
+            clearTimeout(timer);
+        }
+        killGroup(pid, "SIGKILL");
+    }
+    /** Synchronous last resort for process exit. */
+    killNow() {
+        const pid = this.#child.pid;
+        if (pid === undefined)
+            return;
+        if (WINDOWS)
+            killTree(pid);
+        else
+            killGroup(pid, "SIGKILL");
+    }
+    async #waitReady(opts) {
+        const timeout = opts.readyTimeout ?? 30_000;
+        const deadline = Date.now() + timeout;
+        const ready = opts.ready;
+        let logSeen = false;
+        if ("log" in ready) {
+            // Drop g/y so test() doesn't keep state between lines.
+            const pattern = new RegExp(ready.log, ready.flags.replace(/[gy]/g, ""));
+            logSeen = this.#log.some((l) => pattern.test(l));
+            this.#onLine = (line) => (logSeen ||= pattern.test(line));
+        }
+        try {
+            while (Date.now() < deadline) {
+                if (this.#exit) {
+                    const why = this.#exit.error ? this.#exit.error.message : `code ${this.#exit.code}, signal ${this.#exit.signal}`;
+                    throw new Error(`slicetest: app exited before becoming ready (${why})\n${this.logs()}`);
+                }
+                if ("log" in ready) {
+                    if (logSeen)
+                        return;
+                }
+                else {
+                    try {
+                        const res = await fetch(this.url + ready.path, { signal: AbortSignal.timeout(1000) });
+                        await res.body?.cancel();
+                        // Our child may not own the port yet if something else grabbed it; only trust a live child.
+                        if (res.status < 500 && !this.#exit)
+                            return;
+                    }
+                    catch { }
+                }
+                await new Promise((r) => setTimeout(r, 50));
+            }
+            throw new Error(`slicetest: app did not become ready within ${timeout}ms\n${this.logs()}`);
+        }
+        finally {
+            this.#onLine = undefined;
+        }
+    }
+}
+/** Apps still running, killed synchronously if the worker exits without tearing down. */
+const running = new Set();
+process.once("exit", () => {
+    for (const app of running)
+        app.killNow();
+});
+/** Windows: terminate the shell and everything it started. Synchronous so it also works on process exit. */
+function killTree(pid) {
+    spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+}
+function killGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        // Group already gone.
+    }
+}
+export function interpolate(template, vars, where = "app.env") {
+    return template.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (_, key) => {
+        if (!(key in vars)) {
+            throw new Error(`slicetest: unknown placeholder {{${key}}} in ${where}. Available: ${Object.keys(vars).map((k) => `{{${k}}}`).join(", ")}`);
+        }
+        return vars[key];
+    });
+}
+function mapValues(obj, fn) {
+    return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, fn(v)]));
+}
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.unref();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const { port } = srv.address();
+            srv.close(() => resolve(port));
+        });
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import type { SlicetestOptions } from "./config.js";
+export interface CliConfig extends SlicetestOptions {
+    include?: string[];
+}
+export declare function main(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * `npx slicetest`: run YAML scenarios without writing any JavaScript.
+ * Reads slicetest.config.yaml (the same options as the Vitest plugin) and
+ * drives Vitest programmatically.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+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]
+
+Runs *.scenario.yaml files against your app, as configured in slicetest.config.yaml.
+
+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
+  -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}"]
+`;
+export async function main(argv = process.argv.slice(2)) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            config: { type: "string", short: "c" },
+            watch: { type: "boolean", short: "w" },
+            name: { type: "string", short: "t" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    if (values.help) {
+        process.stdout.write(HELP);
+        return;
+    }
+    const configPath = values.config
+        ? path.resolve(values.config)
+        : CONFIG_NAMES.map((n) => path.resolve(n)).find((p) => existsSync(p));
+    if (!configPath || !existsSync(configPath)) {
+        process.stderr.write(`slicetest: no config found. Create ${CONFIG_NAMES[0]} (see --help).\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const { include, ...options } = (parse(await readFile(configPath, "utf8")) ?? {});
+    const { startVitest } = await import("vitest/node");
+    const { slicetest, YAML_SCENARIOS } = await import("./vitest.js");
+    const vitest = await startVitest(positionals, {
+        config: false,
+        root: path.dirname(configPath),
+        include: include ?? [YAML_SCENARIOS],
+        watch: !!values.watch,
+        run: !values.watch,
+        testNamePattern: values.name,
+    }, { plugins: [slicetest(options)] });
+    if (!values.watch)
+        await vitest?.close();
+}
+main().catch((e) => {
+    process.stderr.write(`${e instanceof Error ? e.message : e}\n`);
+    process.exitCode = 1;
+});