@specific.dev/spectest 0.26.0 → 0.28.0

package/dist/components/s3.d.ts

@@ -0,0 +1,99 @@
+import { type S3ClientLike } from "../s3.js";
+export interface S3Options {
+    /** HTTP port the S3 API is served on. Default `9090`. */
+    port?: number;
+    /**
+     * Buckets to create on first boot. The backing server's own `initialBuckets`
+     * env is unreliable across versions, so the component creates them in `setup`
+     * (a plain CreateBucket `PUT`) — captured into the warm snapshot, never
+     * re-run on warm starts/forks.
+     */
+    buckets?: string[];
+    /**
+     * Default bucket the `helpers.client` targets (so `client.file("k")` resolves
+     * without a per-call `{ bucket }`). Defaults to the first entry of `buckets`.
+     */
+    bucket?: string;
+    /**
+     * Hostnames to additionally serve the store at over **HTTPS** (CA-trusted),
+     * via the daemon's TLS-terminating reverse proxy. Optional — defaults to none;
+     * the store is always reachable at `http://<key>:<port>` regardless. Set this
+     * only when the app under test hardcodes a specific prod S3 endpoint it can't
+     * be told to override (`https://<bucket>.s3.amazonaws.com`, a provider's
+     * storage host): the daemon mints a cert for each host and proxies to the
+     * store's plain HTTP. The store ignores SigV4, so the Host rewrite is harmless.
+     */
+    hosts?: string[];
+    /** Access key id the helper client signs with. The store ignores SigV4, so
+     *  any non-empty value works; default `"s3"`. */
+    accessKeyId?: string;
+    /** Secret key the helper client signs with (ignored by the store). Default
+     *  `"s3"`. */
+    secretAccessKey?: string;
+    /** Region for the helper client. Default `"us-east-1"`. */
+    region?: string;
+    /** Extra environment variables forwarded to the container. */
+    env?: Record<string, string>;
+}
+/** Helpers an `s3(...)` service exposes on `ctx.svc.<name>`. */
+export interface S3Helpers {
+    /** An instrumented {@link S3Client} pointed at this store (path-style) — each
+     *  object op lands on the test event log and its result comes back
+     *  provenance-wrapped, so `expect(...)` on a read links to the op. */
+    client: S3ClientLike;
+}
+/**
+ * A ready-to-use, S3-compatible object store (backed by
+ * [`adobe/s3mock`](https://github.com/adobe/S3Mock)), with an instrumented S3
+ * client on `ctx.svc.<key>.client`. Drop into `environment.services`:
+ *
+ * ```ts
+ * import { s3 } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   storage: s3({ buckets: ["uploads"] }),
+ * },
+ * ```
+ *
+ * Tests get an instrumented S3 client at `ctx.svc.<key>.client`:
+ *
+ * ```ts
+ * await ctx.svc.storage.client.write("hello.txt", "hi there");
+ * const body = await ctx.svc.storage.client.file("hello.txt").text();
+ * expect(body).toBe("hi there");          // nests under the s3 read step
+ * ```
+ *
+ * The store skips SigV4 validation and is path-style only (what S3-compatible
+ * clients use), so it stands in for AWS S3, R2, Spaces, etc. without credential
+ * plumbing. If — and only if — the app under test hardcodes a specific prod S3
+ * endpoint, pass `hosts` to also serve the store there over a CA-trusted cert:
+ *
+ * ```ts
+ * // app hardcodes https://files.example.com — serve it there too:
+ * storage: s3({ hosts: ["files.example.com"] }),
+ * ```
+ */
+export declare function s3(opts?: S3Options): {
+    setup?: (({ name }: {
+        name: string;
+    }) => Promise<void>) | undefined;
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+    helpers: ({ name }: {
+        name: string;
+    }) => S3Helpers;
+    tls?: {
+        hostname: string;
+        port: number;
+    }[] | undefined;
+    env?: Record<string, string> | undefined;
+    image: {
+        type: "registry";
+        reference: string;
+    };
+    ports: number[];
+};

package/dist/components/s3.js

@@ -0,0 +1,81 @@
+import { S3Client } from "../s3.js";
+// Backing image, pinned internally (not user-configurable). adobe/s3mock 5.1.0
+// is the current release; avoid exactly 5.0.0, which crashed at startup on
+// Java 25 (`NoClassDefFoundError: KotlinBuiltIns$2`) — fixed in 5.1.0.
+const S3_IMAGE = "adobe/s3mock:5.1.0";
+/**
+ * A ready-to-use, S3-compatible object store (backed by
+ * [`adobe/s3mock`](https://github.com/adobe/S3Mock)), with an instrumented S3
+ * client on `ctx.svc.<key>.client`. Drop into `environment.services`:
+ *
+ * ```ts
+ * import { s3 } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   storage: s3({ buckets: ["uploads"] }),
+ * },
+ * ```
+ *
+ * Tests get an instrumented S3 client at `ctx.svc.<key>.client`:
+ *
+ * ```ts
+ * await ctx.svc.storage.client.write("hello.txt", "hi there");
+ * const body = await ctx.svc.storage.client.file("hello.txt").text();
+ * expect(body).toBe("hi there");          // nests under the s3 read step
+ * ```
+ *
+ * The store skips SigV4 validation and is path-style only (what S3-compatible
+ * clients use), so it stands in for AWS S3, R2, Spaces, etc. without credential
+ * plumbing. If — and only if — the app under test hardcodes a specific prod S3
+ * endpoint, pass `hosts` to also serve the store there over a CA-trusted cert:
+ *
+ * ```ts
+ * // app hardcodes https://files.example.com — serve it there too:
+ * storage: s3({ hosts: ["files.example.com"] }),
+ * ```
+ */
+export function s3(opts = {}) {
+    const port = opts.port ?? 9090;
+    const buckets = opts.buckets ?? [];
+    const defaultBucket = opts.bucket ?? buckets[0];
+    const accessKeyId = opts.accessKeyId ?? "s3";
+    const secretAccessKey = opts.secretAccessKey ?? "s3";
+    const region = opts.region ?? "us-east-1";
+    return {
+        image: { type: "registry", reference: S3_IMAGE },
+        ports: [port],
+        ...(opts.env ? { env: opts.env } : {}),
+        ...(opts.hosts
+            ? { tls: opts.hosts.map((hostname) => ({ hostname, port })) }
+            : {}),
+        // GET / returns the ListBuckets XML with 200 once the store is up.
+        readyCheck: { type: "http", port, path: "/", timeoutSecs: 60 },
+        helpers: ({ name }) => ({
+            client: new S3Client({
+                endpoint: `http://${name}:${port}`,
+                region,
+                accessKeyId,
+                secretAccessKey,
+                ...(defaultBucket ? { bucket: defaultBucket } : {}),
+                // Path-style (Bun's default) — the store is path-style only.
+            }),
+        }),
+        ...(buckets.length > 0
+            ? {
+                setup: async ({ name }) => {
+                    for (const bucket of buckets) {
+                        // CreateBucket is a plain `PUT` on the bucket root; the store
+                        // returns 200 (or 409 if it already exists — idempotent enough to
+                        // ignore).
+                        const res = await fetch(`http://${name}:${port}/${bucket}`, {
+                            method: "PUT",
+                        });
+                        if (!res.ok && res.status !== 409) {
+                            throw new Error(`s3: failed to create bucket ${bucket}: ${res.status}`);
+                        }
+                    }
+                },
+            }
+            : {}),
+    };
+}

package/dist/components/supabase.d.ts

@@ -0,0 +1,197 @@
+import { type ServiceGroup, type ServicesMap } from "../index.js";
+import { type SqlClient } from "../sql.js";
+import { type EmailHelpers } from "./email.js";
+export interface SupabaseOptions {
+    /**
+     * Key of the API-gateway service and the prefix for every other piece.
+     * Default `"supabase"`. The gateway is reachable at `http://<name>:8000`
+     * and its helpers at `ctx.svc.<name>`; the rest are `<name>-db`,
+     * `<name>-auth`, `<name>-rest`, `<name>-storage`, `<name>-realtime`, ….
+     */
+    name?: string;
+    /**
+     * Password for the Postgres roles the services authenticate with (and the
+     * `postgres` superuser the app / SQL helper connect as). Default
+     * `"postgres"`. Purely local to the hermetic VM — not a secret to guard.
+     */
+    dbPassword?: string;
+    /**
+     * HS256 secret that signs and verifies all JWTs (user access tokens plus the
+     * derived `anonKey` / `serviceRoleKey` API keys). Must be ≥32 chars. Default
+     * is Supabase's well-known demo secret. Changing it re-derives the keys
+     * deterministically, so the warm-template cache stays stable.
+     */
+    jwtSecret?: string;
+    /** Studio dashboard Basic-Auth username (only relevant with `studio`). Default `"supabase"`. */
+    dashboardUsername?: string;
+    /** Studio dashboard Basic-Auth password (only relevant with `studio`). */
+    dashboardPassword?: string;
+    /** Include GoTrue auth (`<name>-auth`). Default `true`. */
+    auth?: boolean;
+    /** Include storage-api + imgproxy (`<name>-storage`, `<name>-imgproxy`). Default `true`. */
+    storage?: boolean;
+    /** Include Realtime (`<name>-realtime`). Default `true`. */
+    realtime?: boolean;
+    /**
+     * Include the Studio dashboard (`<name>-studio`) and its postgres-meta
+     * backend (`<name>-meta`). Off by default — Studio is a heavy Next.js image
+     * and is only useful for interactive `ctx.browser()` exploration, not
+     * automated backend assertions. Turning it on implies `meta`.
+     */
+    studio?: boolean;
+    /** Include postgres-meta (`<name>-meta`). Defaults to whatever `studio` is. */
+    meta?: boolean;
+    /**
+     * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
+     * daemon's CA-trusted TLS reverse proxy (in addition to the plain
+     * `http://<name>:8000`). Set this only when the app under test hardcodes a
+     * specific Supabase URL it can't be told to override — otherwise leave it and
+     * point the app at `sb.url`.
+     */
+    hostname?: string;
+    /**
+     * Capture GoTrue's outgoing mail (magic links, OTPs, password recovery,
+     * invites — and signup confirmations with `autoconfirm: false`) with the
+     * standard `email()` component. **On by default**: the stack includes the
+     * capture server (`<name>-mail`) with GoTrue's SMTP wired at it, and tests
+     * read the mailbox through the typed helpers at `ctx.svc.<name>.mail`
+     * (`lastEmail` / `emails` / `clear`), each captured message rendering
+     * mail-client-style on the dashboard timeline.
+     *
+     * Signups stay one-step by default (`autoconfirm: true`) so the mailbox is
+     * purely additive; pass `{ autoconfirm: false }` to test real
+     * email-confirmation flows. Pass `{ service: "<key>" }` to point GoTrue at
+     * an `email()` service the environment already declares — keep a single
+     * mailbox per environment rather than one per component: if the app under
+     * test also sends mail, share one `email()` between it and Supabase
+     * instead of standing up a second capture server. `false` disables mail
+     * capture entirely.
+     */
+    mail?: boolean | SupabaseMailOptions;
+    /**
+     * Extra API keys the gateway accepts alongside the derived JWT keys — for
+     * clients that ship a hardcoded key (e.g. an `sb_publishable_…` /
+     * `sb_secret_…` pair baked into an app build). Each `anon` key is admitted
+     * with anon privileges and each `serviceRole` key with service-role
+     * privileges; Kong swaps the matching *derived JWT* in before proxying, so
+     * GoTrue/PostgREST/Realtime still receive a validly-signed token.
+     */
+    extraApiKeys?: {
+        anon?: string[];
+        serviceRole?: string[];
+    };
+    /**
+     * Auto-apply SQL migrations found in the project before any dependent service
+     * starts. `true` (default) applies every `*.sql` under `supabase/migrations/`
+     * (sorted, the Supabase convention), then `supabase/seed.sql` if present — a
+     * no-op when the directory is absent. Pass a string to point at a different
+     * directory (relative to the project root or absolute), or `false` to skip.
+     * An *explicitly configured* path that doesn't resolve is an error at env
+     * start (a silent no-op there surfaces much later as a confusing
+     * `relation … does not exist`).
+     * Because `supabase/**` is project content, editing a migration correctly
+     * forces a cold rebuild and re-apply (unlike `spectest/tests/**`).
+     */
+    migrations?: boolean | string;
+    /**
+     * Seed SQL applied after migrations. `true` (default) applies
+     * `supabase/seed.sql` if it exists; a string overrides the path; `false`
+     * skips it.
+     */
+    seed?: boolean | string;
+}
+/** Tuning for `SupabaseOptions.mail`. */
+export interface SupabaseMailOptions {
+    /**
+     * Reuse an `email()` service the environment already declares (its
+     * services-map key) instead of adding one to the group — the way to keep a
+     * single global mailbox when the app under test sends mail too. Assumes
+     * the service's default ports (SMTP 1025, API 8025).
+     */
+    service?: string;
+    /**
+     * Whether GoTrue autoconfirms signups. `true` (default): signups complete
+     * in one step and send no confirmation mail — recovery, magic-link and OTP
+     * mail is still sent and captured. Set `false` to exercise real
+     * email-confirmation flows (signups require the emailed verification).
+     */
+    autoconfirm?: boolean;
+    /** Sender address GoTrue mails from. Default `admin@example.com`. */
+    adminEmail?: string;
+    /** Sender display name. Default `Supabase`. */
+    senderName?: string;
+}
+/** Helpers the gateway service exposes on `ctx.svc.<name>`. */
+export interface SupabaseHelpers {
+    /**
+     * An instrumented {@link SqlClient} connected to the database as the
+     * `postgres` superuser — every query lands on the test event log and its rows
+     * come back provenance-wrapped, so `expect(...)` on a read links to the
+     * query. Point of direct DB verification alongside the REST/auth surface.
+     */
+    sql: SqlClient;
+    /** The gateway base URL the app uses as `SUPABASE_URL` (e.g. `http://supabase:8000`). */
+    url: string;
+    /** Long-lived `anon` API key (HS256 JWT). Pass as the `apikey` header. */
+    anonKey: string;
+    /** Long-lived `service_role` API key (HS256 JWT). Bypasses RLS — server-side only. */
+    serviceRoleKey: string;
+    /**
+     * The captured-mail mailbox (`lastEmail` / `emails` / `clear`) — present
+     * unless the stack was built with `mail: false`. Wait for delivery with
+     * the standard `ctx.poll`:
+     *
+     * ```ts
+     * const mail = await ctx.poll("confirmation email", () =>
+     *   ctx.svc.supabase.mail!.lastEmail());
+     * expect(mail.to).toContain("alice@example.com");
+     * ```
+     */
+    mail?: EmailHelpers;
+}
+/** What `supabase()` returns: the service group plus the derived
+ *  connection surface for wiring the app under test. */
+export interface SupabaseStack {
+    /** The Supabase stack as a service group. Mount it at the key matching
+     *  the `name` option (default `"supabase"`):
+     *  `services: { supabase: sb.group, ... }`. */
+    group: ServiceGroup<ServicesMap, SupabaseHelpers>;
+    /** Gateway base URL — `http://<name>:8000`, or `https://<hostname>` when set. */
+    url: string;
+    /** `anon` API key (HS256 JWT). */
+    anonKey: string;
+    /** `service_role` API key (HS256 JWT). */
+    serviceRoleKey: string;
+    /** Direct Postgres URL for the app (`postgres` superuser): `postgresql://postgres:<pw>@<name>-db:5432/postgres`. */
+    dbUrl: string;
+    /** The gateway service key — use in a dependent service's `dependsOn` to wait
+     *  for the whole stack (the gateway waits on the services behind it). */
+    ready: string;
+    /**
+     * Where the stack's SMTP capture server listens (absent with
+     * `mail: false`) — point the app under test's own mail transport here to
+     * share the one mailbox: `env: { SMTP_HOST: sb.smtp.host, SMTP_PORT: String(sb.smtp.port) }`.
+     */
+    smtp?: {
+        host: string;
+        port: number;
+    };
+    /** Ready-to-spread env for the app under test: `SUPABASE_URL`,
+     *  `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `DATABASE_URL`. */
+    appEnv: Record<string, string>;
+}
+/**
+ * A ready-to-use self-hosted Supabase stack. Mount `.group` at the key
+ * matching the `name` option (default `"supabase"`) and wire the app with
+ * `.appEnv` / `.ready`:
+ *
+ * ```ts
+ * const sb = supabase({ dbPassword: "postgres" });
+ * services: { supabase: sb.group, app: { image, env: sb.appEnv, dependsOn: [sb.ready] } }
+ * ```
+ *
+ * See the file header for the full picture. Tests get an instrumented DB client
+ * at `ctx.svc.<name>.sql` plus `sb.url` / `sb.anonKey` / `sb.serviceRoleKey`
+ * for hitting the REST/auth/storage APIs through the gateway.
+ */
+export declare function supabase(opts?: SupabaseOptions): SupabaseStack;