@capybara-hq/testing 0.0.0-stage → 0.1.0-rc.0

package/dist/fake-openapi-server.js

@@ -0,0 +1,278 @@
+import { createServer } from "node:http";
+/** 1×1 透明 PNG。 */
+const PNG = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "base64");
+/**
+ * 默认文档（OpenAPI 3.0.3）：宠物 CRUD + 几个用于测试的操作。servers 用服务器变量给出端口（测试默认值替换），
+ * 参数与模式用内部 `$ref`，认证为 API key。
+ */
+export function defaultFakeOpenApiSpec(base, apiKeyIn = "header") {
+    const port = new URL(base).port;
+    return {
+        openapi: "3.0.3",
+        info: { title: "Fake Pet Store", version: "1.0.0" },
+        servers: [{ url: "http://127.0.0.1:{port}/v1", variables: { port: { default: port } } }],
+        security: [{ apiKey: [] }],
+        paths: {
+            "/pets": {
+                get: {
+                    operationId: "listPets",
+                    summary: "List pets",
+                    description: "Returns all pets, optionally filtered by tag.",
+                    parameters: [
+                        {
+                            name: "limit",
+                            in: "query",
+                            description: "Maximum number of pets to return",
+                            schema: { type: "integer", minimum: 1 },
+                        },
+                        {
+                            name: "tags",
+                            in: "query",
+                            description: "Only pets with one of these tags",
+                            schema: { type: "array", items: { type: "string" } },
+                        },
+                    ],
+                    responses: { "200": { description: "Pets" } },
+                },
+                post: {
+                    operationId: "createPet",
+                    summary: "Create a pet",
+                    requestBody: {
+                        required: true,
+                        content: { "application/json": { schema: { $ref: "#/components/schemas/NewPet" } } },
+                    },
+                    responses: { "201": { description: "Created" } },
+                },
+            },
+            "/pets/{petId}": {
+                parameters: [{ $ref: "#/components/parameters/PetId" }],
+                get: { operationId: "getPet", summary: "Get a pet by id", responses: {} },
+                patch: {
+                    operationId: "updatePet",
+                    summary: "Update a pet",
+                    requestBody: {
+                        content: { "application/json": { schema: { $ref: "#/components/schemas/NewPet" } } },
+                    },
+                    responses: {},
+                },
+                delete: { operationId: "deletePet", summary: "Delete a pet", responses: {} },
+            },
+            "/pets/{petId}/photo": {
+                parameters: [{ $ref: "#/components/parameters/PetId" }],
+                get: { operationId: "getPetPhoto", summary: "Download the pet's photo", responses: {} },
+            },
+            "/echo": {
+                get: {
+                    operationId: "echo",
+                    summary: "Echo the query string and trace header",
+                    parameters: [
+                        { name: "ids", in: "query", explode: false, schema: { type: "array", items: {} } },
+                        {
+                            name: "filter",
+                            in: "query",
+                            style: "deepObject",
+                            schema: { type: "object", additionalProperties: { type: "string" } },
+                        },
+                        { name: "X-Trace-Id", in: "header", schema: { type: "string" } },
+                    ],
+                    responses: {},
+                },
+            },
+            "/notes": {
+                post: {
+                    operationId: "createNote",
+                    summary: "Store a plain-text note",
+                    requestBody: {
+                        required: true,
+                        content: { "text/plain": { schema: { type: "string" } } },
+                    },
+                    responses: {},
+                },
+            },
+            "/boom": { get: { operationId: "boom", summary: "Always fails", responses: {} } },
+            "/moved": { get: { operationId: "moved", summary: "Always redirects", responses: {} } },
+        },
+        components: {
+            parameters: {
+                PetId: {
+                    name: "petId",
+                    in: "path",
+                    required: true,
+                    description: "The pet id",
+                    schema: { type: "integer" },
+                },
+            },
+            schemas: {
+                NewPet: {
+                    type: "object",
+                    required: ["name"],
+                    properties: {
+                        name: { type: "string" },
+                        tag: { type: "string", nullable: true },
+                    },
+                },
+            },
+            securitySchemes: {
+                apiKey: apiKeyIn === "header"
+                    ? { type: "apiKey", in: "header", name: "X-API-Key" }
+                    : { type: "apiKey", in: "query", name: "api_key" },
+            },
+        },
+    };
+}
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+});
+const json = (res, status, body) => {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+};
+/**
+ * 本地假 OpenAPI 服务（127.0.0.1 随机端口）：`/openapi.json` 给出文档（或按选项 302），`/v1/*` 实现文档里的
+ * 宠物 CRUD（内存）、回显、纯文本、二进制、500 与 302 操作；可要求 API key（请求头或 query）。
+ */
+export async function startFakeOpenApiServer(opts = {}) {
+    const keyIn = opts.apiKeyIn ?? "header";
+    const requests = [];
+    let pets = [];
+    let nextId = 1;
+    let base = "";
+    let spec;
+    const handle = async (req, res) => {
+        const u = new URL(req.url ?? "/", base);
+        const body = await readBody(req);
+        const method = (req.method ?? "GET").toUpperCase();
+        requests.push({
+            method,
+            path: u.pathname,
+            query: u.search.replace(/^\?/, ""),
+            headers: { ...req.headers },
+            body,
+        });
+        if (u.pathname === "/openapi.json") {
+            if (opts.specRedirect) {
+                res.writeHead(302, { location: `${base}/elsewhere.json` });
+                res.end();
+                return;
+            }
+            json(res, 200, spec);
+            return;
+        }
+        if (!u.pathname.startsWith("/v1/")) {
+            json(res, 404, { error: "not_found" });
+            return;
+        }
+        const got = keyIn === "header" ? req.headers["x-api-key"] : (u.searchParams.get("api_key") ?? undefined);
+        const echo = opts.echoKey ? { receivedKey: got ?? null } : {};
+        if (opts.apiKey !== undefined && got !== opts.apiKey) {
+            json(res, 401, { error: "unauthorized", ...echo });
+            return;
+        }
+        const path = u.pathname.slice(3);
+        const m = /^\/pets\/([^/]+)(\/photo)?$/.exec(path);
+        if (path === "/pets" && method === "GET") {
+            const tags = u.searchParams.getAll("tags");
+            let out = tags.length > 0 ? pets.filter((p) => p.tag && tags.includes(p.tag)) : pets;
+            const limit = u.searchParams.get("limit");
+            if (limit !== null)
+                out = out.slice(0, Number(limit));
+            json(res, 200, out);
+            return;
+        }
+        if (path === "/pets" && method === "POST") {
+            const b = JSON.parse(body);
+            if (typeof b.name !== "string") {
+                json(res, 400, { error: "name is required" });
+                return;
+            }
+            const pet = {
+                id: nextId++,
+                name: b.name,
+                ...(typeof b.tag === "string" && { tag: b.tag }),
+            };
+            pets.push(pet);
+            json(res, 201, pet);
+            return;
+        }
+        if (m) {
+            const id = Number(decodeURIComponent(m[1]));
+            const pet = pets.find((p) => p.id === id);
+            if (!pet) {
+                json(res, 404, { error: `pet ${m[1]} not found`, ...echo });
+                return;
+            }
+            if (m[2] && method === "GET") {
+                res.writeHead(200, { "content-type": "image/png" });
+                res.end(PNG);
+                return;
+            }
+            if (method === "GET") {
+                json(res, 200, pet);
+                return;
+            }
+            if (method === "PATCH") {
+                const b = JSON.parse(body || "{}");
+                if (typeof b.name === "string")
+                    pet.name = b.name;
+                if (typeof b.tag === "string")
+                    pet.tag = b.tag;
+                json(res, 200, pet);
+                return;
+            }
+            if (method === "DELETE") {
+                pets = pets.filter((p) => p.id !== id);
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+        }
+        if (path === "/echo") {
+            json(res, 200, { query: u.search.replace(/^\?/, ""), trace: req.headers["x-trace-id"] });
+            return;
+        }
+        if (path === "/notes" && method === "POST") {
+            res.writeHead(201, { "content-type": "text/plain; charset=utf-8" });
+            res.end(`stored: ${body}`);
+            return;
+        }
+        if (path === "/boom") {
+            json(res, 500, { error: "boom", ...echo });
+            return;
+        }
+        if (path === "/moved") {
+            res.writeHead(302, { location: "https://example.invalid/elsewhere" });
+            res.end();
+            return;
+        }
+        json(res, 404, { error: "not_found" });
+    };
+    const http = createServer((req, res) => {
+        handle(req, res).catch((e) => {
+            if (!res.headersSent)
+                json(res, 500, { error: "server_error", detail: String(e) });
+            else
+                res.end();
+        });
+    });
+    await new Promise((resolve) => http.listen(0, "127.0.0.1", resolve));
+    const { port } = http.address();
+    base = `http://127.0.0.1:${port}`;
+    spec = opts.spec ? opts.spec(base) : defaultFakeOpenApiSpec(base, keyIn);
+    return {
+        url: base,
+        specUrl: `${base}/openapi.json`,
+        spec: () => spec,
+        setSpec: (s) => {
+            spec = s;
+        },
+        requests,
+        pets: () => pets.map((p) => ({ ...p })),
+        stop: () => new Promise((resolve, reject) => {
+            http.closeAllConnections();
+            http.close((err) => (err ? reject(err) : resolve()));
+        }),
+    };
+}

package/dist/fake-slack.d.ts

@@ -0,0 +1,258 @@
+/**
+ * 可编程的假 Slack（Slack 渠道插件测试用），扮演两块能力：
+ *
+ * - **Web API**：`POST /api/<method>`（表单或 JSON 请求体，令牌取 `Authorization: Bearer`），实现插件用到的
+ *   `auth.test`、`chat.postMessage`、`chat.update`、`users.info`、`apps.connections.open`。机器人令牌 / 应用令牌
+ *   与构造时给的不符 → `invalid_auth`；`chat.postMessage` 文本超过 40000 字符、`chat.update` 超过 4000 字符 →
+ *   `msg_too_long`（与 Slack 文档一致）；{@link FakeSlackServer.failNext} 可让某个方法返回平台错误或 HTTP 状态码
+ *   （429 带 `Retry-After`）。WebClient 用 `slackApiUrl: server.apiUrl` 指过来。
+ * - **Socket Mode**：`apps.connections.open` 返回 `ws://…/link?ticket=<n>`；连上后先发 `hello`，测试用
+ *   {@link FakeSlackServer.push}（或 `pushEvent` / `pushInteractive`）推信封，记下客户端回的确认（`acks`）。
+ *   Envelopes are routed per app (`appToken`): a push goes to the most recently opened socket of that
+ *   app, and is queued while the app has no open socket (delivered, in push order, when one opens).
+ *   With `redeliverUnacked`, an envelope delivered to a socket that closes before acking it is
+ *   retried on the app's next socket with `retry_attempt` / `retry_reason`, like Slack does.
+ * - **Several apps**: {@link FakeSlackOptions.apps} adds Slack apps (one per channel connection) to the
+ *   same fake; each has its own app / bot token and bot user, and `auth.test` answers per bot token.
+ *
+ * - **Sign in with Slack（OpenID Connect）**：`GET /openid/connect/authorize`（测试在授权地址后加 `&as=<user id>`
+ *   表示以该用户登录，302 回 `redirect_uri?code=…&state=…`；`client_id` 不符或用户不存在 → `error=access_denied`）、
+ *   `openid.connect.token`（`client_id` / `client_secret` / `code` / `redirect_uri`，授权码单次有效，成功返回
+ *   access token 与 RS256 签名的 `id_token`，`iss` = `https://slack.com`）、`openid.connect.userInfo`（Bearer
+ *   access token）、`GET /openid/connect/keys`（JWKS）。{@link FakeSlackServer.tamperNextIdToken} 篡改下一个
+ *   ID token 的声明或改用陌生密钥签名。
+ * - **通讯录**：`users.list`（按 `limit` 分页，游标 `response_metadata.next_cursor`；总在最前面带上 Slackbot
+ *   `USLACKBOT`，与 Slack 一样它的 `is_bot` 为 false）。
+ *
+ * 记录：`messages`（发出的消息）、`updates`（对已发消息的更新）、`calls`（每次 Web API 调用）。
+ */
+export interface FakeSlackUser {
+    id: string;
+    teamId: string;
+    name: string;
+    realName?: string;
+    displayName?: string;
+    image72?: string;
+    isBot?: boolean;
+    /** 资料邮箱（`users.list` 的 `profile.email`、OIDC 的 `email`）。 */
+    email?: string;
+    /** OIDC 的 `email_verified`（默认 false）。 */
+    emailVerified?: boolean;
+    /** 已停用（`users.list` 的 `deleted`）。 */
+    deleted?: boolean;
+    /** 多频道访客（`is_restricted`）。 */
+    isRestricted?: boolean;
+    /** 单频道访客（`is_ultra_restricted`）。 */
+    isUltraRestricted?: boolean;
+}
+/** 机器人发出（或更新）的一条消息。 */
+export interface FakeSlackMessage {
+    channel: string;
+    ts: string;
+    text: string;
+    blocks?: unknown[];
+    threadTs?: string;
+    at: number;
+}
+/** 一次 Web API 调用（请求体已解析；`blocks` 等 JSON 字段已解码）。 */
+export interface FakeSlackCall {
+    method: string;
+    token: string;
+    body: Record<string, unknown>;
+}
+/** 客户端对信封的确认。 */
+export interface FakeSlackAck {
+    envelopeId: string;
+    payload: unknown;
+    at: number;
+}
+/**
+ * 让接下来的调用失败：`error` 为平台错误（HTTP 200 + `ok: false`），`status` 为 HTTP 状态码；`body` 给了就以
+ * HTTP 200 原样返回它（模拟成功但字段缺失的响应）。
+ */
+export interface FakeSlackFailure {
+    error?: string;
+    body?: Record<string, unknown>;
+    status?: number;
+    /** 429 时的 `Retry-After`（秒）。 */
+    retryAfter?: number;
+}
+/** One more Slack app on the same fake (another channel connection with its own tokens). */
+export interface FakeSlackApp {
+    appToken: string;
+    botToken: string;
+    /** Defaults to the server's `teamId`. */
+    teamId?: string;
+    /** Defaults to the server's `botUserId`. */
+    botUserId?: string;
+    /** Defaults to the server's `botId`. */
+    botId?: string;
+}
+/** Which app an envelope is for (default: the server's own `appToken`). */
+export interface FakeSlackPushTarget {
+    appToken?: string;
+}
+export interface FakeSlackOptions {
+    teamId?: string;
+    botUserId?: string;
+    botId?: string;
+    botName?: string;
+    botToken?: string;
+    appToken?: string;
+    /** Sign in with Slack 的 OAuth 客户端。 */
+    clientId?: string;
+    clientSecret?: string;
+    /** Extra Slack apps served alongside the default one (whose tokens are `appToken` / `botToken`). */
+    apps?: FakeSlackApp[];
+    /**
+     * Redeliver unacked envelopes (after Slack Socket Mode: an envelope not acked is retried). The fake
+     * redelivers on socket close only: when the socket an envelope went to closes before the client
+     * acked it, the envelope goes again to the app's next open socket, with `retry_attempt` (1, 2, …)
+     * and `retry_reason: "timeout"`. Real Slack also retries on an ack timeout while the socket stays
+     * open; the fake does not. Default off, so tests that leave an envelope unacked on purpose don't
+     * see it again in a later connection.
+     */
+    redeliverUnacked?: boolean;
+}
+export interface FakeSlackServer {
+    /** HTTP 根地址。 */
+    url: string;
+    /** WebClient 的 `slackApiUrl`（`<url>/api/`）。 */
+    apiUrl: string;
+    teamId: string;
+    botUserId: string;
+    botId: string;
+    botToken: string;
+    appToken: string;
+    clientId: string;
+    clientSecret: string;
+    messages: FakeSlackMessage[];
+    updates: FakeSlackMessage[];
+    calls: FakeSlackCall[];
+    acks: FakeSlackAck[];
+    users: Map<string, FakeSlackUser>;
+    /** `apps.connections.open` 成功的次数（given an `appToken`: for that app only）。 */
+    connectionsOpened(appToken?: string): number;
+    /** 当前打开的 WebSocket 数（given an `appToken`: of that app only）。 */
+    openSockets(appToken?: string): number;
+    /** 同时打开的 WebSocket 数峰值（given an `appToken`: of that app only）。 */
+    maxConcurrentSockets(appToken?: string): number;
+    /**
+     * 当前打开的长连接各自的对端（客户端）TCP 端口，按打开顺序（given an `appToken`: of that app only）。
+     * 双副本测试据此（经操作系统查端口属于哪个进程）找出持有长连接的副本——真实插件不带 `x-pid` 之类的标记。
+     */
+    socketPeerPorts(appToken?: string): number[];
+    /**
+     * Envelopes pushed but not acked yet: queued (no open socket) or delivered and awaiting the ack
+     * (given an `appToken`: of that app only). Without `redeliverUnacked`, an envelope whose socket
+     * closed unacked is dropped from this count.
+     */
+    pendingEnvelopes(appToken?: string): number;
+    failNext(method: string, failure: FakeSlackFailure, count?: number): void;
+    /** 之后该方法的每次调用先等 `ms` 毫秒再响应（0 取消）。 */
+    delay(method: string, ms: number): void;
+    /** 接下来 `count` 条 Socket Mode 连接在发出 hello 后立即被关闭（不发 disconnect 消息）。 */
+    dropNextConnections(count: number): void;
+    /**
+     * 推一个原始信封给该 app 最近打开的一条连接，返回 envelope_id；the app has no open socket → queued
+     * and delivered when one opens. Throws for an unknown `appToken`.
+     */
+    push(envelope: {
+        type: string;
+        payload: unknown;
+        envelope_id?: string;
+    }, target?: FakeSlackPushTarget): string;
+    /**
+     * 推一个 Events API 事件（`events_api` 信封，外层 `event_callback` 带 team_id / event_id；team_id
+     * defaults to the target app's team）。
+     */
+    pushEvent(event: Record<string, unknown>, opts?: {
+        eventId?: string;
+        teamId?: string;
+    } & FakeSlackPushTarget): string;
+    /** 推一个交互负载（`interactive` 信封，如 block_actions）。 */
+    pushInteractive(payload: Record<string, unknown>, target?: FakeSlackPushTarget): string;
+    /** 等到该信封被确认（超时抛错）。 */
+    waitForAck(envelopeId: string, timeoutMs?: number): Promise<FakeSlackAck>;
+    /** 是否已确认该信封。 */
+    acked(envelopeId: string): boolean;
+    /** 发 `disconnect` 并关闭所有连接（模拟 Slack 回收连接）。 */
+    disconnectAll(reason?: string): void;
+    /**
+     * 篡改下一个签发的 ID token：`claims` 覆盖（或新增）声明，值为 undefined 即去掉该声明；`foreignKey` 时用
+     * 不在 JWKS 里的密钥签名；`kid` 改写头部的 key id。
+     */
+    tamperNextIdToken(claims: Record<string, unknown>, opts?: {
+        foreignKey?: boolean;
+        kid?: string;
+    }): void;
+    /** 消息最终显示的文本（有更新取最后一次）。 */
+    finalText(m: FakeSlackMessage): string;
+    /** 消息最终的 blocks（有更新取最后一次）。 */
+    finalBlocks(m: FakeSlackMessage): unknown[] | undefined;
+    stop(): Promise<void>;
+}
+/** 启动假 Slack（监听 127.0.0.1 随机端口）。 */
+export declare function startFakeSlack(opts?: FakeSlackOptions): Promise<FakeSlackServer>;
+/** 私聊消息事件（`message.im`；默认频道 `D<user>`）。 */
+export declare function slackDmEvent(user: string, text: string, opts?: {
+    ts?: string;
+    channel?: string;
+    team?: string;
+    extra?: Record<string, unknown>;
+}): Record<string, unknown>;
+/** 频道里 @ 机器人的事件（`app_mention`；`threadTs` 给了表示在话题里）。 */
+export declare function slackMentionEvent(user: string, botUserId: string, text: string, opts?: {
+    ts?: string;
+    channel?: string;
+    threadTs?: string;
+    team?: string;
+}): Record<string, unknown>;
+/**
+ * 用户点了某条消息上的按钮（`block_actions`）。`message` 为假 Slack 记下的那条消息，`actionId` / `value`
+ * 取自其 blocks 里的按钮；`stateValues` 为 `state.values`（多选提交时带上勾选项）。
+ */
+export declare function slackBlockAction(user: {
+    id: string;
+    teamId: string;
+    name?: string;
+}, message: FakeSlackMessage, action: {
+    actionId: string;
+    value?: string;
+    blockId?: string;
+}, opts?: {
+    actionTs?: string;
+    stateValues?: Record<string, unknown>;
+    triggerId?: string;
+}): Record<string, unknown>;
+/** 在消息的 blocks 里找按钮（按 action_id 前缀或谓词），返回 `{ actionId, value, blockId }`。 */
+export declare function findSlackButton(blocks: unknown[] | undefined, match: (el: {
+    action_id: string;
+    value?: string;
+    url?: string;
+    text?: {
+        text?: string;
+    };
+}) => boolean): {
+    actionId: string;
+    value?: string;
+    blockId?: string;
+    url?: string;
+} | undefined;
+/**
+ * An Events API `event_callback` body: what Slack posts to a webhook Request URL, and the payload
+ * of a Socket Mode `events_api` envelope (the same object, so both inbound modes see one shape).
+ */
+export declare function slackEventCallback(event: Record<string, unknown>, opts?: {
+    teamId?: string;
+    eventId?: string;
+}): Record<string, unknown>;
+/**
+ * Signs a Slack webhook request the way Slack does
+ * (https://docs.slack.dev/authentication/verifying-requests-from-slack/): returns the
+ * `x-slack-request-timestamp` and `x-slack-signature` headers, where the signature is
+ * `v0=` + hex HMAC-SHA256(signingSecret, `v0:<ts>:<raw body>`). `ts` is in seconds.
+ */
+export declare function signSlackWebhook(body: string | Uint8Array, signingSecret: string, ts: number): Record<string, string>;
+/** The form body Slack posts for an interactive payload (`payload=<url-encoded JSON>`). */
+export declare const slackInteractiveForm: (payload: Record<string, unknown>) => string;