Spectrum 后端测试指南：基于 Jest 与 GraphQL 的数据库级 e2e 测试实战

后端前端即时通讯社交【免费下载链接】spectrumSimple, powerful online communities.项目地址https://gitcode.com/gh_mirrors/sp/spectrum点击查看免费下载Spectrum 是一个构建在 React、GraphQL 与 RethinkDB 之上的开源社区平台。本文围绕仓库中的测试文档 docs/backend/api/testing.md 展开系统讲解其后端 API 的测试策略如何在没有网络请求的前提下用 Jest 对 GraphQL schema 发起真查询、命中真实的测试数据库并通过快照测试快速锁定解析器行为。读完本文你将掌握 Spectrum 的测试环境搭建、request辅助函数的底层原理、测试数据生命周期以及如何从零编写一个可复用的 GraphQL e2e 测试套件。一、测试策略总览为什么叫e2e却不需要网络Spectrum 的绝大多数测试是e2e端到端测试。这里的引号是有特殊含义的GraphQL 场景下的 e2e 测试不会发出任何网络请求但它依然会命中真实的数据库并完整走完整个解析链路。原文档的原话是Most of our tests are e2e. Thats in quotes because with GraphQL e2e tests dont do any network request, they still hit our database though and all that. (which is awesome since its much faster!)翻译过来就是因为不走网络层这类测试比传统意义上拉起整个服务的 e2e 快得多同时又比纯 mock 的单元测试更接近真实运行状态——数据从 RethinkDB 读出来经过 DataLoader 与解析器最终以 GraphQL 响应返回。这在项目里形成了一条完整的测试分工Jest 测试覆盖 GraphQL 查询/变更解析器与数据库交互本文主题Cypress 集成测试覆盖浏览器端的页面渲染与用户操作流程测试位于 cypress/integration详见 docs/testing/integration.md单元测试针对纯函数与工具库的快速校验详见 docs/testing/unit.md 与 docs/testing/intro.md。二、测试基础设施独立的 testing 数据库2.1 为什么需要独立数据库Spectrum 为测试创建了一个名为testing的独立数据库并在其中填充一批测试数据测试再针对这些数据做断言。这样做的好处是测试环境与开发/生产环境完全隔离任何测试都不会污染真实数据且每次运行都可以基于同一份确定性数据得到稳定结果。数据库连接由 shared/testing/db.js 提供它通过rethinkhaberdashery建立连接目标库固定为testing// flow module.exports require(rethinkhaberdashery)({ db: testing, });2.2 测试数据从哪来seed 数据的复用测试数据并非手写而是直接复用api/migrations/seed/default下的种子数据。文件 shared/testing/data.js 将这些种子数据按表名组装成一个对象供 setup 阶段批量写入const seed require(../../api/migrations/seed/default/index); const data { users: defaultUsers, usersSettings: defaultUsersSettings, communities: defaultCommunities, communitySettings: defaultCommunitySettings, channels: defaultChannels, channelSettings: defaultChannelSettings, threads: defaultThreads, usersThreads: defaultUsersThreads, notifications: defaultNotifications, directMessageThreads: defaultDirectMessageThreads, usersDirectMessageThreads: defaultUsersDirectMessageThreads, usersCommunities: defaultUsersCommunities, usersChannels: defaultUsersChannels, messages: defaultMessages, reactions: defaultReactions, usersNotifications: defaultUsersNotifications, };从这份清单可以看到测试库覆盖了用户、社区、频道、线程、消息、通知、私信等 Spectrum 的核心数据模型。种子数据的定义位于 api/migrations/seed/default 目录其中还导出了像SPECTRUM_COMMUNITY_ID这样的常量测试文件会直接引用它来查询固定社区见下文示例。2.3 生命周期钩子Jest 的 globalSetup 与 globalTeardownJest 的全局配置在 jest.config.js 中定义// flow // The Jest configuration const path require(path); module.exports { setupTestFrameworkScriptFile: path.resolve( __dirname, ./shared/testing/setup-test-framework ), globalSetup: path.resolve(__dirname, ./shared/testing/setup), globalTeardown: path.resolve(__dirname, ./shared/testing/teardown), testPathIgnorePatterns: [/node_modules/, /mutations/], testURL: http://localhost/, };三个关键配置项分别对应测试的三个阶段① globalSetup —— shared/testing/setup.js在所有测试开始前运行一次负责建库、跑迁移、灌数据// This script gets run once before all tests // Its responsible for setting up the test db with the test data const path require(path); const debug require(debug)(testing:setup); const { migrate } require(rethinkdb-migrate/lib); const mockDb require(./db); const data require(./data); const tables Object.keys(data); module.exports async () { debug(run all migrations over database testing); await migrate({ driver: rethinkdbdash, host: localhost, port: 28015, migrationsDirectory: path.resolve(__dirname, ../../api/migrations), db: testing, op: up, }); debug(migrations complete, inserting data into testing); await Promise.all( tables.map(table mockDb .table(table) .insert(data[table], { conflict: replace }) .run() ) ); debug(setup complete); };这段代码揭示了测试库的完整构建流程使用rethinkdb-migrate将 api/migrations 目录下的全部迁移按顺序执行到testing库op: up将data.js中的种子数据以conflict: replace的方式批量插入各表保证数据可重复注入。② setupTestFrameworkScriptFile —— shared/testing/setup-test-framework.js在每个测试文件执行前加载主要做两件事const mockDb require(./db); // Wait for 15s before timing out, this is useful for e2e tests which have a tendency to time out jest.setTimeout(30000); // Mock the database jest.mock(shared/db/db, () ({ db: mockDb, }));将 Jest 默认的 5 秒超时提升到30 秒因为数据库级 e2e 测试有超时倾向通过jest.mock将 API 层使用的数据库模块 shared/db/db 替换为指向testing库的mockDb从而让解析器在测试时打到测试库而不是开发库。③ globalTeardown —— shared/testing/teardown.js在所有测试结束后清空数据。这里有一个值得注意的工程细节——它选择清空各表数据而非直接dbDrop(testing)// NOTE(mxstbr): While this teardown script could also do mockDb.dbDrop(testing), that would mean that our API server would crash everytime due to changefeeds dropping, which would be very annoying. Instead we just clear the data from all the tables. module.exports () { debug(clearing data in database testing); return Promise.all( tables.map(table mockDb .table(table) .delete() .run() ) ); };代码注释明确解释如果直接 drop 数据库RethinkDB 的 changefeed变更订阅会因连接断开导致 API 服务器崩溃所以改为逐表delete()清理数据。这个细节说明 Spectrum 的测试基础设施与订阅系统是深度耦合的。三、编写 GraphQL e2e 测试从request辅助函数说起3.1 核心辅助函数request原文档给出了一个nice little helper function for tests而它在仓库中已经演化成正式工具位于 api/test/utils.js// flow import { graphql } from graphql; import createLoaders from ../loaders; import schema from ../schema; type Options { context?: { user?: ?Object, }, variables?: ?Object, }; // Nice little helper function for tests export const request (query: mixed, { context, variables }: Options {}) { return graphql( schema, query, undefined, { loaders: createLoaders(), ...context, }, variables ); };它的原理本质上是调用graphql-js的graphql()函数完成一次进程内执行schema来自 api/schema.js即生产环境使用的同一个 GraphQL schemacontextValue手工构造包含loaders: createLoaders()的上下文对象createLoaders来自 api/loaders与真实请求的上下文结构保持一致因此 DataLoader 的批处理与缓存行为也会被真实触发支持注入用户与变量通过context.user传入当前用户以模拟登录态通过variables传入查询变量这使得鉴权类、参数化查询也能被测试覆盖。因为整个过程不经过 HTTP、不经过 Apollo Server 中间件所以速度远快于真实网络请求但查询、解析、数据库访问的链路又是真实完整的。3.2 一个完整的测试套件原文档提供的典型测试套件如下docs/backend/api/testing.mdimport { graphql } from graphql; import createLoaders from ../loaders; import schema from ../schema; // Nice little helper function for tests const request query graphql(schema, query, undefined, { loaders: createLoaders() }); describe(queries, () { it(should fetch a user, () { // Define your query const query /* GraphQL */ { user(id: gVk5mYwccUOEKiN5vtOouqroGKo1) { name username profilePhoto } } ; // Make sure the assertion below is called and we dont run into a race condition expect.assertions(1); // Return the Promise returned from the request return request(query).then(result { // Use Jest snapshot testing for neater tests and easier diffs expect(result).toMatchSnapshot(); }); }); })这套模板有三个必须遵守的要点expect.assertions(1)显式声明至少有一个断言会被执行避免异步回调因为数据缺失而静默通过造成误判返回 Promiserequest(query)返回 Promise必须return它Jest 才能正确等待异步完成防止竞态快照断言expect(result).toMatchSnapshot()将完整的 GraphQL 响应与既有快照比对diff 清晰、维护成本低。3.3 仓库中的真实用例community.test.jsapi/test/community.test.js 是这套模式在真实代码中的落地它同时展示了变量注入、嵌套连接查询等进阶用法// flow import { request } from ./utils; import { SPECTRUM_COMMUNITY_ID } from ../migrations/seed/default/constants; it(should fetch a community, async () { const query /* GraphQL */ { community(id: ${SPECTRUM_COMMUNITY_ID}) { id createdAt name slug description website } } ; expect.assertions(1); const result await request(query); expect(result).toMatchSnapshot(); }); it(should fetch a communities threads, async () { const query /* GraphQL */ { community(id: ${SPECTRUM_COMMUNITY_ID}) { threadConnection { edges { node { content { title } } } } } } ; expect.assertions(1); const result await request(query); expect(result).toMatchSnapshot(); }); it(should fetch a list of community members, async () { const query /* GraphQL */ { community(id: ${SPECTRUM_COMMUNITY_ID}) { id members { pageInfo { hasNextPage hasPreviousPage } edges { cursor node { user { id } isOwner isModerator isMember isBlocked } } } } } ; expect.assertions(1); const result await request(query); expect(result).toMatchSnapshot(); });这段代码展示了 Spectrum 测试的几个典型特征引用种子常量SPECTRUM_COMMUNITY_ID从 api/migrations/seed/default/constants 导入保证查询的 ID 一定存在于测试库中使用 async/await与文档示例中的 Promise 链等价但可读性更好覆盖复杂解析链路threadConnection、members这类分页连接查询涉及游标、嵌套节点、权限字段isOwner/isModerator/isMember/isBlocked是 e2e 测试最有价值的覆盖对象。测试目录的组织也与生产代码一一对应例如 api/test/channel 下分queries/与mutations/两个子目录快照文件以.snap形式与测试文件并列存放见 api/test 下的各__snapshots__目录。四、运行测试脚本与 CI 流程4.1 本地运行测试脚本定义在根目录 package.json 的scripts中jest: cross-env NODE_PATH./ jest, test: npm run jest -- --runInBand --watch, test:ci: npm run jest -- --forceExit --outputFile test-results.json --json --maxWorkers2yarn jest执行 Jest通过NODE_PATH./保证源码中shared/...这类根路径导入可以解析yarn test--runInBand串行执行并在 watch 模式下监听文件变化适合开发期持续反馈yarn test:ciCI 环境专用--forceExit强制退出避免 changefeed 等长生命周期句柄阻塞进程--json --outputFile test-results.json输出结构化结果供流水线解析--maxWorkers2控制并发 worker 数量。运行前请确保本地 RethinkDB 已启动默认端口28015与 shared/testing/setup.js 中migrate的port: 28015对应否则 globalSetup 阶段会失败。4.2 测试模式启动 API供集成测试使用如果需要在浏览器端跑 Cypress 集成测试需要让 API 以测试模式运行并连接testing库对应的脚本同样在 package.jsonprestart:api:test: node -e \require(./shared/testing/setup.js)().then(() process.exit())\, start:api:test: TEST_DBtrue FORCE_DEVtrue DEBUGapi*,shared* forever build-api/main.jsprestart:api:test钩子会在启动前先执行setup.js即完成建库、迁移、灌数据TEST_DBtrue使 API 进程连接测试数据库使用forever守护进程运行生产构建产物build-api/main.js因此在此之前需要先执行yarn run build:api。完整的集成测试启动流程记录在 docs/testing/integration.md先yarn run build:api再在终端 A 运行yarn run start:api:test终端 B 运行yarn run dev:web最后yarn run cypress:open打开 Cypress GUI。五、快照测试让 diff 驱动回归检查快照是这套测试体系的核心断言手段。每次运行测试Jest 会把 GraphQL 响应与__snapshots__/下保存的.snap文件逐字比对首次运行自动生成快照文件需要人工审阅后提交到仓库后续运行响应与快照完全一致则通过不一致则失败并输出结构化 diff有意的变更如新增字段、调整返回结构需要人工确认 diff 后使用jest -u更新快照。快照的价值在于GraphQL 解析器返回的数据结构复杂、字段多手写断言既冗长又容易遗漏快照以最低的书写成本提供了最高的结构覆盖率同时它对意外的字段增减极其敏感能第一时间暴露解析器或数据层的破坏性变更。仓库中每个测试目录下都有对应的快照产物例如 api/test/snapshots、api/models/test/snapshots可以直接翻阅观察快照的格式。六、测试边界与最佳实践小结基于原文档与仓库源码可以把 Spectrum 后端测试的最佳实践归纳为以下几点优先使用数据库级 e2e 而非纯 mockgraphql(schema, query, ...)进程内执行足够快却能覆盖 DataLoader、解析器、权限逻辑与真实 RethinkDB 交互的完整链路固定测试数据库 种子数据testing库的数据来自 api/migrations/seed/default测试用例应优先引用种子常量如SPECTRUM_COMMUNITY_ID保证数据确定性牢记异步三件套expect.assertions(1)、returnPromise或 async/await、toMatchSnapshot()用context.user模拟登录态通过 api/test/utils.js 的request(query, { context: { user } })覆盖鉴权分支关注超时与清理e2e 测试超时上限被调高到 30 秒teardown 阶段只清数据不删库避免破坏 changefeed 订阅连接分层互补Jest 覆盖 API 逻辑Cypress 覆盖浏览器集成二者通过测试模式 API testing 库共用同一份测试数据资产。如果希望深入理解测试背后依赖的运行时可以继续阅读 api/schema.jsGraphQL schema 定义、api/loadersDataLoader 批量加载与 api/models数据模型层Jest 官方文档对globalSetup、toMatchSnapshot、jest.mock等机制的详细说明也值得完整通读一遍——正如原文档所建议的it has a lot of great features you might not expect。赞分享后端前端即时通讯社交【免费下载链接】spectrumSimple, powerful online communities.项目地址https://gitcode.com/gh_mirrors/sp/spectrum点击查看免费下载相关推荐Spectrum 单元测试指南基于 Jest 与真实 RethinkDB 数据库的 GraphQL API 测试实践Spectrum 单元测试指南基于 Jest 与真实 RethinkDB 数据库的 GraphQL API 测试实践 本篇技术指南以 Spectrum 仓库后端前端即时通讯社交Jest 集成 MongoDB基于 jest-mongodb Preset 的数据库测试实战指南Jest 集成 MongoDB基于 jest mongodb Preset 的数据库测试实战指南 本文是 Jest 官方文档中 MongoDB 集成指南 d测试质量保障代码覆盖率开发工具OpenTofu 云后端 e2e 验收测试运行指南基于 TFC/TFE 的端到端测试实战OpenTofu 云后端 e2e 验收测试运行指南基于 TFC/TFE 的端到端测试实战 OpenTofu 的 cloud 后端 terraform { c云原生DevOps基础设施创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考