CodeceptJSとは？使い方とPlaywrightでの導入手順｜4.2対応・3系からの移行【2026年10月】

CodeceptJS（コードセプトJS）は、「ページを開く」「ボタンを押す」「文字が見える」といった利用者の操作をそのままテストコードにする、Node.js製のE2E（エンドツーエンド）テストフレームワークです。ブラウザを動かす部分はPlaywrightやWebDriverなどの「ヘルパー」に任せるので、共通のAPIで書いたシナリオを別の実行エンジンでも使い回せます。ヘルパー固有の機能を使った箇所だけは書き直しが要ります。

2026年10月28日時点の最新版は2026年10月20日公開の4.2.2で、4.2.0からNode.js 22.12以上が要件になりました。この記事では、4.2.2とPlaywright 1.64.1を手元に入れて実際に動かした結果をもとに、導入・実行・デバッグ・日本語でのGherkin記述・3系からの移行・AI機能を順に説明します。

まとめ：CodeceptJSの要点（4.2.2時点）

• CodeceptJSはブラウザ自動化ライブラリではなく、その上に乗る「シナリオの書き方の層」です。Playwrightとは競合ではなく、Playwrightをヘルパーとして組み合わせて使います。
• 4系はネイティブESM（"type": "module"）です。4.2からNode.js 22.12以上が要件なので、CIのNode.jsも合わせて上げます。
• 導入は npm install codeceptjs playwright のあと npx codeceptjs init。-y を付けると質問を飛ばしてPlaywright＋Chromiumの雛形ができます。
• 4.2.2の gherkin:init はESMの設定ファイルを exports.config 形式で上書きし、そのままでは起動できなくなります。Gherkinの設定は手で書き足すのが安全です。
• 3系からの移行では、TestCafe・Nightmare・Protractorヘルパーと autoLogin プラグインが消え、AI設定はVercel AI SDKの ai.model 指定に変わりました。

CodeceptJSの仕組み：アクターIの記法とヘルパー

E2Eテストは、ログインから購入完了までのように画面操作を通しで確かめるテストです。位置づけと結合テストとの違いはE2Eテストのベストプラクティスと結合テストとの違いにまとめています。CodeceptJSが変えるのは、そのE2Eテストの「書き方」です。

アクターIを主語にしたシナリオの書き方

テストは、操作する人を表す I を主語にして動作を並べます。amOnPage（ページを開く）、fillField（入力する）、click、see（表示を確かめる）というメソッド名がそのまま操作の意味になるので、テスト仕様書に近い形でレビューできます。要素が現れるまでの待機は各メソッドが内部で行います。

Feature('ログイン');

Scenario('正しい資格情報でログインできる @smoke', ({ I }) => {
  I.amOnPage('/login.html');
  I.fillField('メールアドレス', '[email protected]');
  I.fillField('パスワード', 'secret');
  I.click('ログイン');
  I.see('マイページ');
});

fillField にはCSSセレクタでなくラベル文字列を渡せます。日本語UIなら日本語のラベル名をそのまま書けます。4系では { role: 'button', name: 'ログイン' } のようなARIAロケーターも、Playwright・Puppeteer・WebDriverの各ヘルパーで同じように使えます。

ヘルパーで実行エンジンを切り替える仕組み

CodeceptJS自身はブラウザを操作しません。設定ファイル codecept.conf.js の helpers に書いたヘルパーが、実際の自動化ライブラリに命令を渡します。公式のAPI索引（2026年10月28日確認）には17のヘルパーが載っています。主なものは次のとおりです。

Lightpanda・Obscura・Kitesurfは、Chrome DevTools Protocolで操作する軽量ブラウザ向けのヘルパーです。公式の代替ブラウザのページはexperimentalと位置づけ、CIではブラウザの版を固定し、互換性確認用にPlaywrightかWebDriverのジョブを残すよう求めています。高速化の補助として足すものと考えてください。

CodeceptJS・Playwright・Cypressの違いと使い分け

「CodeceptJSとPlaywrightのどちらを使うか」は二者択一ではありません。Playwrightにはブラウザ操作ライブラリとテストランナーのPlaywright Testがあり、CodeceptJSは前者をヘルパーとして呼び出し、その上にシナリオ記法・プラグイン・レポートを足す層です。Cypressは記述とブラウザ制御が一体になった独立のツールです。

Playwright単体を選ぶ理由と仕組みはPlaywrightとは？仕組み・できること・Seleniumとの違い、Cypressの使い方はCypress E2Eテストの使い方で解説しています。CodeceptJSからPlaywrightの機能を直接呼びたいときは、I.usePlaywrightTo('説明', async ({ page }) => { ... }) で browser・browserContext・page を受け取れるので、ヘルパーにまだ無い新しいAPIも使えます。Playwright本体の更新はPlaywrightの最新バージョンとリリース履歴で追っています。

CodeceptJS 4.2をインストールしてPlaywrightで動かす手順

ここからは、macOS上のNode.js v26.5.0に [email protected] と playwright（1.64.1）を入れ、ヘッドレスのChromiumでテストを通すまでの手順です。出力は検証用のモック画面に対して実行したときの抜粋で、処理時間は環境によって変わります。

動作要件：Node.js 22.12以上とESM

公式のインストールガイドは「CodeceptJS 4.2はNode.js 22.12以上が必要」と明記しています。npmに登録された engines.node も、4.1.0までの >=16.0 から4.2.0で >=22.12.0 に上がりました。移行ガイドは、実行時に依存しているパッケージの最小サポート版に合わせたと説明しています。

ただし、起動時に版を調べて止める処理は入っていません。bin/codecept.js が拒否するのはNode.js 12未満だけで、Node.js v20.20.2で実行してもこの記事のサンプルは通りました。ただ、要件外の環境で問題が出ても公式の対応は期待できません。ローカルとCIのNode.jsは22.12以上にそろえてください。

もう1つの要件はESMです。4系の設定ファイルは export const config = {...} の形で書かれるため、package.json に "type": "module" を入れます。

npx codeceptjs init による設定ファイルの生成

npm init -y
npm pkg set type=module
npm install --save-dev [email protected] [email protected]
npx playwright install chromium
npx codeceptjs init -y

init を -y なしで実行すると、TypeScriptを使うか、テストファイルの場所（既定は ./tests/*_test.js）、ヘルパー（既定はPlaywright）、ログやスクリーンショットの出力先、の順に質問されます。4.2.2の質問にベースURLの項目はありません。生成された設定は次のとおりで、url は後から書き換えます。

/** @type {CodeceptJS.MainConfig} */
export const config = {
  tests: './tests/*_test.js',
  output: './output',
  helpers: {
    Playwright: {
      browser: 'chromium',
      url: 'http://localhost',
      show: false
    }
  },
  include: {
    I: './steps_file.js'
  },
  noGlobals: true,
  plugins: {},
  name: 'cj3726'
}

noGlobals: true は4系の新しい既定です。それでも Feature・Scenario・Before などはテストファイルで今までどおり使えます。within や tryTo はインポートが必要になります（移行の章で触れます）。show: false はヘッドレス実行で、true にするとブラウザの画面が表示されます。

ログイン操作テストの作成と実行

テスト対象には、ボタンを押すと「マイページ」の見出しを足すだけの検証用HTMLを site/login.html に置きました。認証はしない、操作の確認用のモックです。

<!doctype html>
<html lang="ja"><body>
<form id="f"><label for="m">メールアドレス</label><input id="m" name="mail">
<label for="p">パスワード</label><input id="p" type="password" name="pw">
<button type="button" onclick="document.body.insertAdjacentHTML('beforeend','<h1>マイページ</h1>')">ログイン</button></form>
</body></html>

サーバーを立てずにファイルを直接開くため、設定の url を site フォルダの絶対パスに書き換えます（検証時は file:///tmp/cj3726/site）。実際のアプリを相手にするなら、ここに開発サーバーのURL（例 http://localhost:3000）を書きます。

前の節のログインのシナリオを tests/login_test.js に保存し、--steps を付けて実行すると、各ステップが日本語の引数のまま表示されます。

$ npx codeceptjs run --steps
CodeceptJS v4.2.2 #StandWithUkraine

ログイン --
  正しい資格情報でログインできる @smoke
    I am on page "/login.html"
    I fill field "メールアドレス", "[email protected]"
    I fill field "パスワード", "secret"
    I click "ログイン"
    I see "マイページ"
  ✔ OK in 1776ms
  （2本目のシナリオの出力は省略）

  OK  | 2 passed   // 4s

実行前に設定と環境を点検するなら npx codeceptjs check です。設定・ヘルパー・プラグイン・型定義の生成まで順に確かめ、ブラウザの起動と終了も試してから「ALL CHECKS PASSED」を返します。

テストの実行オプション：シナリオの絞り込みと並列実行

特定のシナリオだけを回すときは、シナリオ名やタグを --grep に渡します。タグはシナリオ名の中に @smoke のように書きます。

# タグ @smoke を付けたシナリオだけ実行
npx codeceptjs run --grep '@smoke'

# 2つのワーカーで並列実行
npx codeceptjs run-workers 2

# ブラウザを起動せずにシナリオと各ステップを表示
npx codeceptjs dry-run --steps

run-workers 2 では、出力の各行に [Worker 01] のような番号が付き、2本のシナリオが別々のワーカーで並行に動きました。ブラウザの種類や設定を変えて同じテストを複数回まわすときは run-multiple とプロファイルを使います。画面ごとの操作をクラスにまとめて保守しやすくするなら、Page Object Model（POM）の実装例の考え方を、npx codeceptjs generate:pageobject で作るページオブジェクトにそのまま当てはめられます。

CodeceptJSのデバッグ手順：出力の詳細度・pause・ブレークポイント

テストが落ちたら、まず出力の量を増やします。公式のデバッグガイドは、テストを書いている間は常に --debug を付けることを勧めています。

原因の箇所で止めて画面を触りたいときは、シナリオの途中に pause() を書きます。対話シェルに入り、I.click('…') などをその場で打って結果を確かめられます。4系では pause プラグインが追加され、失敗した時点や特定のファイル・URLで止めることもできます。テストを書かずに操作を試すだけなら npx codeceptjs shell を使います。

ロケーターが当たらない原因を調べるには、4系で入った codeceptq が便利です。保存したHTMLに対してCodeceptJSのロケーターを当て、一致した要素を行番号付きで返します。

$ npx codeceptq 'ログイン' --click --file site/login.html
1 match for 'ログイン' in site/login.html

1. Line 4
   <button type="button" ...>ログイン</button>

Gherkinと日本語でテストを書く方法

非エンジニアと仕様をすり合わせたいときは、Given／When／ThenのGherkin記法でテストを書けます。Gherkinの構文そのものはGherkinの全キーワードと.featureファイルの書き方、同じ記法を使うCucumberはCucumberのテスト自動化の手順で解説しています。CodeceptJSで使うときは、4.2.2に特有の注意点が2つあります。

gherkin:initが設定ファイルを上書きする問題と回避策

4.2.2で npx codeceptjs gherkin:init を実行すると、features/ と step_definitions/steps.js は作られます。ところが同時に codecept.conf.js が exports.config = {...}（CommonJS形式）で書き直され、"type": "module" のプロジェクトでは次のエラーで起動できなくなりました。

Error: Failed to load config file /private/tmp/cj3726/codecept.conf.js:
exports is not defined in ES module scope

設定を書き換える処理（lib/command/utils.js）が、ESMのプロジェクトでも exports.config = の形で書き出すためです。上書きの際に setHeadlessWhen などのimport文も消えます。設定ファイルをgitで管理しておき、gherkin:init のあとで元に戻して、次の gherkin 節だけを手で足すのが確実です。

export const config = {
  // ...既存の設定
  gherkin: {
    features: './features/*.feature',
    steps: ['./step_definitions/steps.js']
  },
}

日本語featureファイルのlanguage指定

「機能」「シナリオ」「前提」「もし」「ならば」の日本語キーワードを使うときは、ファイルの1行目に # language: ja を書きます。この行を消すと、同じファイルが読み込みの段階でエラーになりました。

# language: ja
機能: ログイン
  シナリオ: 正しい資格情報でログインできる
    前提 ログインページを開いている
    もし メールアドレス "[email protected]" とパスワード "secret" でログインする
    ならば "マイページ" が表示される

各ステップの処理は step_definitions/steps.js に書きます。Cucumber式の {string} で引数を受け取れます。

const { I } = inject();

Given('ログインページを開いている', () => {
  I.amOnPage('/login.html');
});

When('メールアドレス {string} とパスワード {string} でログインする', (mail, pw) => {
  I.fillField('メールアドレス', mail);
  I.fillField('パスワード', pw);
  I.click('ログイン');
});

Then('{string} が表示される', (text) => {
  I.see(text);
});

npx codeceptjs run --features --steps で、featureの各行に対応する I の操作が順に表示されて通りました。

translation: ‘ja-JP’ によるメソッド名の日本語化

Gherkinを使わずに、テストコードのメソッド名を日本語にすることもできます。設定に translation: 'ja-JP' を足すと、I の代わりに 私は を受け取り、ページを移動する・フィールドに入力する・クリックする・テキストがあることを確認する などの日本語メソッドで書けます。

// codecept.conf.js に追加
translation: 'ja-JP',
include: { 私は: './steps_file.js' },

// tests/ja_test.js
Scenario('日本語の語彙で書く', ({ 私は }) => {
  私は.ページを移動する('/login.html');
  私は.フィールドに入力する('メールアドレス', '[email protected]');
  私は.クリックする('ログイン');
  私は.テキストがあることを確認する('マイページ');
});

公式の翻訳ページは、既定の翻訳が完成には程遠く、足りないメソッドは自分で語彙を足すよう案内しています。init で言語を選ぶ手順も載っていますが、4.2.2の init にその質問は無いので設定ファイルに直接書きます。英語のメソッド名でも日本語の引数は渡せるので、翻訳は必須ではありません。

CodeceptJS 3系から4系への移行と破壊的変更

4.0.0（2026年5月21日公開）はCommonJSからネイティブESMへの移行を含むメジャーリリースです。公式の移行ガイドのうち、既存のテストが動かなくなる変更をまとめると次のとおりです。

同梱の npx codeceptjs migrate は、JSON形式の設定をJavaScript形式に変えるだけのコマンドです。3系から4系への書き換えはしてくれません。移行ガイドは、npx skills add codeceptjs/skills で入るエージェント向けのスキル migrate-codeceptjs-4 に機械的な書き換えを任せる方法を最初に紹介しています。手で直す場合も、AIに任せる場合も、最後は npx codeceptjs check と run --debug で小さなスモークテストを通して確認します。

ESM化の確認対象は、設定ファイル・ページオブジェクト・カスタムヘルパーに加え、require などCommonJS構文を使うテストや補助ファイル、プログラムからの呼び出しです。3系は2026年4月23日の3.7.9（axiosのセキュリティ修正など）が最新で、4.0.0の公開後に3系の新しい版は出ていません。公式はサポート期限を示していませんが、新機能はすべて4系に入っているので、移行は先延ばしにしないほうが得です。

CodeceptJSのAI機能とMCPサーバーの実態

CodeceptJSはAIテストツールではありません。AIを使わなくてもテストフレームワークとして完結し、AIは設定したときだけ動く追加機能です。4系ではAIの接続にVercel AI SDKを使い、設定ファイルの ai.model にモデルを渡して npx codeceptjs run --ai で有効にします。公式の設定例はOpenAI・Anthropic・Googleで、そのほかにxAI・Mistral・Groq・Cohere・Azure OpenAIのSDKパッケージが挙がっています。

OpenAIを使う例です。先にAI SDKと接続先のパッケージを追加します。

npm install ai @ai-sdk/openai

import { openai } from '@ai-sdk/openai'

export const config = {
  // ...
  ai: {
    model: openai('gpt-5'),  // APIキーは環境変数 OPENAI_API_KEY
  },
}

healプラグインの修復レシピとAIの適用範囲

heal は「失敗したときに実行するレシピ」を登録する仕組みで、AIはその中の1つにすぎません。ログイン切れなら再ログインする、クリックに失敗したら再読み込みする、といったレシピをAIなしで書けます。npx codeceptjs generate:heal でAI修復のレシピと、fillField を click＋type に置き換えるレシピの2つが雛形として作られます。

AIの修復レシピは、エラー内容・実行中のステップ・ページのHTMLをAIに渡し、代わりに実行するコードを提案させる仕組みです。公式のAI解説は、AI修復が解決できるのは「要素のロケーターが変わって操作できなくなった場合」の1つだと説明しています。ボタンの文言が「Sign in」から「Login」に変わった、といったケースです。公式の説明では、対象は click・fillField などの操作で、see などのアサーション・待機・値の取得には働きません。修復が成功する保証もありません。公式のheal解説には、--debug モードでは動かないこと、1テストで修復するステップ数の既定が healLimit: 2 であることも書かれています。修復の提案は実行の最後に表示されます。提案はテストコードに書き戻してください。CIで黙って直し続けると、仕様の変化にテストが追従していないことに気づけません。

codeceptjs-mcpの操作機能とinit:agentによる登録

4系には、AIエージェントからCodeceptJSを操作するMCPサーバー codeceptjs-mcp が同梱されています。公式のMCPページによると、テストの一覧取得、ブラウザの起動、任意の I.* コードの実行、シナリオの実行、ステップごとの一時停止と再開、HTML・ARIA・スクリーンショットのスナップショット取得を提供します。

# Claude Code に登録する
npx codeceptjs init:agent claude
# 他のエージェントでは claude を codex・cursor・opencode のいずれかに変更

公式は、MCPサーバーをグローバルにインストールしたCodeceptJSから起動しないよう警告しています。プロジェクトのヘルパーやページオブジェクトを読めなくなるためで、プロジェクトのディレクトリで npx codeceptjs-mcp を使います。失敗時のDOM・コンソール・ネットワーク・スクリーンショットをMarkdownにまとめる aiTrace プラグインと組み合わせると、エージェントが失敗の原因を読み取れます。

CodeceptJSの採用を見送る条件

CodeceptJSの利点は「エンジンを替えても共通APIのシナリオを使い回せる」「Web・モバイル・APIを同じ記法で書ける」ことです。これが効かない場面では、抽象化の層が1つ増える分だけ損になります。

• チームがPlaywrightのAPIに慣れていて、対象がWebだけ：Playwright公式の情報を毎回 I のメソッドに読み替える手間が増えます。Playwright Testをそのまま使ってください。
• Node.js 22.12以上に上げられない環境：4.2系の動作要件を満たせません。3系の将来の修正提供は保証できないため、Node.jsの更新計画と併せて移行を判断してください。
• テストの大半を usePlaywrightTo で書くことになる：CodeceptJSの記法の利点が消えています。

逆に、実行エンジンを将来入れ替える余地を残したい、Webとモバイルアプリ（Appium）とAPIのテストを1つの記法で束ねたい、Gherkinで企画側と仕様を共有したい、という要件があるなら、抽象化の手間を上回る効果が出ます。E2Eテストの設計からCIへの組み込みまでをまとめて進めるなら、DevOps・CI/CD導入支援も相談先の1つです。ブラウザを直接扱う他の選択肢は、Puppeteerの仕組みと使い方や、モバイルのAppium 3でのモバイルテスト自動化で比べられます。

よくある質問

CodeceptJSは何に使うものですか？

Webアプリやモバイルアプリの画面操作を通しで確かめるE2Eテストの自動化に使います。ログインから購入完了までの流れを、I.click('ログイン') のように人の操作に近い形で書いて自動実行します。

CodeceptJSはAIツールですか？

いいえ。Node.js製のE2Eテストフレームワークです。AIは ai.model を設定して --ai で実行したときだけ動く追加機能で、使わなくてもテストは書けます。

PlaywrightとCodeceptJSの違いは何ですか？

Playwrightはブラウザを操作するライブラリで、CodeceptJSはPlaywrightをヘルパーとして呼び出し、その上にシナリオ記法やプラグインを足すフレームワークです。CodeceptJSの init の既定のヘルパーがPlaywrightで、両方を一緒にインストールして使います。

CodeceptJSに必要なNode.jsのバージョンは？

4.2系はNode.js 22.12以上です。4.1.0まではNode.js 16以上でした。Node.js 20でも起動はしますが、公式のサポート外です。

TypeScriptやJavaでも書けますか？

TypeScriptは使えます。init でTypeScriptを選ぶと codecept.conf.ts が作られ、4系ではテストファイルの読み込みに tsx を使います。Javaでは書けないので、Javaで書くならSelenium（Seleniumの使い方の解説）やPlaywright for Javaが候補です。

関連記事

• Playwright（プレイライト）とは？仕組み・できること・Seleniumとの違いを解説
• Playwrightのインストール方法とできない時の対処｜バージョン確認・Windows・Python
• Gherkinとは？構文の全キーワードと.featureファイルの書き方・実行例
• E2E（エンドツーエンド）テストのベストプラクティス｜結合テストとの違いとツール選定
• Cypress E2Eテストの使い方｜インストールからcy.intercept・CI実行まで【Cypress 16対応】