migrate-codeceptjs-4

将 CodeceptJS 3.x 迁移到 4.x

CodeceptJS 4 仅支持 ESM，并以 TypeScript 为先。它不提供 CommonJS 兼容层——每个 helper、页面对象、自定义步骤和配置文件都必须使用 ESM。本技能将引导项目完成端到端升级。

权威参考文档位于 node_modules/codeceptjs/docs/migration-4.md（执行 npm install codeceptjs@4 后）。请先阅读一次；本技能负责协调迁移，并指出 Agent 容易遗漏的部分。

触发条件

操作前先检测。检查以下任一情况：

• package.json 中列出 "codeceptjs": "^3" / "3.x"，或未设置 "type": "module"。
• 测试、页面对象、helper 或配置中针对 CodeceptJS 使用了 require() / module.exports。
• 配置仍引用已移除的 helper（Nightmare、Protractor、TestCafe、AI、SoftExpectHelper、Mochawesome）或已移除的插件（autoLogin、tryTo、retryTo、eachElement、commentStep、fakerTransform、enhancedRetryFailedStep、allure、htmlReporter、wdio、selenoid、screenshotOnFail、pauseOnFail、stepByStepReport）。
• 使用 3.x API：ai.request、seeResponseMatchesJsonSchema 中的 Joi schema、restart: 'browser'、I.retry()、I.limitTime()、Playwright customLocators、I.softExpect* / I.flushSoftAssertions。
• 脚本/CI 中使用了 --reporter mochawesome，或 package.json / mocha.reporterOptions 中包含 mochawesome。

如果没有这些 3.x 特征，项目可能已经使用 4.x——请交由 codeceptjs-fundamentals 处理。

工作流

各阶段按顺序执行。在每个阶段完成时提交更改，以便通过二分法定位回归。

1. 升级 Node 和 CodeceptJS

• 确认 Node ≥ 16（建议使用 20+）；更新 engines.node 和 CI 运行器。
• npm install codeceptjs@4。
• TypeScript 项目：npm install --save-dev tsx。它将替代 ts-node/esm，后者现在会发出警告。

2. 将项目转换为 ESM

• 在 package.json 中添加 "type": "module"。否则，每个 .js 文件都会被解析为 CommonJS，ESM 导入会在加载时抛出错误。
• 转换配置、页面对象、自定义 helper、自定义步骤和编程式用法：
  • const Helper = require('@codeceptjs/helper') → import Helper from '@codeceptjs/helper'
  • module.exports = X → export default X（或命名导出）
  • const { codecept, container, event } = require('codeceptjs') → import codeceptjs, { container, event } from 'codeceptjs'
• Container.create() 和 Config.load() 现在是异步的——请对它们使用 await。
• 确实需要 CJS 的文件（很少见，通常是第三方 shim）请重命名为 .cjs。

3. 移除或替换已删除的 helper 和插件

旧项	替代方案
Helper Nightmare / Protractor / TestCafe	Playwright、Puppeteer 或 WebDriver。
Helper AI	顶层 ai: 配置 + aiTrace 插件。
Helper SoftExpectHelper	import { hopeThat } from 'codeceptjs/effects'；在场景末尾调用 hopeThat.noErrors()。
Helper Mochawesome	暂停并询问用户——见下方“Mochawesome 决策”。不要擅自删除。
Plugin autoLogin	auth 插件（参见 codeceptjs-auth 技能）。
Plugin tryTo / retryTo	import { tryTo, retryTo } from 'codeceptjs/effects'
Plugin eachElement	import { eachElement } from 'codeceptjs/els'
Plugin commentStep	import step from 'codeceptjs/steps' → step.section('name') / step.endSection()
Plugin fakerTransform	在测试中直接从 @faker-js/faker 导入 faker。
Plugin enhancedRetryFailedStep	已重命名为 retryFailedStep。
Plugin allure / htmlReporter	@testomatio/reporter（HTML 管道）。对于 JUnit XML，使用 junitReporter 插件。
Plugin wdio / selenoid	通过 helpers.WebDriver 配置，或在外部运行。
Plugin screenshotOnFail / pauseOnFail / stepByStepReport	已分别重命名为 screenshot / pause / screenshot（并设置 slides: true）。旧名称仍可解析，但会发出弃用警告。

Mochawesome 的处理选择

4.x 中移除了内置的 Mochawesome 辅助器（辅助器类、mochawesome 依赖项和工作进程报告目录接线）。mochawesome 报告器本身仍可正常使用——它是 Mocha 自带的报告器，从未需要 CodeceptJS 将其打包。

这是一个由用户选择的事项——不要替用户做决定。检测到 Mochawesome 时（出现在 helpers: 中的辅助器、--reporter mochawesome，或 package.json/mocha.reporterOptions 中的 mochawesome），请停下来询问用户想选择哪种方案：

1. 切换到 @testomatio/reporter（推荐）。 更丰富的 HTML 报告（步骤、截图、视频、跟踪记录），支持工作进程，不需要辅助器或内部耦合。运行 npm install --save-dev @testomatio/reporter，启用 testomatio 插件，并使用 TESTOMATIO_DISABLE_UPLOAD=1 运行。要生成 JUnit XML，请添加 junitReporter 插件。建议推荐此方案。
2. 保留 Mochawesome——仅生成报告。 从 helpers: 中移除 Mochawesome 辅助器，保留 npm i -D mochawesome 和 --reporter mochawesome --reporter-options reportDir=output。这会失去辅助器自动嵌入失败截图的功能。
3. 保留 Mochawesome——嵌入截图。 从 helpers: 中移除辅助器，并将其重建为一个项目本地自定义辅助器，用来封装 mochawesome/addContext（迁移指南的「Keeping Mochawesome」一节中提供了忠实移植版）。说明两点注意事项：它会导入不遵循 semver 稳定性的 codeceptjs/lib/* 内部模块（请固定版本）；截图插件的文件名同步不再自动进行（请在辅助器和 screenshot 插件中设置相同的 uniqueScreenshotNames）。

无论选择哪种方案，还要从任何自定义工作进程脚本中移除对 mochawesome 报告目录的处理，并替换任何对 I.addMochawesomeContext() 的依赖（只有方案 3 会保留此方法）。

明确列出方案 1–3，并在做任何更改前让用户决定。默认推荐方案 1。完整参考（更改前后的配置及自定义辅助器移植版）位于 node_modules/codeceptjs/docs/migration-4.md →「Mochawesome → Testomat.io Reporter」。

4. 更新已更改的 API

• AI 配置——删除 request 函数。安装 Vercel AI SDK 和提供方（npm install ai @ai-sdk/openai），并设置 ai: { model: openai('gpt-5') }。@ai-sdk/anthropic、@ai-sdk/google 等也使用相同的结构。
• JSON 架构——I.seeResponseMatchesJsonSchema() 现在使用 Zod，而非 Joi。请重写（Joi.object().keys({...}) → z.object({...})、Joi.string().required() → z.string() 等），并运行 npm uninstall joi。
• Playwright——将 restart: 'browser' 替换为 'session'（默认值）、'context' 或 'keep'。移除 customLocators 配置；改用 customLocator 插件或 ARIA 定位器（{ role: 'button', name: 'Submit' }）。
• I.retry() / I.limitTime()——已移除（不只是弃用）。请改用步骤选项 API：import step from 'codeceptjs/steps'，然后将配置作为步骤的最后一个参数传入。I.retry(3).click('Submit') → I.click('Submit', step.retry(3))；I.limitTime(10).fillField('Email', x) → I.fillField('Email', x, step.timeout(10))。还可以使用 step.opts({ elementIndex: 2 })。行为不变，但选项不再泄漏到后续步骤。recorder.retry() 不受影响（仅适用于自定义辅助器）。
• within 和 session——不再是全局方法。import { within, session } from 'codeceptjs'（或从 codeceptjs/effects 导入 within）。两者都返回 Promise——需要返回值时请使用 await。
• 子路径导入——codeceptjs/effects、codeceptjs/els、codeceptjs/steps、codeceptjs/store、codeceptjs/assertions。完整列表请参阅迁移指南。
• tryTo / hopeThat——返回 Promise<boolean>（不再采用 3.x 的 Promise<T | false> 结构）。

5. 采用 noGlobals: true

3.x 会将 Helper、actor、inject、share、secret、locate、dataTable、within、session、codecept_dir、output_dir 泄漏为全局变量。4.x 的新配置默认启用 noGlobals: true，并会对未启用该选项的项目发出警告。请将其添加到配置中，并从 codeceptjs / @codeceptjs/helper 显式导入，以替换全局变量。测试运行器全局变量（Feature、Scenario、Before、After、BeforeSuite、AfterSuite、pause、inject、share）和 BDD 步骤定义全局变量（Given、When、Then、And）保持不变——它们由运行器注入到作用域中。

6. 升级依赖包

如果项目直接依赖以下包，请确认升级后没有问题：chai（4 → 6，仅支持 ESM）、chai-as-promised（7 → 8）、commander（11 → 14）、@faker-js/faker（9 → 10）、chokidar（4 → 5）、@cucumber/gherkin（35 → 38）、webdriverio（9.12 → 9.23）。joi 和 testcafe 已移除。完整表格请参阅迁移指南 §7。

7. 验证

按顺序运行：

1. npx codeceptjs check -c <config> — 检查配置、Helper、插件和页面对象问题，无需启动浏览器。
2. 使用一个小型冒烟测试场景运行 npx codeceptjs run --debug。确认步骤正常执行，报告内容合理。
3. 运行 npx codeceptjs run-workers 2 — 确认工作进程事件分发器会像单进程模式一样触发每个测试的事件（4.x 变更）。
4. TypeScript 用户：确认错误堆栈跟踪指向 .ts 源代码行（这证明加载的是 tsx，而非 ts-node/esm）。
5. 在代码库中搜索 tryTo(、retryTo(、eachElement(、commentStep(、softExpect、I.softExpect、Joi.、restart: 'browser'、I.retry(、I.limitTime(，以及（除非用户选择保留）Mochawesome / --reporter mochawesome — 这些内容都不应残留。作为步骤参数传入的 step.retry( / step.timeout( 是预期的替代写法，不属于残留。
6. 如果项目使用了 autoLogin：确认 auth 插件能恢复会话和角色。

相关技能

• codeceptjs-auth — 用于替代已移除的 autoLogin 插件
• codeceptjs-fundamentals — 迁移完成后运行，以确认各项配置已正确连接
• 完整参考：node_modules/codeceptjs/docs/migration-4.md