clerk-testing について
Clerkを使う開発者向けのテストリファレンスです。PlaywrightとCypressの設定や認証状態の扱いを説明し、開発用キーと状態の再利用を案内します。
主な機能
- 01PlaywrightとCypressに対応
- 02テスト環境の初期化
- 03ボット検知の回避
- 04storageStateによる認証状態の保存
活用シーン
- 01サインインフローのブラウザテスト
- 02テスト間での認証状態の再利用
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/clerk-testingを入力して読み込まれたか確認します。
詳細
テスト
判断ツリー
メンタルモデル
認証テストでは、セッション状態を分離します。各テストには新しい認証コンテキストが必要です。
clerkSetup()でテスト環境を初期化しますsetupClerkTestingToken()でボット検出を回避しますstorageStateでテスト間の認証状態を保持し、処理を高速化します
ワークフロー
- テストフレームワーク（Playwright または Cypress）を特定します
- 上記の判断ツリーから該当する URL を WebFetch します
- 公式のセットアップ手順に従います
- 開発インスタンスのキーのみを使用します（
pk_test_*/sk_test_*）。プロジェクトにキーがまだない場合は、npx clerk@latest init（Clerk CLI。clerk-setupを参照）で Clerk アプリケーションを作成し、開発インスタンスのキーを環境ファイルに書き込みます。Clerk アカウントも Dashboard へのアクセスも必要ありません。
ベストプラクティス
- 認証ページに移動する前に
setupClerkTestingToken()を使用します - テスト用 API キーを使用します：
pk_test_xxx、sk_test_xxx storageStateで認証状態を保存し、テストを高速化します- Clerk UI には
page.waitForSelector('[data-clerk-component]')を使用します
アンチパターン
| パターン | 問題 | 修正 |
|---|---|---|
| テストで本番用キーを使用する | セキュリティリスク | pk_test_* キーを使用します |
setupClerkTestingToken() を使用しない | 認証に失敗する | ページ遷移の前に呼び出します |
| 毎回 UI からサインインする | テストが遅くなる | storageState を使用します |
フレームワーク固有の設定
Playwright：認証状態には globalSetup を使用します
Cypress：サポートファイルに addClerkCommands({ Cypress, cy }) を追加します
関連項目
clerk-setup- テストを追加する前に Clerk をインストールしますclerk-nextjs-patterns- テスト対象の Next.js パターン- デモリポジトリ
コメント
Markdown 対応