SurfSense Playwright E2E 实战用测试数据工厂、Faker 与数据驱动模式构建可复用的测试数据体系【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense在端到端E2E测试中如何构造并管理测试数据往往决定了测试套件的稳定性与可维护性。本文以 SurfSense 仓库中沉淀的 Playwright 测试数据技能文档 test-data.md 为主体完整讲解工厂模式Factory Pattern、Faker 集成、数据驱动测试、测试数据 Fixtures 以及数据库 Seeding 五类核心手段并结合 SurfSense 前端 E2E 套件中真实存在的 fixtures、canary 令牌与 workspace 清理机制说明这些模式在 Next.js FastAPI 全栈项目里如何落地。读完本文你能够独立设计一套每个测试都有新鲜数据、失败可复现、资源可清理的测试数据体系。需要先明确本文档在 SurfSense 的 Playwright 技能体系中的定位它专注可复用的测试数据构建器factories、Faker、data generators与另外两个相邻主题分工明确——Per-test 数据库 fixtures测试隔离、事务回滚参见 fixtures-hooks.md 的 Database Fixtures 章节一次性数据库初始化migrations、snapshots参见 global-setup.md 的 Database Patterns 章节。也就是说本文解决的是数据从哪来、怎么长得可预测而 fixture 生命周期与全局初始化由上述两篇配套文档覆盖。一、Factory Pattern用工厂函数替代散落的硬编码数据1.1 基本工厂最直接的工厂是一个带overrides参数的构造函数默认值集中在一处调用方只覆盖需要变化的字段。文档给出的factories/user.factory.ts示例完整如下// factories/user.factory.ts interface User { id: string; email: string; name: string; role: admin | user | guest; createdAt: Date; } let userIdCounter 0; export function createUser(overrides: PartialUser {}): User { userIdCounter; return { id: user-${userIdCounter}, email: user${userIdCounter}test.com, name: Test User ${userIdCounter}, role: user, createdAt: new Date(), ...overrides, }; } // Usage const user createUser(); const admin createUser({ role: admin, name: Admin User });两个设计细节值得注意模块级计数器userIdCounter保证同进程内 ID 与 email 唯一。这在一次运行内创建多个实体的场景下天然避免主键/唯一约束冲突但代价是数据不是每测试一次全新重置的——若跨测试有持久化需要配合清理机制见后文 Seeding 章节的cleanupUsers模式。...overrides放在对象字面量最后确保调用方覆盖优先级最高这是工厂模式的约定默认值 → 派生关系 → 显式覆盖。1.2 带 Traits 的工厂当某个实体存在常见的状态变体缺货、促销、高价……时逐个手写 overrides 会变得冗长。Traits 把常见变体注册为命名片段调用时按名追加// factories/product.factory.ts interface Product { id: string; name: string; price: number; stock: number; category: string; featured: boolean; } type ProductTrait outOfStock | featured | expensive | sale; const traits: RecordProductTrait, PartialProduct { outOfStock: { stock: 0 }, featured: { featured: true }, expensive: { price: 999.99 }, sale: { price: 9.99 }, }; let productIdCounter 0; export function createProduct( overrides: PartialProduct {}, ...traitNames: ProductTrait[] ): Product { productIdCounter; const appliedTraits traitNames.reduce( (acc, trait) ({ ...acc, ...traits[trait] }), {}, ); return { id: prod-${productIdCounter}, name: Product ${productIdCounter}, price: 29.99, stock: 100, category: General, featured: false, ...appliedTraits, ...overrides, }; } // Usage const product createProduct(); const featuredProduct createProduct({}, featured); const saleItem createProduct({ name: Sale Item }, sale, featured); const soldOut createProduct({}, outOfStock);Trait 合并使用reduce按传入顺序依次展开后一个 trait 覆盖前一个的相同字段例如同时传sale和expensive时最终价格由顺序决定而overrides永远压过所有 traits。这个优先级链默认值 → traits → overrides是工厂可扩展性的关键新增一个 trait 只需往traits表里加一行所有既有调用不受影响。1.3 带关系的工厂真实数据几乎总是成体系的订单引用用户订单行引用商品。关系型工厂通过复用其他工厂来保证关系闭包完整同时保留对每个关联对象的可覆盖性// factories/order.factory.ts import { createUser, User } from ./user.factory; import { createProduct, Product } from ./product.factory; interface OrderItem { product: Product; quantity: number; } interface Order { id: string; user: User; items: OrderItem[]; total: number; status: pending | paid | shipped | delivered; } let orderIdCounter 0; export function createOrder(overrides: PartialOrder {}): Order { orderIdCounter; const user overrides.user ?? createUser(); const items overrides.items ?? [{ product: createProduct(), quantity: 1 }]; const total items.reduce( (sum, item) sum item.product.price * item.quantity, 0, ); return { id: order-${orderIdCounter}, user, items, total, status: pending, ...overrides, }; } // Usage const order createOrder(); const bigOrder createOrder({ items: [ { product: createProduct({ price: 100 }), quantity: 5 }, { product: createProduct({ price: 50 }), quantity: 2 }, ], });这里overrides.user ?? createUser()的写法体现了关系工厂的惯用法先尊重调用方显式提供的关联对象缺省时才用子工厂造一个而total这样的派生字段在工厂内部根据items计算避免调用方手算出错。1.4 结合 SurfSense 仓库的实践对照SurfSense 的 Web E2E 套件playwright.config.ts 指定testDir: ./tests并没有在浏览器侧维护一套纯内存工厂而是把数据创建下沉为API 调用的 fixture——tests/fixtures/index.ts 中的注释明确说明了继承链所有 connector fixture 都从workspaceFixtures派生需要聊天线程的场景再extend一层chatThreadFixtures。这种工厂即 API helper fixture 组合的思路与本文档的工厂模式同构只是产物从内存对象变成了数据库真实行。一个与计数器唯一化直接对应的真实实现是 tests/helpers/canary.ts 中的uniqueWorkspaceName/** Generate a unique-per-run workspace name. Keeps parallel tests isolated. */ export function uniqueWorkspaceName(prefix e2e): string { return ${prefix}-${randomUUID().slice(0, 8)}; }它用randomUUID()前 8 位生成每运行唯一的工作区名源码注释点明了目的让并行测试相互隔离。这与文档 Factory Pattern 中计数器方案的意图一致唯一标识但选择了每运行随机而非进程内自增更适配 Playwright 多 worker 并行的场景。二、Faker Integration用随机真实感数据且保持可复现2.1 安装与基本用法Faker 解决计数器数据缺乏真实感的问题如user1test.com这样的数据无法暴露表单校验、渲染截断等问题npm install -D faker-js/faker// factories/faker-user.factory.ts import { faker } from faker-js/faker; interface User { id: string; email: string; name: string; avatar: string; address: { street: string; city: string; country: string; zipCode: string; }; } export function createFakeUser(overrides: PartialUser {}): User { return { id: faker.string.uuid(), email: faker.internet.email(), name: faker.person.fullName(), avatar: faker.image.avatar(), address: { street: faker.location.streetAddress(), city: faker.location.city(), country: faker.location.country(), zipCode: faker.location.zipCode(), }, ...overrides, }; }可以看到 Faker 工厂与第一节的手写工厂完全兼容overrides机制原封不动只是默认值来源换成了faker.*生成器。2.2 Seeded Faker可复现的随机数据随机数据的头号风险是失败不可复现——同一失败重跑一次数据就变了。Faker 通过全局种子解决import { faker } from faker-js/faker; // Set seed for reproducible data faker.seed(12345); export function createDeterministicUser(): User { return { id: faker.string.uuid(), email: faker.internet.email(), name: faker.person.fullName(), // Same seed same data every time }; } // Or seed per test test(user profile, async ({ page }) { faker.seed(42); // Reset seed for this test const user createFakeUser(); // user will always have the same data });文档给出了两个粒度的播种方式模块级faker.seed(12345)整条测试序列可复现和测试级faker.seed(42)每个测试从相同起点生成数据既保留随机外观又保证单测内确定性。2.3 把 Faker 做成 Playwright Fixture更工程化的做法是把播种封装进 fixture让测试代码完全不感知种子细节// fixtures/faker.fixture.ts import { test as base } from playwright/test; import { faker } from faker-js/faker; type FakerFixtures { fake: typeof faker; }; export const test base.extendFakerFixtures({ fake: async ({}, use, testInfo) { // Seed based on test name for reproducibility faker.seed(testInfo.title.length); await use(faker); }, }); // Usage test(create user with fake data, async ({ page, fake }) { await page.goto(/signup); await page.getByLabel(Name).fill(fake.person.fullName()); await page.getByLabel(Email).fill(fake.internet.email()); await page.getByLabel(Password).fill(fake.internet.password()); await page.getByRole(button, { name: Sign Up }).click(); });这个 fixture 利用testInfo.title.length作为种子派生值让不同测试得到不同数据、而同一测试重跑得到相同数据。2.4 SurfSense 的选择确定性 Canary 令牌而非 Faker有意思的是SurfSense 的实际 E2E 套件刻意没有使用随机数据。从 tests/helpers/canary.ts 的源码注释看其设计动机是/** * Canary tokens deterministic test data. * * Embedded by the backend Composio fake into fake Drive file contents * (see surfsense_backend/tests/e2e/fakes/fixtures/drive_files.json). * Specs assert these strings appear in the resulting Document rows to * prove the indexing pipeline ran end-to-end. * * Each token is a stable string keyed by file id so multi-test runs * remain deterministic and the resulting Document.content is greppable * in failure traces. */ export const CANARY_TOKENS { driveCanaryFile: SURFSENSE_E2E_CANARY_TOKEN_DRIVE_001, drivePdfCanary: SURFSENSE_E2E_CANARY_TOKEN_DRIVE_PDF_001, ... } as const;这与文档Seeded Faker一节的精神完全一致甚至更彻底SurfSense 的断言链路是跨进程的connector → Celery → indexing → DB需要证明这条特定假文件的内容最终出现在 Document 行里因此使用稳定的、按文件 id 索引的固定令牌如SURFSENSE_E2E_CANARY_TOKEN_DRIVE_001保证多次运行结果确定、且失败时令牌字符串可以直接在失败产物中 grep 定位。同文件中还有FAKE_DRIVE_FILES、FAKE_GMAIL_MESSAGES、FAKE_LINEAR_ISSUES等一批与后端 fake如drive_files.json严格对齐的假数据清单形成前后端共享同一份确定性测试数据集的契约。可以推断对于需要端到端内容穿透验证的套件可 grep 的稳定 canary比 Faker 的随机真实感数据更具调试价值——这正是文档反模式表里Random data without seed → 不可复现失败在真实项目中的解法。三、Data-Driven Testing让数据定义用例3.1 场景数组驱动用例数据驱动测试的核心思想是把用例矩阵与执行逻辑分离。文档第一个例子是登录场景数组const loginScenarios [ { email: userexample.com, password: pass123, expected: Dashboard }, { email: adminexample.com, password: admin123, expected: Admin Panel }, { email: invalidexample.com, password: wrong, expected: Invalid credentials, }, ]; for (const { email, password, expected } of loginScenarios) { test(login with ${email}, async ({ page }) { await page.goto(/login); await page.getByLabel(Email).fill(email); await page.getByLabel(Password).fill(password); await page.getByRole(button, { name: Sign In }).click(); await expect(page.getByText(expected)).toBeVisible(); }); }for循环 模板字符串标题让 Playwright 为每个数据行注册独立测试失败时可精确定位到哪一行数据出了问题报告里也能看到全部行。3.2 参数化测试把场景数据独立成模块当场景数据变多或需要被多个 spec 共享时抽到独立数据模块data/checkout-scenarios.ts// data/checkout-scenarios.ts export const checkoutScenarios [ { name: standard shipping, shipping: standard, expectedDays: 5-7 business days, expectedCost: $5.99, }, { name: express shipping, shipping: express, expectedDays: 2-3 business days, expectedCost: $14.99, }, { name: overnight shipping, shipping: overnight, expectedDays: Next business day, expectedCost: $29.99, }, ];import { checkoutScenarios } from ./data/checkout-scenarios; test.describe(shipping options, () { for (const scenario of checkoutScenarios) { test(checkout with ${scenario.name}, async ({ page }) { await page.goto(/checkout); await page.getByLabel(scenario.shipping, { exact: false }).check(); await expect(page.getByText(scenario.expectedDays)).toBeVisible(); await expect(page.getByText(scenario.expectedCost)).toBeVisible(); }); } });3.3 CSV/JSON 数据源对非开发者如 QA 或产品维护的用例矩阵最友好的形式是外部数据文件import fs from fs; interface TestCase { input: string; expected: string; } // Load test data from JSON const testCases: TestCase[] JSON.parse( fs.readFileSync(./data/search-tests.json, utf-8), ); test.describe(search functionality, () { for (const { input, expected } of testCases) { test(search for ${input}, async ({ page }) { await page.goto(/search); await page.getByLabel(Search).fill(input); await page.getByLabel(Search).press(Enter); await expect(page.getByText(expected)).toBeVisible(); }); } });注意这里在describe作用域内同步读文件模块加载期即完成解析而不是在测试体内读——这保证数据文件缺失/格式错误时错误立即暴露在套件收集阶段而不是某个用例执行中途。SurfSense 对照SurfSense 用目录结构实现了同一种数据维度分离。tests/README.md 规定每个 connector 对应一条最小的浏览器旅程 spec如 tests/connectors/composio/drive/journey.spec.ts数据fake 文件清单、canary 令牌集中在 helpers/canary.ts 与后端fakes/fixtures/*.json逻辑connect → select scope → index → assert canary集中在 journey spec。这与参数化测试数据模块 单一执行循环的分离是同一种工程思想在不同维度上的体现。四、Test Data Fixtures把工厂接进 Playwright 的依赖注入4.1 Fixture with FactoryPlaywright fixture 提供了比beforeEach更精细的依赖图。文档的示例把第一节定义的工厂挂到 fixture 上// fixtures/data.fixture.ts import { test as base } from playwright/test; import { createUser, User } from ../factories/user.factory; import { createProduct, Product } from ../factories/product.factory; type DataFixtures { testUser: User; testProducts: Product[]; }; export const test base.extendDataFixtures({ testUser: async ({}, use) { const user createUser({ name: E2E Test User }); await use(user); }, testProducts: async ({}, use) { const products [ createProduct({ name: Test Product 1 }), createProduct({ name: Test Product 2 }), createProduct({ name: Test Product 3 }), ]; await use(products); }, }); // Usage test(add product to cart, async ({ page, testUser, testProducts }) { // Mock API with test data await page.route(**/api/user, (route) route.fulfill({ json: testUser })); await page.route(**/api/products, (route) route.fulfill({ json: testProducts }), ); await page.goto(/products); await expect(page.getByText(testProducts[0].name)).toBeVisible(); });这里还有两个值得注意的点use()之前的代码是 setup之后的代码是 teardown。fixture 因此可以精确表达数据何时创建、何时回收这是beforeEach/afterEach难以做到的。工厂产物既可以直接喂给page.route()做 API mock本例也可以作为真实请求的 payload下一节。同一份工厂数据在两条路径间复用避免了 mock 数据与真实数据各写一套。4.2 SurfSense 的 fixture 继承链SurfSense 把这种fixture 承载测试数据的模式用到了极致tests/fixtures/index.ts 的文件头注释画出了完整继承链base → workspaceFixtures → 各 connector fixtures → 可选 chatThreadFixtures并导出 15 个按场景命名的test变体composioDriveTest、nativeGmailWithChatTest……。其中 tests/fixtures/chat-thread.fixture.ts 展示了数据即 API 调用的 fixture 写法chatThread: async ({ request, apiToken, workspace }, use) { const response await request.post(${BACKEND_URL}/api/v1/threads, { headers: authHeaders(apiToken), data: { title: e2e-drive-journey, workspace_id: workspace.id, visibility: PRIVATE, }, }); if (!response.ok()) { throw new Error(create chat thread failed (${response.status()}): ${await response.text()}); } await use((await response.json()) as ChatThreadRow); },对照文档的 Fixture with Factory 模式可以看到一致的三要素类型化的 fixture 名ChatThreadFixtures.chatThread、创建逻辑集中在 fixture 内而非散落在各 spec、失败快速显形非 2xx 直接抛错带响应体。而组合性则体现在 index.ts 中一行composioDriveFixtures.extendChatThreadFixtures(chatThreadFixtures)就完成了新数据维度的叠加。五、Database Seeding数据要进库也要能退场5.1 API-Based Seeding推荐路径通过应用自己的 API 造数据天然保证数据经过真实校验逻辑。文档示例的精髓在于把创建与清理配成一对 fixture// fixtures/seed.fixture.ts import { test as base, APIRequestContext } from playwright/test; import { createUser } from ../factories/user.factory; type SeedFixtures { seedUser: (overrides?: PartialUser) PromiseUser; cleanupUsers: string[]; }; export const test base.extendSeedFixtures({ cleanupUsers: [], seedUser: async ({ request, cleanupUsers }, use) { await use(async (overrides {}) { const userData createUser(overrides); const response await request.post(/api/test/users, { data: userData, }); const user await response.json(); cleanupUsers.push(user.id); return user; }); }, // Cleanup after test cleanupUsers: async ({ request }, use) { const userIds: string[] []; await use(userIds); // Delete all created users for (const id of userIds) { await request.delete(/api/test/users/${id}); } }, }); // Usage test(user profile page, async ({ page, seedUser }) { const user await seedUser({ name: John Doe }); await page.goto(/users/${user.id}); await expect(page.getByText(John Doe)).toBeVisible(); });cleanupUsers数组作为 fixture 被seedUser依赖注入所有创建过的 id 累积其中teardown 阶段统一删除——谁造的数据谁负责回收这一契约由依赖图强制保证而不是靠开发者记忆。SurfSense 的对应实现几乎是该模式的逐行放大tests/fixtures/workspace.fixture.ts 中apiToken使用{ scope: worker }让每个 worker 只登录一次logins are cheap, but caching is cheaper而workspacefixture 则严格遵循创建 → use → finally 删除的闭环workspace: async ({ request, apiToken }, use) { const space await createWorkspace( request, apiToken, uniqueWorkspaceName(composio-drive-e2e) ); try { await use(space); } finally { await deleteWorkspace(request, apiToken, space.id); } },配合 auth.setup.ts 的一次性认证获取 bearer token 后写入playwright/.auth/user.json会话状态playwright.config.ts的 chromium project 通过storageState复用整个套件实现了文档反模式表所要求的目标每测试新鲜数据 测试间零串扰。至于为什么选择 API 造数据而不是直连数据库tests/README.md 的 Why API-driven? 一节给出了明确理由确定性不等待 UI 动画/水合/编译、走与 UI 相同的后端代码路径、以及把昂贵的 E2E 断言留给只有 E2E 才能证明的跨进程接缝connector → Celery → indexing → DB。5.2 Transaction Rollback Seeding直连数据库路径当需要绕过应用层直接写库如造 API 无法创建的数据、或验证 DB 级不变式事务回滚是最干净的隔离手段——每个测试在独立事务里种数据测试结束ROLLBACK数据库回到原点// fixtures/db.fixture.ts export const test base.extend{}, { db: DbTransaction }({ db: [ async ({}, use) { const client await pool.connect(); await client.query(BEGIN); await use({ query: (sql: string, params?: any[]) client.query(sql, params), seed: async (table: string, data: object) { const keys Object.keys(data); const values Object.values(data); const placeholders keys.map((_, i) $${i 1}); const result await client.query( INSERT INTO ${table} (${keys.join(, )}) VALUES (${placeholders.join(, )}) RETURNING *, values, ); return result.rows[0]; }, }); await client.query(ROLLBACK); client.release(); }, { scope: test }, ], });实现要点{ scope: test }保证每个测试独立事务、独立连接互不泄漏BEGIN/ROLLBACK夹住整个use即使测试失败use抛出后依然会执行到ROLLBACKfixture teardown 语义seed助手用$1, $2, ...占位符参数化 INSERT 并RETURNING *返回插入后的完整行含数据库生成的列测试可直接用返回值做断言。需要注意适用前提该模式要求测试对数据库有直连权限、且被测逻辑不会开启自己的独立事务/连接否则回滚隔离失效。这也是文档开头把事务回滚归入 fixtures-hooks.md 的 Database Fixtures 专题、而本文只给出种子接口的原因——两条路径应按项目实际权限与隔离需求二选一。六、Anti-Patterns四类必须避免的测试数据反模式文档最后给出的反模式对照表是全文的收束值得逐条落实反模式问题解法硬编码测试数据Hardcoded test data脆弱、重复使用工厂未播种的随机数据Random data without seed失败不可复现每个测试播种 faker共享可变测试数据Shared mutable test data测试相互干扰每测试创建新鲜数据到处手工造数据Manual data creation everywhere重复、维护负担集中到工厂前文的 SurfSense 实践可以逐一映射回这张表uniqueWorkspaceName用随机 UUID 前缀避免共享数据串扰第 3 行canary 令牌全部是稳定可 grep 的字符串而非未播种随机值第 2 行workspacefixture 的 create/finally-delete 闭环让每个测试拿到全新工作区第 1、3 行数据构造集中在helpers/api/*与 fixturesspec 里不出现裸 SQL/裸 JSON第 4 行。七、延伸阅读与参考路径Fixtures 模式fixtures-hooks.md——fixture 生命周期、hook 与数据库 fixture 细节全局初始化global-setup.md——一次性 migrations / snapshot 类 Database PatternsAPI 测试与 mockingtest-suite-structure.mdSurfSense 实际套件tests/README.md三层防真实外呼的确定性 harness、playwright.config.ts默认测试账号e2e-testsurfsense.net等环境约定、storageState与webServer配置、tests/helpers/canary.ts确定性 canary 令牌全集、tests/fixtures/workspace.fixture.tsworker 级 token 缓存 测试级工作区创建/清理、tests/fixtures/index.ts15 个 typed test 变体的组合方式后端侧 E2E 入口surfsense_backend/tests/e2e/run_backend.py与run_celery.py按 tests/README.md 所述在导入应用前劫持sys.modules注入严格 fake配合哨兵 API key 与代理拒绝保证任何泄漏的外呼在网络前即失败。小结测试数据的工程化可以浓缩为一句话——用工厂集中默认值、用 traits/overrides 表达变体、用种子或稳定令牌保证可复现、用 fixture 的 setup/teardown 语义保证隔离与回收。工厂模式负责数据怎么来Faker或确定性 canary负责数据长什么样数据驱动负责哪些数据值得测而 API Seeding / 事务回滚负责数据进库与退场。把这四层各自落实E2E 套件就具备了失败可定位、重跑可复现、并行不串扰的确定性基础。【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
SurfSense Playwright E2E 实战：用测试数据工厂、Faker 与数据驱动模式构建可复用的测试数据体系
SurfSense Playwright E2E 实战用测试数据工厂、Faker 与数据驱动模式构建可复用的测试数据体系【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense在端到端E2E测试中如何构造并管理测试数据往往决定了测试套件的稳定性与可维护性。本文以 SurfSense 仓库中沉淀的 Playwright 测试数据技能文档 test-data.md 为主体完整讲解工厂模式Factory Pattern、Faker 集成、数据驱动测试、测试数据 Fixtures 以及数据库 Seeding 五类核心手段并结合 SurfSense 前端 E2E 套件中真实存在的 fixtures、canary 令牌与 workspace 清理机制说明这些模式在 Next.js FastAPI 全栈项目里如何落地。读完本文你能够独立设计一套每个测试都有新鲜数据、失败可复现、资源可清理的测试数据体系。需要先明确本文档在 SurfSense 的 Playwright 技能体系中的定位它专注可复用的测试数据构建器factories、Faker、data generators与另外两个相邻主题分工明确——Per-test 数据库 fixtures测试隔离、事务回滚参见 fixtures-hooks.md 的 Database Fixtures 章节一次性数据库初始化migrations、snapshots参见 global-setup.md 的 Database Patterns 章节。也就是说本文解决的是数据从哪来、怎么长得可预测而 fixture 生命周期与全局初始化由上述两篇配套文档覆盖。一、Factory Pattern用工厂函数替代散落的硬编码数据1.1 基本工厂最直接的工厂是一个带overrides参数的构造函数默认值集中在一处调用方只覆盖需要变化的字段。文档给出的factories/user.factory.ts示例完整如下// factories/user.factory.ts interface User { id: string; email: string; name: string; role: admin | user | guest; createdAt: Date; } let userIdCounter 0; export function createUser(overrides: PartialUser {}): User { userIdCounter; return { id: user-${userIdCounter}, email: user${userIdCounter}test.com, name: Test User ${userIdCounter}, role: user, createdAt: new Date(), ...overrides, }; } // Usage const user createUser(); const admin createUser({ role: admin, name: Admin User });两个设计细节值得注意模块级计数器userIdCounter保证同进程内 ID 与 email 唯一。这在一次运行内创建多个实体的场景下天然避免主键/唯一约束冲突但代价是数据不是每测试一次全新重置的——若跨测试有持久化需要配合清理机制见后文 Seeding 章节的cleanupUsers模式。...overrides放在对象字面量最后确保调用方覆盖优先级最高这是工厂模式的约定默认值 → 派生关系 → 显式覆盖。1.2 带 Traits 的工厂当某个实体存在常见的状态变体缺货、促销、高价……时逐个手写 overrides 会变得冗长。Traits 把常见变体注册为命名片段调用时按名追加// factories/product.factory.ts interface Product { id: string; name: string; price: number; stock: number; category: string; featured: boolean; } type ProductTrait outOfStock | featured | expensive | sale; const traits: RecordProductTrait, PartialProduct { outOfStock: { stock: 0 }, featured: { featured: true }, expensive: { price: 999.99 }, sale: { price: 9.99 }, }; let productIdCounter 0; export function createProduct( overrides: PartialProduct {}, ...traitNames: ProductTrait[] ): Product { productIdCounter; const appliedTraits traitNames.reduce( (acc, trait) ({ ...acc, ...traits[trait] }), {}, ); return { id: prod-${productIdCounter}, name: Product ${productIdCounter}, price: 29.99, stock: 100, category: General, featured: false, ...appliedTraits, ...overrides, }; } // Usage const product createProduct(); const featuredProduct createProduct({}, featured); const saleItem createProduct({ name: Sale Item }, sale, featured); const soldOut createProduct({}, outOfStock);Trait 合并使用reduce按传入顺序依次展开后一个 trait 覆盖前一个的相同字段例如同时传sale和expensive时最终价格由顺序决定而overrides永远压过所有 traits。这个优先级链默认值 → traits → overrides是工厂可扩展性的关键新增一个 trait 只需往traits表里加一行所有既有调用不受影响。1.3 带关系的工厂真实数据几乎总是成体系的订单引用用户订单行引用商品。关系型工厂通过复用其他工厂来保证关系闭包完整同时保留对每个关联对象的可覆盖性// factories/order.factory.ts import { createUser, User } from ./user.factory; import { createProduct, Product } from ./product.factory; interface OrderItem { product: Product; quantity: number; } interface Order { id: string; user: User; items: OrderItem[]; total: number; status: pending | paid | shipped | delivered; } let orderIdCounter 0; export function createOrder(overrides: PartialOrder {}): Order { orderIdCounter; const user overrides.user ?? createUser(); const items overrides.items ?? [{ product: createProduct(), quantity: 1 }]; const total items.reduce( (sum, item) sum item.product.price * item.quantity, 0, ); return { id: order-${orderIdCounter}, user, items, total, status: pending, ...overrides, }; } // Usage const order createOrder(); const bigOrder createOrder({ items: [ { product: createProduct({ price: 100 }), quantity: 5 }, { product: createProduct({ price: 50 }), quantity: 2 }, ], });这里overrides.user ?? createUser()的写法体现了关系工厂的惯用法先尊重调用方显式提供的关联对象缺省时才用子工厂造一个而total这样的派生字段在工厂内部根据items计算避免调用方手算出错。1.4 结合 SurfSense 仓库的实践对照SurfSense 的 Web E2E 套件playwright.config.ts 指定testDir: ./tests并没有在浏览器侧维护一套纯内存工厂而是把数据创建下沉为API 调用的 fixture——tests/fixtures/index.ts 中的注释明确说明了继承链所有 connector fixture 都从workspaceFixtures派生需要聊天线程的场景再extend一层chatThreadFixtures。这种工厂即 API helper fixture 组合的思路与本文档的工厂模式同构只是产物从内存对象变成了数据库真实行。一个与计数器唯一化直接对应的真实实现是 tests/helpers/canary.ts 中的uniqueWorkspaceName/** Generate a unique-per-run workspace name. Keeps parallel tests isolated. */ export function uniqueWorkspaceName(prefix e2e): string { return ${prefix}-${randomUUID().slice(0, 8)}; }它用randomUUID()前 8 位生成每运行唯一的工作区名源码注释点明了目的让并行测试相互隔离。这与文档 Factory Pattern 中计数器方案的意图一致唯一标识但选择了每运行随机而非进程内自增更适配 Playwright 多 worker 并行的场景。二、Faker Integration用随机真实感数据且保持可复现2.1 安装与基本用法Faker 解决计数器数据缺乏真实感的问题如user1test.com这样的数据无法暴露表单校验、渲染截断等问题npm install -D faker-js/faker// factories/faker-user.factory.ts import { faker } from faker-js/faker; interface User { id: string; email: string; name: string; avatar: string; address: { street: string; city: string; country: string; zipCode: string; }; } export function createFakeUser(overrides: PartialUser {}): User { return { id: faker.string.uuid(), email: faker.internet.email(), name: faker.person.fullName(), avatar: faker.image.avatar(), address: { street: faker.location.streetAddress(), city: faker.location.city(), country: faker.location.country(), zipCode: faker.location.zipCode(), }, ...overrides, }; }可以看到 Faker 工厂与第一节的手写工厂完全兼容overrides机制原封不动只是默认值来源换成了faker.*生成器。2.2 Seeded Faker可复现的随机数据随机数据的头号风险是失败不可复现——同一失败重跑一次数据就变了。Faker 通过全局种子解决import { faker } from faker-js/faker; // Set seed for reproducible data faker.seed(12345); export function createDeterministicUser(): User { return { id: faker.string.uuid(), email: faker.internet.email(), name: faker.person.fullName(), // Same seed same data every time }; } // Or seed per test test(user profile, async ({ page }) { faker.seed(42); // Reset seed for this test const user createFakeUser(); // user will always have the same data });文档给出了两个粒度的播种方式模块级faker.seed(12345)整条测试序列可复现和测试级faker.seed(42)每个测试从相同起点生成数据既保留随机外观又保证单测内确定性。2.3 把 Faker 做成 Playwright Fixture更工程化的做法是把播种封装进 fixture让测试代码完全不感知种子细节// fixtures/faker.fixture.ts import { test as base } from playwright/test; import { faker } from faker-js/faker; type FakerFixtures { fake: typeof faker; }; export const test base.extendFakerFixtures({ fake: async ({}, use, testInfo) { // Seed based on test name for reproducibility faker.seed(testInfo.title.length); await use(faker); }, }); // Usage test(create user with fake data, async ({ page, fake }) { await page.goto(/signup); await page.getByLabel(Name).fill(fake.person.fullName()); await page.getByLabel(Email).fill(fake.internet.email()); await page.getByLabel(Password).fill(fake.internet.password()); await page.getByRole(button, { name: Sign Up }).click(); });这个 fixture 利用testInfo.title.length作为种子派生值让不同测试得到不同数据、而同一测试重跑得到相同数据。2.4 SurfSense 的选择确定性 Canary 令牌而非 Faker有意思的是SurfSense 的实际 E2E 套件刻意没有使用随机数据。从 tests/helpers/canary.ts 的源码注释看其设计动机是/** * Canary tokens deterministic test data. * * Embedded by the backend Composio fake into fake Drive file contents * (see surfsense_backend/tests/e2e/fakes/fixtures/drive_files.json). * Specs assert these strings appear in the resulting Document rows to * prove the indexing pipeline ran end-to-end. * * Each token is a stable string keyed by file id so multi-test runs * remain deterministic and the resulting Document.content is greppable * in failure traces. */ export const CANARY_TOKENS { driveCanaryFile: SURFSENSE_E2E_CANARY_TOKEN_DRIVE_001, drivePdfCanary: SURFSENSE_E2E_CANARY_TOKEN_DRIVE_PDF_001, ... } as const;这与文档Seeded Faker一节的精神完全一致甚至更彻底SurfSense 的断言链路是跨进程的connector → Celery → indexing → DB需要证明这条特定假文件的内容最终出现在 Document 行里因此使用稳定的、按文件 id 索引的固定令牌如SURFSENSE_E2E_CANARY_TOKEN_DRIVE_001保证多次运行结果确定、且失败时令牌字符串可以直接在失败产物中 grep 定位。同文件中还有FAKE_DRIVE_FILES、FAKE_GMAIL_MESSAGES、FAKE_LINEAR_ISSUES等一批与后端 fake如drive_files.json严格对齐的假数据清单形成前后端共享同一份确定性测试数据集的契约。可以推断对于需要端到端内容穿透验证的套件可 grep 的稳定 canary比 Faker 的随机真实感数据更具调试价值——这正是文档反模式表里Random data without seed → 不可复现失败在真实项目中的解法。三、Data-Driven Testing让数据定义用例3.1 场景数组驱动用例数据驱动测试的核心思想是把用例矩阵与执行逻辑分离。文档第一个例子是登录场景数组const loginScenarios [ { email: userexample.com, password: pass123, expected: Dashboard }, { email: adminexample.com, password: admin123, expected: Admin Panel }, { email: invalidexample.com, password: wrong, expected: Invalid credentials, }, ]; for (const { email, password, expected } of loginScenarios) { test(login with ${email}, async ({ page }) { await page.goto(/login); await page.getByLabel(Email).fill(email); await page.getByLabel(Password).fill(password); await page.getByRole(button, { name: Sign In }).click(); await expect(page.getByText(expected)).toBeVisible(); }); }for循环 模板字符串标题让 Playwright 为每个数据行注册独立测试失败时可精确定位到哪一行数据出了问题报告里也能看到全部行。3.2 参数化测试把场景数据独立成模块当场景数据变多或需要被多个 spec 共享时抽到独立数据模块data/checkout-scenarios.ts// data/checkout-scenarios.ts export const checkoutScenarios [ { name: standard shipping, shipping: standard, expectedDays: 5-7 business days, expectedCost: $5.99, }, { name: express shipping, shipping: express, expectedDays: 2-3 business days, expectedCost: $14.99, }, { name: overnight shipping, shipping: overnight, expectedDays: Next business day, expectedCost: $29.99, }, ];import { checkoutScenarios } from ./data/checkout-scenarios; test.describe(shipping options, () { for (const scenario of checkoutScenarios) { test(checkout with ${scenario.name}, async ({ page }) { await page.goto(/checkout); await page.getByLabel(scenario.shipping, { exact: false }).check(); await expect(page.getByText(scenario.expectedDays)).toBeVisible(); await expect(page.getByText(scenario.expectedCost)).toBeVisible(); }); } });3.3 CSV/JSON 数据源对非开发者如 QA 或产品维护的用例矩阵最友好的形式是外部数据文件import fs from fs; interface TestCase { input: string; expected: string; } // Load test data from JSON const testCases: TestCase[] JSON.parse( fs.readFileSync(./data/search-tests.json, utf-8), ); test.describe(search functionality, () { for (const { input, expected } of testCases) { test(search for ${input}, async ({ page }) { await page.goto(/search); await page.getByLabel(Search).fill(input); await page.getByLabel(Search).press(Enter); await expect(page.getByText(expected)).toBeVisible(); }); } });注意这里在describe作用域内同步读文件模块加载期即完成解析而不是在测试体内读——这保证数据文件缺失/格式错误时错误立即暴露在套件收集阶段而不是某个用例执行中途。SurfSense 对照SurfSense 用目录结构实现了同一种数据维度分离。tests/README.md 规定每个 connector 对应一条最小的浏览器旅程 spec如 tests/connectors/composio/drive/journey.spec.ts数据fake 文件清单、canary 令牌集中在 helpers/canary.ts 与后端fakes/fixtures/*.json逻辑connect → select scope → index → assert canary集中在 journey spec。这与参数化测试数据模块 单一执行循环的分离是同一种工程思想在不同维度上的体现。四、Test Data Fixtures把工厂接进 Playwright 的依赖注入4.1 Fixture with FactoryPlaywright fixture 提供了比beforeEach更精细的依赖图。文档的示例把第一节定义的工厂挂到 fixture 上// fixtures/data.fixture.ts import { test as base } from playwright/test; import { createUser, User } from ../factories/user.factory; import { createProduct, Product } from ../factories/product.factory; type DataFixtures { testUser: User; testProducts: Product[]; }; export const test base.extendDataFixtures({ testUser: async ({}, use) { const user createUser({ name: E2E Test User }); await use(user); }, testProducts: async ({}, use) { const products [ createProduct({ name: Test Product 1 }), createProduct({ name: Test Product 2 }), createProduct({ name: Test Product 3 }), ]; await use(products); }, }); // Usage test(add product to cart, async ({ page, testUser, testProducts }) { // Mock API with test data await page.route(**/api/user, (route) route.fulfill({ json: testUser })); await page.route(**/api/products, (route) route.fulfill({ json: testProducts }), ); await page.goto(/products); await expect(page.getByText(testProducts[0].name)).toBeVisible(); });这里还有两个值得注意的点use()之前的代码是 setup之后的代码是 teardown。fixture 因此可以精确表达数据何时创建、何时回收这是beforeEach/afterEach难以做到的。工厂产物既可以直接喂给page.route()做 API mock本例也可以作为真实请求的 payload下一节。同一份工厂数据在两条路径间复用避免了 mock 数据与真实数据各写一套。4.2 SurfSense 的 fixture 继承链SurfSense 把这种fixture 承载测试数据的模式用到了极致tests/fixtures/index.ts 的文件头注释画出了完整继承链base → workspaceFixtures → 各 connector fixtures → 可选 chatThreadFixtures并导出 15 个按场景命名的test变体composioDriveTest、nativeGmailWithChatTest……。其中 tests/fixtures/chat-thread.fixture.ts 展示了数据即 API 调用的 fixture 写法chatThread: async ({ request, apiToken, workspace }, use) { const response await request.post(${BACKEND_URL}/api/v1/threads, { headers: authHeaders(apiToken), data: { title: e2e-drive-journey, workspace_id: workspace.id, visibility: PRIVATE, }, }); if (!response.ok()) { throw new Error(create chat thread failed (${response.status()}): ${await response.text()}); } await use((await response.json()) as ChatThreadRow); },对照文档的 Fixture with Factory 模式可以看到一致的三要素类型化的 fixture 名ChatThreadFixtures.chatThread、创建逻辑集中在 fixture 内而非散落在各 spec、失败快速显形非 2xx 直接抛错带响应体。而组合性则体现在 index.ts 中一行composioDriveFixtures.extendChatThreadFixtures(chatThreadFixtures)就完成了新数据维度的叠加。五、Database Seeding数据要进库也要能退场5.1 API-Based Seeding推荐路径通过应用自己的 API 造数据天然保证数据经过真实校验逻辑。文档示例的精髓在于把创建与清理配成一对 fixture// fixtures/seed.fixture.ts import { test as base, APIRequestContext } from playwright/test; import { createUser } from ../factories/user.factory; type SeedFixtures { seedUser: (overrides?: PartialUser) PromiseUser; cleanupUsers: string[]; }; export const test base.extendSeedFixtures({ cleanupUsers: [], seedUser: async ({ request, cleanupUsers }, use) { await use(async (overrides {}) { const userData createUser(overrides); const response await request.post(/api/test/users, { data: userData, }); const user await response.json(); cleanupUsers.push(user.id); return user; }); }, // Cleanup after test cleanupUsers: async ({ request }, use) { const userIds: string[] []; await use(userIds); // Delete all created users for (const id of userIds) { await request.delete(/api/test/users/${id}); } }, }); // Usage test(user profile page, async ({ page, seedUser }) { const user await seedUser({ name: John Doe }); await page.goto(/users/${user.id}); await expect(page.getByText(John Doe)).toBeVisible(); });cleanupUsers数组作为 fixture 被seedUser依赖注入所有创建过的 id 累积其中teardown 阶段统一删除——谁造的数据谁负责回收这一契约由依赖图强制保证而不是靠开发者记忆。SurfSense 的对应实现几乎是该模式的逐行放大tests/fixtures/workspace.fixture.ts 中apiToken使用{ scope: worker }让每个 worker 只登录一次logins are cheap, but caching is cheaper而workspacefixture 则严格遵循创建 → use → finally 删除的闭环workspace: async ({ request, apiToken }, use) { const space await createWorkspace( request, apiToken, uniqueWorkspaceName(composio-drive-e2e) ); try { await use(space); } finally { await deleteWorkspace(request, apiToken, space.id); } },配合 auth.setup.ts 的一次性认证获取 bearer token 后写入playwright/.auth/user.json会话状态playwright.config.ts的 chromium project 通过storageState复用整个套件实现了文档反模式表所要求的目标每测试新鲜数据 测试间零串扰。至于为什么选择 API 造数据而不是直连数据库tests/README.md 的 Why API-driven? 一节给出了明确理由确定性不等待 UI 动画/水合/编译、走与 UI 相同的后端代码路径、以及把昂贵的 E2E 断言留给只有 E2E 才能证明的跨进程接缝connector → Celery → indexing → DB。5.2 Transaction Rollback Seeding直连数据库路径当需要绕过应用层直接写库如造 API 无法创建的数据、或验证 DB 级不变式事务回滚是最干净的隔离手段——每个测试在独立事务里种数据测试结束ROLLBACK数据库回到原点// fixtures/db.fixture.ts export const test base.extend{}, { db: DbTransaction }({ db: [ async ({}, use) { const client await pool.connect(); await client.query(BEGIN); await use({ query: (sql: string, params?: any[]) client.query(sql, params), seed: async (table: string, data: object) { const keys Object.keys(data); const values Object.values(data); const placeholders keys.map((_, i) $${i 1}); const result await client.query( INSERT INTO ${table} (${keys.join(, )}) VALUES (${placeholders.join(, )}) RETURNING *, values, ); return result.rows[0]; }, }); await client.query(ROLLBACK); client.release(); }, { scope: test }, ], });实现要点{ scope: test }保证每个测试独立事务、独立连接互不泄漏BEGIN/ROLLBACK夹住整个use即使测试失败use抛出后依然会执行到ROLLBACKfixture teardown 语义seed助手用$1, $2, ...占位符参数化 INSERT 并RETURNING *返回插入后的完整行含数据库生成的列测试可直接用返回值做断言。需要注意适用前提该模式要求测试对数据库有直连权限、且被测逻辑不会开启自己的独立事务/连接否则回滚隔离失效。这也是文档开头把事务回滚归入 fixtures-hooks.md 的 Database Fixtures 专题、而本文只给出种子接口的原因——两条路径应按项目实际权限与隔离需求二选一。六、Anti-Patterns四类必须避免的测试数据反模式文档最后给出的反模式对照表是全文的收束值得逐条落实反模式问题解法硬编码测试数据Hardcoded test data脆弱、重复使用工厂未播种的随机数据Random data without seed失败不可复现每个测试播种 faker共享可变测试数据Shared mutable test data测试相互干扰每测试创建新鲜数据到处手工造数据Manual data creation everywhere重复、维护负担集中到工厂前文的 SurfSense 实践可以逐一映射回这张表uniqueWorkspaceName用随机 UUID 前缀避免共享数据串扰第 3 行canary 令牌全部是稳定可 grep 的字符串而非未播种随机值第 2 行workspacefixture 的 create/finally-delete 闭环让每个测试拿到全新工作区第 1、3 行数据构造集中在helpers/api/*与 fixturesspec 里不出现裸 SQL/裸 JSON第 4 行。七、延伸阅读与参考路径Fixtures 模式fixtures-hooks.md——fixture 生命周期、hook 与数据库 fixture 细节全局初始化global-setup.md——一次性 migrations / snapshot 类 Database PatternsAPI 测试与 mockingtest-suite-structure.mdSurfSense 实际套件tests/README.md三层防真实外呼的确定性 harness、playwright.config.ts默认测试账号e2e-testsurfsense.net等环境约定、storageState与webServer配置、tests/helpers/canary.ts确定性 canary 令牌全集、tests/fixtures/workspace.fixture.tsworker 级 token 缓存 测试级工作区创建/清理、tests/fixtures/index.ts15 个 typed test 变体的组合方式后端侧 E2E 入口surfsense_backend/tests/e2e/run_backend.py与run_celery.py按 tests/README.md 所述在导入应用前劫持sys.modules注入严格 fake配合哨兵 API key 与代理拒绝保证任何泄漏的外呼在网络前即失败。小结测试数据的工程化可以浓缩为一句话——用工厂集中默认值、用 traits/overrides 表达变体、用种子或稳定令牌保证可复现、用 fixture 的 setup/teardown 语义保证隔离与回收。工厂模式负责数据怎么来Faker或确定性 canary负责数据长什么样数据驱动负责哪些数据值得测而 API Seeding / 事务回滚负责数据进库与退场。把这四层各自落实E2E 套件就具备了失败可定位、重跑可复现、并行不串扰的确定性基础。【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考