How to Test reCAPTCHA v3 with Playwright: Complete 2026 Guide

Goal

Submit a contact form and assert that the POST request includes a non-empty g-recaptcha-response field.

Playwright Implementation

import { test, expect } from '@playwright/test';

test('contact form sends reCAPTCHA token in POST body', async ({ page }) => {
  const formRequestPromise = page.waitForRequest(
    (req) => req.url().includes('/api/contact') && req.method() === 'POST'
  );

  await page.goto('/contact');
  await page.waitForFunction(() => {
    return typeof (window as any).grecaptcha !== 'undefined'
      && typeof (window as any).grecaptcha.execute === 'function';
  }, { timeout: 10_000 });

  await page.getByLabel('Name').fill('Test User');
  await page.getByLabel('Email').fill('test@assrt.ai');
  await page.getByLabel('Message').fill('This is an automated test.');
  await page.getByRole('button', { name: /send|submit/i }).click();

  const formRequest = await formRequestPromise;
  const body = formRequest.postDataJSON();

  expect(body['g-recaptcha-response']).toBeTruthy();
  expect(typeof body['g-recaptcha-response']).toBe('string');
  expect(body['g-recaptcha-response'].length).toBeGreaterThan(10);
});

Goal

Using Google test keys, submit a form, verify the token with your server, and confirm the server accepts the submission because Google returns a score of 1.0.

Playwright Implementation

test('test keys: form submission succeeds with score 1.0', async ({ page, request }) => {
  await page.goto('/contact');

  // Confirm the page loaded with the test site key
  const siteKey = await page.evaluate(() => {
    const script = document.querySelector('script[src*="recaptcha"]');
    return script?.getAttribute('src') || '';
  });
  expect(siteKey).toContain('6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI');

  // Wait for grecaptcha to be ready
  await page.waitForFunction(() => {
    return typeof (window as any).grecaptcha !== 'undefined';
  });

  // Fill and submit the form
  await page.getByLabel('Name').fill('Test User');
  await page.getByLabel('Email').fill('testkeys@assrt.ai');
  await page.getByLabel('Message').fill('Testing with Google test keys.');
  await page.getByRole('button', { name: /send|submit/i }).click();

  // Assert successful submission (your server verified with test secret)
  await expect(page.getByText(/thank you|message sent|success/i))
    .toBeVisible({ timeout: 10_000 });

  // Optionally verify via your API that the score was recorded
  const res = await request.get('/api/contact/last?email=testkeys@assrt.ai');
  const data = await res.json();
  expect(data.recaptchaScore).toBe(1.0);
});

Assrt Equivalent

# scenarios/recaptcha-test-keys-pass.assrt
describe: Form submission succeeds with Google test keys

given:
  - I am on the contact page
  - the app is configured with Google reCAPTCHA test keys

steps:
  - fill in Name with "Test User"
  - fill in Email with "testkeys@assrt.ai"
  - fill in Message with "Testing with Google test keys."
  - click "Send"

expect:
  - the page shows a success message
  - the server recorded a reCAPTCHA score of 1.0

Goal

Simulate a reCAPTCHA score of 0.1 (bot) and verify your server rejects the form submission with an appropriate error message.

Playwright Implementation

test('low score: server rejects submission when score is 0.1', async ({ page }) => {
  // Your server should support a test header or env var that overrides
  // the reCAPTCHA verification response for testing purposes.
  // Option A: Use a custom header to tell your server to mock the score.
  await page.setExtraHTTPHeaders({
    'X-Recaptcha-Test-Score': '0.1',
  });

  await page.goto('/contact');

  await page.waitForFunction(() => {
    return typeof (window as any).grecaptcha !== 'undefined';
  });

  await page.getByLabel('Name').fill('Bot User');
  await page.getByLabel('Email').fill('bot@assrt.ai');
  await page.getByLabel('Message').fill('I am definitely not a bot.');
  await page.getByRole('button', { name: /send|submit/i }).click();

  // Assert the server rejected the submission
  await expect(page.getByText(/suspicious activity|verification failed|try again/i))
    .toBeVisible({ timeout: 10_000 });

  // Verify the form is still visible (user can retry)
  await expect(page.getByLabel('Message')).toBeVisible();
});

// Option B: Mock at the API level using Playwright's request interception
test('low score via API mock: server returns 403', async ({ page }) => {
  // Intercept your own server's contact endpoint to simulate the 403
  await page.route('**/api/contact', async (route) => {
    const request = route.request();
    if (request.method() === 'POST') {
      // Forward the request but override the response
      const response = await route.fetch();
      const status = response.status();

      // If your server returns 403 for low scores, verify that behavior
      // by mocking the verification endpoint your server calls
      await route.fulfill({
        status: 403,
        contentType: 'application/json',
        body: JSON.stringify({
          error: 'reCAPTCHA verification failed',
          score: 0.1,
        }),
      });
    }
  });

  await page.goto('/contact');
  await page.waitForFunction(() => typeof (window as any).grecaptcha !== 'undefined');

  await page.getByLabel('Name').fill('Bot User');
  await page.getByLabel('Email').fill('bot2@assrt.ai');
  await page.getByLabel('Message').fill('Testing low score rejection.');
  await page.getByRole('button', { name: /send|submit/i }).click();

  await expect(page.getByText(/verification failed|try again/i))
    .toBeVisible({ timeout: 10_000 });
});

Assrt Equivalent

# scenarios/recaptcha-low-score.assrt
describe: Server rejects form submission when reCAPTCHA score is low

given:
  - I am on the contact page
  - the reCAPTCHA verification is mocked to return score 0.1

steps:
  - fill in Name with "Bot User"
  - fill in Email with "bot@assrt.ai"
  - fill in Message with "I am definitely not a bot."
  - click "Send"

expect:
  - the page shows a verification failed error
  - the form is still visible so the user can retry

Goal

Block the reCAPTCHA script from loading and verify the form still submits (or shows a meaningful fallback message).

Playwright Implementation

Assrt Equivalent

# scenarios/recaptcha-blocked.assrt
describe: Form degrades gracefully when reCAPTCHA script is blocked

given:
  - all requests to google.com/recaptcha are blocked
  - I am on the contact page

steps:
  - fill in Name with "Blocked User"
  - fill in Email with "blocked@assrt.ai"
  - fill in Message with "reCAPTCHA could not load."
  - click "Send"

expect:
  - the page shows either a success message or a clear explanation
  - the page does not show an unhandled JavaScript error

Goal

Capture the outgoing form request, validate the token format, and verify that the request includes all expected fields alongside the reCAPTCHA response.

Playwright Implementation

test('form POST includes valid reCAPTCHA token and all fields', async ({ page }) => {
  const requests: Array<{ url: string; body: any; headers: Record<string, string> }> = [];

  // Listen to all outgoing requests to your API
  page.on('request', (req) => {
    if (req.url().includes('/api/contact') && req.method() === 'POST') {
      requests.push({
        url: req.url(),
        body: req.postDataJSON(),
        headers: req.headers(),
      });
    }
  });

  await page.goto('/contact');
  await page.waitForFunction(() => typeof (window as any).grecaptcha !== 'undefined');

  await page.getByLabel('Name').fill('Network Test');
  await page.getByLabel('Email').fill('network@assrt.ai');
  await page.getByLabel('Message').fill('Verifying request shape.');
  await page.getByRole('button', { name: /send|submit/i }).click();

  // Wait for the request to be captured
  await expect.poll(() => requests.length, { timeout: 10_000 }).toBeGreaterThan(0);

  const req = requests[0];

  // Verify content type
  expect(req.headers['content-type']).toContain('application/json');

  // Verify all form fields are present
  expect(req.body.name).toBe('Network Test');
  expect(req.body.email).toBe('network@assrt.ai');
  expect(req.body.message).toBe('Verifying request shape.');

  // Verify reCAPTCHA token format
  const token = req.body['g-recaptcha-response'];
  expect(token).toBeTruthy();
  expect(typeof token).toBe('string');
  // reCAPTCHA tokens are typically 400+ characters
  expect(token.length).toBeGreaterThan(100);
});

Assrt Equivalent

# scenarios/recaptcha-request-shape.assrt
describe: Form POST includes valid reCAPTCHA token and all fields

given:
  - I am on the contact page
  - reCAPTCHA has loaded

steps:
  - fill in Name with "Network Test"
  - fill in Email with "network@assrt.ai"
  - fill in Message with "Verifying request shape."
  - click "Send"

expect:
  - the POST to /api/contact has content-type application/json
  - the body includes name, email, and message fields
  - the body includes g-recaptcha-response as a string longer than 100 characters

Goal

On a page with multiple forms (or across multiple routes), verify each form sends the correct reCAPTCHA action name in its request.

Playwright Implementation

const actionScenarios = [
  {
    route: '/login',
    action: 'login',
    fill: async (page: any) => {
      await page.getByLabel('Email').fill('action@assrt.ai');
      await page.getByLabel('Password').fill('TestPass123!');
    },
    submitLabel: /log in|sign in/i,
    apiEndpoint: '/api/auth/login',
  },
  {
    route: '/signup',
    action: 'signup',
    fill: async (page: any) => {
      await page.getByLabel('Email').fill('action@assrt.ai');
      await page.getByLabel('Password').fill('TestPass123!');
      await page.getByLabel('Confirm password').fill('TestPass123!');
    },
    submitLabel: /sign up|create account/i,
    apiEndpoint: '/api/auth/signup',
  },
  {
    route: '/contact',
    action: 'contact',
    fill: async (page: any) => {
      await page.getByLabel('Name').fill('Action Test');
      await page.getByLabel('Email').fill('action@assrt.ai');
      await page.getByLabel('Message').fill('Testing action names.');
    },
    submitLabel: /send|submit/i,
    apiEndpoint: '/api/contact',
  },
];

for (const scenario of actionScenarios) {
  test(`reCAPTCHA action is "${scenario.action}" on ${scenario.route}`, async ({ page }) => {
    const requestPromise = page.waitForRequest(
      (req: any) => req.url().includes(scenario.apiEndpoint) && req.method() === 'POST'
    );

    await page.goto(scenario.route);
    await page.waitForFunction(() => typeof (window as any).grecaptcha !== 'undefined');

    await scenario.fill(page);
    await page.getByRole('button', { name: scenario.submitLabel }).click();

    const req = await requestPromise;
    const body = req.postDataJSON();

    // Verify the action name matches what the server expects
    expect(body['recaptcha_action'] || body['action']).toBe(scenario.action);

    // Also verify the token is present
    expect(body['g-recaptcha-response']).toBeTruthy();
  });
}

Assrt Equivalent

# scenarios/recaptcha-multi-action.assrt
describe: Each form sends the correct reCAPTCHA action name

scenarios:
  - route: /login
    action: login
    steps:
      - fill in Email and Password
      - click "Log in"
    expect:
      - the POST to /api/auth/login includes recaptcha_action "login"

  - route: /signup
    action: signup
    steps:
      - fill in Email, Password, and Confirm password
      - click "Sign up"
    expect:
      - the POST to /api/auth/signup includes recaptcha_action "signup"

  - route: /contact
    action: contact
    steps:
      - fill in Name, Email, and Message
      - click "Send"
    expect:
      - the POST to /api/contact includes recaptcha_action "contact"