🎭How to test Next.js SSR API (Playwright + MSW) Part 2 Parallel test🎭

Intro

Last time, I made a Next.js Server Side Rendering (SSR) API test using Playwright and Mock Service Worker (MSW).↓
https://dev.to/webdeveloperhyper/how-to-test-nextjs-ssr-api-playwright-msw-k65

However, because MSW keeps its state globally, I couldn't run Playwright in parallel and had to run it sequentially instead.🚀 This time, I revised the code to make Playwright run in parallel and speed up.🚀🚀🚀🚀

Please note that this is just my personal memo.

Summary of revises

1️⃣ I changed mock-server.ts to dynamically control how many mock servers run.🙆 The number of mock servers is defined by MOCK_SERVER_COUNT in .env.

Before the revise, only one mock server would run.🙅

2️⃣ I changed playwright.config.ts to handle parallel tests. I added test.info().workerIndex to the test code to read how many servers to run and apply it to parallel tests.

3️⃣ I changed server.ts, handler.ts and page.tsx, to allow dynamic ports in the API path so multiple servers can run at ones.🙆

Before the revise, the API port was fixed to 3001.🙅

4️⃣ Because the number of mock servers is now dynamic, you can increase it as much as your PC can handle.🙆 All you have to do is to change the value of MOCK_SERVER_COUNT in .env.

Before the revise, port number was fix to only one.🙅

How to test in parallel

I will show how to do it step by step.
I added a beginner friendly comment to the code.

↓ Install Next.js

npx create-next-app@latest my-app --yes

↓ Move to my-app folder

cd my-app

↓ Copy and paste the code
↓ my-app/src/app/page.tsx

/**
 * Pokemon Display Page - Simple Next.js Server Component
 * 
 * This page fetches Pokemon data and displays it in a simple layout.
 * During tests, MSW (Mock Service Worker) intercepts the API call and returns
 * mock data based on what the test specifies (Charizard, Pikachu, Eevee, or 500 error).
 * 
 * Key concepts for beginners:
 * - Server-Side Rendering: This runs on the server first, then sends HTML to browser
 * - Fetch API: Makes HTTP requests to get data
 * - Error handling: Shows error page when API fails
 * - MSW integration: Tests can switch between different Pokemon or trigger errors
 */

// Reusable title component to avoid duplication
const DemoTitle = () => (
  <h2 className="text-4xl font-bold text-blue-600 mb-6">
    How to test Next.js SSR API
    <br />
    (Playwright + MSW)
  </h2>
);

export default async function Home({ searchParams }: { searchParams?: Promise<{ mockPort?: string }> }) {
  try {
    // Await searchParams for Next.js 15 compatibility
    const params = await searchParams;
    // Get the mock port from URL search params (set by tests) or default to 3001
    const mockPort = params?.mockPort || '3001';

    // Fetch Pokemon data from our mock API
    // MSW will intercept this request and return the appropriate mock data
    const response = await fetch(`http://localhost:${mockPort}/api/v2/pokemon/charizard`);

    // Check if request was successful (status 200-299)
    // If not, throw an error to trigger the catch block
    if (!response.ok) throw new Error(`HTTP ${response.status}`);

    // Parse the JSON response into a JavaScript object
    const pokemon = await response.json();

    // SUCCESS: Display the Pokemon data
    return (
      <div className="min-h-screen flex items-center justify-center p-4">
        <div className="text-center">
          {/* Page title explaining the demo purpose */}
          <DemoTitle />

          {/* Pokemon name with first letter capitalized */}
          <h1 className="text-3xl font-bold mb-4">
            {pokemon.name.charAt(0).toUpperCase() + pokemon.name.slice(1)}
          </h1>

          {/* Pokemon image */}
          <img 
            src={pokemon.sprites.front_default} 
            alt={pokemon.name}
            className="mx-auto mb-4 w-32 h-32"
          />

          {/* Pokemon ID number */}
          <p className="text-lg">Pokemon #{pokemon.id}</p>
        </div>
      </div>
    );
  } catch (error) {
    // ERROR: Something went wrong with the API request
    // This could happen if the mock server isn't running or returns an error status
    return (
      <div className="min-h-screen flex items-center justify-center p-4">
        <div className="text-center">
          {/* Page title explaining the demo purpose */}
          <DemoTitle />

          <h1 className="text-2xl font-bold text-red-600 mb-4">Error</h1>
        </div>
      </div>
    );
  }
} 

↓ Install Playwright

npm init playwright@latest

↓ Install Mock Service Worker (MSW)

npm i msw --save-dev

↓ Install tsx
tsx will reduce your build from TypeScript to JavaScript and writing a complicated tsconfig.json for the mock.

npm install -D tsx

↓ Install dotenv
dotenv enables you to load environment variables from .env into your code.

npm install --save-dev dotenv

↓ Copy and paste the code
↓ tests/example.spec.ts

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

/**
 * Helper function to set up mock Pokemon data for tests
 * This function communicates with our mock server to switch which Pokemon data is returned
 *
 * @param page - Playwright page object for making requests
 * @param mockType - Which Pokemon to mock ("pikachu", "eevee", or null for default "charizard")
 */
const setMockPokemon = async (
  page: any,
  mockType: "pikachu" | "eevee" | "blastoise" | "venusaur" | "jigglypuff" | "gengar" | "machamp" | "alakazam" | "dragonite" | "mewtwo" | "error500" | null
) => {
  // If no specific Pokemon is requested, default to charizard
  const pokemon = mockType || "charizard";

  // Calculate port based on worker index for parallel testing
  const port = 3001 + test.info().workerIndex;

  // Send a request to our mock server to switch the Pokemon data
  // This uses MSW's server.use() internally to override the API response
  await page.request.post(`http://localhost:${port}/api/switch-pokemon`, {
    data: { pokemon },
  });


  // Navigate to the home page with the mock port parameter
  await page.goto(`/?mockPort=${port}`);

  // Wait for all network requests to complete before proceeding with test
  await page.waitForLoadState("networkidle");
};

test.describe("Pokemon Basic Tests", () => {
  /**
   * Test 1: Default Charizard Pokemon
   * This test verifies that the default Pokemon (Charizard) is displayed correctly
   * when no specific mock is set
   */
  test("Charizard (Default Pokemon)", async ({ page }) => {
    // Set up the test to use default Charizard data
    await setMockPokemon(page, null);

    // Verify the Pokemon name appears in the main heading
    await expect(page.locator("h1")).toContainText("Charizard");

    // Verify the Pokemon ID number is displayed correctly
    await expect(page.locator("text=Pokemon #6")).toBeVisible();

    // Take a screenshot for visual verification
    await page.screenshot({ path: "./test-results/screenshots/charizard.png" });
  });

  /**
   * Test 2: Pikachu Mock
   * This test verifies that the mock server can switch to Pikachu data
   * and display it correctly on the page
   */
  test("Pikachu Mock", async ({ page }) => {
    // Switch the mock server to return Pikachu data instead of default Charizard
    await setMockPokemon(page, "pikachu");

    // Verify Pikachu name appears in the main heading
    await expect(page.locator("h1")).toContainText("Pikachu");

    // Verify Pikachu's ID number is displayed correctly
    await expect(page.locator("text=Pokemon #25")).toBeVisible();

    // Take a screenshot for visual verification
    await page.screenshot({ path: "./test-results/screenshots/pikachu.png" });
  });

  /**
   * Test 3: Eevee Mock
   * This test verifies that the mock server can switch to Eevee data
   * and display it correctly on the page
   */
  test("Eevee Mock", async ({ page }) => {
    // Switch the mock server to return Eevee data instead of default Charizard
    await setMockPokemon(page, "eevee");

    // Verify Eevee name appears in the main heading
    await expect(page.locator("h1")).toContainText("Eevee");

    // Verify Eevee's ID number is displayed correctly
    await expect(page.locator("text=Pokemon #133")).toBeVisible();

    // Take a screenshot for visual verification
    await page.screenshot({ path: "./test-results/screenshots/eevee.png" });
  });

  /**
   * Test 4: 500 Error Response
   * This test verifies that the error page is displayed correctly
   * when the API returns a 500 server error
   */
  test("500 Error", async ({ page }) => {
    // Switch the mock server to return 500 error
    await setMockPokemon(page, "error500");

    // Verify error page is displayed
    await expect(page.locator("h1")).toContainText("Error");

    // Take a screenshot for visual verification
    await page.screenshot({ path: "./test-results/screenshots/error500.png" });
  });

  test("Blastoise Mock", async ({ page }) => {
    await setMockPokemon(page, "blastoise");
    await expect(page.locator("h1")).toContainText("Blastoise");
    await expect(page.locator("text=Pokemon #9")).toBeVisible();
    await page.screenshot({ path: "./test-results/screenshots/blastoise.png" });
  });

  test("Venusaur Mock", async ({ page }) => {
    await setMockPokemon(page, "venusaur");
    await expect(page.locator("h1")).toContainText("Venusaur");
    await expect(page.locator("text=Pokemon #3")).toBeVisible();
    await page.screenshot({ path: "./test-results/screenshots/venusaur.png" });
  });

  test("Jigglypuff Mock", async ({ page }) => {
    await setMockPokemon(page, "jigglypuff");
    await expect(page.locator("h1")).toContainText("Jigglypuff");
    await expect(page.locator("text=Pokemon #39")).toBeVisible();
    await page.screenshot({ path: "./test-results/screenshots/jigglypuff.png" });
  });

  test("Gengar Mock", async ({ page }) => {
    await setMockPokemon(page, "gengar");
    await expect(page.locator("h1")).toContainText("Gengar");
    await expect(page.locator("text=Pokemon #94")).toBeVisible();
    await page.screenshot({ path: "./test-results/screenshots/gengar.png" });
  });

  test("Machamp Mock", async ({ page }) => {
    await setMockPokemon(page, "machamp");
    await expect(page.locator("h1")).toContainText("Machamp");
    await expect(page.locator("text=Pokemon #68")).toBeVisible();
    await page.screenshot({ path: "./test-results/screenshots/machamp.png" });
  });

  test("Alakazam Mock", async ({ page }) => {
    await setMockPokemon(page, "alakazam");
    await expect(page.locator("h1")).toContainText("Alakazam");
    await expect(page.locator("text=Pokemon #65")).toBeVisible();
    await page.screenshot({ path: "./test-results/screenshots/alakazam.png" });
  });

  test("Dragonite Mock", async ({ page }) => {
    await setMockPokemon(page, "dragonite");
    await expect(page.locator("h1")).toContainText("Dragonite");
    await expect(page.locator("text=Pokemon #149")).toBeVisible();
    await page.screenshot({ path: "./test-results/screenshots/dragonite.png" });
  });

  test("Mewtwo Mock", async ({ page }) => {
    await setMockPokemon(page, "mewtwo");
    await expect(page.locator("h1")).toContainText("Mewtwo");
    await expect(page.locator("text=Pokemon #150")).toBeVisible();
    await page.screenshot({ path: "./test-results/screenshots/mewtwo.png" });
  });
});

↓ mocks/handlers.ts

/**
 * MSW (Mock Service Worker) Handlers
 *
 * This file contains the mock data and default handlers for our Pokemon API.
 * MSW intercepts network requests and returns mock data instead of making real API calls.
 *
 * Learn more about MSW: https://mswjs.io/
 */

import { http, HttpResponse } from "msw";

/**
 * Mock Pokemon data with HTTP status codes
 * This object contains fake Pokemon data and their HTTP response status
 * Each entry has: status (HTTP code) and data (Pokemon info or null for errors)
 */
export const mockData = {
  // Fire-type Pokemon, ID #6
  charizard: {
    status: 200,
    data: {
      name: "charizard",
      id: 6,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/6.png",
      },
    },
  },
  // Electric-type Pokemon, ID #25 (the most famous Pokemon!)
  pikachu: {
    status: 200,
    data: {
      name: "pikachu",
      id: 25,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/25.png",
      },
    },
  },
  // Normal-type Pokemon, ID #133
  eevee: {
    status: 200,
    data: {
      name: "eevee",
      id: 133,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/133.png",
      },
    },
  },
  // Water-type Pokemon, ID #9
  blastoise: {
    status: 200,
    data: {
      name: "blastoise",
      id: 9,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/9.png",
      },
    },
  },
  // Grass-type Pokemon, ID #3
  venusaur: {
    status: 200,
    data: {
      name: "venusaur",
      id: 3,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/3.png",
      },
    },
  },
  // Normal-type Pokemon, ID #39
  jigglypuff: {
    status: 200,
    data: {
      name: "jigglypuff",
      id: 39,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/39.png",
      },
    },
  },
  // Ghost-type Pokemon, ID #94
  gengar: {
    status: 200,
    data: {
      name: "gengar",
      id: 94,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/94.png",
      },
    },
  },
  // Fighting-type Pokemon, ID #68
  machamp: {
    status: 200,
    data: {
      name: "machamp",
      id: 68,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/68.png",
      },
    },
  },
  // Psychic-type Pokemon, ID #65
  alakazam: {
    status: 200,
    data: {
      name: "alakazam",
      id: 65,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/65.png",
      },
    },
  },
  // Dragon-type Pokemon, ID #149
  dragonite: {
    status: 200,
    data: {
      name: "dragonite",
      id: 149,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/149.png",
      },
    },
  },
  // Psychic-type Pokemon, ID #150
  mewtwo: {
    status: 200,
    data: {
      name: "mewtwo",
      id: 150,
      sprites: {
        front_default:
          "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/150.png",
      },
    },
  },
  // Server error for testing error handling
  error500: {
    status: 500,
    data: null,
  },
};

/**
 * Single handler factory function
 * Creates handlers for any port - used by both single and multi-port setups
 * 
 * By default, we return Charizard data when the Pokemon API is called
 * Tests can override this behavior using server.use() in server.ts
 */
export const createHandlers = (port: number) => [
  // Intercept GET requests to the Pokemon API endpoint
  http.get(`http://localhost:${port}/api/v2/pokemon/charizard`, () => {
    console.log(`MSW[${port}]: → returning charizard data (default handler)`);
    return HttpResponse.json(mockData.charizard.data);
  }),
];

↓ mock-server.ts

/**
 * Mock Server - API Bridge between Tests and MSW
 *
 * This server acts as a bridge between our Playwright tests and the MSW (Mock Service Worker).
 * Since tests run in a separate process from the mock server, we need HTTP endpoints
 * to communicate between them.
 *
 * What this server does:
 * 1. Starts up MSW to intercept API calls
 * 2. Provides HTTP endpoints that tests can call to change mock behavior
 * 3. Forwards other requests to be processed by MSW
 * 4. Can spawn multiple server instances for parallel testing
 */

import http from "http";
import type { IncomingMessage, ServerResponse } from "http";
import { spawn } from 'child_process';
import { config } from 'dotenv';
import { createServer, createSetMockPokemon } from "./src/mocks/server.ts";

// Load environment variables from .env file
config();

// Check MOCK_SERVER_COUNT to determine if we should spawn multiple servers
const mockServerCount = parseInt(process.env.MOCK_SERVER_COUNT || '1');

if (mockServerCount > 1) {
  // Multi-server mode - spawn multiple instances
  const basePort = 3001;

  console.log(`Starting ${mockServerCount} mock servers...`);

  const processes: any[] = [];

  for (let i = 0; i < mockServerCount; i++) {
    const port = basePort + i;
    const child = spawn('npx', ['tsx', 'mock-server.ts', port.toString()], {
      stdio: 'inherit',
      shell: true,
      env: { ...process.env, MOCK_SERVER_COUNT: '1' }
    });

    processes.push(child);
    console.log(`Started mock server on port ${port}`);
  }

  process.on('SIGINT', () => {
    console.log('\nShutting down all mock servers...');
    processes.forEach(proc => proc.kill());
    process.exit(0);
  });

} else {
  // Single server mode
  // Get port from command line argument
  const port: number = parseInt(process.argv[2]) || 3001;

  console.log(`Starting MSW server on port ${port}`);

  // Create MSW server instance using single server factory
  const mswServer = createServer(port);

  // Function to switch mock Pokemon data using single factory
  const setMockPokemon = createSetMockPokemon(port, mswServer);

  // Start listening for requests with MSW
  // 'bypass' means unhandled requests will pass through normally
  mswServer.listen({
    onUnhandledRequest: "bypass",
  });

  console.log(
    `✅ MSW server on port ${port} is now intercepting requests in Node.js environment`
  );

  /**
   * HTTP Server - Bridge between tests and MSW
   * This server provides API endpoints that tests can call to control MSW behavior
   */
  const server = http.createServer(
    async (req: IncomingMessage, res: ServerResponse) => {
      console.log(`📨 Port ${port}: Received request: ${req.method} ${req.url}`);

      /**
       * API Endpoint: POST /api/switch-pokemon
       *
       * This endpoint allows tests to switch which Pokemon data MSW returns.
       * Tests send a POST request with { pokemon: "pikachu" | "eevee" | "charizard" }
       * and we use server.use() to override the mock behavior.
       */
      if (req.url === "/api/switch-pokemon" && req.method === "POST") {
        let body = "";

        // Collect the request body data
        req.on("data", (chunk) => (body += chunk.toString()));

        // Process the request when all data is received
        req.on("end", () => {
          const { pokemon } = JSON.parse(body);

          // Call our MSW server function to switch the Pokemon data
          // This uses server.use() internally to override the default handler
          setMockPokemon(pokemon);
          console.log(`🔄 Port ${port}: Switched mock data to: ${pokemon}`);

          // Send success response back to the test
          res.writeHead(200, { "Content-Type": "application/json" });
          res.end(JSON.stringify({ message: `Switched to ${pokemon}` }));
        });
        return;
      }

      /**
       * Handle other requests (not our special API endpoints)
       *
       * For requests that aren't our control APIs, we attempt to process them
       * through MSW. This allows MSW to intercept and mock the responses.
       */
      try {
        // Forward the request to MSW for processing
        const url = `http://localhost:${port}${req.url}`;
        const response = await fetch(url, {
          method: req.method,
          // Forward all headers except 'host' to avoid conflicts
          headers: Object.fromEntries(
            Object.entries(req.headers).filter(([key]) => key !== "host")
          ),
        });

        // Return the MSW response back to the client
        // Handle both JSON and non-JSON responses (like 500 errors with null content)
        let data;
        try {
          data = await response.json();
        } catch {
          data = null; // For responses like 500 errors that don't have JSON content
        }

        res.writeHead(response.status, { "Content-Type": "application/json" });
        res.end(data ? JSON.stringify(data) : null);
      } catch (error) {
        // Handle any errors that occur during request processing
        console.error(`❌ Port ${port}: Error processing request:`, error);
        res.writeHead(500, { "Content-Type": "application/json" });
        res.end(JSON.stringify({ error: "Internal server error" }));
      }
    }
  );

  /**
   * Start the bridge server
   * This server will accept requests from tests and forward them to MSW
   */
  server.listen(port, () => {
    console.log(`🚀 Mock bridge server listening on port ${port}`);
    console.log(
      `📡 Port ${port}: Ready to receive test commands and forward API requests to MSW`
    );
  });

  /**
   * Clean shutdown handling
   * When the process is terminated (Ctrl+C), gracefully close both servers
   */
  process.on("SIGINT", () => {
    console.log(`\n🔄 Port ${port}: Shutting down servers...`);

    // Close MSW server
    mswServer.close();

    // Close HTTP bridge server
    server.close();

    console.log(`✅ Port ${port}: Servers closed successfully`);
    process.exit(0);
  });
}

↓ .env

MOCK_SERVER_COUNT=6

↓ Set playwright.config.ts
① Delete comment out (//) of
baseURL: 'http://localhost:3000',
② Delete comment out (//) of
import dotenv from "dotenv";
import path from "path";
dotenv.config({ path: path.resolve(__dirname, ".env") });
③ Change fullyParallel to
fullyParallel: true, (default)
④ Change workers to
workers: parseInt(process.env.MOCK_SERVER_COUNT || "4"),
⑤ Comment out projects of firefox and webkit

↓ Run mock server (terminal 1)

npx tsx mock-server.ts

↓ Run Next.js (terminal 2)

npm run dev

↓ Run Playwright test (terminal 3)

npx playwright test

Outro

In my previous code, Playwright + MSW tests for Next.js SSR API could only run sequentially.🚀 But in the new code, tests can run in parallel according to your PC's specifications and speed up.🚀🚀🚀🚀 Although I still need to learn more about effective testing.

I hope you learned something from this post.😊
Thank you for reading.
Happy AI coding!🤖