fix(client): 集成测试的串行声明改用 Vitest 4 的 fileParallelism,不再是失效的 poolOptions (#5564)

[baozhoutao]

Fixes #5564

前提复核(先证后改)

最新 main(c11369013)上复现,警告仍在,前提成立:

$ cd packages/client && npx vitest list --config vitest.integration.config.ts
 DEPRECATED  `test.poolOptions` was removed in Vitest 4. All previous `poolOptions` are now top-level options. Please, refer to the migration guide: https://vitest.dev/guide/migration#pool-rework
tests/integration/01-discovery.test.ts > ... TC-DISC-001 ...  (共 4 条)

vitest 实际版本 4.1.10。

依文档核实(不照猜)

Vitest 4 迁移指南 docs/guide/migration.md @ tag v4.1.10,「Pool Rework」一节原文:

• singleThread and singleFork are now maxWorkers: 1, isolate: false.
• poolOptions is removed. All previous poolOptions are now top-level options.

docs/config/fileparallelism.md @ v4.1.10:

• Type: boolean Default: true —— Should all test files run in parallel. Setting this to false will override maxWorkers option to 1.

改法与一处刻意偏离

pool: 'forks' 保留,poolOptions 整块换成顶层 fileParallelism: false。

迁移指南给 singleFork 的等价物有两半,这里只迁并行度那一半,isolate: false 刻意不带:

• 它和 singleFork 一样从来没生效过 —— 旧写法整块被忽略,所以没有任何现存行为依赖「跨文件共享模块注册表」;
• 本单要落实的声明是注释写的「串行执行以避免竞态」,isolate 与之无关;
• 真把隔离关掉,模块状态会在文件之间泄漏,正是这条声明要防的同一类文件间干扰。

理由写在文件注释里,连同 #5564 编号,免得下一位读者以为迁移漏了一半。

验收证据

1. 警告消失,4 个用例仍被收集

$ npx vitest list --config vitest.integration.config.ts
tests/integration/01-discovery.test.ts > Discovery & Connection > TC-DISC-001: ... > should discover API from /api/v1/discovery
tests/integration/01-discovery.test.ts > Discovery & Connection > TC-DISC-002: ... > should provide valid API version information
tests/integration/01-discovery.test.ts > Discovery & Connection > TC-DISC-003: ... > should throw error when server is unreachable
tests/integration/01-discovery.test.ts > Discovery & Connection > TC-DISC-004: ... > should resolve API routes from discovery info
=== exit 0 ===

无 DEPRECATED 行。

2. 串行声明实际生效 —— resolve 后的实际值

用 createVitest 解析该 config,打印 project 的 resolved config(本机 os.availableParallelism() === 4):

字段	修前(旧写法)	修后
pool	forks	forks
fileParallelism	undefined(即默认 true,并行)	false
maxWorkers	undefined	1
isolate	true	true
poolOptions	{ forks: { singleFork: true } } 原样留着当惰性数据	不存在

修后 maxWorkers 解析成 1,正是文档说的「override maxWorkers to 1」,串行是 resolve 后的实际值而不是注释。

3. 反向验证(方向先判后跑)

预判:还原旧写法后 DEPRECATED 警告回来,且 resolved config 里 fileParallelism / maxWorkers 根本不出现(证明旧写法一次都没串行过)。实跑两条都命中 —— 见上表「修前」列;旧写法下 poolOptions 原封不动躺在 resolved config 里,vitest 不读它。

4. 常规通道不受影响

$ pnpm --filter @objectstack/client test
 Test Files  17 passed (17)
      Tests  222 passed (222)

$ pnpm --filter @objectstack/client typecheck
tsc --noEmit  ✓
check:test-typecheck: OK — @objectstack/client's test layer compiles under packages/client/tsconfig.test.json

$ node scripts/check-nul-bytes.mjs
check-nul-bytes: OK (scanned 5516 tracked text file(s); ... no raw ASCII control bytes).

集成套件本体需要外部活服务器,按分诊约定不真跑。

changeset

请 PM 打 skip-changeset 标签:本 PR 只动一个测试运行器 config 与其注释,不改任何发布产物、公共 API 或用户可见行为 —— 与 #5546 / #5565 同类,走 skip-changeset 路径。

边界

只动 packages/client/vitest.integration.config.ts。tests/integration/README.md 的 17 缺 16 规划表缺口按分诊划界不在本单,未动;tsconfig.test.json / vitest.config.ts / 任何测试文件均未动。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 5, 2026 7:37pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/client.

14 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx (via packages/client)
• content/docs/api/client-sdk.mdx (via @objectstack/client)
• content/docs/api/data-flow.mdx (via @objectstack/client)
• content/docs/api/environment-routing.mdx (via @objectstack/client)
• content/docs/api/error-catalog.mdx (via @objectstack/client)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/client)
• content/docs/kernel/runtime-services/data-service.mdx (via packages/client)
• content/docs/kernel/runtime-services/index.mdx (via packages/client)
• content/docs/permissions/authentication.mdx (via @objectstack/client)
• content/docs/plugins/packages.mdx (via @objectstack/client)
• content/docs/protocol/kernel/realtime-protocol.mdx (via @objectstack/client)
• content/docs/releases/implementation-status.mdx (via @objectstack/client)
• content/docs/releases/v16.mdx (via @objectstack/client)
• content/docs/releases/v17.mdx (via @objectstack/client)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.