@substrio/cli 0.0.0-stage → 0.1.0

package/src/sdk.mjs

@@ -0,0 +1,26 @@
+/**
+ * The one place the CLI loads the SDK's generated operation client.
+ *
+ * An installed CLI resolves it by package name (@substrio/sdk, a declared
+ * dependency). A substrio checkout runs the CLI with no install step, so when the
+ * package is not found the client loads from the sibling packages/substrio-sdk.
+ * Only "module not found" falls back; any other load error is rethrown.
+ */
+
+export const PACKAGE = '@substrio/sdk/operation-client';
+const CHECKOUT = new URL('../../substrio-sdk/substrio_operation_client.mjs', import.meta.url).href;
+
+async function load() {
+  try {
+    return { client: await import(PACKAGE), source: 'package' };
+  } catch (err) {
+    if (err?.code !== 'ERR_MODULE_NOT_FOUND') throw err;
+    return { client: await import(CHECKOUT), source: 'checkout' };
+  }
+}
+
+const { client, source } = await load();
+
+/** Where the client came from: 'package' (installed) or 'checkout'. */
+export const sdkSource = source;
+export const { buildRequest, catalogRoute, pickRoute, routeParams } = client;

package/src/settings.mjs

@@ -0,0 +1,117 @@
+/**
+ * Substrio CLI: the app's settings substrio.toml declares, carried in the version
+ * `substrio push` makes and applied when that version goes live (the sandbox on
+ * push, the app on promote, the older ones again on a rollback):
+ *
+ *   plans_file = "plans.json"               # version member "plans", as POST /v1/_plans takes
+ *   [auth]                                  # version member "auth", as PUT /v1/_auth/settings takes
+ *   email_function = "send_auth_mail"
+ *   reset_url = "https://app.example/reset?token={token}"
+ *   verify_url_env = "APP_VERIFY_URL"       # a value that differs between environments (the site of a
+ *                                           # development deploy and of the live one): the NAME of the
+ *                                           # variable that holds it, in place of the value (never both);
+ *                                           # a variable that is not set refuses the config
+ *
+ * The keys a settings table accepts are the properties of its operation's
+ * input schema in the server's GET /v1/_openapi (generated from the
+ * operation registry), so a new setting needs no change here. A key the
+ * schema does not declare fails the push before anything is sent. An absent
+ * table or plans_file leaves the target's settings as they are. The
+ * functions here do no network.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { PROVIDERS_KEY, unsetMessage, valueOrEnv } from './identity.mjs';
+import { findOperation } from './ops.mjs';
+
+/**
+ * @typedef {object} SettingsTable
+ * @property {string} table      substrio.toml table name, such as "auth"
+ * @property {string} operation  registry operation whose input schema it follows
+ * @property {string} member     the version member that carries it
+ * @property {string} label      what the CLI calls it in its output
+ * @property {string} [apart]   a key of the table that is not a setting (another module applies it)
+ */
+
+/** @type {readonly SettingsTable[]} */
+export const SETTINGS_TABLES = Object.freeze([
+    Object.freeze({ table: 'auth', operation: 'auth.settings.set', member: 'auth', label: 'Auth settings', apart: PROVIDERS_KEY }),
+    Object.freeze({ table: 'login', operation: 'auth.login.set', member: 'login', label: 'Shared login' }),
+]);
+
+const isTable = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const FROM_ENV = '_env';
+const plain = (message) => new Error(message);
+
+/**
+ * The settings tables substrio.toml declares, in SETTINGS_TABLES order:
+ * [{table, operation, label, values}], each value written in the file or read from the
+ * variable its `<key>_env` names (`env`, process.env by default; identity.mjs valueOrEnv).
+ * Throws when one is not a table, or a named variable is not set. [auth.providers.NAME]
+ * tables are not settings (identity.mjs applies them): `values` leaves them out, and a
+ * table that holds nothing else is not declared.
+ */
+export function declaredSettings(config, env = process.env) {
+    const declared = [];
+    for (const spec of SETTINGS_TABLES) {
+        const values = config[spec.table];
+        if (values === undefined || values === null) continue;
+        if (!isTable(values)) throw new Error(`[${spec.table}] must be a table of settings`);
+        const where = `[${spec.table}]`;
+        const own = {};
+        for (const written of Object.keys(values)) {
+            if (written === spec.apart) continue;
+            const key = written.endsWith(FROM_ENV) ? written.slice(0, -FROM_ENV.length) : written;
+            if (Object.hasOwn(own, key)) continue;
+            const value = valueOrEnv(where, values, key, env, plain);
+            if (value === null) throw plain(unsetMessage(where, values, key));
+            own[key] = value;
+        }
+        if (Object.keys(own).length === 0 && Object.keys(values).length > 0) continue;
+        declared.push({ ...spec, values: own });
+    }
+    return declared;
+}
+
+/**
+ * Checks each declared table's keys against its operation's input schema in
+ * the indexed operations `ops` (ops.mjs indexOperations). Throws naming the
+ * first unknown key and the keys the table accepts.
+ */
+export function checkSettings(declared, ops) {
+    for (const setting of declared) {
+        const routes = findOperation(ops, setting.operation);
+        const schema = routes.find((r) => r.bodySchema)?.bodySchema;
+        const known = Object.keys(schema?.properties ?? {});
+        const unknown = Object.keys(setting.values).find((key) => !known.includes(key));
+        if (unknown !== undefined) {
+            throw new Error(`[${setting.table}] has unknown key "${unknown}"; it accepts ${known.join(', ') || 'no keys'}`);
+        }
+    }
+}
+
+/**
+ * The plans substrio.toml's plans_file names, parsed (the body POST /v1/_plans
+ * takes), or null when it names none. Throws when the file is missing or is
+ * not JSON.
+ */
+export function declaredPlans(config, cwd) {
+    if (!config.plans_file) return null;
+    const path = resolve(cwd, config.plans_file);
+    if (!existsSync(path)) throw new Error(`plans_file ${config.plans_file} does not exist`);
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    } catch (err) {
+        throw new Error(`plans_file ${config.plans_file} is not JSON: ${err.message}`);
+    }
+}
+
+/** Puts the declared settings and plans into a version body as its members. */
+export function carrySettings(body, declared, plans) {
+    for (const setting of declared) body[setting.member] = setting.values;
+    if (plans !== null) body.plans = plans;
+    return body;
+}

package/src/testing/app.mjs

@@ -0,0 +1,507 @@
+/**
+ * The test harness of `substrio test`: an isolated test tenant per `startApp()`,
+ * the app applied to it exactly as `substrio dev` applies it, and typed ways to call
+ * its functions, cron schedules and triggers directly, to read and write its
+ * data and logs, to stub the outbound fetches its functions make and to move
+ * its clock.
+ *
+ * Everything here runs over a Transport, one function
+ * `(operation, input) => {ok, status, data, text}`; the real one is the test
+ * tenant's own API client (transportOf), a unit test passes a fake.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { request as httpRequest } from 'node:http';
+
+import { errorText } from '../api.mjs';
+import { loadApp, makeLive, publishVersion, readApp } from '../apply.mjs';
+import { applyCollections } from '../collections.mjs';
+import { CliError } from '../cli.mjs';
+import { OpError, callOperation } from '../commands/op.mjs';
+import { followLogs } from '../commands/logs.mjs';
+import { LocalServer } from '../local/server.mjs';
+import { readTestEnv } from './env.mjs';
+import {
+    CallOutcome, ClockMode, HttpMethod, Level, PathMatch, RunOutcome, TestError, TestErrorCode, TriggerKind, member,
+} from './types.mjs';
+
+/** The Transport of a tenant's API client. A refused name or input is a TestError, a server error is data. */
+export function transportOf(api, ops) {
+    return async (name, input) => {
+        try {
+            return await callOperation(api, ops, name, input);
+        } catch (err) {
+            if (err instanceof OpError) throw new TestError(err.message, TestErrorCode.INVALID_ARGUMENT);
+            throw err;
+        }
+    };
+}
+
+/** The data of an answer that must be ok, else the server's typed error as a CliError. */
+function expectOk(result, what) {
+    if (result.ok) return result.data;
+    throw CliError.fromResponse(`${what}: ${errorText(result.data, result.status)}`, result.data, result.status);
+}
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+/** The documents of one collection a test starts with. */
+export class Fixture {
+    constructor(collection, documents) {
+        if (typeof collection !== 'string' || collection === '') {
+            throw new TestError('A fixture needs the name of its collection', TestErrorCode.INVALID_FIXTURE);
+        }
+        if (!Array.isArray(documents) || documents.some((d) => d === null || typeof d !== 'object' || Array.isArray(d))) {
+            throw new TestError(`The documents of fixture ${collection} must be an array of objects`, TestErrorCode.INVALID_FIXTURE);
+        }
+        this.collection = collection;
+        this.documents = documents;
+    }
+}
+
+export const fixture = (collection, documents) => new Fixture(collection, documents);
+
+// ---------------------------------------------------------------------------
+// Calling functions, cron and triggers
+// ---------------------------------------------------------------------------
+
+/** One call of a function: how it ended, its answer, or its typed error. */
+export class Run {
+    constructor({ outcome, status, value = null, error = null, durationMs = null }) {
+        this.outcome = outcome;
+        this.status = status;
+        this.value = value;       // OK: the function's answer, parsed as JSON when it is
+        this.error = error;       // ERROR: {code, message, functionError}
+        this.durationMs = durationMs;
+    }
+
+    get ok() { return this.outcome === RunOutcome.OK; }
+}
+
+function runOf(result) {
+    if (result.ok) {
+        return new Run({ outcome: RunOutcome.OK, status: result.status, value: result.data !== undefined ? result.data : result.text });
+    }
+    const body = result.data ?? {};
+    return new Run({
+        outcome: RunOutcome.ERROR,
+        status: result.status,
+        error: { code: body.code ?? null, message: errorText(result.data, result.status), functionError: body.function_error ?? null },
+    });
+}
+
+/** A deployed function, by a name the app really has. */
+export class FunctionRef {
+    constructor(name, transport) {
+        this.name = name;
+        this.transport = transport;
+    }
+
+    /** Calls it with `event` (any JSON); never throws on a function that throws: that is Run.outcome ERROR. */
+    async call(event = {}) {
+        return runOf(await this.transport('function.invoke', { name: this.name, event }));
+    }
+}
+
+/**
+ * The event a collection trigger hands its function (the one the server builds on a write):
+ * {trigger: {type, collection, documentId, timestamp, data}}, `data` left out for a delete.
+ */
+export function triggerEvent({ kind, collection, id = '', data = undefined, timestamp }) {
+    member(TriggerKind, kind, 'a trigger kind');
+    if (typeof collection !== 'string' || collection === '') {
+        throw new TestError('A trigger needs its collection', TestErrorCode.INVALID_ARGUMENT);
+    }
+    return {
+        trigger: {
+            type: kind, collection, documentId: id, timestamp,
+            ...(kind !== TriggerKind.DELETE && data !== undefined ? { data } : {}),
+        },
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Data
+// ---------------------------------------------------------------------------
+
+/** One collection of the test tenant, over the data operations. */
+export class TestCollection {
+    constructor(name, transport) {
+        this.name = name;
+        this.transport = transport;
+    }
+
+    /** Stores `document` under a new id; returns the stored record's _id. */
+    async insert(document) {
+        const answer = expectOk(await this.transport('data.insert', { collection: this.name, document }), `insert into ${this.name}`);
+        return answer._id ?? answer.id;
+    }
+
+    /** Stores every document of `documents` (data.import): their own _id kept when they name one. */
+    async load(documents) {
+        const answer = expectOk(await this.transport('data.import', { collection: this.name, documents }), `import into ${this.name}`);
+        if (answer.errors?.length) {
+            throw new TestError(`import into ${this.name} refused ${answer.errors.length} documents: ${JSON.stringify(answer.errors[0])}`, TestErrorCode.INVALID_FIXTURE);
+        }
+        return answer.inserted;
+    }
+
+    /** The record with `id`, or null. */
+    async get(id) {
+        const result = await this.transport('data.get', { collection: this.name, id });
+        if (result.status === 404) return null;
+        return expectOk(result, `get ${this.name}/${id}`);
+    }
+
+    /** The records matching `where` (a data.query filter; every record when none), in `sort` order, at most `limit`. */
+    async find(where = {}, { sort, limit } = {}) {
+        const answer = expectOk(await this.transport('data.query', {
+            collection: this.name, where, ...(sort ? { sort } : {}), ...(limit ? { limit } : {}),
+        }), `query ${this.name}`);
+        return answer.data ?? answer.results ?? answer.records ?? [];
+    }
+
+    /** How many records match `where` (every record when it has no field); 0 for a collection never made. */
+    async count(where = {}) {
+        // An empty filter is no filter, and query.count's GET route has no `where`
+        // query option: an empty one is left out rather than sent.
+        const input = Object.keys(where).length > 0 ? { collection: this.name, where } : { collection: this.name };
+        const result = await this.transport('query.count', input);
+        if (result.status === 404) return 0;
+        const answer = expectOk(result, `count ${this.name}`);
+        return answer.count;
+    }
+
+    async delete(id) {
+        expectOk(await this.transport('data.delete', { collection: this.name, id }), `delete ${this.name}/${id}`);
+    }
+}
+
+export class TestDb {
+    constructor(transport) { this.transport = transport; }
+
+    collection(name) { return new TestCollection(name, this.transport); }
+
+    /** Loads fixtures: every Fixture's documents into its collection. */
+    async load(fixtures) {
+        for (const f of fixtures) {
+            if (!(f instanceof Fixture)) throw new TestError('load() takes fixture(collection, documents) values', TestErrorCode.INVALID_FIXTURE);
+            await this.collection(f.collection).load(f.documents);
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Logs
+// ---------------------------------------------------------------------------
+
+const DEFAULT_WAIT_MS = 10_000;
+
+export class TestLogs {
+    /**
+     * @param {Function} transport
+     * @param {(filter: object, onEntry: Function, signal: AbortSignal, onConnected: Function) => Promise<void>} follow
+     */
+    constructor(transport, follow) {
+        this.transport = transport;
+        this.follow = follow;
+    }
+
+    /** The log lines now stored, oldest first, of `function` and/or at `level`. */
+    async entries({ function: fn, level, requestId, limit } = {}) {
+        if (level !== undefined) member(Level, level, 'a log level');
+        const answer = expectOk(await this.transport('function.logs', {
+            ...(fn ? { function: fn } : {}), ...(level ? { level } : {}),
+            ...(requestId ? { request_id: requestId } : {}), ...(limit ? { limit } : {}),
+        }), 'read logs');
+        return answer.logs ?? [];
+    }
+
+    /** The message of each line of entries(filter). */
+    async messages(filter = {}) {
+        return (await this.entries(filter)).map((e) => e.message ?? e.msg);
+    }
+
+    /**
+     * Resolves with the first log line (stored now, or arriving later) for which `predicate(entry)` is true, waiting on
+     * the log stream, never on a timer, but giving up with a TestError TIMEOUT at `timeoutMs`. This is how a test waits for
+     * what a trigger or another asynchronous run logs.
+     */
+    async waitFor(predicate, { timeoutMs = DEFAULT_WAIT_MS, function: fn, level } = {}) {
+        const abort = new AbortController();
+        const filter = { ...(fn ? { function: fn } : {}), ...(level ? { level } : {}) };
+        let arrived;
+        const found = new Promise((resolve) => { arrived = resolve; });
+        let connected;
+        const ready = new Promise((resolve) => { connected = resolve; });
+        const following = this.follow(filter, (entry) => { if (predicate(entry)) arrived(entry); }, abort.signal, connected);
+        const deadline = new Promise((_, reject) => {
+            const timer = setTimeout(() => reject(new TestError(`No log line matched within ${timeoutMs} ms`, TestErrorCode.TIMEOUT)), timeoutMs);
+            found.finally(() => clearTimeout(timer));
+            abort.signal.addEventListener('abort', () => clearTimeout(timer), { once: true });
+        });
+        try {
+            // Subscribed first, so nothing logged from here on is missed; then what is already stored.
+            await Promise.race([ready, following, deadline]);
+            const stored = (await this.entries(filter)).find(predicate);
+            if (stored !== undefined) return stored;
+            return await Promise.race([found, deadline, following.then(() => { throw new TestError('The log stream ended', TestErrorCode.TIMEOUT); })]);
+        } finally {
+            abort.abort();
+            await following.catch(() => {});
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Fetch stubs and calls
+// ---------------------------------------------------------------------------
+
+/** A fetch a function made, as the server recorded it. */
+export class FetchCall {
+    constructor(record) {
+        this.seq = record.seq;
+        this.atMs = record.at_ms;
+        this.method = record.method;
+        this.url = record.url;
+        this.headers = record.headers;
+        this.body = record.body;
+        this.outcome = member(CallOutcome, record.outcome, 'a call outcome');
+        this.stubId = record.stub_id;
+    }
+
+    /** The request body parsed as JSON. */
+    json() { return JSON.parse(this.body); }
+}
+
+/** The outbound requests of the test tenant's functions: stubbed, and recorded. Anything unstubbed is rejected. */
+export class FetchStubs {
+    constructor(transport) { this.transport = transport; }
+
+    /**
+     * Stubs one request. `method` omitted: any method. `json` or `text` is the response body (not both);
+     * `times` answers before the stub is spent (omitted: no limit). Returns the stub's id.
+     */
+    async stub({ method, url, pathMatch = PathMatch.EXACT, status = 200, headers = {}, json, text, times } = {}) {
+        if (typeof url !== 'string' || url === '') throw new TestError('A stub needs the url its function fetches', TestErrorCode.INVALID_ARGUMENT);
+        if (method !== undefined) member(HttpMethod, method, 'a stub method');
+        member(PathMatch, pathMatch, 'a stub path match');
+        if (!Number.isInteger(status) || status < 100 || status > 599) throw new TestError('A stub status is a whole number from 100 to 599', TestErrorCode.INVALID_ARGUMENT);
+        if (json !== undefined && text !== undefined) throw new TestError('A stub has json or text, not both', TestErrorCode.INVALID_ARGUMENT);
+        if (times !== undefined && (!Number.isInteger(times) || times < 0)) throw new TestError('A stub times is a whole number, 0 for no limit', TestErrorCode.INVALID_ARGUMENT);
+        const body = json !== undefined ? JSON.stringify(json) : (text ?? '');
+        const withType = json !== undefined && !Object.keys(headers).some((h) => h.toLowerCase() === 'content-type')
+            ? { 'content-type': 'application/json', ...headers } : headers;
+        const answer = expectOk(await this.transport('sandbox.stub.set', {
+            ...(method ? { method } : {}), url, path_match: pathMatch, status, headers: withType, body,
+            ...(times !== undefined ? { times } : {}),
+        }), `stub ${url}`);
+        return answer.id;
+    }
+
+    /** Every fetch made since the last clear, oldest first. */
+    async calls() {
+        return expectOk(await this.transport('sandbox.stub.list', {}), 'read fetch calls').calls.map((c) => new FetchCall(c));
+    }
+
+    /** The stubs, with how often each answered. */
+    async stubs() {
+        return expectOk(await this.transport('sandbox.stub.list', {}), 'read stubs').stubs;
+    }
+
+    /** Forgets every stub and every recorded call. */
+    async clear() {
+        const answer = expectOk(await this.transport('sandbox.stub.clear', {}), 'clear stubs');
+        return { stubs: answer.cleared_stubs, calls: answer.cleared_calls };
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Clock
+// ---------------------------------------------------------------------------
+
+/** The test tenant's clock: what Date.now() and new Date() give its functions. setTimeout and cron stay on real time. */
+export class TestTenantClock {
+    #setting = { mode: ClockMode.REAL, at: null, offsetMs: null };
+
+    constructor(transport) { this.transport = transport; }
+
+    async #set(body) {
+        const answer = expectOk(await this.transport('tenant.clock.set', body), 'set the clock');
+        this.#setting = { mode: answer.mode, at: answer.at, offsetMs: answer.offset_ms };
+        return { mode: answer.mode, at: answer.at, offsetMs: answer.offset_ms, nowMs: answer.now_ms };
+    }
+
+    /** Freezes the clock at `at`: a Date or Unix milliseconds. */
+    freeze(at) {
+        const ms = at instanceof Date ? at.getTime() : at;
+        if (!Number.isInteger(ms)) throw new TestError('freeze takes a Date or whole Unix milliseconds', TestErrorCode.INVALID_ARGUMENT);
+        return this.#set({ mode: ClockMode.FROZEN, at: ms });
+    }
+
+    /** Real time plus `ms` (negative: earlier). */
+    offset(ms) {
+        if (!Number.isInteger(ms)) throw new TestError('offset takes whole milliseconds', TestErrorCode.INVALID_ARGUMENT);
+        return this.#set({ mode: ClockMode.OFFSET, offset_ms: ms });
+    }
+
+    /** Moves the clock on by `ms`: a frozen clock stays frozen, anything else gets that much more offset. */
+    advance(ms) {
+        if (!Number.isInteger(ms)) throw new TestError('advance takes whole milliseconds', TestErrorCode.INVALID_ARGUMENT);
+        const { mode, at, offsetMs } = this.#setting;
+        if (mode === ClockMode.FROZEN) return this.freeze(at + ms);
+        return this.offset((mode === ClockMode.OFFSET ? offsetMs : 0) + ms);
+    }
+
+    /** Real time again. */
+    release() { return this.#set({ mode: ClockMode.REAL }); }
+
+    /** The clock's reading now, in Unix milliseconds. */
+    async now() {
+        const { mode, at, offsetMs } = this.#setting;
+        const body = mode === ClockMode.FROZEN ? { mode, at } : mode === ClockMode.OFFSET ? { mode, offset_ms: offsetMs } : { mode };
+        return (await this.#set(body)).nowMs;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// The app
+// ---------------------------------------------------------------------------
+
+/** An HTTP request to the test tenant's routes, with its Host (node:http: fetch would drop it). */
+export function httpTo({ base, host }) {
+    const url = new URL(base);
+    return (method, path, { headers = {}, body } = {}) => new Promise((resolve, reject) => {
+        member(HttpMethod, method, 'a request method');
+        const payload = body === undefined ? undefined : typeof body === 'string' || Buffer.isBuffer(body) ? body : JSON.stringify(body);
+        const req = httpRequest({
+            host: url.hostname, port: url.port, method, path,
+            headers: {
+                host: `${host}:${url.port}`,
+                ...(payload !== undefined ? { 'content-length': Buffer.byteLength(payload), 'content-type': typeof body === 'string' ? 'text/plain' : 'application/json' } : {}),
+                ...headers,
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => {
+                const text = Buffer.concat(chunks).toString('utf8');
+                resolve({ status: res.statusCode, headers: new Headers(res.headers), text, json: () => JSON.parse(text) });
+            });
+        });
+        req.on('error', reject);
+        if (payload !== undefined) req.write(payload);
+        req.end();
+    });
+}
+
+/** One isolated test tenant running the app. */
+export class TestApp {
+    /**
+     * @param {object} parts
+     * @param {string} parts.slug the tenant's slug
+     * @param {string[]} parts.functions the names of the functions the app deploys
+     * @param {Function} parts.transport
+     * @param {Function} parts.follow log stream (see TestLogs)
+     * @param {Function} parts.http (method, path, options) => response
+     * @param {() => Promise<void>} parts.dispose removes the tenant
+     */
+    constructor({ slug, functions, transport, follow, http, dispose }) {
+        this.slug = slug;
+        this.functions = functions;
+        this.transport = transport;
+        this.db = new TestDb(transport);
+        this.logs = new TestLogs(transport, follow);
+        this.fetch = new FetchStubs(transport);
+        this.clock = new TestTenantClock(transport);
+        this.http = http;
+        this.dispose = dispose;
+        this.closed = null;
+    }
+
+    /** The function `name`; a name the app does not deploy is a TestError listing the ones it does. */
+    fn(name) {
+        if (!this.functions.includes(name)) {
+            throw new TestError(`The app deploys no function ${JSON.stringify(name)}; it deploys ${this.functions.join(', ') || 'none'}`, TestErrorCode.UNKNOWN_FUNCTION);
+        }
+        return new FunctionRef(name, this.transport);
+    }
+
+    /** Runs the schedule of `functionName` now (schedule.run) with its cron event; a Run of how it ended. */
+    async cron(functionName) {
+        const listed = expectOk(await this.transport('schedule.list', {}), 'list schedules');
+        const entries = listed.cron_triggers ?? listed.schedules ?? [];
+        const entry = entries.find((e) => (e.function ?? e.function_name) === functionName);
+        if (entry === undefined) {
+            throw new TestError(`The app has no [[cron]] for ${JSON.stringify(functionName)}; it has ${entries.map((e) => e.function ?? e.function_name).join(', ') || 'none'}`, TestErrorCode.NO_SCHEDULE);
+        }
+        const result = await this.transport('schedule.run', { id: entry.id });
+        if (!result.ok) return runOf(result);
+        const run = result.data;
+        return new Run({
+            outcome: run.outcome === 'ok' ? RunOutcome.OK : RunOutcome.ERROR, status: result.status, value: run.result ?? null,
+            error: run.outcome === 'ok' ? null : { code: null, message: run.error ?? 'the run failed', functionError: run.error_id ?? null },
+            durationMs: run.duration_ms,
+        });
+    }
+
+    /** Calls `functionName` as the trigger of a change would (the event the server builds), directly. */
+    async trigger(functionName, { kind, collection, id, data }) {
+        const event = triggerEvent({ kind, collection, id, data, timestamp: await this.clock.now() });
+        return this.fn(functionName).call(event);
+    }
+
+    /** Removes the tenant and everything in it. Safe to call again. */
+    close() {
+        this.closed ??= this.dispose();
+        return this.closed;
+    }
+}
+
+/**
+ * Makes a test tenant on the server `substrio test` runs, applies the app to it (the
+ * way `substrio dev` does: one version of substrio.toml and its files), loads `fixtures`
+ * and returns the TestApp. Every call is a new tenant: no data, stub or clock is
+ * shared between two. Pass the node:test context as `context` to have the tenant
+ * removed after the test.
+ */
+export async function startApp({ fixtures = [], cwd = null, context = null, env = process.env } = {}) {
+    const test = readTestEnv(env);
+    const appDir = cwd ?? test.appDir;
+    for (const f of fixtures) if (!(f instanceof Fixture)) throw new TestError('fixtures are fixture(collection, documents) values', TestErrorCode.INVALID_FIXTURE);
+    const server = LocalServer.attach({ url: test.url, masterKey: readFileSync(test.keyFile, 'utf8').trim() });
+    const slug = `t${randomBytes(6).toString('hex')}`;
+    const tenant = await server.createTenant(slug, { test: true });
+    const dispose = () => server.deleteTenant(slug);
+    try {
+        const { config, manifest } = readApp(appDir);
+        // No sidecars for tests: brotli at its best quality per tenant would be slow.
+        const plain = manifest.site ? { ...manifest, site: { ...manifest.site, precompress: null } } : manifest;
+        const loaded = await loadApp(config, plain, appDir, undefined);
+        // The app's declared collections and schemas, as `substrio dev` has them, before the version whose rules are about them.
+        await applyCollections(tenant.invoke, loaded.collections);
+        const published = await publishVersion(tenant.api, tenant.ops, loaded, tenant.invoke);
+        await makeLive(tenant.invoke, published.number, { backup: false });
+        const transport = transportOf(tenant.api, tenant.ops);
+        const app = new TestApp({
+            slug,
+            functions: loaded.app.functions.map((f) => f.name),
+            transport,
+            follow: (filter, onEntry, signal, onConnected) => followLogs(tenant.api, filter, onEntry, signal, onConnected),
+            http: httpTo({ base: server.url, host: `${slug}.localhost` }),
+            dispose,
+        });
+        await app.db.load(fixtures);
+        context?.after(() => app.close());
+        return app;
+    } catch (err) {
+        await dispose().catch(() => {});
+        if (err instanceof TestError) throw err;
+        const failure = new TestError(`The app could not be applied to the test tenant: ${err.message}`, TestErrorCode.APP_FAILED);
+        failure.cause = err;
+        throw failure;
+    }
+}