E2E テストから Turnstile を除外する

このチュートリアルでは、Turnstile 専用のテスト用キーを使って、エンドツーエンド（E2E）テストで Turnstile を扱う方法を説明します。

概要

E2E テストを実行するときは、Turnstile の検証をスキップするか、簡略化したいことがよくあります。Cloudflare は、検証が常に成功する公式のテスト用認証情報を提供しています。テスト環境に適しています。

テスト用 sitekey: 1x00000000000000000000AA
テスト用 secret key: 1x0000000000000000000000000000000AA

実装

テスト環境を判定するポイントは、サーバー側でテストリクエストを識別することです。次のようなシンプルな方法があります。

// Detect test environments using IP addresses or headers
function isTestEnvironment(request) {
  const testIPs = ['127.0.0.1', '::1'];
  const isTestIP = testIPs.includes(request.ip);
  const hasTestHeader = request.headers['x-test-environment'] === 'secret-token';

  return isTestIP || hasTestHeader;
}

// Use the appropriate credentials based on the environment
function getTurnstileCredentials(request) {
  if (isTestEnvironment(request)) {
    return {
      sitekey: '1x00000000000000000000AA',
      secretKey: '1x0000000000000000000000000000000AA'
    };
  }

  return {
    sitekey: process.env.TURNSTILE_SITE_KEY,
    secretKey: process.env.TURNSTILE_SECRET_KEY
  };
}

サーバー側の統合

ページをレンダリングするときに、環境に応じた sitekey を渡します。

app.get('/your-form', (req, res) => {
  const { sitekey } = getTurnstileCredentials(req);
  res.render('form', { sitekey });
});

クライアント側の統合

テンプレートでは、渡された sitekey を次のように使います。

<div class="turnstile" data-sitekey="<%= sitekey %>"></div>

ベストプラクティス

環境の判定
- テスト環境の識別には、複数の要素（IP、ヘッダーなど）を使います。
- 公開 Web からテストする必要がある場合は、テスト環境の識別子を安全に管理します。
認証情報の管理
- 本番用の認証情報は安全に保存します（たとえば環境変数）。
- 認証情報をバージョン管理にコミットしないでください。
- 環境ごとに異なる認証情報を使います。
デプロイ時の安全対策
- 本番環境にテスト用の認証情報が入らないよう、チェックを追加します。
- CI/CD パイプラインに認証情報の検証を含めます。
- テスト用の認証情報が誤って使われていないかを監視します。

テスト時の注意点

テスト用の認証情報では、検証が常に成功します。
自動テスト環境に適しています。
テスト中のレート制限を避けやすくなります。
テストの結果が予測しやすく、実行も速くなります。

テスト設定の例

Cypress などの E2E テストフレームワークでは、次のように設定します。

// Set test header for all test requests
beforeEach(() => {
  cy.intercept('*', (req) => {
    req.headers['x-test-environment'] = 'secret-token';
  });
});

// Your test can now interact with the form normally
it('submits form successfully', () => {
  cy.visit('/your-form');
  cy.get('form').submit();
  // Turnstile will automatically pass verification
});

まとめ

Turnstile のテスト用認証情報と適切な環境判定を組み合わせると、本番のセキュリティを保ったまま、信頼性の高い E2E テストを作れます。テスト用の認証情報は本番と必ず分け、デプロイ手順にも適切な安全対策を入れてください。