Skip to content

secondsky/claude-skills / plugins/cloudflare-turnstile/skills/cloudflare-turnstile

cloudflare-turnstile

Verified

This skill should be used when the user asks to "add turnstile", "implement bot protection", "validate turnstile token", "fix turnstile error", "setup captcha alternative", or encounters error codes 100*/300*/600*, CSP errors, or token validation failures. Provides CAPTCHA-alternative protection for Cloudflare Workers, React, Next.js, and Hono.

references/testing-guide.md

View on GitHub
# 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@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall