Turnstile の実装をテストする

ダミーのサイトキーとシークレットキーを使うと、自動テストスイートを妨げる本番のチャレンジを発生させずに、Turnstile の実装をテストできます。

Selenium、Cypress、Playwright などの自動テストスイートは、Turnstile からボットとして検出されます。その結果、次の問題が起きることがあります。

Turnstile が自動ブラウザーをブロックして、テストが失敗する
チャレンジのばらつきにより、テスト結果が安定しない
フォーム送信のテストが妨げられる
一連のユーザーフローをテストしにくい

ダミーキーは、予測可能で制御された応答を返すため、自動テストツールと組み合わせて使えます。

テスト用サイトキー

サイトキー	動作	ウィジェットタイプ	用途
`1x00000000000000000000AA`	常に成功	Visible	フォーム送信の成功をテストする
`2x00000000000000000000AB`	常に失敗	Visible	エラー処理と再試行ロジックをテストする
`1x00000000000000000000BB`	常に成功	Invisible	Invisible ウィジェットの成功フローをテストする
`2x00000000000000000000BB`	常に失敗	Invisible	Invisible ウィジェットのエラー処理をテストする
`3x00000000000000000000FF`	インタラクティブチャレンジを強制する	Visible	ユーザー操作のシナリオをテストする

テスト用シークレットキー

サーバー側の検証テストには、次のシークレットキーを使います。

シークレットキー	動作	用途
`1x0000000000000000000000000000000AA`	検証は常に成功	トークン検証の成功をテストする
`2x0000000000000000000000000000000AA`	検証は常に失敗	検証エラーの処理をテストする
`3x0000000000000000000000000000000AA`	「token already spent」エラーを返す	トークンの重複処理をテストする

実装

ローカル開発

テストキーは、次を含む任意のドメインで使えます。

localhost
127.0.0.1
0.0.0.0
任意の開発用ドメイン

Cloudflare は、本番で使うサイトキーにローカルドメイン（localhost または 127.0.0.1）を許可しないことを推奨します。ただし、ホスト名管理の許可ドメイン一覧にローカルドメインを追加することもできます。ダミーサイトキーは localhost を含む任意のドメインから使えます。

クライアント側のテスト

本番のサイトキーをテスト用サイトキーに置き換えます。

<!-- Development/Testing -->
<div class="cf-turnstile" data-sitekey="1x00000000000000000000AA"></div>

<!-- Production -->
<div class="cf-turnstile" data-sitekey="your-real-sitekey"></div>

サーバー側のテスト

本番のシークレットキーをテスト用シークレットキーに置き換えます。

// Environment-based configuration
const SECRET_KEY = process.env.NODE_ENV === 'production' 
  ? process.env.TURNSTILE_SECRET_KEY 
  : '1x0000000000000000000000000000000AA';

// Use in validation
const validation = await validateTurnstile(token, SECRET_KEY);

環境ごとの設定

環境ごとに異なるキーを設定します。


# .env.development
TURNSTILE_SITEKEY=1x00000000000000000000AA
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA

# .env.test  
TURNSTILE_SITEKEY=2x00000000000000000000AB
TURNSTILE_SECRET_KEY=2x0000000000000000000000000000000AA

# .env.production
TURNSTILE_SITEKEY=your-real-sitekey
TURNSTILE_SECRET_KEY=your-real-secret-key

ダミートークンの動作

トークンの生成

テスト用サイトキーは、ダミートークン XXXX.DUMMY.TOKEN.XXXX を生成します。

トークンの検証

テスト用シークレットキー: ダミートークンだけを受け付け、本番トークンは拒否します。
本番のシークレットキー: 本番トークンだけを受け付け、ダミートークンは拒否します。

検証レスポンス

成功レスポンスjson

{
  "success": true,
  "challenge_ts": "2022-02-28T15:14:30.096Z",
  "hostname": "localhost",
  "error-codes": [],
  "action": "test",
  "cdata": "test-data"
}

失敗レスポンスjson

{
  "success": false,
  "error-codes": ["invalid-input-response"]
}

使用済みトークンjson

{
  "success": false,
  "error-codes": ["timeout-or-duplicate"]
}

テストシナリオ

テスト用サイトキー	テスト用シークレットキー	テストケース
`1x00000000000000000000AA`	`1x0000000000000000000000000000000AA`	この組み合わせでは、検証は常に成功します。
`2x00000000000000000000AB`	`2x0000000000000000000000000000000AA`	この組み合わせでは、常に失敗します。
`1x00000000000000000000AA`	`3x0000000000000000000000000000000AA`	この組み合わせでは、常に "timeout-or-duplicate" エラーで失敗します。