How to Test Stripe Checkout (Past the Bot Wall)

/**
 * Stripe Checkout E2E test using Playwright.
 *
 * Prerequisites:
 *   - Node 18+
 *   - STRIPE_PUBLISHABLE_KEY_TEST set in environment (pk_test_...)
 *   - STRIPE_SECRET_KEY set in environment (sk_test_...) — used to create a test session
 *   - Playwright installed: npx playwright install chromium
 *
 * Run: npx playwright test tests/stripe-checkout.spec.ts
 *
 * The test:
 *   1. Creates a Stripe Checkout Session via the API (server-side, no UI needed)
 *   2. Navigates to the hosted Checkout URL
 *   3. Uses frameLocator to reach into Stripe's cross-origin card iframe
 *   4. Fills the test card (4242 4242 4242 4242 — always succeeds)
 *   5. Submits and asserts on the success redirect URL
 *   6. Asserts the checkout.session.completed event was received (order-independently)
 */

import { test, expect } from "@playwright/test";
import Stripe from "stripe";

// ---------------------------------------------------------------------------
// Configuration — set these in your .env file or CI environment variables
// ---------------------------------------------------------------------------
const STRIPE_SECRET_KEY = process.env.STRIPE_SECRET_KEY ?? "";
const SUCCESS_URL = process.env.SUCCESS_URL ?? "http://localhost:4242/success";
const CANCEL_URL = process.env.CANCEL_URL ?? "http://localhost:4242/cancel";

// Webhook endpoint that the webhook/server.js listener exposes
const WEBHOOK_ENDPOINT = process.env.WEBHOOK_ENDPOINT ?? "http://localhost:4242/webhook/events";

// ---------------------------------------------------------------------------
// Helper: create a Stripe Checkout Session via the API
// ---------------------------------------------------------------------------
async function createCheckoutSession(stripe: Stripe): Promise<{ url: string; sessionId: string }> {
  const session = await stripe.checkout.sessions.create({
    payment_method_types: ["card"],
    line_items: [
      {
        price_data: {
          currency: "usd",
          product_data: { name: "Test Product" },
          unit_amount: 1000, // $10.00
        },
        quantity: 1,
      },
    ],
    mode: "payment",
    success_url: `${SUCCESS_URL}?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: CANCEL_URL,
  });

  if (!session.url) {
    throw new Error("Stripe did not return a checkout URL for the created session.");
  }

  return { url: session.url, sessionId: session.id };
}

// ---------------------------------------------------------------------------
// Helper: poll the webhook listener's event log for the session
// ---------------------------------------------------------------------------
async function pollForWebhookEvent(
  sessionId: string,
  timeoutMs = 30_000,
  intervalMs = 500
): Promise<boolean> {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    try {
      const response = await fetch(`${WEBHOOK_ENDPOINT}?session_id=${sessionId}`);
      if (response.ok) {
        const data = (await response.json()) as { received: boolean };
        if (data.received) {
          return true;
        }
      }
    } catch {
      // Webhook listener not yet ready or network blip — continue polling
    }

    await new Promise<void>((resolve) => setTimeout(resolve, intervalMs));
  }

  return false;
}

// ---------------------------------------------------------------------------
// Test
// ---------------------------------------------------------------------------
test.describe("Stripe Checkout E2E", () => {
  test("completes a payment with a test card and receives the webhook", async ({ page }) => {
    if (!STRIPE_SECRET_KEY.startsWith("sk_test_")) {
      test.skip(true, "STRIPE_SECRET_KEY is not set or is not a test key — skipping.");
    }

    const stripe = new Stripe(STRIPE_SECRET_KEY, { apiVersion: "2025-05-28.basil" });

    // Step 1: Create a Checkout Session server-side
    const { url: checkoutUrl, sessionId } = await createCheckoutSession(stripe);

    // Step 2: Navigate to hosted Checkout
    await page.goto(checkoutUrl, { waitUntil: "domcontentloaded" });

    // Step 3: Locate the Stripe card iframe.
    //
    // Stripe renders the card number, expiry, and CVC inside iframes served
    // from js.stripe.com. The iframes are cross-origin. Playwright's frameLocator
    // API lets you scope selectors inside them.
    //
    // The iframe selector below matches by the title attribute Stripe sets.
    // If Stripe changes the attribute, update this selector.
    const cardNumberFrame = page.frameLocator('iframe[title="Secure card number input frame"]');
    const expiryFrame = page.frameLocator('iframe[title="Secure expiration date input frame"]');
    const cvcFrame = page.frameLocator('iframe[title="Secure CVC input frame"]');

    // Step 4: Fill the test card details
    // Card 4242 4242 4242 4242 — always succeeds in Stripe test mode
    await cardNumberFrame.locator('[name="cardnumber"], [autocomplete="cc-number"], input').fill("4242424242424242");
    await expiryFrame.locator('[name="exp-date"], [autocomplete="cc-exp"], input').fill("12/28");
    await cvcFrame.locator('[name="cvc"], [autocomplete="cc-csc"], input').fill("123");

    // Some Stripe Checkout layouts include email and name fields outside iframes
    const emailField = page.locator('input[type="email"]');
    if (await emailField.isVisible({ timeout: 2_000 }).catch(() => false)) {
      await emailField.fill("test@example.com");
    }

    // Step 5: Assert on both the redirect URL and the webhook — order-independently
    //
    // The checkout.session.completed webhook and the success redirect do not
    // arrive in a guaranteed order. Using Promise.all lets both assertions
    // resolve concurrently regardless of which lands first.
    const submitButton = page.locator('button[type="submit"], button:has-text("Pay"), button:has-text("Subscribe")').first();
    await submitButton.click();

    const [webhookReceived] = await Promise.all([
      // Webhook assertion: poll the listener for the event
      pollForWebhookEvent(sessionId),

      // Redirect assertion: wait for the browser to reach the success URL
      page.waitForURL(`${SUCCESS_URL}**`, { timeout: 30_000 }),
    ]);

    // Confirm redirect
    expect(page.url()).toContain(SUCCESS_URL.replace("http://localhost:4242", ""));

    // Confirm webhook
    expect(webhookReceived).toBe(true);
  });
});

/**
 * Stripe webhook listener — validates Stripe-Signature and logs
 * checkout.session.completed events.
 *
 * Prerequisites:
 *   - Node 18+
 *   - STRIPE_SECRET_KEY  : your Stripe test secret key (sk_test_...)
 *   - STRIPE_WEBHOOK_SECRET : webhook signing secret from the Stripe Dashboard
 *                             or the output of `stripe listen`
 *
 * Run:
 *   node webhook/server.js
 *
 * Forward live Stripe events to this server in development:
 *   stripe listen --forward-to localhost:4242/webhook
 *
 * The server also exposes GET /webhook/events?session_id=<id> so that the
 * Playwright test can poll for receipt of a specific checkout.session.completed
 * event without coupling the order of the redirect and the webhook.
 */

import express from "express";
import Stripe from "stripe";

// ---------------------------------------------------------------------------
// Configuration
// ---------------------------------------------------------------------------
const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 4242;
const STRIPE_SECRET_KEY = process.env.STRIPE_SECRET_KEY ?? "";
const STRIPE_WEBHOOK_SECRET = process.env.STRIPE_WEBHOOK_SECRET ?? "";

if (!STRIPE_SECRET_KEY.startsWith("sk_test_")) {
  console.error(
    "ERROR: STRIPE_SECRET_KEY is missing or not a test key.\n" +
    "Set STRIPE_SECRET_KEY=sk_test_... in your environment before starting the server."
  );
  process.exit(1);
}

if (!STRIPE_WEBHOOK_SECRET) {
  console.error(
    "ERROR: STRIPE_WEBHOOK_SECRET is missing.\n" +
    "Set STRIPE_WEBHOOK_SECRET to the signing secret from the Stripe Dashboard\n" +
    "or from the output of `stripe listen --forward-to localhost:4242/webhook`."
  );
  process.exit(1);
}

// ---------------------------------------------------------------------------
// State: in-memory log of received checkout.session.completed events
// In production you would persist this; for testing an in-memory map is fine.
// ---------------------------------------------------------------------------

/** @type {Map<string, import('stripe').Stripe.Checkout.Session>} */
const completedSessions = new Map();

// ---------------------------------------------------------------------------
// Stripe client
// ---------------------------------------------------------------------------
const stripe = new Stripe(STRIPE_SECRET_KEY, { apiVersion: "2025-05-28.basil" });

// ---------------------------------------------------------------------------
// Express app
// ---------------------------------------------------------------------------
const app = express();

/**
 * POST /webhook
 *
 * Receives Stripe webhook events. Uses express.raw() for the body so that
 * stripe.webhooks.constructEvent can verify the Stripe-Signature header.
 * Never parse the body as JSON before passing it to constructEvent — the
 * raw bytes are required for signature verification.
 */
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.headers["stripe-signature"];

    if (!sig) {
      console.error("Webhook rejected: missing Stripe-Signature header.");
      return res.status(400).send("Missing Stripe-Signature header.");
    }

    let event;
    try {
      event = stripe.webhooks.constructEvent(req.body, sig, STRIPE_WEBHOOK_SECRET);
    } catch (err) {
      console.error(`Webhook signature verification failed: ${err.message}`);
      return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    // Handle the event
    switch (event.type) {
      case "checkout.session.completed": {
        const session = event.data.object;
        completedSessions.set(session.id, session);
        console.log(`checkout.session.completed — session ${session.id}, payment status: ${session.payment_status}`);
        break;
      }

      case "payment_intent.succeeded": {
        const paymentIntent = event.data.object;
        console.log(`payment_intent.succeeded — ${paymentIntent.id}, amount: ${paymentIntent.amount}`);
        break;
      }

      default:
        // Log other event types but do not act on them
        console.log(`Unhandled event type: ${event.type}`);
    }

    // Acknowledge receipt — always return 200 promptly
    res.status(200).json({ received: true });
  }
);

/**
 * GET /webhook/events?session_id=<id>
 *
 * Polling endpoint used by the Playwright test to check whether a specific
 * checkout.session.completed event has been received.
 *
 * Returns: { received: true | false, session?: object }
 */
app.get("/webhook/events", (req, res) => {
  const sessionId = req.query.session_id;

  if (!sessionId || typeof sessionId !== "string") {
    return res.status(400).json({ error: "Missing or invalid session_id query parameter." });
  }

  if (completedSessions.has(sessionId)) {
    return res.status(200).json({ received: true, session: completedSessions.get(sessionId) });
  }

  res.status(200).json({ received: false });
});

/**
 * GET /success  (convenience stub for local testing without a real success page)
 */
app.get("/success", (req, res) => {
  const sessionId = req.query.session_id ?? "unknown";
  res.status(200).send(`
    <!DOCTYPE html>
    <html lang="en">
    <head><title>Payment successful</title></head>
    <body>
      <h1>Payment successful</h1>
      <p>Session: ${sessionId}</p>
    </body>
    </html>
  `);
});

// ---------------------------------------------------------------------------
// Start server
// ---------------------------------------------------------------------------
app.listen(PORT, () => {
  console.log(`Stripe webhook listener running on http://localhost:${PORT}`);
  console.log(`Webhook endpoint: POST http://localhost:${PORT}/webhook`);
  console.log(`Event poll endpoint: GET http://localhost:${PORT}/webhook/events?session_id=<id>`);
  console.log();
  console.log("To forward Stripe events in development:");
  console.log(`  stripe listen --forward-to localhost:${PORT}/webhook`);
});