在端到端 (E2E) 测试中排除 Turnstile

本教程说明如何通过使用 Turnstile 的专用测试密钥，在端到端 (E2E) 测试中处理 Turnstile。

概述

运行 E2E 测试时，您通常希望绕过或简化 Turnstile 验证过程。Cloudflare 提供了始终能通过验证的官方测试凭证，非常适合测试环境：

测试 sitekey：1x00000000000000000000AA
测试密匙 (secret key)：1x0000000000000000000000000000000AA

更多详情请参阅测试文档。

实施

实施测试环境检测的关键是在服务器端识别测试请求。以下是一个简单的方法：

// 使用 IP 地址或请求头检测测试环境
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;
}

// 根据环境使用相应的凭证
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、请求头等）。
- 如果您需要从公共网络进行测试，请确保测试环境标识符的安全。
凭证管理
- 安全地存储生产环境凭证（例如，在环境变量中）。
- 切勿将凭证提交到版本控制中。
- 为每个环境使用不同的凭证。
部署安全性
- 添加检查以防止测试凭证混入生产环境。
- 在您的 CI/CD 流水线中包含凭证验证。
- 监控意外的测试凭证使用情况。

测试注意事项

测试凭证将始终通过验证。
它们非常适合自动化测试环境。
它们有助于避免测试期间的速率限制。
它们使测试更具可预测性且速度更快。

测试设置示例

对于 Cypress 或类似的 E2E 测试框架：

// 为所有测试请求设置测试请求头
beforeEach(() => {
  cy.intercept('*', (req) => {
    req.headers['x-test-environment'] = 'secret-token';
  });
});

// 您的测试现在可以正常与表单进行交互
it('submits form successfully', () => {
  cy.visit('/your-form');
  cy.get('form').submit();
  // Turnstile 将自动通过验证
});

结论

通过使用 Turnstile 的测试凭证和适当的环境检测，您可以在保持生产环境安全的同时创建可靠的 E2E 测试。请记住，始终将测试凭证与生产环境隔离开来，并在部署流程中实施适当的防护措施。