migrate-codeceptjs-4

CodeceptJS 3.x → 4.x への移行

CodeceptJS 4 はESM のみで、TypeScript を優先しています。CommonJS との互換性を保つための仕組みはありません。すべてのヘルパー、ページオブジェクト、カスタムステップ、設定ファイルを ESM にする必要があります。このスキルでは、アップグレードを最初から最後まで進めます。

正式なリファレンスは node_modules/codeceptjs/docs/migration-4.md（npm install codeceptjs@4 の実行後）です。一度目を通してください。このスキルでは作業を統括し、エージェントが見落としがちな点を取り上げます。

実行するタイミング

作業を始める前に検出してください。次のいずれかに当てはまるか確認します。

• package.json に "codeceptjs": "^3"／"3.x" が記載されている、または "type": "module" がない。
• テスト、ページオブジェクト、ヘルパー、設定で、CodeceptJS に対して require()／module.exports を使用している。
• 設定で削除済みのヘルパー（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 スキーマ、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 のインポートは読み込み時にエラーになります。
• 設定、ページオブジェクト、カスタムヘルパー、カスタムステップ、プログラムからの使用を変換します。
  • 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 が必要なファイル（まれで、通常はサードパーティーのシム）は、.cjs に名前を変更します。

3. 削除されたヘルパーとプラグインを削除または置き換える

旧版	置き換え先
ヘルパー Nightmare／Protractor／TestCafe	Playwright、Puppeteer、または WebDriver。
ヘルパー AI	トップレベルの ai: 設定と aiTrace プラグイン。
ヘルパー SoftExpectHelper	import { hopeThat } from 'codeceptjs/effects' を使用し、シナリオの最後に hopeThat.noErrors() を呼び出します。
ヘルパー Mochawesome	作業を止めてユーザーに確認してください。「Mochawesome の選択」を参照してください。黙って削除しないでください。
プラグイン autoLogin	auth プラグイン（codeceptjs-auth スキルを参照）。
プラグイン tryTo／retryTo	import { tryTo, retryTo } from 'codeceptjs/effects'
プラグイン eachElement	import { eachElement } from 'codeceptjs/els'
プラグイン commentStep	import step from 'codeceptjs/steps' → step.section('name')／step.endSection()
プラグイン fakerTransform	テスト内で import { faker } from '@faker-js/faker' を直接使用します。
プラグイン enhancedRetryFailedStep	retryFailedStep に改名されました。
プラグイン allure／htmlReporter	@testomatio/reporter（HTML パイプ）。JUnit XML には junitReporter プラグインを使用します。
プラグイン wdio／selenoid	helpers.WebDriver で設定するか、外部で実行します。
プラグイン screenshotOnFail／pauseOnFail／stepByStepReport	screenshot／pause／slides: true を指定した screenshot に改名されました。旧名も引き続き使用できますが、非推奨の警告が出ます。

Mochawesome に関する判断

同梱の Mochawesome ヘルパーは 4.x で削除されています（ヘルパークラス、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」セクションにあります）。次の 2 つの注意点を伝えてください。非 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() では Joi ではなく Zod を使用するようになりました。書き換えます（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'（または within は codeceptjs/effects から）を使用します。どちらも 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> — ブラウザーを起動せずに、設定／ヘルパー／プラグイン／ページオブジェクトの問題を検出します。
2. 小規模なスモークシナリオで npx codeceptjs run --debug を実行します。ステップが実行され、レポートに問題がないことを確認します。
3. npx codeceptjs run-workers 2 を実行します。ワーカーイベントディスパッチャーが、単一プロセスモードと同じ方法でテストごとのイベントを発行することを確認します（4.x の変更点）。
4. TypeScript ユーザー：エラースタックトレースが .ts のソース行を指していることを確認します（ts-node/esm ではなく tsx が読み込まれている証拠です）。
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