@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.5

package/dist/testing/conformance.d.ts

@@ -0,0 +1,335 @@
+/**
+ * The slice of a test runner the web harness needs.
+ *
+ * @stability experimental
+ */
+export interface WebConformanceTestApi {
+    /** Registers a group of tests. */
+    describe(name: string, fn: () => void): void;
+    /** Registers one test. */
+    it(name: string, fn: () => void | Promise<void>): void;
+    /** The assertion entry point; only the matchers below are ever used. */
+    expect: (actual: unknown) => {
+        /** Deep equality with `expected`. */
+        toEqual(expected: unknown): void;
+        /** The actual array contains `item`. */
+        toContain(item: unknown): void;
+        /** The actual number is at least `n`. */
+        toBeGreaterThanOrEqual(n: number): void;
+        /** Strict identity (`Object.is`) with `expected`. */
+        toBe(expected: unknown): void;
+        /** The actual object has every property of `expected`, compared deeply and ignoring extras. */
+        toMatchObject(expected: object): void;
+        /** The actual array or string has exactly `length` items. */
+        toHaveLength(length: number): void;
+        /** The actual function throws; when `expected` is given, the message contains it (a string) or matches it (a RegExp). */
+        toThrow(expected?: string | RegExp): void;
+    };
+}
+/**
+ * One card of an app's settings registry, as the harness types it. Structural:
+ * the app's `SettingsSectionDef[]` is assignable, and the settings suites read
+ * it back as that type. (This slice cannot import the settings slice.)
+ *
+ * @stability experimental
+ */
+export interface WebConformanceCard {
+    /** The card and page title. */
+    title: string;
+    /** The card's one or two sentences. */
+    description: string;
+    /** The icon component. */
+    Icon: unknown;
+    /** The route the card navigates to. */
+    path?: string;
+    /** Rendered but inert. */
+    disabled?: boolean;
+    /** The permission (or any-of list) required to see the card. */
+    permission?: string | readonly string[];
+    /** Show the card even when `permission` is not held. */
+    alwaysShow?: boolean;
+    /** The deployment feature the card exists under. */
+    feature?: string;
+}
+/**
+ * A titled group of cards, as the harness types it.
+ *
+ * @stability experimental
+ */
+export interface WebConformanceSection {
+    /** The group's label. */
+    label: string;
+    /** Its cards, in order. */
+    cards: WebConformanceCard[];
+}
+/**
+ * One route the app declares, as the suites read it.
+ *
+ * @stability experimental
+ */
+export interface AppRouteDef {
+    /** The route path (`/admin/settings/users`), exactly as declared. */
+    path: string;
+    /**
+     * The permission gate of the route: a permission, the ANY-OF list of an
+     * any-of guard, or `null` for a route with no permission gate (a redirect,
+     * or a page open to every signed-in user).
+     */
+    permission?: string | readonly string[] | null;
+}
+/**
+ * The app's destination table, as the route-ownership suite reads it. The app
+ * passes its own functions (`config/destinations.ts`), so the suite checks the
+ * table the app really runs.
+ *
+ * @stability experimental
+ */
+export interface WebDestinationsView {
+    /** Route prefixes each destination owns, by destination key. */
+    routes: Readonly<Record<string, readonly string[]>>;
+    /** Routes deliberately owned by no destination (the login screen). */
+    unowned: readonly string[];
+    /** Whether `prefix` owns `path`, on segment boundaries. */
+    owns(prefix: string, path: string): boolean;
+    /** The destination key that is active at `pathname`, or `null`. */
+    resolveActive(pathname: string): string | null;
+    /** Every destination, with the path it navigates to. */
+    destinations: readonly WebDestinationEntry[];
+}
+/**
+ * A hub's route and title.
+ *
+ * @stability experimental
+ */
+export interface WebConformanceHub {
+    /** The hub's route (`/admin/settings`). */
+    path: string;
+    /** The hub's title, which `settingsPageTitle` falls back to. */
+    title: string;
+}
+/**
+ * The admin and the per-user settings hub.
+ *
+ * @stability experimental
+ */
+export interface WebConformanceHubs {
+    /** The admin hub (`/admin/settings`). */
+    admin: WebConformanceHub;
+    /** The per-user hub (`/settings`). */
+    user: WebConformanceHub;
+}
+/**
+ * One destination of the app's navigation.
+ *
+ * @stability experimental
+ */
+export interface WebDestinationEntry {
+    /** The destination's key (`home`, `settings`, `console`). */
+    key: string;
+    /** The path it navigates to. */
+    path: string;
+    /**
+     * The destination is a link to another site (`ShellDestination.external`): it
+     * owns no route, so the route-ownership suite does not expect one.
+     */
+    external?: boolean;
+}
+/**
+ * The text of the app's route file, which the suites parse for `<Route>` elements.
+ *
+ * @stability experimental
+ */
+export interface WebConformanceRouteSource {
+    /** The source text of `App.tsx` (the app reads the file; this package has no Node types). */
+    appTsx: string;
+}
+/**
+ * The app's OpenAPI document, as far as the suites read it.
+ *
+ * @stability experimental
+ */
+export interface WebConformanceOpenApiDocument {
+    /** Path items by path, each holding one operation per HTTP method. */
+    paths?: Record<string, unknown>;
+}
+/**
+ * An explicit, argued opt-out of one suite.
+ *
+ * @stability experimental
+ */
+export interface WebConformanceSkip {
+    /** Why this app does not run the suite; required, and printed in the run summary. */
+    skip: string;
+}
+/**
+ * What an app passes under one suite id: the suite's options, or an opt-out.
+ * The options of a suite are any object that does not carry a `skip` key.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export type WebConformanceSuiteEntry = WebConformanceSkip | Readonly<Record<string, unknown>>;
+/**
+ * What the app hands the web suites: its registries and route table, and the
+ * permission ids its API enforces.
+ *
+ * @stability experimental
+ */
+export interface WebConformanceContext {
+    /** The admin settings registry (`ADMIN_SECTIONS`). */
+    adminSections: WebConformanceSection[];
+    /** The per-user settings registry (`USER_SETTINGS_SECTIONS`). */
+    userSettingsSections: WebConformanceSection[];
+    /** Each hub's route and title (`settingsPageTitle` falls back to the title). */
+    hubs: WebConformanceHubs;
+    /**
+     * The route table, preferably as data. The fallback is the text of the app's
+     * route file (`App.tsx`), parsed for `<Route path=... permission=...>`, so the
+     * suite still reads the live routes and never a copy; the app reads the file.
+     */
+    routes: readonly AppRouteDef[] | WebConformanceRouteSource;
+    /** Every permission id the API enforces (the generated permission catalog, `apps/api/prisma/catalog/permissions.json`). */
+    apiPermissions: readonly string[];
+    /**
+     * The app's OpenAPI document, when the test environment has one (it is
+     * generated by `npm run openapi:dump`). With it, a card's permission must also
+     * be one a route of the surface it fronts declares in its `x-rbac` metadata.
+     */
+    openApiDocument?: WebConformanceOpenApiDocument;
+    /** The destination table; required by `settings-route-ownership` and the console check of `settings-card-routes`. */
+    destinations?: WebDestinationsView;
+}
+/**
+ * A runnable web invariant. Register one in {@link webConformanceSuites}; the
+ * harness registers a `describe` block for it unless the app skips it.
+ *
+ * @typeParam TOptions - what the app passes to configure the suite through
+ *   {@link PlatformWebConformanceOptions.suites}. `undefined` for a suite that
+ *   takes none (the platform's `settings-*` suites).
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export interface WebConformanceSuite<TOptions = undefined> {
+    /** Stable id, for example `'settings-registry-gates'`; the key of an app's `skip` entry. */
+    readonly id: string;
+    /** The `describe` title. */
+    readonly title: string;
+    /** One sentence: the invariant this enforces. */
+    readonly description: string;
+    /**
+     * Registers the suite's tests against the app's data.
+     *
+     * @param api - the runner's `describe`, `it` and the {@link WebConformanceTestApi.expect} subset.
+     * @param context - the app's registries, route table and permission ids.
+     * @param options - what the app passed under this suite's id in
+     *   {@link PlatformWebConformanceOptions.suites}; `undefined` when it passed
+     *   nothing. A suite that needs options throws on `undefined` with a message
+     *   naming the key to pass.
+     * @throws Error only on misconfiguration.
+     */
+    register(api: WebConformanceTestApi, context: WebConformanceContext, options: TOptions): void;
+}
+/**
+ * What an app passes to {@link runPlatformWebConformance}.
+ *
+ * @example
+ * ```ts
+ * import '@marinoscar/platform-web/settings/testing'; // registers the settings suites
+ * runPlatformWebConformance({
+ *   adminSections: ADMIN_SECTIONS,
+ *   userSettingsSections: USER_SETTINGS_SECTIONS,
+ *   hubs: { admin: { path: ADMIN_HUB_PATH, title: ADMIN_HUB_TITLE }, user: { path: USER_HUB_PATH, title: USER_HUB_TITLE } },
+ *   routes: { appTsx: readFileSync(APP_TSX, 'utf8') },
+ *   apiPermissions: catalog.permissions.map((p) => p.name),
+ *   suites: { 'settings-route-ownership': { skip: 'This app has no destination table.' } },
+ * });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface PlatformWebConformanceOptions extends WebConformanceContext {
+    /**
+     * One entry per suite id the app configures or opts out of. An entry is the
+     * suite's options (handed to its `register` as the third argument) or
+     * `{ skip: 'reason' }` to opt out: the reason is required and is printed in
+     * the run summary. A suite with no entry runs with `undefined` options. An
+     * unknown id throws, so a typo cannot disable a check.
+     */
+    suites?: Readonly<Record<string, WebConformanceSuiteEntry>>;
+    /** Defaults to the globals `describe`/`it`/`expect` (Vitest with `globals: true`, or Jest). */
+    testApi?: WebConformanceTestApi;
+    /** Where the summary table of suites run and skipped goes. Default: the console, unless `testApi` is injected (then nothing is printed). */
+    summaryOutput?: (table: string) => void;
+}
+/**
+ * Every web conformance suite the harness can run, by id. Filled when a
+ * slice's `testing` entry is imported; frozen on the first run, so a late
+ * registration fails loudly.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const webConformanceSuites: {
+    /** @internal */ entries: Map<string, WebConformanceSuite<any>>;
+    /** @internal */ frozen: boolean;
+    /**
+     * Adds a suite, the way an app adds its own (`webConformanceSuites.register(mySuite)`
+     * at the top of its conformance test).
+     *
+     * @param suite - the suite; its `id` must not be registered yet.
+     * @throws Error when a suite with the same id is already registered (the second
+     *   one would silently never run); guard an idempotent registration with
+     *   `webConformanceSuites.has(id)`.
+     * @throws Error once the harness has run: a suite registered after the first run would never run.
+     *
+     * @example
+     * ```ts
+     * webConformanceSuites.register(myRouteSuite);
+     * runPlatformWebConformance({ ...appData, suites: { 'my-route-suite': { requiredRoutes: ['/orders'] } } });
+     * ```
+     */
+    register<TOptions>(suite: WebConformanceSuite<TOptions>): void;
+    /** Whether a suite is registered under `id`. */
+    has(id: string): boolean;
+    /** The registered suites, in registration order. */
+    list(): WebConformanceSuite<any>[];
+    /** The registered suite ids, in registration order. */
+    ids(): string[];
+};
+/**
+ * One row of the run summary.
+ *
+ * @stability experimental
+ */
+export interface WebConformanceSummaryEntry {
+    /** The suite id. */
+    id: string;
+    /** `run`, or `skipped` when the app opted out with a reason. */
+    status: 'run' | 'skipped';
+    /** The app's reason, for a skipped suite. */
+    reason?: string;
+}
+/**
+ * The summary table `runPlatformWebConformance` prints.
+ *
+ * @param entries - one per registered suite.
+ * @returns a plain-text table, one line per suite under a header.
+ *
+ * @stability experimental
+ */
+export declare function formatWebConformanceSummary(entries: readonly WebConformanceSummaryEntry[]): string;
+/**
+ * Registers one `describe` block per registered web conformance suite, over
+ * the app's own registries and route table. Call it at the top level of a test
+ * file.
+ *
+ * @param options - see {@link PlatformWebConformanceOptions}.
+ * @throws Error when `suites` names a suite that is not registered (a typo must not disable a check), when a skip has no reason, when no suite is registered (the testing entry was not imported), or when no test API is available.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare function runPlatformWebConformance(options: PlatformWebConformanceOptions): void;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../src/testing/conformance.ts"],"names":[],"mappings":"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"}

package/dist/testing/conformance.js

@@ -0,0 +1,150 @@
+// =============================================================================
+// The web conformance harness (issue #742)
+// =============================================================================
+//
+// The counterpart of `runPlatformConformance` (`@marinoscar/platform-api/testing`)
+// for the browser app. A suite is an invariant over what the app DECLARES (its
+// settings registries, its route table, its destinations), discovered from that
+// data and never hand-listed; the app calls `runPlatformWebConformance(...)` in
+// one test file and passes the data. A slice that ships a suite registers it in
+// `webConformanceSuites` when its `testing` entry is imported
+// (`@marinoscar/platform-web/settings/testing`).
+//
+// This file imports no test runner and no Node module: it is handed a minimal
+// test API (`describe`, `it`, `expect`), defaulting to the runner's globals, so
+// it works under Vitest with `globals: true` and in a package test with a
+// recording fake. Reading a file is the APP's job (it passes the text), which
+// keeps the package free of Node types.
+// =============================================================================
+/**
+ * Every web conformance suite the harness can run, by id. Filled when a
+ * slice's `testing` entry is imported; frozen on the first run, so a late
+ * registration fails loudly.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export const webConformanceSuites = {
+    // `any` only at the registry boundary: each entry has its own options type,
+    // and the runner hands it whatever the app passed under the suite's id.
+    /** @internal */ entries: new Map(),
+    /** @internal */ frozen: false,
+    /**
+     * Adds a suite, the way an app adds its own (`webConformanceSuites.register(mySuite)`
+     * at the top of its conformance test).
+     *
+     * @param suite - the suite; its `id` must not be registered yet.
+     * @throws Error when a suite with the same id is already registered (the second
+     *   one would silently never run); guard an idempotent registration with
+     *   `webConformanceSuites.has(id)`.
+     * @throws Error once the harness has run: a suite registered after the first run would never run.
+     *
+     * @example
+     * ```ts
+     * webConformanceSuites.register(myRouteSuite);
+     * runPlatformWebConformance({ ...appData, suites: { 'my-route-suite': { requiredRoutes: ['/orders'] } } });
+     * ```
+     */
+    register(suite) {
+        if (this.entries.has(suite.id)) {
+            throw new Error(`webConformanceSuites: a suite with id "${suite.id}" is already registered. Suite ids are unique; rename yours, or guard the call with webConformanceSuites.has("${suite.id}").`);
+        }
+        if (this.frozen) {
+            throw new Error(`webConformanceSuites: "${suite.id}" registered after runPlatformWebConformance ran; import the testing entry first.`);
+        }
+        this.entries.set(suite.id, suite);
+    },
+    /** Whether a suite is registered under `id`. */
+    has(id) {
+        return this.entries.has(id);
+    },
+    /** The registered suites, in registration order. */
+    list() {
+        return [...this.entries.values()];
+    },
+    /** The registered suite ids, in registration order. */
+    ids() {
+        return [...this.entries.keys()];
+    },
+};
+/** The runner's own globals, or a clear error when there are none. */
+function globalTestApi() {
+    const g = globalThis;
+    if (typeof g.describe !== 'function' || typeof g.it !== 'function' || typeof g.expect !== 'function') {
+        throw new Error('runPlatformWebConformance: no global describe/it/expect. Run it under Vitest with `globals: true`, or pass `testApi`.');
+    }
+    return { describe: g.describe, it: g.it, expect: g.expect };
+}
+/** An opt-out is an object with a `skip` key (a suite's own options never name one). */
+function isSkipEntry(value) {
+    return typeof value === 'object' && value !== null && 'skip' in value;
+}
+/**
+ * The summary table `runPlatformWebConformance` prints.
+ *
+ * @param entries - one per registered suite.
+ * @returns a plain-text table, one line per suite under a header.
+ *
+ * @stability experimental
+ */
+export function formatWebConformanceSummary(entries) {
+    const width = Math.max('suite'.length, ...entries.map((entry) => entry.id.length));
+    const lines = entries.map((entry) => `${entry.id.padEnd(width)}  ${entry.status === 'run' ? 'run' : `skipped: ${entry.reason ?? ''}`}`);
+    const ran = entries.filter((entry) => entry.status === 'run').length;
+    return [`${'suite'.padEnd(width)}  status`, ...lines, `${ran} run, ${entries.length - ran} skipped`].join('\n');
+}
+/**
+ * Registers one `describe` block per registered web conformance suite, over
+ * the app's own registries and route table. Call it at the top level of a test
+ * file.
+ *
+ * @param options - see {@link PlatformWebConformanceOptions}.
+ * @throws Error when `suites` names a suite that is not registered (a typo must not disable a check), when a skip has no reason, when no suite is registered (the testing entry was not imported), or when no test API is available.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export function runPlatformWebConformance(options) {
+    webConformanceSuites.frozen = true;
+    const known = new Set(webConformanceSuites.ids());
+    const skips = options.suites ?? {};
+    for (const [id, entry] of Object.entries(skips)) {
+        if (!known.has(id)) {
+            throw new Error(`runPlatformWebConformance: unknown conformance suite "${id}". Known suites: ${[...known].join(', ') || '(none)'}. ` +
+                "A suite that ships with a slice registers when the slice's testing entry is imported ('@marinoscar/platform-web/settings/testing').");
+        }
+        if (isSkipEntry(entry) && (typeof entry.skip !== 'string' || entry.skip.trim() === '')) {
+            throw new Error(`runPlatformWebConformance: suite "${id}" is skipped without a reason. Pass \`'${id}': { skip: 'why this app does not run it' }\`.`);
+        }
+    }
+    if (known.size === 0) {
+        throw new Error("runPlatformWebConformance: no suite is registered. Import a slice's testing entry first ('@marinoscar/platform-web/settings/testing').");
+    }
+    const api = options.testApi ?? globalTestApi();
+    const summary = [];
+    for (const suite of webConformanceSuites.list()) {
+        const entry = skips[suite.id];
+        if (isSkipEntry(entry)) {
+            const reason = entry.skip.trim();
+            summary.push({ id: suite.id, status: 'skipped', reason });
+            api.describe(suite.title, () => {
+                api.it(`${suite.id}: skipped by the app (${reason})`, () => undefined);
+            });
+            continue;
+        }
+        summary.push({ id: suite.id, status: 'run' });
+        suite.register(api, options, entry);
+    }
+    // The summary is printed at registration time, not registered as a test: a
+    // test would change the case list of the suites the app runs. A test API the
+    // caller injects (a recording fake) prints nothing unless `summaryOutput` says where.
+    const table = formatWebConformanceSummary(summary);
+    if (options.summaryOutput)
+        options.summaryOutput(table);
+    else if (options.testApi === undefined) {
+        // `console` is not in this package's types (a browser package); the harness
+        // only ever runs in a test runner, where it is.
+        globalThis.console.info(`\n${table}`);
+    }
+}
+//# sourceMappingURL=conformance.js.map

package/dist/testing/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","sourceRoot":"","sources":["../../src/testing/conformance.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -1,3 +1,5 @@
 export { createTestApiError, createTestBlobResponse, createTestPlatformHost } from './test-platform-host.js';
 export type { TestApiRequest, TestApiResponse, TestPlatformHost, TestPlatformHostOptions, TestSseFrame, } from './test-platform-host.js';
+export { formatWebConformanceSummary, runPlatformWebConformance, webConformanceSuites } from './conformance.js';
+export type { AppRouteDef, PlatformWebConformanceOptions, WebConformanceCard, WebConformanceContext, WebConformanceHub, WebConformanceHubs, WebConformanceOpenApiDocument, WebConformanceRouteSource, WebConformanceSkip, WebConformanceSection, WebConformanceSuite, WebConformanceSuiteEntry, WebConformanceSummaryEntry, WebConformanceTestApi, WebDestinationEntry, WebDestinationsView, } from './conformance.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAC7G,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,uBAAuB,EACvB,YAAY,GACb,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAC7G,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,uBAAuB,EACvB,YAAY,GACb,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAChH,YAAY,EACV,WAAW,EACX,6BAA6B,EAC7B,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,6BAA6B,EAC7B,yBAAyB,EACzB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,EACxB,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC"}

package/dist/testing/index.js

@@ -1,4 +1,6 @@
 // `@marinoscar/platform-web/testing`: test doubles for the web host ports
-// (issue #696). For package tests and app tests; never in production code.
+// (issue #696) and the web conformance harness (issue #742). For package tests
+// and app tests; never in production code.
 export { createTestApiError, createTestBlobResponse, createTestPlatformHost } from './test-platform-host.js';
+export { formatWebConformanceSummary, runPlatformWebConformance, webConformanceSuites } from './conformance.js';
 //# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,2EAA2E;AAE3E,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,+EAA+E;AAC/E,2CAA2C;AAE3C,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAS7G,OAAO,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/testing/test-platform-host.d.ts

@@ -1,3 +1,4 @@
+import type { ThemePreferenceId } from '@marinoscar/platform-contract/settings';
 import type { PlatformApiError, PlatformBlobResponse, PlatformWebHost } from '../core/index.js';
 /**
  * One request a test host received.
@@ -13,6 +14,8 @@ export interface TestApiRequest {
     body?: unknown;
     /** The `ifMatch` option of a PUT, PATCH or DELETE. */
     ifMatch?: string;
+    /** The `headers` option, when the page passed one. */
+    headers?: Readonly<Record<string, string>>;
 }
 /**
  * One frame a canned {@link PlatformApiClient.postSse} answer delivers, in order.
@@ -55,6 +58,10 @@ export interface TestPlatformHostOptions {
     responses?: Readonly<Record<string, TestApiResponse>>;
     /** The host's relative-time formatter. Default none (the page's fallback). */
     formatRelativeTime?: (iso: string) => string;
+    /** The host's theme setter (the Appearance page). Default none. */
+    applyTheme?: (theme: ThemePreferenceId) => void;
+    /** The host's extension ports, read by `usePlatformPort`. Default none. */
+    extensions?: Readonly<Record<string | symbol, unknown>>;
 }
 /**
  * A {@link PlatformWebHost} for tests, plus the requests it received.
@@ -71,11 +78,12 @@ export interface TestPlatformHost extends PlatformWebHost {
  * @param status - the HTTP status.
  * @param message - the API's message.
  * @param code - the API's error code.
+ * @param details - the error envelope's `details` (e.g. `{ reason: 'LAST_GROUP_ADMIN' }`).
  * @returns an `Error` that is also a {@link PlatformApiError}.
  *
  * @stability experimental
  */
-export declare function createTestApiError(status: number, message: string, code?: string): Error & PlatformApiError;
+export declare function createTestApiError(status: number, message: string, code?: string, details?: unknown): Error & PlatformApiError;
 /**
  * A canned download for {@link PlatformApiClient.getBlob}: a body and response headers.
  *

package/dist/testing/test-platform-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-platform-host.d.ts","sourceRoot":"","sources":["../../src/testing/test-platform-host.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,gBAAgB,EAChB,oBAAoB,EAEpB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7C;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IACtD,8EAA8E;IAC9E,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,gBAAgB,CAE3G;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAAG,oBAAoB,CAMzH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,CAoD9F"}
+{"version":3,"file":"test-platform-host.d.ts","sourceRoot":"","sources":["../../src/testing/test-platform-host.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAEhF,OAAO,KAAK,EAEV,gBAAgB,EAChB,oBAAoB,EAEpB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7C;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IACtD,8EAA8E;IAC9E,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7C,mEAAmE;IACnE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAChD,2EAA2E;IAC3E,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,OAAO,GAChB,KAAK,GAAG,gBAAgB,CAO1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAAG,oBAAoB,CAMzH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,CA4D9F"}

package/dist/testing/test-platform-host.js

@@ -7,12 +7,18 @@
  * @param status - the HTTP status.
  * @param message - the API's message.
  * @param code - the API's error code.
+ * @param details - the error envelope's `details` (e.g. `{ reason: 'LAST_GROUP_ADMIN' }`).
  * @returns an `Error` that is also a {@link PlatformApiError}.
  *
  * @stability experimental
  */
-export function createTestApiError(status, message, code) {
-    return Object.assign(new Error(message), { name: 'PlatformApiError', status, ...(code === undefined ? {} : { code }) });
+export function createTestApiError(status, message, code, details) {
+    return Object.assign(new Error(message), {
+        name: 'PlatformApiError',
+        status,
+        ...(code === undefined ? {} : { code }),
+        ...(details === undefined ? {} : { details }),
+    });
 }
 /**
  * A canned download for {@link PlatformApiClient.getBlob}: a body and response headers.
@@ -64,10 +70,14 @@ export function createTestPlatformHost(options = {}) {
         const response = responses[key];
         return (await (typeof response === 'function' ? response(request) : response));
     };
-    const withIfMatch = (options) => options?.ifMatch === undefined ? {} : { ifMatch: options.ifMatch };
+    const withIfMatch = (options) => ({
+        ...(options?.ifMatch === undefined ? {} : { ifMatch: options.ifMatch }),
+        ...withHeaders(options),
+    });
+    const withHeaders = (options) => options?.headers === undefined ? {} : { headers: options.headers };
     const api = {
-        get: (path) => call({ method: 'GET', path }),
-        post: (path, body) => call({ method: 'POST', path, body }),
+        get: (path, getOptions) => call({ method: 'GET', path, ...withHeaders(getOptions) }),
+        post: (path, body, postOptions) => call({ method: 'POST', path, body, ...withHeaders(postOptions) }),
         put: (path, body, putOptions) => call({ method: 'PUT', path, body, ...withIfMatch(putOptions) }),
         patch: (path, body, patchOptions) => call({ method: 'PATCH', path, body, ...withIfMatch(patchOptions) }),
         delete: (path, deleteOptions) => call({ method: 'DELETE', path, ...withIfMatch(deleteOptions) }),
@@ -75,6 +85,8 @@ export function createTestPlatformHost(options = {}) {
         // the canned value is a `PlatformBlobResponse`, e.g. from `createTestBlobResponse`.
         getBlob: (path) => call({ method: 'GET', path }),
         postBlob: (path, body) => call({ method: 'POST', path, body }),
+        // A multipart upload answers from `'POST <path>'`; the request's `body` is the FormData.
+        postFormData: (path, body) => call({ method: 'POST', path, body }),
         // A stream answers with an array of frames; anything else delivers none.
         postSse: async (path, body, sseOptions) => {
             const frames = await call({ method: 'POST', path, body });
@@ -95,6 +107,8 @@ export function createTestPlatformHost(options = {}) {
             isFeatureEnabled: (feature) => features[feature] === true,
         },
         ...(options.formatRelativeTime ? { formatRelativeTime: options.formatRelativeTime } : {}),
+        ...(options.applyTheme ? { applyTheme: options.applyTheme } : {}),
+        ...(options.extensions ? { extensions: options.extensions } : {}),
         requests,
     };
 }