@specific.dev/spectest 0.43.0 → 0.45.0

package/dist/components/apple.d.ts

@@ -0,0 +1,47 @@
+import type { ProviderOptions } from "./emulate/service.js";
+export type AppleOptions = ProviderOptions;
+/**
+ * Apple, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { apple } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   apple: apple({
+ *     users: [{ email: "alice@example.com", name: "Alice Example" }],
+ *     client: {
+ *       clientId: "com.example.app",
+ *       clientSecret: "client-assertion",
+ *       redirectUris: ["https://app.test/callback/apple"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["apple"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://appleid.apple.com/auth/authorize` and exchanges the code at
+ * `https://appleid.apple.com/auth/token`.
+ */
+export declare function apple(opts?: AppleOptions): {
+    image: {
+        type: "dockerfile";
+        content: string;
+    };
+    command: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    env: {
+        SPECTEST_AUTH_CONFIG: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};

package/dist/components/apple.js

@@ -0,0 +1,59 @@
+// `apple()` — Apple, emulated inside the environment, answering at its real
+// endpoints.
+//
+// Today that is Sign in with Apple: discovery, the account picker, the
+// token exchange, the refresh grant, and revocation, all on
+// `appleid.apple.com`.
+//
+// Apple publishes **no userinfo endpoint** — the real one does not either,
+// because for Apple the id_token is the whole profile. An app that wants to
+// re-read an account uses the refresh grant, which is the only
+// server-to-server call Apple offers.
+import { emulatorService, oauthClients, resolveUsers } from "./emulate/service.js";
+function spec(users, opts) {
+    return {
+        name: "apple",
+        module: "@emulators/apple",
+        pluginExport: "applePlugin",
+        baseUrl: "https://appleid.apple.com",
+        // Every Apple endpoint is on this one host, so no path or discovery
+        // correction is needed.
+        hosts: ["appleid.apple.com"],
+        jwksPath: "^/auth/keys$",
+        fallbackUser: { login: users[0].email, id: 1, scopes: ["openid", "email", "name"] },
+        seed: {
+            users: users.map((u) => ({ email: u.email, name: u.name })),
+            // Apple authenticates the client with a signed assertion rather than
+            // a shared secret, so the registration carries a team id instead.
+            ...oauthClients(opts.client, { team_id: "SPECTEST" }),
+        },
+    };
+}
+/**
+ * Apple, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { apple } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   apple: apple({
+ *     users: [{ email: "alice@example.com", name: "Alice Example" }],
+ *     client: {
+ *       clientId: "com.example.app",
+ *       clientSecret: "client-assertion",
+ *       redirectUris: ["https://app.test/callback/apple"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["apple"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://appleid.apple.com/auth/authorize` and exchanges the code at
+ * `https://appleid.apple.com/auth/token`.
+ */
+export function apple(opts = {}) {
+    const users = resolveUsers("apple", opts.users);
+    return emulatorService(spec(users, opts));
+}

package/dist/components/emulate/service.d.ts

@@ -0,0 +1,126 @@
+/** A person who can sign in. Seeded into the provider's account picker. */
+export interface ProviderUser {
+    /** Primary address. Also the account's test id on the picker page. */
+    email: string;
+    /** Display name. */
+    name?: string;
+    /** Avatar URL, passed through to the profile claims. */
+    picture?: string;
+    /** GitHub username. Defaults to the local part of `email`. */
+    login?: string;
+}
+/** An OAuth client, as registered with the real provider. Declaring one
+ *  makes the environment **stricter**: `clientId`, `clientSecret` and
+ *  `redirectUris` are then all validated, exactly as in production. Omit it
+ *  and any client is accepted. */
+export interface OAuthClient {
+    clientId: string;
+    clientSecret: string;
+    /** Callback URLs the app is allowed to return to. A request to any other
+     *  one is refused, which is what makes a misconfigured callback fail here
+     *  rather than in production. */
+    redirectUris?: string[];
+}
+/**
+ * The accounts every provider offers when a component declares none.
+ *
+ * Two, not one: a test that asserts it signed in as Alice only means
+ * something if the provider had somebody else to return. Both carry a
+ * `login`, so GitHub gets a handle without the caller supplying one.
+ *
+ * `example.com` is reserved for exactly this (RFC 2606), so no default
+ * account can ever collide with a real address.
+ */
+export declare const DEFAULT_USERS: readonly ProviderUser[];
+/** Options every provider component takes. */
+export interface ProviderOptions {
+    /**
+     * The accounts offered on the provider's picker page. Defaults to
+     * **Alice Example** (`alice@example.com`) and **Bob Example**
+     * (`bob@example.com`) — enough to sign in as somebody, and to tell two
+     * people apart, without declaring anything.
+     */
+    users?: ProviderUser[];
+    /** The app's OAuth client. Omit it and any client id, secret and callback
+     *  URL are accepted. */
+    client?: OAuthClient;
+}
+/** What `entry.mjs` consumes. Everything provider-specific lives in the
+ *  per-provider module; the script itself is generic. */
+export interface ProviderSpec {
+    name: string;
+    module: string;
+    pluginExport: string;
+    /** Base URL the emulator advertises — the provider's real sign-in host. */
+    baseUrl: string;
+    /** Every hostname routed to this emulator. */
+    hosts: string[];
+    /** False for a plain OAuth 2.0 provider with no id_token (GitHub). */
+    oidc?: boolean;
+    /** Issuer to stamp on the re-issued id_token, where the emulator cannot
+     *  derive it from `baseUrl`. */
+    issuer?: string;
+    /** Values merged over the emulator's discovery document. */
+    discovery?: Record<string, string>;
+    /** Path (as a regex source) answered with our own JWKS. */
+    jwksPath?: string;
+    /** Picker-page identifier → the account's email, where the provider
+     *  identifies an account by something else. Keeps the account's test id
+     *  the same on every provider. */
+    aliases?: Record<string, string>;
+    /** Real path → the path this emulator serves it on. Identity elsewhere. */
+    rewrites?: {
+        from: string;
+        to: string;
+    }[];
+    fallbackUser?: {
+        login: string;
+        id: number;
+        scopes: string[];
+    };
+    seed?: Record<string, unknown>;
+}
+/** The service definition for one provider: the container, plus the claim
+ *  on its domains (one certificate carrying every hostname as a SAN, and a
+ *  proxy route each). One `certificate(...)` rather than per-host `tls`
+ *  entries, for the reason `aws()` gives — `tls` mints a separate leaf per
+ *  entry, and a provider can claim four names. */
+export declare function emulatorService(spec: ProviderSpec): {
+    image: {
+        type: "dockerfile";
+        content: string;
+    };
+    command: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    env: {
+        SPECTEST_AUTH_CONFIG: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};
+/** The accounts to seed: what the caller declared, or {@link DEFAULT_USERS}.
+ *  An explicitly empty list is a mistake, not a request for none — a
+ *  provider with no accounts can never sign anyone in. */
+export declare function resolveUsers(component: string, users: ProviderUser[] | undefined): ProviderUser[];
+export declare function localPart(email: string): string;
+export declare function givenName(user: ProviderUser): string | undefined;
+export declare function familyName(user: ProviderUser): string | undefined;
+/** The `oauth_clients` seed entry every provider but GitHub uses. */
+export declare function oauthClients(client: OAuthClient | undefined, extra?: Record<string, unknown>): {
+    oauth_clients?: undefined;
+} | {
+    oauth_clients: {
+        client_id: string;
+        client_secret: string;
+        name: string;
+        redirect_uris: string[];
+    }[];
+};

package/dist/components/emulate/service.js

@@ -0,0 +1,153 @@
+// Shared runtime behind the third-party provider components — `google()`,
+// `github()`, `apple()`, `microsoft()`, `okta()`.
+//
+// Each of those is one container answering at that provider's **real**
+// endpoints: the component claims the provider's domains, so DNS, a leaf
+// certificate from the in-VM root CA, and a reverse proxy all point at it.
+// The app under test keeps its production configuration and never learns it
+// is under test.
+//
+// A provider component is therefore a table, not a program. It names the
+// hosts it claims, the emulator package behind it, the handful of paths
+// where that emulator differs from the real service, and how to seed it.
+// Everything else lives here and in `entry.mjs`.
+//
+// ── Internal notes (deliberately not in the user-facing docs) ─────────────
+//
+// The emulators come from vercel-labs/emulate (Apache-2.0), used through
+// their published `@emulators/*` packages and pinned. They are NOT SDK
+// dependencies: they install into the image below. That matters —
+// `sdk/package.json` is in the base-snapshot discriminator, so a dependency
+// here would force a base rebuild and one cold start for every project on
+// the box, for components most projects never use.
+//
+// Each emulator serves every one of its endpoints on ONE origin. Real
+// providers spread them over several hosts, and a few paths differ.
+// `entry.mjs` routes by Host header, applies the per-provider path table,
+// and corrects the discovery document. It also re-issues every id_token
+// with one RSA key it generates at boot, and serves that key at the
+// provider's real JWKS URL. That single step covers three separate faults:
+// the Google emulator signs HS256 and publishes an empty JWKS (so nothing
+// can verify its token), the Microsoft one cannot put the tenant in its
+// issuer, and any future provider whose issuer is not its base URL is
+// handled in advance.
+//
+// The Dockerfile is deliberately CONSTANT — every provider package is
+// installed whether or not this component is the one using it. Two reasons:
+// one image is shared by every provider component and every project on the
+// box, so the layer cache is hit; and the daemon dedupes identical
+// dockerfile builds inside one bootstrap, so five provider services in one
+// environment cost one build, not five.
+//
+// `entry.mjs` ships as an asset next to this file, read at load time and
+// injected with `files`. It is not a `.ts` string constant: it imports
+// `@emulators/*`, which the SDK does not depend on, so `tsc` could not
+// check it anyway, and 200 lines inside a template literal is worse to
+// maintain. `.mjs` also keeps it out of `tsconfig`'s `include` with no
+// exclude rule, and `files: ["src"]` in the manifest still ships it.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { certificate, provides, proxy, SELF_SERVICE_TOKEN } from "../../index.js";
+/** Base image, pinned. Bun runs the emulators' ESM directly. */
+const IMAGE_BASE = "oven/bun:1.3.14-alpine";
+/** Emulator package version, pinned rather than floated. */
+const EMULATE_VERSION = "0.9.0";
+/** The port the provider is served on. Callers reach it through the
+ *  provider's real hostnames, never through this port. */
+const PORT = 4000;
+/** Ready-check budget. The container boots in about a second; the slow part
+ *  is a cold image build on a machine that has never run it. */
+const READY_TIMEOUT_SECS = 120;
+/**
+ * The accounts every provider offers when a component declares none.
+ *
+ * Two, not one: a test that asserts it signed in as Alice only means
+ * something if the provider had somebody else to return. Both carry a
+ * `login`, so GitHub gets a handle without the caller supplying one.
+ *
+ * `example.com` is reserved for exactly this (RFC 2606), so no default
+ * account can ever collide with a real address.
+ */
+export const DEFAULT_USERS = [
+    { email: "alice@example.com", name: "Alice Example", login: "alice" },
+    { email: "bob@example.com", name: "Bob Example", login: "bob" },
+];
+/** The entry script, read from disk next to this module. */
+const ENTRY_SCRIPT = (() => {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return readFileSync(path.join(here, "entry.mjs"), "utf8");
+})();
+const DOCKERFILE = `
+FROM ${IMAGE_BASE}
+WORKDIR /srv
+RUN echo '{"name":"spectest-provider","private":true}' > package.json \\
+ && bun add \\
+      @emulators/core@${EMULATE_VERSION} \\
+      @emulators/google@${EMULATE_VERSION} \\
+      @emulators/github@${EMULATE_VERSION} \\
+      @emulators/apple@${EMULATE_VERSION} \\
+      @emulators/microsoft@${EMULATE_VERSION} \\
+      @emulators/okta@${EMULATE_VERSION} \\
+      jose@6
+`;
+/** The service definition for one provider: the container, plus the claim
+ *  on its domains (one certificate carrying every hostname as a SAN, and a
+ *  proxy route each). One `certificate(...)` rather than per-host `tls`
+ *  entries, for the reason `aws()` gives — `tls` mints a separate leaf per
+ *  entry, and a provider can claim four names. */
+export function emulatorService(spec) {
+    const service = {
+        image: { type: "dockerfile", content: DOCKERFILE },
+        command: "bun /srv/auth.mjs",
+        files: [{ path: "/srv/auth.mjs", content: ENTRY_SCRIPT }],
+        env: { SPECTEST_AUTH_CONFIG: JSON.stringify({ port: PORT, providers: [spec] }) },
+        ports: [PORT],
+        readyCheck: {
+            type: "http",
+            port: PORT,
+            path: "/healthz",
+            timeoutSecs: READY_TIMEOUT_SECS,
+        },
+    };
+    return provides(service, [
+        certificate(spec.hosts),
+        ...spec.hosts.map((hostname) => proxy(hostname, { service: SELF_SERVICE_TOKEN, port: PORT })),
+    ]);
+}
+// ── Seeding helpers, shared by the provider modules ───────────────────────
+/** The accounts to seed: what the caller declared, or {@link DEFAULT_USERS}.
+ *  An explicitly empty list is a mistake, not a request for none — a
+ *  provider with no accounts can never sign anyone in. */
+export function resolveUsers(component, users) {
+    if (users && users.length === 0) {
+        throw new Error(`${component}(): \`users\` is empty — omit it for the default accounts`);
+    }
+    return users ?? [...DEFAULT_USERS];
+}
+export function localPart(email) {
+    return email.split("@")[0] ?? email;
+}
+export function givenName(user) {
+    return user.name?.split(" ")[0];
+}
+export function familyName(user) {
+    const parts = user.name?.split(" ") ?? [];
+    return parts.length > 1 ? parts.slice(1).join(" ") : undefined;
+}
+/** The `oauth_clients` seed entry every provider but GitHub uses. */
+export function oauthClients(client, extra = {}) {
+    if (!client)
+        return {};
+    return {
+        oauth_clients: [
+            {
+                client_id: client.clientId,
+                client_secret: client.clientSecret,
+                name: "spectest",
+                redirect_uris: client.redirectUris ?? [],
+                ...extra,
+            },
+        ],
+    };
+}

package/dist/components/github.d.ts

@@ -0,0 +1,52 @@
+import type { ProviderOptions } from "./emulate/service.js";
+export type GithubOptions = ProviderOptions;
+/**
+ * GitHub, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { github } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   github: github({
+ *     users: [{ email: "bob@example.com", name: "Bob Example", login: "bob" }],
+ *     client: {
+ *       clientId: "Iv1.example",
+ *       clientSecret: "ghs_example",
+ *       redirectUris: ["https://app.test/callback/github"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["github"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://github.com/login/oauth/authorize`, exchanges the code at
+ * `https://github.com/login/oauth/access_token`, and reads the account from
+ * `https://api.github.com/user`.
+ *
+ * The account's test id on the picker page is its **email**, even though
+ * GitHub identifies it by login — so a test reads the same whichever
+ * provider it drives.
+ */
+export declare function github(opts?: GithubOptions): {
+    image: {
+        type: "dockerfile";
+        content: string;
+    };
+    command: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    env: {
+        SPECTEST_AUTH_CONFIG: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};

package/dist/components/github.js

@@ -0,0 +1,90 @@
+// `github()` — GitHub, emulated inside the environment, answering at its
+// real endpoints.
+//
+// Today that is Sign in with GitHub — the authorize page, the token
+// exchange, and the profile reads every GitHub sign-in makes (`/user`,
+// `/user/emails`). The component is named for the provider rather than for
+// the feature: the backing emulator carries most of the REST API — repos,
+// issues, pull requests, checks, webhooks — and reaching it is a matter of
+// what this component chooses to expose, not of new plumbing.
+//
+// Landmine for whoever extends this: the claim is env-wide. `github.com`
+// and `api.github.com` stop reaching the internet for every container in
+// the environment, so anything else that talks to GitHub — a build step
+// that clones a repository, an unrelated API call — reaches the emulator
+// and gets a 404 outside the surface it serves.
+import { emulatorService, localPart, resolveUsers } from "./emulate/service.js";
+function spec(users, opts) {
+    const client = opts.client;
+    return {
+        name: "github",
+        module: "@emulators/github",
+        pluginExport: "githubPlugin",
+        baseUrl: "https://github.com",
+        // api.github.com cannot be avoided: every GitHub sign-in reads the
+        // profile from /user and the addresses from /user/emails.
+        hosts: ["github.com", "api.github.com"],
+        // OAuth 2.0, not OIDC — there is no id_token to re-issue and no JWKS.
+        oidc: false,
+        // GitHub identifies an account by login, not by address.
+        aliases: Object.fromEntries(users.map((u) => [u.login ?? localPart(u.email), u.email])),
+        fallbackUser: {
+            login: users[0].login ?? localPart(users[0].email),
+            id: 1,
+            scopes: ["user", "user:email"],
+        },
+        seed: {
+            users: users.map((u) => ({
+                login: u.login ?? localPart(u.email),
+                name: u.name,
+                email: u.email,
+            })),
+            // GitHub calls them oauth_apps, and its own field is `oauth_apps`.
+            ...(client
+                ? {
+                    oauth_apps: [
+                        {
+                            client_id: client.clientId,
+                            client_secret: client.clientSecret,
+                            name: "spectest",
+                            redirect_uris: client.redirectUris ?? [],
+                        },
+                    ],
+                }
+                : {}),
+        },
+    };
+}
+/**
+ * GitHub, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { github } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   github: github({
+ *     users: [{ email: "bob@example.com", name: "Bob Example", login: "bob" }],
+ *     client: {
+ *       clientId: "Iv1.example",
+ *       clientSecret: "ghs_example",
+ *       redirectUris: ["https://app.test/callback/github"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["github"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://github.com/login/oauth/authorize`, exchanges the code at
+ * `https://github.com/login/oauth/access_token`, and reads the account from
+ * `https://api.github.com/user`.
+ *
+ * The account's test id on the picker page is its **email**, even though
+ * GitHub identifies it by login — so a test reads the same whichever
+ * provider it drives.
+ */
+export function github(opts = {}) {
+    const users = resolveUsers("github", opts.users);
+    return emulatorService(spec(users, opts));
+}

package/dist/components/google.d.ts

@@ -0,0 +1,57 @@
+import type { ProviderOptions } from "./emulate/service.js";
+export type GoogleOptions = ProviderOptions;
+/**
+ * Google, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { google } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   // Accounts default to Alice and Bob Example; declare `users` to
+ *   // choose your own. A `client` makes the environment validate the
+ *   // app's client id, secret and callback URL.
+ *   google: google({
+ *     client: {
+ *       clientId: "1234.apps.googleusercontent.com",
+ *       clientSecret: "GOCSPX-test",
+ *       redirectUris: ["https://app.test/callback/google"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["google"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://accounts.google.com/o/oauth2/v2/auth`, exchanges the code at
+ * `https://oauth2.googleapis.com/token`, and verifies the id_token against
+ * `https://www.googleapis.com/oauth2/v3/certs`, exactly as it does live.
+ *
+ * A test signs in the way a user does, through the browser:
+ *
+ * ```ts
+ * await page.getByTestId("login-google").click();
+ * await page.getByTestId("spectest-user-alice@example.com").click();
+ * ```
+ */
+export declare function google(opts?: GoogleOptions): {
+    image: {
+        type: "dockerfile";
+        content: string;
+    };
+    command: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    env: {
+        SPECTEST_AUTH_CONFIG: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};

package/dist/components/google.js

@@ -0,0 +1,92 @@
+// `google()` — Google, emulated inside the environment, answering at its
+// real endpoints.
+//
+// Today that is Sign in with Google: OpenID Connect discovery, the account
+// picker, PKCE, the token exchange, refresh, and userinfo. The component is
+// named for the provider rather than for the feature, because the backing
+// emulator also carries Gmail, Calendar and Drive — claiming
+// `gmail.googleapis.com` and routing it here is a table entry, not a new
+// design.
+import { emulatorService, familyName, givenName, oauthClients, resolveUsers, } from "./emulate/service.js";
+function spec(users, opts) {
+    return {
+        name: "google",
+        module: "@emulators/google",
+        pluginExport: "googlePlugin",
+        baseUrl: "https://accounts.google.com",
+        hosts: [
+            "accounts.google.com",
+            "oauth2.googleapis.com",
+            "www.googleapis.com",
+            "openidconnect.googleapis.com",
+        ],
+        discovery: {
+            issuer: "https://accounts.google.com",
+            authorization_endpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+            token_endpoint: "https://oauth2.googleapis.com/token",
+            userinfo_endpoint: "https://openidconnect.googleapis.com/v1/userinfo",
+            revocation_endpoint: "https://oauth2.googleapis.com/revoke",
+            jwks_uri: "https://www.googleapis.com/oauth2/v3/certs",
+        },
+        jwksPath: "^/oauth2/v3/certs$",
+        rewrites: [
+            // oauth2.googleapis.com serves these at the root; the emulator puts
+            // them under /oauth2.
+            { from: "^/token$", to: "/oauth2/token" },
+            { from: "^/revoke$", to: "/oauth2/revoke" },
+            // openidconnect.googleapis.com and the v3 alias both mean userinfo.
+            { from: "^/v1/userinfo$", to: "/oauth2/v2/userinfo" },
+            { from: "^/oauth2/v3/userinfo$", to: "/oauth2/v2/userinfo" },
+        ],
+        fallbackUser: { login: users[0].email, id: 1, scopes: ["openid", "email", "profile"] },
+        seed: {
+            users: users.map((u) => ({
+                email: u.email,
+                name: u.name,
+                given_name: givenName(u),
+                family_name: familyName(u),
+                picture: u.picture,
+                email_verified: true,
+            })),
+            ...oauthClients(opts.client),
+        },
+    };
+}
+/**
+ * Google, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { google } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   // Accounts default to Alice and Bob Example; declare `users` to
+ *   // choose your own. A `client` makes the environment validate the
+ *   // app's client id, secret and callback URL.
+ *   google: google({
+ *     client: {
+ *       clientId: "1234.apps.googleusercontent.com",
+ *       clientSecret: "GOCSPX-test",
+ *       redirectUris: ["https://app.test/callback/google"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["google"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://accounts.google.com/o/oauth2/v2/auth`, exchanges the code at
+ * `https://oauth2.googleapis.com/token`, and verifies the id_token against
+ * `https://www.googleapis.com/oauth2/v3/certs`, exactly as it does live.
+ *
+ * A test signs in the way a user does, through the browser:
+ *
+ * ```ts
+ * await page.getByTestId("login-google").click();
+ * await page.getByTestId("spectest-user-alice@example.com").click();
+ * ```
+ */
+export function google(opts = {}) {
+    const users = resolveUsers("google", opts.users);
+    return emulatorService(spec(users, opts));
+}