Playwright API Testing: A Complete Guide

// @ts-check
const { test, expect } = require('@playwright/test');

test.describe('API Request Context', () => {
  /** @type {import('@playwright/test').APIRequestContext} */
  let apiContext;

  test.beforeAll(async ({ playwright }) => {
    apiContext = await playwright.request.newContext({
      baseURL: 'https://jsonplaceholder.typicode.com',
      extraHTTPHeaders: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
      },
    });
  });

  test.afterAll(async () => {
    await apiContext.dispose();
  });

  test('GET /posts/1 returns a valid post', async () => {
    const response = await apiContext.get('/posts/1');

    expect(response.ok()).toBeTruthy();
    expect(response.status()).toBe(200);

    const body = await response.json();
    expect(body).toHaveProperty('id', 1);
    expect(body).toHaveProperty('userId');
    expect(body).toHaveProperty('title');
    expect(body).toHaveProperty('body');
  });

  test('GET /posts returns an array of posts', async () => {
    const response = await apiContext.get('/posts');

    expect(response.ok()).toBeTruthy();

    const posts = await response.json();
    expect(Array.isArray(posts)).toBeTruthy();
    expect(posts.length).toBeGreaterThan(0);
    expect(posts[0]).toHaveProperty('id');
  });

  test('POST /posts creates a new post', async () => {
    const newPost = {
      title: 'Playwright API Testing',
      body: 'Testing POST requests with Playwright.',
      userId: 1,
    };

    const response = await apiContext.post('/posts', { data: newPost });

    expect(response.ok()).toBeTruthy();
    expect(response.status()).toBe(201);

    const created = await response.json();
    expect(created).toHaveProperty('id');
    expect(created.title).toBe(newPost.title);
    expect(created.body).toBe(newPost.body);
    expect(created.userId).toBe(newPost.userId);
  });

  test('PUT /posts/1 updates an existing post', async () => {
    const updatedPost = {
      id: 1,
      title: 'Updated Title',
      body: 'Updated body content.',
      userId: 1,
    };

    const response = await apiContext.put('/posts/1', { data: updatedPost });

    expect(response.ok()).toBeTruthy();

    const body = await response.json();
    expect(body.title).toBe(updatedPost.title);
  });

  test('DELETE /posts/1 removes a post', async () => {
    const response = await apiContext.delete('/posts/1');

    expect(response.ok()).toBeTruthy();
    expect(response.status()).toBe(200);
  });
});

// @ts-check
const { test, expect } = require('@playwright/test');
const fs = require('fs');
const path = require('path');

/**
 * Pattern 1: Token capture in beforeAll with Authorization header reuse.
 *
 * This pattern authenticates once, stores the token, and reuses it
 * across all tests in the describe block via a shared request context.
 */
test.describe('Pattern 1 — Bearer token reuse', () => {
  /** @type {import('@playwright/test').APIRequestContext} */
  let authedContext;

  test.beforeAll(async ({ playwright }) => {
    // Step 1: Authenticate and capture a token.
    // Using reqres.in which provides a real auth endpoint for testing.
    const loginContext = await playwright.request.newContext({
      baseURL: 'https://reqres.in',
    });

    const loginResponse = await loginContext.post('/api/login', {
      data: {
        email: 'eve.holt@reqres.in',
        password: 'cityslicka',
      },
    });

    expect(loginResponse.ok()).toBeTruthy();
    const { token } = await loginResponse.json();
    expect(token).toBeTruthy();

    await loginContext.dispose();

    // Step 2: Create a new context that injects the token on every request.
    authedContext = await playwright.request.newContext({
      baseURL: 'https://reqres.in',
      extraHTTPHeaders: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json',
      },
    });
  });

  test.afterAll(async () => {
    await authedContext.dispose();
  });

  test('authenticated GET /api/users/2 returns user data', async () => {
    const response = await authedContext.get('/api/users/2');

    expect(response.ok()).toBeTruthy();

    const { data } = await response.json();
    expect(data).toHaveProperty('id', 2);
    expect(data).toHaveProperty('email');
    expect(data).toHaveProperty('first_name');
  });

  test('authenticated GET /api/users returns paginated list', async () => {
    const response = await authedContext.get('/api/users?page=1');

    expect(response.ok()).toBeTruthy();

    const body = await response.json();
    expect(body).toHaveProperty('page', 1);
    expect(body.data.length).toBeGreaterThan(0);
  });
});

/**
 * Pattern 2: storageState serialization to a file.
 *
 * Useful when you want to authenticate once and share cookies/localStorage
 * across browser-based tests. Here we demonstrate the serialization mechanism.
 */
test.describe('Pattern 2 — storageState serialization', () => {
  const storagePath = path.join(__dirname, '..', '.auth', 'storage-state.json');

  test.beforeAll(async ({ playwright }) => {
    const dir = path.dirname(storagePath);
    if (!fs.existsSync(dir)) {
      fs.mkdirSync(dir, { recursive: true });
    }

    // Authenticate and capture the storage state.
    const context = await playwright.request.newContext({
      baseURL: 'https://reqres.in',
    });

    const loginResponse = await context.post('/api/login', {
      data: {
        email: 'eve.holt@reqres.in',
        password: 'cityslicka',
      },
    });

    expect(loginResponse.ok()).toBeTruthy();

    // Save the storage state (cookies + origins) to a JSON file.
    await context.storageState({ path: storagePath });
    await context.dispose();
  });

  test('storageState file is created and valid JSON', async () => {
    expect(fs.existsSync(storagePath)).toBeTruthy();

    const raw = fs.readFileSync(storagePath, 'utf-8');
    const state = JSON.parse(raw);

    // storageState always contains these top-level keys.
    expect(state).toHaveProperty('cookies');
    expect(state).toHaveProperty('origins');
  });

  test('new context can load from saved storageState', async ({ playwright }) => {
    const restoredContext = await playwright.request.newContext({
      baseURL: 'https://reqres.in',
      storageState: storagePath,
    });

    // The restored context carries forward cookies from the auth session.
    const response = await restoredContext.get('/api/users/2');
    expect(response.ok()).toBeTruthy();

    await restoredContext.dispose();
  });

  test.afterAll(() => {
    // Clean up the auth file after tests.
    if (fs.existsSync(storagePath)) {
      fs.unlinkSync(storagePath);
      const dir = path.dirname(storagePath);
      if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
        fs.rmdirSync(dir);
      }
    }
  });
});

/**
 * Pattern 3: HTTP Basic authentication.
 *
 * Playwright's request context accepts httpCredentials directly,
 * which sets the Authorization: Basic header on every request.
 */
test.describe('Pattern 3 — HTTP Basic auth', () => {
  test('request with httpCredentials sends Basic header', async ({ playwright }) => {
    const context = await playwright.request.newContext({
      baseURL: 'https://httpbin.org',
      httpCredentials: {
        username: 'testuser',
        password: 'testpass',
      },
    });

    const response = await context.get('/basic-auth/testuser/testpass');

    expect(response.ok()).toBeTruthy();

    const body = await response.json();
    expect(body).toHaveProperty('authenticated', true);
    expect(body).toHaveProperty('user', 'testuser');

    await context.dispose();
  });
});

// @ts-check
const { test, expect } = require('@playwright/test');

/**
 * Network interception patterns using page.route().
 *
 * These tests launch a real browser page and demonstrate three core
 * interception strategies: fulfill, abort, and continue-with-modification.
 */
test.describe('Network Interception with page.route()', () => {
  test('route.fulfill() — return static JSON without hitting the server', async ({ page }) => {
    const mockTodos = [
      { id: 1, title: 'Write Playwright tests', completed: true },
      { id: 2, title: 'Ship to production', completed: false },
    ];

    // Intercept any request to /todos and return a canned response.
    await page.route('**/todos', (route) => {
      route.fulfill({
        status: 200,
        contentType: 'application/json',
        body: JSON.stringify(mockTodos),
      });
    });

    // Navigate to a page that would fetch /todos.
    // We use a data URI so no real page load is needed — the route
    // intercepts the fetch regardless of origin.
    await page.goto('data:text/html,<script>fetch("https://jsonplaceholder.typicode.com/todos").then(r=>r.json()).then(d=>document.title=JSON.stringify(d))</script>');

    // Wait for the fetch to resolve and update the title.
    await page.waitForFunction(() => {
      try { return JSON.parse(document.title).length > 0; } catch { return false; }
    });

    const title = await page.title();
    const parsed = JSON.parse(title);

    expect(parsed).toHaveLength(2);
    expect(parsed[0].title).toBe('Write Playwright tests');
  });

  test('route.abort() — simulate network failure', async ({ page }) => {
    // Abort all requests to the /posts endpoint.
    await page.route('**/posts', (route) => {
      route.abort('failed');
    });

    // Use a data URI page that attempts a fetch and catches the error.
    await page.goto('data:text/html,<script>fetch("https://jsonplaceholder.typicode.com/posts").then(()=>document.title="ok").catch(()=>document.title="network-error")</script>');

    await page.waitForFunction(() => document.title !== '');

    const title = await page.title();
    expect(title).toBe('network-error');
  });

  test('route.continue() — modify the response body on the fly', async ({ page }) => {
    // Intercept /users/1 and rewrite the response body.
    await page.route('**/users/1', async (route) => {
      // Let the real request go through, then modify the response.
      const response = await route.fetch();
      const originalBody = await response.json();

      const modifiedBody = {
        ...originalBody,
        name: 'Overridden Name',
        company: { ...originalBody.company, name: 'Playwright Corp' },
      };

      await route.fulfill({
        response,
        body: JSON.stringify(modifiedBody),
      });
    });

    // Navigate to a data URI that fetches /users/1.
    await page.goto('data:text/html,<script>fetch("https://jsonplaceholder.typicode.com/users/1").then(r=>r.json()).then(d=>document.title=JSON.stringify(d))</script>');

    await page.waitForFunction(() => {
      try { return JSON.parse(document.title).name !== undefined; } catch { return false; }
    });

    const title = await page.title();
    const user = JSON.parse(title);

    expect(user.name).toBe('Overridden Name');
    expect(user.company.name).toBe('Playwright Corp');
    // Original fields are still present.
    expect(user).toHaveProperty('id', 1);
    expect(user).toHaveProperty('email');
  });
});

// @ts-check
const { test, expect } = require('@playwright/test');

/**
 * GraphQL API testing with Playwright.
 *
 * Uses the public SpaceX GraphQL API (r/spacex) which requires no auth
 * and supports both queries and mutations (read-only in practice,
 * but the request shape is identical).
 *
 * Endpoint: https://spacex-production.up.railway.app/graphql
 *
 * Fallback: if the SpaceX API is unavailable, tests use the
 * Countries GraphQL API at https://countries.trevorblades.com/graphql
 */

const GRAPHQL_URL = 'https://countries.trevorblades.com/graphql';

test.describe('GraphQL API Testing', () => {
  /** @type {import('@playwright/test').APIRequestContext} */
  let apiContext;

  test.beforeAll(async ({ playwright }) => {
    apiContext = await playwright.request.newContext({
      baseURL: GRAPHQL_URL,
      extraHTTPHeaders: {
        'Content-Type': 'application/json',
      },
    });
  });

  test.afterAll(async () => {
    await apiContext.dispose();
  });

  test('query — fetch a country by code', async () => {
    const query = `
      query GetCountry($code: ID!) {
        country(code: $code) {
          name
          capital
          currency
          languages {
            name
          }
        }
      }
    `;

    const response = await apiContext.post('', {
      data: {
        query,
        variables: { code: 'US' },
      },
    });

    expect(response.ok()).toBeTruthy();

    const { data, errors } = await response.json();

    // A well-formed GraphQL response should not contain errors.
    expect(errors).toBeUndefined();

    expect(data.country).toBeTruthy();
    expect(data.country.name).toBe('United States');
    expect(data.country.capital).toBe('Washington D.C.');
    expect(data.country.currency).toContain('USD');
    expect(data.country.languages.length).toBeGreaterThan(0);
  });

  test('query — fetch a list of countries in a continent', async () => {
    const query = `
      query GetContinent($code: ID!) {
        continent(code: $code) {
          name
          countries {
            code
            name
          }
        }
      }
    `;

    const response = await apiContext.post('', {
      data: {
        query,
        variables: { code: 'EU' },
      },
    });

    expect(response.ok()).toBeTruthy();

    const { data, errors } = await response.json();
    expect(errors).toBeUndefined();

    expect(data.continent.name).toBe('Europe');
    expect(data.continent.countries.length).toBeGreaterThan(0);

    // Verify a known European country is in the results.
    const countryCodes = data.continent.countries.map((c) => c.code);
    expect(countryCodes).toContain('DE');
  });

  test('query with invalid field returns errors array', async () => {
    const query = `
      query {
        country(code: "US") {
          nonExistentField
        }
      }
    `;

    const response = await apiContext.post('', {
      data: { query },
    });

    const body = await response.json();

    // GraphQL servers return errors for invalid queries.
    expect(body.errors).toBeDefined();
    expect(body.errors.length).toBeGreaterThan(0);
    expect(body.errors[0]).toHaveProperty('message');
  });

  test('mutation-shaped request — demonstrates the POST body format', async () => {
    // The Countries API is read-only, so we send a mutation-shaped request
    // to demonstrate the format. This query uses the same POST structure
    // a real mutation would use: { query: "mutation { ... }", variables: {} }.
    //
    // In a real app, replace this with an actual mutation endpoint.
    const mutation = `
      query SimulateMutationShape($code: ID!) {
        country(code: $code) {
          name
          emoji
        }
      }
    `;

    const response = await apiContext.post('', {
      data: {
        query: mutation,
        variables: { code: 'FR' },
      },
    });

    expect(response.ok()).toBeTruthy();

    const { data, errors } = await response.json();
    expect(errors).toBeUndefined();

    expect(data.country.name).toBe('France');
    expect(data.country.emoji).toBeTruthy();
  });
});

// @ts-check
const { test, expect } = require('@playwright/test');

/**
 * Advanced wait patterns for network requests in Playwright.
 *
 * Demonstrates waitForResponse, waitForRequest, and the
 * Promise-race pattern for capturing responses that fire
 * as a result of user actions.
 */
test.describe('Wait Patterns for Network Requests', () => {
  test('Promise-race pattern — start waiting before triggering the action', async ({ page }) => {
    // Navigate to a page that will make a fetch on button click.
    await page.goto('data:text/html,' + encodeURIComponent(`
      <button id="load">Load Post</button>
      <pre id="result"></pre>
      <script>
        document.getElementById('load').addEventListener('click', async () => {
          const res = await fetch('https://jsonplaceholder.typicode.com/posts/1');
          const data = await res.json();
          document.getElementById('result').textContent = JSON.stringify(data);
        });
      </script>
    `));

    // Start waiting BEFORE clicking — this is the Promise-race pattern.
    // If you click first and then wait, you might miss the response.
    const [response] = await Promise.all([
      page.waitForResponse('**/posts/1'),
      page.click('#load'),
    ]);

    expect(response.status()).toBe(200);

    const body = await response.json();
    expect(body).toHaveProperty('id', 1);
    expect(body).toHaveProperty('title');
  });

  test('predicate-form waitForResponse — match on URL and status', async ({ page }) => {
    await page.goto('data:text/html,' + encodeURIComponent(`
      <button id="fetch-users">Fetch Users</button>
      <script>
        document.getElementById('fetch-users').addEventListener('click', async () => {
          await fetch('https://jsonplaceholder.typicode.com/users');
        });
      </script>
    `));

    const [response] = await Promise.all([
      page.waitForResponse(
        (resp) => resp.url().includes('/users') && resp.status() === 200
      ),
      page.click('#fetch-users'),
    ]);

    const users = await response.json();
    expect(Array.isArray(users)).toBeTruthy();
    expect(users.length).toBeGreaterThan(0);
    expect(users[0]).toHaveProperty('email');
  });

  test('waitForRequest with postDataJSON() inspection', async ({ page }) => {
    await page.goto('data:text/html,' + encodeURIComponent(`
      <button id="create-post">Create Post</button>
      <script>
        document.getElementById('create-post').addEventListener('click', async () => {
          await fetch('https://jsonplaceholder.typicode.com/posts', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              title: 'Wait Pattern Demo',
              body: 'Inspecting request payloads with Playwright.',
              userId: 42,
            }),
          });
        });
      </script>
    `));

    // Wait for the outgoing request and inspect its payload.
    const [request] = await Promise.all([
      page.waitForRequest((req) => {
        if (!req.url().includes('/posts') || req.method() !== 'POST') {
          return false;
        }
        const postData = req.postDataJSON();
        return postData && postData.userId === 42;
      }),
      page.click('#create-post'),
    ]);

    // Verify the captured request.
    expect(request.method()).toBe('POST');

    const payload = request.postDataJSON();
    expect(payload.title).toBe('Wait Pattern Demo');
    expect(payload.userId).toBe(42);
  });

  test('wait for multiple sequential responses', async ({ page }) => {
    await page.goto('data:text/html,' + encodeURIComponent(`
      <button id="load-all">Load All</button>
      <script>
        document.getElementById('load-all').addEventListener('click', async () => {
          await fetch('https://jsonplaceholder.typicode.com/posts/1');
          await fetch('https://jsonplaceholder.typicode.com/posts/2');
        });
      </script>
    `));

    // Capture both responses in order.
    const [firstResponse, secondResponse] = await Promise.all([
      page.waitForResponse('**/posts/1'),
      page.waitForResponse('**/posts/2'),
      page.click('#load-all'),
    ]);

    const first = await firstResponse.json();
    const second = await secondResponse.json();

    expect(first.id).toBe(1);
    expect(second.id).toBe(2);
  });
});

name: Playwright API Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20]

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      - name: Cache node_modules
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.os }}-node-${{ matrix.node-version }}-${{ hashFiles('package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-${{ matrix.node-version }}-

      - name: Cache Playwright browsers
        uses: actions/cache@v4
        with:
          path: ~/.cache/ms-playwright
          key: ${{ runner.os }}-playwright-${{ hashFiles('package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-playwright-

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright Chromium
        run: npx playwright install chromium --with-deps

      - name: Run Playwright API tests
        run: npx playwright test
        env:
          BASE_URL: ${{ secrets.BASE_URL || 'https://jsonplaceholder.typicode.com' }}