Cloudflare Workers 集成测试深度拆解只 stub 一个东西如何在 cloudflare-os 里驱动真实的 workerd Worker 跑完端到端【免费下载链接】cloudflare-osAgent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-os给一个 Cloudflare Workers 系统做集成测试你会撞上一堵 mock 帮不了忙的墙被测代码不在测试进程里它跑在另一个 workerd 进程里——有自己的时钟、自己的fetch、自己的 KV 存储。本文以 cloudflare-os 的packages/integration-tests套件为样本从源码层拆解这套架构wrangler的createTestHarness()如何在内存中把workshop-backend与 gatekeeper Worker 原样启动、到底只 stub 了什么出站 HTTP、假定时器失效时时间敏感状态由谁控制、以及一个新厂商的测试套件如何零 fork 地加进来。读完你可以为任何 Worker 系统复刻这套 harness interceptor RPC client 组合。先建立坐标系同一套基础设施的两种形态cloudflare-os 是一个构建在 Cloudflare Workers 上的 Agent workspace用户在工作区里创建文档、绑定外部系统的资源gatekeeper 负责每个厂商的凭证与访问控制并由一个 overseer 组件仲裁观察者observer的准入。这个系统的集成测试体系分两种形态职责边界必须先分清本仓库的packages/integration-tests消费方仓库的 per-vendor 套件跑在哪pnpm testCI 常规测试任务消费方自己的 CI 步骤Gatekeeper 是谁一个 fixture Worker验证结果由测试通过 HTTP 指定未修改的真实厂商 gatekeeper验证什么overseer 的 observer 仲裁逻辑真实过期凭证下的端到端行为各自拥有harness、interceptor、RPC client该厂商的 handler 模块与 token 铸造新增覆盖加测试文件加一个 handler 模块 指向该包要强调一点本仓库里不存在第二列那种套件也没有任何代码依赖它存在。它被详细描述是因为 toolkit 的全部参数化设计就是为它准备的——harness 接受 gatekeeper 列表interceptor 接受可插拔 handler 模块。文档里描述 per-vendor 套件时应把它读作「这种形态的工作示例」。支撑两种形态的是四块源码全部在 packages/integration-tests/src/ 与 packages/integration-tests/fixtures/gatekeeper-test/ 下harness.ts——把真实 Worker 从 checked-in 配置启动起来的「流水线」fixtures/gatekeeper-test/src/test-gatekeeper.ts——说着真实协议的测试替身network-interceptor.ts——唯一被 stub 的出站 HTTP 层rpc-client.ts——让测试用浏览器同款传输协议与 Workshop 对话。拆解一harness——如何把真实 Worker「原样」从 checked-in 配置启动harness.ts 的startHarness()是整个套件的入口。它的职责拿仓库里真实部署用的wrangler.jsonc在内存中打补丁交给createTestHarness()启动。三个处理步骤每一步都在回避一个具体的坑。步骤 1宽松 schema 校验 钉死路径。配置用jsonc-parser解析后过 zod schema但 schema 是刻意的z.looseObject——只校验 harness 自己会读写的字段name、main、services、vars等其余字段原样透传由 wrangler 在 Worker 启动时对完整文件重新校验。这样做的理由是失败定位配置一旦损坏会在这里带着字段名报错而不是被强制类型转换后在更隐蔽的地方炸掉。紧接着是两处路径修正const config parsed.data; config.build { ...config.build, cwd: dir }; config.main join(dir, config.main);main改成绝对路径是因为 inline 配置没有自己的文件路径wrangler 会把相对main相对 harness 的root解析build.cwd钉到 Worker 自身目录是因为main由capnweb-validate构建生成的 Worker 若不钉 cwd产物会落到错误位置。步骤 2从一个「没有任何 var 文件」的目录启动。这是最隐蔽的一处。HARNESS_ROOT被设为.wrangler/harness-root这个空目录源码注释解释了因果链wrangler 把 inline 配置当作位于root/wrangler.jsonc于是会去加载该目录的.dev.vars/.env并让这些值覆盖配置自身的同名 vars。如果 harness 的 root 是仓库根目录开发者本地的CF_AI_GATEWAY_*之类设置就会渗进测试——套件在个人机器与 CI 上行为不一致甚至可能发出真实 AI 流量。源码还要求配置不得声明secrets因为那会让 wrangler 把process.env以同样方式折叠进 vars。步骤 3按套件请求裁剪 workshop 配置。关键片段config.services gatekeepers.map(gk ({ binding: GATEKEEPER_${gk.binding}, service: gk.name, entrypoint: GatekeeperVendor, }));只为套件显式请求的 gatekeeper 添加 service 绑定。Workshop 靠扫描GATEKEEPER_binding发现 vendor——多绑一个observer 配置提示里就多出一行意外内容。同样在这个函数里不设置CF_ACCESS_AUD让/api走未认证路径、ADMINS设为[admin]、默认删除worker_loaders绝大多数测试不需要 Gadget 执行显式enableGadgetExecution才保留。启动后返回的Harness对象暴露fetchWorker(name, ...)——直接向指定 Worker 自身的 HTTP entrypoint 派发请求。host 永远不会被 DNS 解析请求直达该 Worker所以不需要routes配置但路径仍须匹配该 Worker 的预期。fixture 的控制面/control/verify-outcome等就靠它调用封装在testControl()helper 里。拆解二fixture gatekeeper——说着真实协议的测试替身overseer 的测试需要一个能按命令拒绝 observer的 gatekeeper。每个现役公开 gatekeeper 都做不到这一点或代价会主导整个测试OAuth 类要在账号存在之前 mock 一整套厂商认证面Context Library 只有观察被记录后才拒绝且是单例永远产生不了某些用例需要的「两个同时失败的绑定」。于是 test-gatekeeper.ts 是一个真 Worker说真实协议所有 RPC 类都带validateRpc()与生产 gatekeeper 走同一套capnweb-validate校验内部结构分四层TestControlDurableObject持有全部控制状态。setVerifyOutcome(label, outcome, resourceUrl?)把验证结果按outcome:${label}或outcome:${label}:${resourceUrl}写入 KV资源级结果优先于账号级getVerifyOutcome()默认{ allow: true }——保证协作者第一次打开必然成功。GatekeeperVendorWorkerEntrypointdescribe()返回autoProvisionAccount: truecreateAccount()每次调用铸造一个全新账号test-uuidgadgets-test.example。一次 RPC 即完成「连接」这正是让测试聚焦 overseer 而非 OAuth 舞会的手段。TestVerifieridentify()返回账号标签是 overseer 问「谁在请求」的通道。TestGatekeeperDurableObject每绑定资源一个核心行为在addObserver()const outcome await control(this.ctx.exports).getVerifyOutcome(label, resourceUrl); if (!outcome.allow) throw new Error(outcome.reason);抛错就是 gatekeeper 报告「此用户不可观察」的方式也是 overseer 失败处理围绕的核心行为。readValue()则通过approvalQueue.authorizeObservation()走真实审批流后返回固定值 42——连「读」都是可审计的。两个设计细节值得放大。其一fixture 刻意不区分「定型拒绝」你不可读此数据与「运行性失败」凭证过期两者到达 overseer 时完全一样都是抛出的错误overseer 无法区分——这是设计使然因为它把所有失败都视为可修复的。所以只有一个控制旋钮allow区分由 reason 字符串承载测试通过选择不同的 reason 文本演练两种叙事见 observer-reverification.test.ts 的EXPIRED_REASON/DENIED_REASON。其二HTTP 控制面对每个请求体逐字段校验badRequest()返回指明哪个字段错了的 400。注释说明这不是为了安全调用者只有本包内的 helper而是为了失败模式一个拼错的字段会给名为undefined的账号注册结果gatekeeper 继续放行本该失败的账号测试在若干步之后死于一个与真实原因毫不相干的断言。fixture 还有一个「负向证明」路由/control/fetch-probe让 Worker 对https://example.com/definitely-not-mocked发起真实子请求。注意源码注释解释的现象——被拦截的请求不会在 Worker 内 rejectharness 代理出站 fetch代理侧失败以合成 500 返回。probe 让测试能断言「Worker 发起的子请求确实经过 interceptor」从而排除「其它零逃逸断言全部测了个寂寞」的可能性。拆解三network-interceptor——唯一被 stub 的东西自带证明network-interceptor.ts 是整套隔离保证的机制层原理一行说清createTestHarness会把 Worker 的出站fetch()路由回 Node 进程所以只需 patchglobalThis.fetch无需任何拦截库。行为规则按顺序loopbacklocalhost/127.0.0.1/[::1]默认放行让测试客户端直连 harness安全敏感场景可关allowLoopback让模型作者发起的请求也走 handler 链无法触达宿主服务命中allow回调的外部请求强制设置accept-encoding: identity——Node 的 fetch 解压了压缩体却原样转发Content-Encodingworkerd 会对明文再次解压源码注释「Gzip decompression failed」曾这样杀死本地 eval 目标里每条 Anthropic 流;走 handler 链没人接住则记录并抛错for (const handler of this.#handlers) { const response await handler(url, method, request.headers, request); if (response) return response; } this.#unmockedCalls.push(${method} ${raw}); throw new Error(Unmocked outbound request: ${method} ${raw});未 mock 的调用失败测试而不是悄悄触网——这是隔离保证的本体。handler 是纯函数签名(url, method, headers, request) Response | null返回null表示「不接让下一个 handler 试」。约束微妙在 body 上handler 只有在决定自己拥有该 URL 之后才可读取request——先消费 body 再返回null会破坏后续 handler 对同一流的读取。handler 可以是 async 的有些需要等待测试在 Worker 发起请求后才决定返回什么。记录与提取分离得也很讲究getUnmockedCalls()只读拷贝takeUnmockedCalls(substring)只移除并返回含指定子串的条目、不 reset 整个列表——这是为并发测试准备的一个用例故意诱发逃逸请求后取走自己的条目兄弟测试放跑的逃逸仍留在列表里等afterAll统一清算。拆解四rpc-client——让测试说浏览器的话rpc-client.ts 让测试以浏览器完全相同的方式驱动 Workshopconnect(baseUrl)把/api转成ws:URL用 capnweb 的newWebSocketRpcSessionPublicApi()开一个 RPC 会话。几个函数各消一个工程难题passwordHashFor()——直接用 SHA-256 代替前端的 argon2id64 MiB 每次调用。成立的依据在源码注释里server 对这些字节原样存储比较、从不重新推导所以确定性替代值是安全的。nextUsernames()——递增计数器铸造新身份export function nextUsernames(...prefixes: string[]): string[] { const n userSeq; return prefixes.map(prefix ${prefix}${n}); }nextUsernames(alice, bob)得到[alice7, bob7]Workshop 要求用户名以字母开头且为字母数字前缀也必须如此。它不是便利函数而是存储隔离机制本身——原因见下节取舍 1。waitFor()——30 秒内以 25ms 间隔轮询用于「效果只能通过 API 的最终状态观察」的场景如账号出现在用户列表而不是等某个 Promise。listConnectedAccounts()——把订阅协议驱动到可断言的形态临时实现ConnectedAccountsSubscriber收集增量add/remove事件等ready()后返回快照。用using声明式资源管理按逆序释放先退订、再释放原始 stub并覆盖订阅调用自身抛错的路径。accountLabel()——镜像 overseer#describeObserverFailures的优先级uniqueName || displayName || account N。这个看似琐碎的对齐保证测试断言的错误消息与用户在 UI 里读到的是同一个字符串。ObserverConfigRecorder——整个 overseer 测试套件的断言面。它实现ObserverConfigCallbackcalls数组记录每次configure()收到的ObserverBindingNeed[]应答来自脚本化队列。alwaysChoose(accountId, times)的times必须显式队列空时configure()会抛错多出来的意外提示应当失败而不是被静默应答。MAX_OBSERVER_PROMPTS 2overseer 的MAX_CONFIG_REPROMPTS为 1即初始提示 至多一次重提示作为常量集中断言避免每个套件重复出现魔法数字。取舍六个设计决定以及被否掉的替代方案这一节是全文判断力所在。每条按「决定 / 被否掉的替代方案 / 为什么现在这样更好」展开。取舍 1存储隔离靠「每次取全新身份」的约定被否掉的替代方案测试之间调用server.reset()清空存储。实测数据一锤定音每次调用约 3 秒比整个套件跑一遍还久而且它重启 server——server.url变为 undefined所有已打开的 WebSocket RPC 会话都以 WebSocket connection failed 死掉。它不是存储清空工具是 teardown。现在的做法存储在整个 harness 生命周期内持续存在任何测试不得假设干净的起点。测试通过nextUsernames()、每测试唯一的资源 URL、由 connect/provision helper 分配的账号标签保持独立——这同时也是用例能以it.concurrent并行跑起来的条件。取舍 2时间敏感状态由 fixture 控制面制造不用假定时器被否掉的替代方案vi.useFakeTimers()。它 patch 的是测试进程的时钟而被测代码读取的是workerd 的时钟——跨进程假时钟对它不可见。isTokenExpired()的 30 秒 skew 位于gatekeeper-shared内部在 Worker 内求值测试进程里的假定时器根本影响不到它。边界要划清在vitest-pool-workers下测试与被测代码在同一个 isolate内此时假定时器确实可用。所以这条限制只针对跨进程的集成测试。现在的做法是把时间敏感状态如「凭证已过期」建模为 fixture 的一个控制旋钮/control/verify-outcome设为拒绝 过期文案的 reason一次 HTTP 调用即可翻状态。取舍 3overseer 逻辑用 fixture 测厂商真实性用真实 gatekeeper 测被否掉的替代方案一给现役 gatekeeper 加测试钩子如「标记已观察」。被否决的理由是循环论证那会 stub 掉 tracker 维护的状态本身测试于是验证了自己 stub 的东西。被否掉的替代方案二直接用真实 OAuth gatekeeper 测 overseer。账号存在之前就得 mock 一整套厂商认证面代价主导测试本身。现在的做法两条线分工。fixture 验证 overseer 的仲裁逻辑收集所有失败、重提示一次、指明哪条连接哪个账号失败真实 gatekeeper 未修改地跑在 mocked 厂商端点上验证端到端行为。fixture 顶部注释明确写着它「deliberately does not try to be」后者。取舍 4零逃逸断言放在 afterAll不放 afterEach被否掉的替代方案每个用例的afterEach里断言「没有任何请求逃逸到互联网」。在it.concurrent下某个afterEach触发时兄弟姐妹仍在运行——它会检查并清空那些兄弟还在使用的状态甚至可能丢掉一个本该由某个兄弟测试背锅的逃逸请求。现在的做法observer-reverification.test.ts 的afterAllconst unmocked interceptor.getUnmockedCalls(); await harness?.server.close(); interceptor.uninstall(); interceptor.reset(); expect(unmocked).toEqual([]);先快照再拆除一个文件一次断言。取舍 5wrangler / miniflare / workerd 栈联动钉死被否掉的替代方案让 wrangler 按自己的节奏升级。更新的 wrangler 带来更新的 miniflare后者要求比当前二进制更新的 workerdharness 启动即失败The Workers runtime failed to start ... requires compatibility date 2026-07-08, but the newest date supported by this server binary is 2026-06-30.现在的做法pnpm-workspace.yaml 的 catalog 把miniflare钉到精确预发布版本5.20260921.1-alpha与 catalog 的 wrangler 所依赖的一致overrides块把测试池的依赖折叠进 catalogoverrides: cloudflare/vitest-pool-workersminiflare: catalog: cloudflare/vitest-pool-workerswrangler: catalog:升级 wrangler 必须同步升级 miniflare二者不能各自为政——让版本漂移会装出第二套 Wrangler/Miniflare/workerd 栈。取舍 6capnweb 边界由 toolkit 独占被否掉的替代方案测试文件直接import { RpcStub } from capnweb铸造回调 stub。消费方仓库会安装自己的工作区和public/子模块的工作区作为两个独立的 pnpm store——于是capnweb解析出两份副本toolkit 的rpc-client拿到子模块那份消费方自己包拿另一份。stub 只能由拥有会话的那个实例序列化混用必然失败TypeError: Cannot serialize value: [object RpcStub]陷阱在于它只在 CI 出现开发机上单次pnpm install会把两份去重合并问题不复现CI 分别执行pnpm install与pnpm --dir public install才暴露。现在的做法回调 stub 一律经stubFor()铸造rpc-client.ts内部用new RpcStub把RpcStub当类型导入没问题类型在编译期擦除。本仓库在结构上强制执行这一点——vite.config.ts 关联的 lint 规则把本包内capnweb的值导入限制到rpc-client.tsallowTypeImports放行类型导入。没有 linter 的消费方仓库应把它当约定。边界与陷阱速查陷阱现象正确做法Worker 入口模块导出字符串常量等普通值workerd 报Incorrect type for map entry XXX: the provided value is not of type function or ExportedHandler入口模块只导出类与默认 handler其它值保持模块私有类型导出没问题它们被擦除假设测试从干净存储开始用例互相污染且只在并发下出现全新身份nextUsernames()、每测试唯一资源 URL、helper 分配账号标签把server.reset()当存储清空每次约 3 秒且所有已开 WebSocket 会话断开只当 teardown 用隔离靠全新身份零逃逸断言放afterEach并发下误判或丢掉兄弟测试的逃逸证据放afterAllgetUnmockedCalls()一次断言值导入RpcStub铸造 stubCI 报Cannot serialize value: [object RpcStub]开发机不复现一律stubFor()类型导入没问题升级 wrangler 不同步 catalogharness 启动失败compatibility date 报错wrangler 与 miniflare 联动升级本地.dev.vars渗进 harness个人机器与 CI 行为不一致可能发出真实 AI 流量harness 从空目录启动配置不声明secretshandler 先读 body 再返回 null后续 handler 无法读取同一 stream只在决定拥有该 URL 之后才读request出站请求未被任何 handler 接住Unmocked outbound request抛错这正是隔离保证补 handler 或显式allow而不是放行落地跑起来并加一个新厂商的套件仓库地址https://gitcode.com/GitHub_Trending/cl/cloudflare-os。git clone https://gitcode.com/GitHub_Trending/cl/cloudflare-os cd cloudflare-os pnpm install跑整套集成测试CI 常规路径pnpm test只跑集成测试包pnpm --filter gadgets/integration-tests run test:run # 预构建 vitest run pnpm --filter gadgets/integration-tests run test:watch # 预构建 监听模式test:run先执行test:prebuild即vp run -F gadgets/integration-tests build:test-gatekeeper把workshop-backend与 fixture gatekeeper 的main都预构建到各自的.wrangler/validate/。global-setup.ts 随后验证两个预构建产物存在缺失即抛错并设置WORKSHOP_INTEGRATION_PREBUILT1——harness 看到它就把 workshop 配置的build删掉因为共享构建已完成每个 fork 里重建会争抢同一目录。watch 模式下有个细节重跑前会waitForTestRunEnd()等当前 run 结束再重建因为 rerun 入口不会取消它要替换的 run直接重建会覆盖仍在启动的 Worker 正在读取的文件被删除的 Worker 输入文件则通过prependListener(unlink, ...)转入onFileChange路径触发重跑vitest 的删除路径从不查询forceRerunTriggers这是 vitest.config.ts 注释里点名的缺口。vitest.config.ts 另设 120 秒的testTimeout/hookTimeout——workerd 启动与真实 RPC 往返需要这个量级的余量。扩展一个新厂商的套件无论在本仓库还是消费方仓库形态相同且零 fork新建 handler 模块如google-handlers.ts实现Handler签名mock 该厂商的 token 端点与 API 端点返回真实形状的响应把 harness 指向该 gatekeeper 包startHarness({ gatekeepers: [{ binding: GOOGLE, dir: ../gatekeeper-google }] })必要时用GatekeeperSpec.patch调整其配置如设置测试依赖的vars不要碰生产代码真实 gatekeeper 原样运行厂商外部面全部由 handler 模块 mock。消费方仓库额外遵守两条本仓库已内建为结构的约定回调 stub 一律经stubFor()「零逃逸」断言放afterAll。收尾回到开头那堵墙被测代码在另一个进程里。cloudflare-os 的答案不是绕过这个事实而是承认它——测试经浏览器同款传输协议WebSocket 上的 Capn Web驱动它存储隔离靠约定时间敏感状态由一个说真实协议的 fixture 暴露控制面唯一被 stub 的是出站 HTTP而且连「拦截真的生效」都有 probe 自证。六条设计约束全部由这一事实推导而来而 harness 接受 gatekeeper 列表、interceptor 接受 handler 模块的参数化形态正是让任何新厂商、任何消费方仓库零 fork 接入的扩展点。【免费下载链接】cloudflare-osAgent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-os创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考