codeceptjs-auth

CodeceptJS Auth Plugin

auth プラグインは、各ユーザーを一度だけログインさせ、Cookie（またはオーバーライドを使った localStorage／トークン）を取得し、後続のテストでセッションを復元します。セッションが古くなっている場合は、自動的に再ログインします。

プロジェクトですでに auth が設定されている場合（fundamentals の検出結果）、既存の inject 名とユーザーキーを再利用してください。再設定しないでください。

まず判断する — ユーザーに確認する

プラグインの動作は4つの回答によって決まります。推測しないでください。

1. そもそもセッションが必要ですか？ 公開フロー（ランディングページ、サインアップ）なら、プラグインは使用しません。
2. ユーザーは1人ですか、複数ですか？ デフォルトは1人です。実際に使用する場合に限り、ユーザーを追加します。
3. 複数の場合、何を基準に分けますか？ ロール、ワークスペース／テナント、プランの種類、サインインプロバイダー、テストごとのフィクスチャなど、システムによって異なります。確認したうえで、回答に合わせて users.<key> エントリーに名前を付けます。
4. 認証の種類は何ですか？
   • フォーム — デフォルト。以下の標準形を参照してください。
   • OAuth／SSO — プロバイダーボタンをクリックし、IdP ページを操作します（別オリジンの場合がよくあります）。
   • マジックリンク／パスワードレス — UI フローの自動化は割に合わないことが多いため、API での発行、またはテスト用メールボックスからのリンク取得を優先します。
   • API トークン — フォームは使わず、executeScript でトークンを localStorage に書き込むか、I.setCookie(...) を使用します。
   • 2FA／OTP — login を非同期にし、送信前にテスト用メールボックス／バックドアからコードを取得します。

ルール

1. ログインフローを conf に記述しないでください。 steps_file.js（含まれている場合）またはページオブジェクトに記述し、conf からは参照するだけにします：login: (I) => I.login()。
2. 認証情報は環境変数からのみ取得します — .env は process.loadEnvFile() で読み込みます（dotenv への依存は禁止）。パスワードは secret(...) でラップします。conf、steps ファイル、テスト、Git の履歴のいずれにも、値を直接記述しないでください。
3. .env は Git の追跡対象外にし、.env.example には値を含めず、変数名を記述してコミットします。 output/*_session.json も Git の追跡対象外にします。

標準形

// codecept.conf.js — first line of the file
process.loadEnvFile()

export const config = {
  include: { I: './steps_file.js' },
  plugins: {
    auth: {
      enabled: true,
      saveToFile: true,
      users: {
        admin: {
          login: (I) => I.login(),
          check: (I) => I.see('Welcome, User', '.navbar'),
        },
      },
    },
  },
}

// steps_file.js
import { secret } from 'codeceptjs'
const { I } = inject()

export default function () {
  return actor({
    login() {
      I.amOnPage('/login')
      I.fillField('Email', process.env.ADMIN_EMAIL)
      I.fillField('Password', secret(process.env.ADMIN_PASSWORD))
      I.click('Sign in')
    },
  })
}

# .env (gitignored)        # .env.example (committed)
USER_EMAIL=...             USER_EMAIL=
USER_PASSWORD=<secret>     USER_PASSWORD=

事前確認（設定を書く前に）

1. 実際のログインページを確認します — MCP の run_code で /login に移動し、ARIA スナップショットを確認します（codeceptjs-exploration）。フィールドのラベル／name／id／送信コントロールは、推測ではなく実際のページから取得します。認証の仕組みが不明な場合は、ユーザーに確認します。
2. ロール固有のログイン後マーカーを選びます — このユーザーにだけ表示されるもの（ナビゲーションバーのユーザー名、data-user-role など）を選びます。
3. セッションの保存場所を確認します — サーバーサイドレンダリングのアプリでは Cookie（デフォルト）、SPA では localStorage／sessionStorage を使用します。手動ログイン後に I.executeScript(() => Object.keys(localStorage)) を実行して確認します。Cookie の取得／復元は、トークンストレージに対しては何もせずに終了します。

検証

login(<role>) を呼び出し、ログイン後マーカーをアサートする Scenario を1つ含むファイルを実行します。

npx codeceptjs run --grep '<scenario>' --debug    # real run, not dry — dry-run doesn't init plugins

このラウンドトリップが成功してから、saveToFile: true を有効にします。無効な保存済みセッションは、壊れた login を見えなくしてしまいます。

その後、フック／テストに組み込みます：スイート全体に適用する場合は Before(({ login }) => login())、必要に応じてテストごとに適用します。

複数ロールの形

質問3への回答を得てから設定します。キーは、このシステムでユーザーを分ける基準に合わせて命名し、各キーに対応するアクターメソッドを1つ用意します。

users: {
  admin:      { login: (I) => I.loginAsAdmin() },
  workspaceB: { login: (I) => I.loginToWorkspaceB() },
}

login(key) 1つにパラメーター化しないでください。プラグインはセッションを名前で管理するため、メソッドを明示したほうが読みやすくなります。Scenario の途中で切り替えるには、session('<key>') を使います。これにより、並列のブラウザーコンテキストが開きます（fundamentals § テストの作成）。

トークン／localStorage 認証

セッションが Cookie 以外に保存されている場合は、fetch／restore をオーバーライドします。

admin: {
  login: (I) => I.loginAsAdmin(),
  check: (I) => I.see('Admin', '.navbar'),
  fetch: (I) => I.executeScript(() => localStorage.getItem('session_id')),
  restore: (I, session) => {
    I.amOnPage('/')
    I.executeScript((s) => localStorage.setItem('session_id', s), session)
  },
}

check(I, session) には fetch が返した値が渡されます。再ログインを強制するには、check 内で例外をスローします（例：/me エンドポイントでユーザーの不一致が確認された場合）。

注意点

• 認証情報を conf／テストに直接記述しないでください。常に環境変数から取得し、secret() を使います。
• .env と output/*_session.json を Git の追跡対象外にするのを忘れないでください。どちらからも認証情報が漏れる可能性があります。

関連するスキル

• codeceptjs-fundamentals — シークレットのルール、セッション、設定変更の落とし穴
• codeceptjs-exploration — 実際のログインページの確認
• writing-codeceptjs-tests／refactoring-codeceptjs-tests — 認証が確認されたらこのスキルを呼び出します
• debugging-codeceptjs-tests — 認証関連の失敗パターン