ScreenshotNeo
Sign in Get a free key

BlogHow-to

How to Test Stripe Elements with Cypress

Test Stripe Elements reliably with Cypress by respecting cross-origin limits, simulating outcomes, and using Stripe test values for integration checks.

By the ScreenshotNeo team1 October 20269 min read

Direct answer: treat Stripe Elements as an externally hosted payment UI. Cypress cannot communicate with Stripe’s cross-origin iframe under its documented default behavior, so do not build tests around typing into Stripe fields from Cypress. Use Cypress to verify your page, your submit flow, and your success and error states. Use Stripe’s test environment and documented test values for integration coverage, and simulate representative payment outcomes for deterministic application tests.

This boundary applies to Stripe Payment Element integrations and other Stripe Elements forms rendered in an iframe. Cypress documents cross-origin iframe access as unsupported; cy.origin() handles top-level navigation to another origin and does not unlock commands inside an iframe.

What your Cypress tests should prove

  1. Your checkout page renders the payment area and the controls your application owns.
  2. Your application enables or disables submission at the correct time.
  3. Submitting your form calls your own payment endpoint with the expected order or cart data.
  4. Your UI displays the correct success, decline, validation, and recovery states.
  5. Your server creates or confirms the intended Stripe object in test mode.

Do not select or type into fields inside Stripe’s cross-origin document. Those assertions would test an implementation Cypress cannot reach and will fail or become browser-specific.

A maintainable test layout

1. Keep selectors on your application

Use stable selectors such as data-cy on your checkout form, submit button, status region, and retry control. Avoid selectors that depend on Stripe’s generated iframe names, field markup, or internal classes.

describe('checkout payment flow', () => {
  beforeEach(() => {
    cy.visit('/checkout');
  });

  it('renders the payment area and keeps submit disabled until ready', () => {
    cy.get('[data-cy=payment-element]').should('be.visible');
    cy.get('[data-cy=pay-button]').should('be.disabled');

    // Your application should enable this after Elements reports readiness.
    cy.get('[data-cy=payment-element]').trigger('payment-ready');
    cy.get('[data-cy=pay-button]').should('be.enabled');
  });
});

The exact readiness event depends on your integration. Assert the state transition exposed by your own component rather than an event emitted by Stripe’s iframe.

2. Stub your application payment endpoint for UI tests

For deterministic success and error tests, intercept the request from your checkout page to your own backend. Return the application response shape your frontend consumes.

describe('checkout result states', () => {
  beforeEach(() => {
    cy.visit('/checkout');
  });

  it('shows a confirmation after a successful payment', () => {
    cy.intercept('POST', '/api/payments/confirm', {
      statusCode: 200,
      body: { status: 'succeeded', orderId: 'order_test_123' }
    }).as('confirmPayment');

    cy.get('[data-cy=payment-element]').trigger('payment-ready');
    cy.get('[data-cy=pay-button]').click();
    cy.wait('@confirmPayment').its('request.body').should('include', {
      cartId: 'cart_test_123'
    });
    cy.get('[data-cy=payment-success]').should('contain', 'Payment complete');
  });

  it('shows a decline and allows retry', () => {
    cy.intercept('POST', '/api/payments/confirm', {
      statusCode: 402,
      body: {
        error: {
          type: 'card_error',
          code: 'card_declined',
          message: 'Your card was declined.'
        }
      }
    }).as('confirmPayment');

    cy.get('[data-cy=payment-element]').trigger('payment-ready');
    cy.get('[data-cy=pay-button]').click();
    cy.wait('@confirmPayment');
    cy.get('[data-cy=payment-error]').should('contain', 'declined');
    cy.get('[data-cy=retry-button]').should('be.visible');
  });
});

The intercepted response should match the contract between your backend and frontend. Keep the object representative of the Stripe error shape your code handles; a mock proves your application branch, not that Stripe’s hosted UI rendered or accepted input.

3. Test loading, validation, and cancellation branches

it('prevents duplicate submits while confirmation is pending', () => {
  cy.intercept('POST', '/api/payments/confirm', (request) => {
    request.reply({
      delay: 1200,
      statusCode: 200,
      body: { status: 'succeeded', orderId: 'order_test_456' }
    });
  }).as('confirmPayment');

  cy.get('[data-cy=payment-element]').trigger('payment-ready');
  cy.get('[data-cy=pay-button]').click().should('be.disabled');
  cy.get('[data-cy=pay-button]').click();
  cy.wait('@confirmPayment');
  cy.get('[data-cy=payment-success]').should('be.visible');
});

Add cases for an empty cart, expired session, network failure, server error, user cancellation, and a second click while confirmation is pending. These are application behaviors and remain fully testable without entering the iframe.

Simulate Stripe outcomes instead of invoking Stripe for every error test

Stripe’s automated testing guidance recommends recording a representative error object and returning it in a test when you need to exercise an error branch. This keeps tests fast and repeatable.

// cypress/fixtures/payment-declined.json
{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "decline_code": "generic_decline"
  }
}

// cypress/e2e/decline.cy.js
it('renders the declined-payment recovery path', () => {
  cy.fixture('payment-declined').then((body) => {
    cy.intercept('POST', '/api/payments/confirm', {
      statusCode: 402,
      body
    }).as('confirmPayment');
  });

  cy.visit('/checkout');
  cy.get('[data-cy=payment-element]').trigger('payment-ready');
  cy.get('[data-cy=pay-button]').click();
  cy.wait('@confirmPayment');
  cy.get('[data-cy=payment-error]').should('contain', 'declined');
});

Keep the fixture aligned with the fields your code reads. Do not claim that this test verifies Stripe.js, the hosted iframe, or a live payment authorization.

Use Stripe test values for integration coverage

When a test must validate requests and responses against Stripe, use test API keys and Stripe-provided test values. Stripe recommends PaymentMethod values such as pm_card_visa in test code instead of sending raw card numbers from server-side code. Test mode simulates payments without moving money.

Limit these checks. Stripe says test environments have stricter rate limits and are not suitable for load testing. Run a small number of integration checks in CI, and keep broad state coverage in mocked Cypress tests.

cURL: create a test PaymentIntent

curl https://api.stripe.com/v1/payment_intents \\
  -u sk_test_YOUR_SECRET_KEY: \\
  -d amount=2000 \\
  -d currency=usd \\
  -d payment_method=pm_card_visa \\
  -d confirm=true

Python: create a test PaymentIntent

import os
import requests

response = requests.post(
    "https://api.stripe.com/v1/payment_intents",
    auth=(os.environ["STRIPE_TEST_SECRET_KEY"], ""),
    data={
        "amount": 2000,
        "currency": "usd",
        "payment_method": "pm_card_visa",
        "confirm": "true",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["status"])

Node.js: create a test PaymentIntent

const params = new URLSearchParams({
  amount: '2000',
  currency: 'usd',
  payment_method: 'pm_card_visa',
  confirm: 'true'
});

const auth = Buffer.from(`${process.env.STRIPE_TEST_SECRET_KEY}:`).toString('base64');
const response = await fetch('https://api.stripe.com/v1/payment_intents', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${auth}`,
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: params
});

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log((await response.json()).status);

Never commit a secret key. Keep it in the CI secret store and use a test key only. The client should receive a PaymentIntent client secret through your application backend, then call the Stripe.js confirmation flow appropriate to your integration.

Payment Element submit and result states

Stripe’s Payment Element migration guide shows the client-side pattern using an Elements instance and stripe.confirmPayment with the PaymentIntent client secret. Your Cypress assertions should follow the states your code produces around that call:

async function submitPayment() {
  setStatus('submitting');

  const { error } = await stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: { return_url: `${window.location.origin}/payment-result` },
    redirect: 'if_required'
  });

  if (error) {
    setStatus('error');
    setMessage(error.message || 'Payment could not be completed.');
    return;
  }

  setStatus('success');
}

Use your actual redirect policy and result handling. Assert that your UI transitions to submitting, error, or success, and that a retry returns the component to a usable state.

Why the common iframe recipe fails

A frequently copied Cypress pattern waits for contentDocument.body, wraps the body, and then queries inside the frame:

cy.get('iframe').its('0.contentDocument.body')
  .should('not.be.empty')
  .then(cy.wrap)
  .find('input');

This pattern is for same-origin frames. The Cypress FAQ explicitly says it does not work for a cross-origin Stripe payment form. Setting chromeWebSecurity: false can allow access in Chromium-family browsers, but not Firefox or WebKit; it is not a portable Cypress solution and should not be your default strategy.

cy.origin() does not change this boundary. It is designed for commands after a top-level navigation to another origin, while Stripe Elements remains embedded inside your page.

Browser and CI configuration

  • Run the same browser families you support, but keep assertions independent of Stripe’s iframe internals.
  • Use a stable test backend or intercept your own payment endpoint so tests do not depend on timing from a remote provider.
  • Use a fixed test cart and deterministic order identifiers.
  • Wait on application requests with cy.intercept() aliases instead of arbitrary sleeps.
  • Clear sessions and local storage between tests when checkout state can leak.
  • Keep Stripe test-environment integration checks separate from high-volume UI suites.

3D Secure and redirect flows

A browser-level check can use Stripe’s test values to exercise the real payment UI, but Cypress still cannot issue commands inside the cross-origin iframe. Redirects and 3D Secure flows also depend on the exact Stripe integration and browser matrix. The cited official guidance does not establish a universal Cypress procedure for fully automating a 3D Secure interaction inside Stripe Elements, so validate your project’s specific approach before treating it as reliable coverage.

For your application, test the states around the flow: redirect initiated, return URL loaded, payment status retrieved, success displayed, and failure or cancellation recovered. Test the server’s status lookup independently with Stripe test data.

Troubleshooting

Symptom Cause Fix
contentDocument is empty The iframe is cross-origin or has not loaded. Do not query Stripe fields. Assert your wrapper and simulate the application result.
cy.origin() still cannot find payment inputs cy.origin() handles top-level navigation, not iframe contents. Move assertions to your page and use Stripe test values for limited integration checks.
Tests pass in Chrome but fail in Firefox chromeWebSecurity: false is Chromium-specific. Remove the workaround and use a cross-origin-safe test boundary.
Decline tests are flaky They call a remote API for every UI branch or depend on hosted UI timing. Intercept your own endpoint and return a representative error fixture.
CI hits Stripe rate limits Too many test-environment API requests. Reduce live integration checks; keep state coverage mocked. Do not load test Stripe’s test environment.
Payment appears successful but the page hangs Your return URL or status polling path is not covered. Test the return route and backend status lookup separately, including timeout and cancellation.
Duplicate orders are created The submit button remains active or requests are retried without idempotency. Disable submission while pending and verify your backend idempotency behavior.

Performance, reliability, and cost

  • Speed: mocked Cypress tests avoid iframe and network variability and should make up most of the suite. Reserve slower Stripe test-environment checks for a small integration set.
  • Reliability: assert your own DOM and network contract. Avoid sleeps, generated Stripe selectors, and assumptions about iframe load timing.
  • Coverage: combine deterministic success and error fixtures with a few test-mode API checks and, where necessary, a manually reviewed browser payment flow.
  • Cost: Stripe test mode does not move money, but excessive API calls can consume rate-limit capacity. Cypress runs also consume CI time, so keep remote checks focused.

Or skip the browser setup

If your goal is a clean visual record of a checkout page, ScreenshotNeo can capture the page without maintaining browser automation. It accepts one GET request and returns PNG, JPEG, WebP, or PDF. Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the page verdict and billing result.

ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for options such as full-page capture, device presets, custom CSS and JavaScript, waits, hidden selectors, PDF output, caching, signed links, async jobs, and bulk capture. Create a free ScreenshotNeo account to get 1,000 screenshots each month with no card.

FAQ

Can Cypress interact with Stripe Elements?

It can test your surrounding page and application flow, but it cannot communicate with Stripe’s cross-origin iframe under Cypress’s documented default behavior.

Should I disable web security?

That workaround is limited to Chromium-family browsers and does not provide a portable solution for Firefox or WebKit. Keep it out of the default strategy.

Do mocked errors test Stripe?

No. They test that your application handles a representative Stripe-shaped response. Use a small number of Stripe test-environment checks when you need to validate Stripe API behavior.

Can I use real card numbers in CI?

Use Stripe test keys and Stripe-provided test values, such as PaymentMethod values, in automated tests. Never use live credentials for Cypress runs.

Is the same approach valid for every Stripe integration?

The cross-origin iframe boundary is the key constraint, but exact submit, redirect, and status behavior depends on whether you use Payment Element, another Elements component, or a custom flow. Match assertions to your integration’s contract.

Keep reading

7 min read

Full-Page Capture Chrome Plugin

Capture an entire webpage in Chrome with extensions, understand their limits, and automate clean full-page screenshots with ScreenshotNeo.

7 min read

Facebook Open Graph Debugger

Use Facebook’s Open Graph debugger to refresh stale link previews, verify metadata, and fix incorrect titles, descriptions, and images.