try-works/role-model / .agents/skills/turnstile-spin
turnstile-spin
VerifiedSet up Cloudflare Turnstile end-to-end in a project — scan the codebase, create the widget via the Cloudflare API, deploy the managed siteverify Worker, write the frontend snippets, validate, and persist the skill. Load this when a user asks to add Turnstile, set up CAPTCHA, protect a form from bots, or fix a Turnstile integration. Mirrors developers.cloudflare.com/turnstile/spin.
templates/worker/test/validation.test.ts
View on GitHub/**
* tests/4 — Validation surface.
*
* Tests the endpoints that Turnstile Spin's wizard relies on during its
* post-deploy validation step:
*
* - GET /health returns {ok: true, version}
* - GET / returns the same shape
* - POST / with dummy returns a structured error (success: false, error-codes,
* _worker metadata) rather than a bare 500
* - hostname mismatch when EXPECTED_HOSTNAME is set
*
* These match the assertions in the wizard's Step 7. If any of these fail,
* the wizard's validation step will fail, and the customer will see a
* misleading "setup complete" message followed by a broken integration.
*/
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
import worker, { WORKER_VERSION } from '../src/index.js';
import type { Env } from '../src/types.js';
const ENV: Env = {
TURNSTILE_SECRET_KEY: 'test-secret-key',
ALLOWED_ORIGIN: '*',
};
describe('validation surface — /health', () => {
it('returns ok:true and a semver version', async () => {
const res = await worker.fetch(new Request('https://w/health'), ENV);
expect(res.status).toBe(200);
const body = (await res.json()) as { ok: boolean; version: string };
expect(body.ok).toBe(true);
expect(body.version).toMatch(/^\d+\.\d+\.\d+$/);
expect(body.version).toBe(WORKER_VERSION);
});
it('GET / returns the same shape as /health', async () => {
const [a, b] = await Promise.all([
worker.fetch(new Request('https://w/'), ENV),
worker.fetch(new Request('https://w/health'), ENV),
]);
const ja = (await a.json()) as { ok: boolean; version: string };
const jb = (await b.json()) as { ok: boolean; version: string };
expect(ja.ok).toBe(jb.ok);
expect(ja.version).toBe(jb.version);
});
it('responds in well under the wizard timeout (1s)', async () => {
const start = Date.now();
await worker.fetch(new Request('https://w/health'), ENV);
expect(Date.now() - start).toBeLessThan(1000);
});
});
describe('validation surface — dummy siteverify returns structured error', () => {
beforeEach(() => vi.restoreAllMocks());
afterEach(() => vi.restoreAllMocks());
it('returns success:false + error-codes + _worker for a dummy token', async () => {
vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async () => {
return new Response(
JSON.stringify({ success: false, 'error-codes': ['invalid-input-response'] }),
{ status: 200 },
);
});
const res = await worker.fetch(
new Request('https://w/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token: 'XXXX.DUMMY.TOKEN.XXXX' }),
}),
ENV,
);
expect(res.status).toBe(200);
const body = (await res.json()) as {
success: boolean;
'error-codes': string[];
_worker?: { duration_ms: number; worker_version: string };
};
// Wizard's required assertions:
expect(body.success).toBe(false);
expect(Array.isArray(body['error-codes'])).toBe(true);
expect(body['error-codes'].length).toBeGreaterThan(0);
expect(body._worker).toBeDefined();
expect(typeof body._worker?.duration_ms).toBe('number');
expect(body._worker?.worker_version).toBe(WORKER_VERSION);
});
it('returns structured error on Worker-level failure (no bare 500)', async () => {
// Force the upstream to be unreachable.
vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async () => {
throw new TypeError('network unreachable');
});
// Disable the retry loop by also failing the second attempt.
vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async () => {
throw new TypeError('network unreachable');
});
const res = await worker.fetch(
new Request('https://w/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token: 'whatever' }),
}),
ENV,
);
// Worker-level failure still returns a *parseable* error body.
const body = (await res.json()) as { success: boolean; 'error-codes': string[]; _worker?: unknown };
expect(body.success).toBe(false);
expect(body['error-codes'][0]).toBe('upstream-unreachable');
expect(body._worker).toBeDefined();
});
});
describe('validation surface — hostname mismatch', () => {
beforeEach(() => vi.restoreAllMocks());
afterEach(() => vi.restoreAllMocks());
it('rejects success when EXPECTED_HOSTNAME does not match', async () => {
vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async () => {
return new Response(
JSON.stringify({ success: true, hostname: 'attacker.example.com', 'error-codes': [] }),
{ status: 200 },
);
});
const env: Env = { ...ENV, EXPECTED_HOSTNAME: 'www.example.com' };
const res = await worker.fetch(
new Request('https://w/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token: 'abc' }),
}),
env,
);
const body = (await res.json()) as { success: boolean; 'error-codes': string[] };
expect(body.success).toBe(false);
expect(body['error-codes']).toContain('hostname-mismatch');
});
});
describe('validation surface — telemetry marker passthrough', () => {
beforeEach(() => vi.restoreAllMocks());
afterEach(() => vi.restoreAllMocks());
it('passes data-action through to siteverify and surfaces it in the response', async () => {
// Upstream echoes the action field. Spin marker should survive.
vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async () => {
return new Response(
JSON.stringify({
success: true,
hostname: 'example.com',
action: 'turnstile-spin-v1',
'error-codes': [],
}),
{ status: 200 },
);
});
const res = await worker.fetch(
new Request('https://w/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token: 'abc' }),
}),
ENV,
);
const body = (await res.json()) as { success: boolean; action?: string };
expect(body.success).toBe(true);
expect(body.action).toBe('turnstile-spin-v1');
});
});
describe('validation surface — post-deploy form is reachable', () => {
it('GET /post-deploy returns 404 when ASSETS binding is missing (test env)', async () => {
// In the unit-test env we don't have the ASSETS binding wired, so the
// handler falls through. The real Worker has the binding from wrangler.toml.
const res = await worker.fetch(new Request('https://w/post-deploy'), ENV);
expect(res.status).toBe(404);
});
it('GET /post-deploy serves the HTML file when ASSETS is bound', async () => {
const html = '<!doctype html><title>Post-deploy</title>';
const mockAssets: Fetcher = {
fetch: async () =>
new Response(html, { status: 200, headers: { 'Content-Type': 'text/html' } }),
} as unknown as Fetcher;
const envWithAssets: Env = { ...ENV, ASSETS: mockAssets };
const res = await worker.fetch(new Request('https://w/post-deploy'), envWithAssets);
expect(res.status).toBe(200);
expect(await res.text()).toContain('Post-deploy');
});
});
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |