playwright-request-mocker

Automatically generate and use network request mocks inside Playwright!

Features :mag_right:

Mocking your API requests takes too much precious development time, this library strives to make it effortless by:

• Allowing you to declare just once the hook use, it finds the mock file;
• If the mock file does not exist yet, it will open a Playwright's chromium tab, and record all your XHR requests and responses;
• It'll automatically intercept all registered HTTP requests defined in the mock file for any future runs.

Install :construction_worker:

1. Install the package:
   • npm install playwright-request-mocker -D
   • or yarn add playwright-request-mocker -D;
2. Be sure to have @playwright/test also installed.

Using :electric_plug:

1. Add to a .spec file, inside a beforeEach or test method, the hook call useNetworkRecordMocks passing the test context page, identifier of the mock (only necessary if each test scenario has a different mock), and a route to be used by the recording tab if there is no mock file yet;

   • e.g.

     
     import { useNetworkRecordMocks } from 'playwright-request-mocker';          // if using .mjs / .ts
     // const { useNetworkRecordMocks } = require('playwright-request-mocker');  //if using .js

test.describe('Your test', () => { // If your network requests/responses are the same for every test scenario, define it here. test.beforeEach(async ({ page }) => { await useNetworkRecordMocks(page, { recordRoute: ${process.env.APP_URL}/page-you-are-testing, });

await page.goto(`${process.env.APP_URL}/page-you-are-testing`);

});

// else use it here if each test scenario expects different results. test('scenario1', async ({ page }) => { // It'll generate a new file if it does not exist (".spec.scenario1.mocks.json") // then it'll read it and mock all defined network requests. await useNetworkRecordMocks(page, { identifier: 'scenario1', recordRoute: ${process.env.APP_URL}/page-you-are-testing });

await page.goto(`${process.env.APP_URL}/page-you-are-testing`);

//... your steps and asserts.

}); });

1. Run in debug mode;
- PWDEBUG=console forces Playwright to run headed, disables the timeouts and shows the console helper. 

// Linux/macOS PWDEBUG=console npm run playwright test

// Windows on cmd.exe set PWDEBUG=console npm run playwright test

// Windows on PowerShell $env:PWDEBUG="console" npm run playwright test

- If the mock file does not exist yet, it'll open a new tab and will be recording all the XHR requests as you navigate. When you think you recorded everything you needed, press the resume button in the ``playwright/test`` UI.
- After it, or if the mock file ever exists, it will use the results to run your test scenario.

### How it works :question:

- useNetworkRecordMocks checks if there is a file ``[invoker-file-name].mocks.json`` (or ``[invoker-file-name].[identifier].mocks.json``), if it doesn't exists, it'll open a chromiun tab using chrome's [recordHAR](https://en.wikipedia.org/wiki/HAR_(file_format)) option. When the Playwright debug mode is unpaused, it'll process such file removing every request other than XHR ones;
- useNetworkRecordMocks will parse the existing file, and mock every request declared on it.

### Different use cases :footprints:

- **For a given test scenario, I need to change the mocked value**: there are 3 ways to achieve this, 1 being creating a new specific mock file at each scenario (by calling useNetworkRecordMocks inside each test with a identifier), and others being overriding the route response, like the following:

Overriding approach: for when the ``useNetworkRecordMocks`` call is inside the test scenario:
``` ts
  import { useNetworkRecordMocks, mockRouteResponse } from 'playwright-request-mocker';

  // [...]

  test('my different scenario', async ({
    page,
  }) => {
    const errorMessage = 'error message I expect';

    await useNetworkRecordMocks(page, {
      recordRoute: `${process.env.APP_URL}/page-you-are-testing`,
      overrideResponses: {
        "/ENDPOINT_TO_CHANGE": { errors: [{ message: errorMessage }] }
      }
    });

    await page.goto(`${process.env.APP_URL}/page-you-are-testing`);

    await Promise.all([
      page.waitForRequest('**/ENDPOINT_TO_CHANGE'),
      fillForm(page),
    ]);

    await page.waitForSelector(`text=${errorMessage}`);
    const visible = await page.isVisible(`text=${errorMessage}`);
    expect(visible).toBeTruthy();
  });

Unrouting approach: for when the useNetworkRecordMocks call is inside a beforeEach:

test.describe('Test', () => {
  test.beforeEach(async ({ page }) => {
    await useNetworkRecordMocks(page, {
      recordRoute: `${process.env.APP_URL}/page-you-are-testing`,
    });

    await page.goto(`${process.env.APP_URL}/page-you-are-testing`);
  });

  test('my different scenario', async ({
    page
  }) => {
    const errorMessage = 'error message I expect';

    page.unroute('**/ENDPOINT_TO_CHANGE');
    mockRouteResponse(
      page,
      '**/ENDPOINT_TO_CHANGE',
      { errors: [{ message: errorMessage }] },
      400,
    );

    await Promise.all([
      page.waitForRequest('**/ENDPOINT_TO_CHANGE'),
      fillForm(page),
    ]);

    await page.waitForSelector(`text=${errorMessage}`);
    const visible = await page.isVisible(`text=${errorMessage}`);
    expect(visible).toBeTruthy();
  });
}

• I want to assert the payload sent against what was expected: useNetworkRecordMocks returns every mocked request payload, you can use it to assert the values:

  test('my different scenario', async ({
    page,
  }) => {

    const requests = await useNetworkRecordMocks(
      page,
      {
        recordRoute: `${process.env.APP_URL}/test-route`,
      }
    );

    const [req] = await Promise.all([
      page.waitForRequest('**/ENDPOINT_TO_TEST'),
      fillForm(page),
    ]);

    const expectedPayload = requests.find(r => r.url.includes('ENDPOINT_TO_TEST'))?.requestData;

    expect(expectedPayload).toStrictEqual(req.postDataJSON());

  });

• I already have a HAR recorded file that I want to use: as long as it follows the same name structure as the file that is using it, the lib will prioritize it over recording a new one to generate the new mocks.json file:

  
  /tests
  |- my-test.spec.js
  |- my-test.spec.har
  |- my-test.spec.identifier.har

----

Feel free to contribute, report bugs, or [contact me](https://github.com/kousenlsn).