431 lines
10 KiB
Markdown
431 lines
10 KiB
Markdown
# Turnstile Testing Guide
|
|
|
|
**Complete testing strategies for E2E, unit, and integration tests**
|
|
|
|
**Official Docs**: https://developers.cloudflare.com/turnstile/troubleshooting/testing/
|
|
|
|
---
|
|
|
|
## Quick Reference: Dummy Credentials
|
|
|
|
### Sitekeys (Client-Side)
|
|
```typescript
|
|
const TEST_SITEKEYS = {
|
|
ALWAYS_PASS: '1x00000000000000000000AA', // Visible, always passes
|
|
ALWAYS_BLOCK: '2x00000000000000000000AB', // Visible, always blocks
|
|
ALWAYS_PASS_INVISIBLE: '1x00000000000000000000BB', // Invisible, always passes
|
|
ALWAYS_BLOCK_INVISIBLE: '2x00000000000000000000BB',// Invisible, always blocks
|
|
FORCE_INTERACTIVE: '3x00000000000000000000FF', // Visible, forces checkbox
|
|
}
|
|
```
|
|
|
|
### Secret Keys (Server-Side)
|
|
```typescript
|
|
const TEST_SECRET_KEYS = {
|
|
ALWAYS_PASS: '1x0000000000000000000000000000000AA', // success: true
|
|
ALWAYS_FAIL: '2x0000000000000000000000000000000AA', // success: false
|
|
TOKEN_SPENT: '3x0000000000000000000000000000000AA', // "already spent" error
|
|
}
|
|
```
|
|
|
|
### Dummy Token
|
|
```typescript
|
|
const DUMMY_TOKEN = 'XXXX.DUMMY.TOKEN.XXXX'
|
|
```
|
|
|
|
**CRITICAL**:
|
|
- Dummy sitekeys generate `XXXX.DUMMY.TOKEN.XXXX`
|
|
- Dummy secret keys ONLY accept dummy token
|
|
- Production secret keys REJECT dummy token
|
|
- Real tokens FAIL with dummy secret keys
|
|
|
|
---
|
|
|
|
## Environment Detection Patterns
|
|
|
|
### Pattern 1: Request Headers
|
|
```typescript
|
|
function isTestEnvironment(request: Request): boolean {
|
|
return request.headers.get('x-test-environment') === 'true'
|
|
}
|
|
|
|
// Usage in Cloudflare Worker
|
|
if (isTestEnvironment(request)) {
|
|
secretKey = TEST_SECRET_KEYS.ALWAYS_PASS
|
|
}
|
|
```
|
|
|
|
### Pattern 2: IP Address
|
|
```typescript
|
|
function isTestEnvironment(request: Request): boolean {
|
|
const ip = request.headers.get('CF-Connecting-IP') || ''
|
|
const testIPs = ['127.0.0.1', '::1', 'localhost']
|
|
return testIPs.includes(ip)
|
|
}
|
|
```
|
|
|
|
### Pattern 3: Query Parameter
|
|
```typescript
|
|
function isTestEnvironment(request: Request): boolean {
|
|
const url = new URL(request.url)
|
|
return url.searchParams.get('test') === 'true'
|
|
}
|
|
```
|
|
|
|
### Pattern 4: Environment Variable
|
|
```typescript
|
|
const sitekey = process.env.NODE_ENV === 'test'
|
|
? TEST_SITEKEYS.ALWAYS_PASS
|
|
: process.env.TURNSTILE_SITE_KEY
|
|
```
|
|
|
|
---
|
|
|
|
## Playwright Testing
|
|
|
|
### Setup
|
|
```typescript
|
|
// playwright.config.ts
|
|
export default defineConfig({
|
|
use: {
|
|
baseURL: 'http://localhost:5173',
|
|
extraHTTPHeaders: {
|
|
'x-test-environment': 'true', // Auto-use test credentials
|
|
},
|
|
},
|
|
})
|
|
```
|
|
|
|
### Basic Test
|
|
```typescript
|
|
// tests/contact-form.spec.ts
|
|
import { test, expect } from '@playwright/test'
|
|
|
|
test('submits contact form with Turnstile', async ({ page }) => {
|
|
await page.goto('/contact')
|
|
|
|
// Fill form
|
|
await page.fill('input[name="email"]', 'test@example.com')
|
|
await page.fill('textarea[name="message"]', 'Test message')
|
|
|
|
// Turnstile auto-solves with dummy token in test mode
|
|
await page.click('button[type="submit"]')
|
|
|
|
// Verify success
|
|
await expect(page.locator('.success-message')).toBeVisible()
|
|
})
|
|
```
|
|
|
|
### Advanced: Multiple Scenarios
|
|
```typescript
|
|
test('handles Turnstile failure gracefully', async ({ page, context }) => {
|
|
// Override to use "always fail" sitekey
|
|
await context.route('**/api.js', route => {
|
|
const FAIL_SITEKEY = '2x00000000000000000000AB'
|
|
// Inject failing sitekey
|
|
route.continue()
|
|
})
|
|
|
|
await page.goto('/contact')
|
|
await page.fill('input[name="email"]', 'test@example.com')
|
|
await page.click('button[type="submit"]')
|
|
|
|
await expect(page.locator('.error-message')).toContainText('verification failed')
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Cypress Testing
|
|
|
|
### Setup
|
|
```typescript
|
|
// cypress.config.ts
|
|
export default defineConfig({
|
|
e2e: {
|
|
baseUrl: 'http://localhost:5173',
|
|
setupNodeEvents(on, config) {
|
|
// Set test header on all requests
|
|
on('before:browser:launch', (browser, launchOptions) => {
|
|
launchOptions.args.push('--disable-web-security')
|
|
return launchOptions
|
|
})
|
|
},
|
|
},
|
|
})
|
|
```
|
|
|
|
### Test Example
|
|
```typescript
|
|
// cypress/e2e/turnstile.cy.ts
|
|
describe('Turnstile Form', () => {
|
|
beforeEach(() => {
|
|
cy.intercept('**/*', (req) => {
|
|
req.headers['x-test-environment'] = 'true'
|
|
})
|
|
})
|
|
|
|
it('submits form successfully', () => {
|
|
cy.visit('/contact')
|
|
|
|
cy.get('input[name="email"]').type('test@example.com')
|
|
cy.get('textarea[name="message"]').type('Test message')
|
|
|
|
// Turnstile auto-solves in test mode
|
|
cy.get('button[type="submit"]').click()
|
|
|
|
cy.contains('Success').should('be.visible')
|
|
})
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Jest / Vitest (React)
|
|
|
|
### Mock @marsidev/react-turnstile
|
|
```typescript
|
|
// jest.setup.ts or vitest.setup.ts
|
|
import React from 'react'
|
|
|
|
jest.mock('@marsidev/react-turnstile', () => ({
|
|
Turnstile: ({ onSuccess }: { onSuccess: (token: string) => void }) => {
|
|
// Auto-solve with dummy token
|
|
React.useEffect(() => {
|
|
onSuccess('XXXX.DUMMY.TOKEN.XXXX')
|
|
}, [onSuccess])
|
|
|
|
return <div data-testid="turnstile-mock" />
|
|
},
|
|
}))
|
|
```
|
|
|
|
### Component Test
|
|
```typescript
|
|
// ContactForm.test.tsx
|
|
import { render, screen, fireEvent, waitFor } from '@testing-library/react'
|
|
import { ContactForm } from './ContactForm'
|
|
|
|
test('submits form with Turnstile', async () => {
|
|
render(<ContactForm />)
|
|
|
|
fireEvent.change(screen.getByLabelText('Email'), {
|
|
target: { value: 'test@example.com' },
|
|
})
|
|
|
|
fireEvent.change(screen.getByLabelText('Message'), {
|
|
target: { value: 'Test message' },
|
|
})
|
|
|
|
// Turnstile auto-solves (mocked)
|
|
const submitButton = screen.getByRole('button', { name: 'Submit' })
|
|
expect(submitButton).not.toBeDisabled()
|
|
|
|
fireEvent.click(submitButton)
|
|
|
|
await waitFor(() => {
|
|
expect(screen.getByText('Success')).toBeInTheDocument()
|
|
})
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Server-Side Testing (Vitest)
|
|
|
|
### Validate Dummy Token
|
|
```typescript
|
|
// server.test.ts
|
|
import { describe, it, expect } from 'vitest'
|
|
import { validateTurnstile } from './turnstile-server-validation'
|
|
import { TEST_SECRET_KEYS, DUMMY_TOKEN } from './turnstile-test-config'
|
|
|
|
describe('Turnstile Validation', () => {
|
|
it('validates dummy token with test secret', async () => {
|
|
const result = await validateTurnstile(
|
|
DUMMY_TOKEN,
|
|
TEST_SECRET_KEYS.ALWAYS_PASS
|
|
)
|
|
|
|
expect(result.success).toBe(true)
|
|
})
|
|
|
|
it('rejects real token with test secret', async () => {
|
|
const realToken = 'real-production-token'
|
|
|
|
const result = await validateTurnstile(
|
|
realToken,
|
|
TEST_SECRET_KEYS.ALWAYS_PASS
|
|
)
|
|
|
|
expect(result.success).toBe(false)
|
|
})
|
|
|
|
it('handles always-fail secret key', async () => {
|
|
const result = await validateTurnstile(
|
|
DUMMY_TOKEN,
|
|
TEST_SECRET_KEYS.ALWAYS_FAIL
|
|
)
|
|
|
|
expect(result.success).toBe(false)
|
|
})
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Cloudflare Workers Testing (Miniflare)
|
|
|
|
### Setup
|
|
```typescript
|
|
// vitest.config.ts
|
|
import { defineConfig } from 'vitest/config'
|
|
|
|
export default defineConfig({
|
|
test: {
|
|
environment: 'miniflare',
|
|
environmentOptions: {
|
|
bindings: {
|
|
TURNSTILE_SECRET_KEY: '1x0000000000000000000000000000000AA',
|
|
TURNSTILE_SITE_KEY: '1x00000000000000000000AA',
|
|
},
|
|
},
|
|
},
|
|
})
|
|
```
|
|
|
|
### Worker Test
|
|
```typescript
|
|
// worker.test.ts
|
|
import { env, createExecutionContext, waitOnExecutionContext } from 'cloudflare:test'
|
|
import { describe, it, expect } from 'vitest'
|
|
import worker from '../src/index'
|
|
import { DUMMY_TOKEN } from './turnstile-test-config'
|
|
|
|
describe('Worker with Turnstile', () => {
|
|
it('validates test token successfully', async () => {
|
|
const formData = new FormData()
|
|
formData.append('email', 'test@example.com')
|
|
formData.append('cf-turnstile-response', DUMMY_TOKEN)
|
|
|
|
const request = new Request('http://localhost/api/contact', {
|
|
method: 'POST',
|
|
body: formData,
|
|
headers: {
|
|
'x-test-environment': 'true',
|
|
},
|
|
})
|
|
|
|
const ctx = createExecutionContext()
|
|
const response = await worker.fetch(request, env, ctx)
|
|
await waitOnExecutionContext(ctx)
|
|
|
|
expect(response.status).toBe(200)
|
|
})
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## CI/CD Configuration
|
|
|
|
### GitHub Actions
|
|
```yaml
|
|
# .github/workflows/test.yml
|
|
name: Test
|
|
|
|
on: [push, pull_request]
|
|
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
|
|
- name: Setup Node
|
|
uses: actions/setup-node@v3
|
|
with:
|
|
node-version: '20'
|
|
|
|
- name: Install dependencies
|
|
run: npm ci
|
|
|
|
- name: Run tests
|
|
env:
|
|
TURNSTILE_SITE_KEY: 1x00000000000000000000AA
|
|
TURNSTILE_SECRET_KEY: 1x0000000000000000000000000000000AA
|
|
NODE_ENV: test
|
|
run: npm test
|
|
```
|
|
|
|
### GitLab CI
|
|
```yaml
|
|
# .gitlab-ci.yml
|
|
test:
|
|
image: node:20
|
|
script:
|
|
- npm ci
|
|
- npm test
|
|
variables:
|
|
TURNSTILE_SITE_KEY: "1x00000000000000000000AA"
|
|
TURNSTILE_SECRET_KEY: "1x0000000000000000000000000000000AA"
|
|
NODE_ENV: "test"
|
|
```
|
|
|
|
---
|
|
|
|
## Testing Best Practices
|
|
|
|
✅ **Always use dummy keys** - Never use production credentials in tests
|
|
✅ **Test both success and failure** - Use both pass and fail test keys
|
|
✅ **Mock in unit tests** - Mock Turnstile component for fast unit tests
|
|
✅ **E2E with real widget** - Use test sitekeys in E2E tests
|
|
✅ **Separate environments** - Different config for test/dev/staging/prod
|
|
✅ **Test expiration** - Verify token expiration handling
|
|
✅ **Test error states** - Validate error callback behavior
|
|
|
|
❌ **Never commit production keys** - Use environment variables
|
|
❌ **Don't skip server validation tests** - Critical security component
|
|
❌ **Don't test with production sitekeys** - Can trigger rate limits
|
|
❌ **Don't hardcode test keys** - Use constants/config files
|
|
|
|
---
|
|
|
|
## Debugging Tests
|
|
|
|
### Enable Verbose Logging
|
|
```typescript
|
|
turnstile.render('#container', {
|
|
sitekey: TEST_SITEKEYS.ALWAYS_PASS,
|
|
callback: (token) => console.log('[TEST] Token:', token),
|
|
'error-callback': (error) => console.error('[TEST] Error:', error),
|
|
'expired-callback': () => console.warn('[TEST] Token expired'),
|
|
})
|
|
```
|
|
|
|
### Check Network Requests
|
|
```typescript
|
|
// Playwright
|
|
await page.route('**/siteverify', route => {
|
|
console.log('Siteverify called with:', route.request().postData())
|
|
route.continue()
|
|
})
|
|
```
|
|
|
|
### Verify Environment Detection
|
|
```typescript
|
|
test('uses test credentials in test env', async ({ page }) => {
|
|
const response = await page.evaluate(() => {
|
|
return document.querySelector('.cf-turnstile')?.getAttribute('data-sitekey')
|
|
})
|
|
|
|
expect(response).toBe('1x00000000000000000000AA')
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-10-22
|
|
**Test Framework Support**: Playwright, Cypress, Jest, Vitest, Miniflare
|