Skip to main content

Mocky Balboa and Playwright

How to use Mocky Balboa with Playwright.

Supported versions

≥ 1.x.x

Installation​

pnpm add -D @mocky-balboa/playwright

Usage​

Below is a basic example of how to use Mocky Balboa to mock a network request from directly within your Playwright tests.

import { expect } from "@playwright/test";
import test from "@mocky-balboa/playwright/test";

test("my page loads", async ({ page, mocky }) => {
  // Register our fixture on routes matching '**/api/users'
  mocky.route("**/api/users", (route) => {
    return route.fulfill({
      status: 200,
      body: JSON.stringify([
        { id: "user-1", name: "John Doe" },
        { id: "user-2", name: "Jane Doe" }
      ]),
      headers: {
        "Content-Type": "application/json"
      },
    });
  });

  // Visit the page of our application in the browser
  await page.goto("http://localhost:3000");

  // Our mock above should have been returned on our server
  await expect(page.getByText("John Doe")).toBeVisible();
});

Extending test​

If you are already extending Playwrights test you'll need to either extend the test exported on @mocky-balboa/playwright/test or utilise the exported extendTest function.

Extending directly:

import test from "@mocky-balboa/playwright/test";

const myExtendedTest = test.extend({
  // ...
});

Using extendTest:

import { test } from "@playwright/test";
import { extendTest } from "@mocky-balboa/playwright/test";

const myExtendedTest = extendTest(test.extend({
  // ...
}));

extendTest allows you to compose multiple integrations that may run test.extend without having to use Mocky Balboa as the base test.

Configuring connection options​

If you are using the Mocky Balboa test object you can define the connection parameters for the client on a per test basis in test.beforeEach or at a global level on extendTest.

Extending in test.beforeEach:

import { expect } from "@playwright/test";
import test from "@mocky-balboa/playwright/test";

/**
 * If you are using `mocky` in a beforeEach hook make sure you
 * update the mockyConnectOptions in it's own isolated
 * beforeEach hook first, otherwise the mocky instance will
 * try and connect using the global or default options.
 */
test.beforeEach(({ mockyConnectOptions }) => {
  // Set the WebSocket server port for connecting to
  mockyConnectOptions.port = 1234;

  // Custom timeout for waiting on requests from the server
  mockyConnectOptions.timeout = 10000;
});

Extending globally with extendTest:

import { test } from "@playwright/test";
import { extendTest } from "@mocky-balboa/playwright/test";

const myExtendedTest = extendTest(test.extend({
  // ...
}), {
  // Override the websocket server port
  port: 1234,
  // Custom timeout for waiting on requests from the server
  timeout: 10000,
});

Opting out of test.extend​

You don't need to use the test object exported from @mocky-balboa/playwright/test. This might be the case if you are testing multiple applications from the same test suite where not all applications have an embedded Mocky Balboa server. For this you can manage your own instance of the client.

import { test, expect } from "@playwright/test";
import { createClient } from "@mocky-balboa/playwright";

test("my page loads", async ({ page }) => {
  // Optionally pass connection options here
  const mocky = createClient();

  // Register our fixture on routes matching '**/api/users'
  mocky.route("**/api/users", (route) => {
    return route.fulfill({
      status: 200,
      body: JSON.stringify([
        { id: "user-1", name: "John Doe" },
        { id: "user-2", name: "Jane Doe" }
      ]),
      headers: {
        "Content-Type": "application/json"
      },
    });
  });

  // Visit the page of our application in the browser
  await page.goto("http://localhost:3000");

  // Our mock above should have been returned on our server
  await expect(page.getByText("John Doe")).toBeVisible();
});

Further usage​

  1. See the client guide for more information on how you can setup routes via the mocky client.
  2. See the route guide for more information on how you can interact interact with routes on mocky.route.
  3. See the advanced page for more information on advanced usage and how the framework works under the hood.