Overriding MSW handlers in Playwright

[d-ivashchuk]

Hey @kettanaito & maintainers! I have a use case where I run programatic Playwright executions where I need to overwrite the MSW handlers in the following fashion:

const context = await browser.newContext();
const page = await context.newPage();

await page.evaluate(()=>{
 const { worker, rest } = window.msw;

    worker.use(
          rest.post('/login', (req, res, ctx) => {
            return res(ctx.json({ success: true }))
          }),
        )
// expect runtime msw /login route to return mocked response now, even thought this handler has not being defined in advance
})

I think Playwright does not have the msw in its window context so this makes the things harder than I expected. It's just pseudocode to demonstrate what I want to achieve in the end so if there is any better solution to such problem - I'd be very eager to look into that as well.

[kettanaito]

Hey, @d-ivashchuk.

I think Playwright does not have the msw in its window context so this makes the things harder than I expected.

I think that's the main culprit. You need to set window.msw in your browser context. For example, when opening an app with Playwright, you'd have to go through the Browser integration of MSW in your app:

// src/index.js
// Also a pseudo-code, please refer to the docs!
worker.start()

window.worker = worker // <- this

When Playwright opens your app, it will have window.msw because your application sets it.

Given that everything you send to Playwright from the test undergoes serialization, the best option is to set window.msw in your application directly (you can't do page.evalute() and pass it a worker reference from a test).

[kettanaito]

This is also how we test the library (we're using Playwright and test how MSW behaves in the actual browser):

Mock definition (read: your app)

msw/test/msw-api/setup-worker/use.mocks.ts

Lines 12 to 17 in ec57fbf

	// Propagate the worker and `rest` references to be globally available.
	// This would allow to modify request handlers on runtime.
	window.msw = {
	worker,
	rest,
	}

Accessing window.msw in Playwright

msw/test/msw-api/setup-worker/use.test.ts

Lines 17 to 25 in ec57fbf

	await runtime.page.evaluate(() => {
	const { msw } = window
	msw.worker.use(
	msw.rest.post('/login', function postLoginResolver(req, res, ctx) {
	return res(ctx.json({ accepted: true }))
	}),
	)
	})

[d-ivashchuk]

Thanks, it's already very much enough for me to try out next steps 🙏🏼

[ScubaDaniel]

Thanks for this work-around! I've been trying to use playwright-msw, but can't get it working.

Do you guys have any plans to integrate with Playwright a bit better? It'd be great if every override didn't need the page.evaluate and window spread for msw. I don't really see a way to create a fixture with this as you can't serialize a function in Playwright unless you make it a string to "eval".

[valendres]

Thanks for sharing this library @ScubaDaniel. Unfortunately, there was a breaking change in msw@0.47.1 that broke compatibility with playwright-msw. This breaking change has now been addressed.

I have provided an alternative answer in #1322 (comment) that covers this library in more detail.

[valendres]

Another way to easily override handlers on a per test basis in Playwright is to use my playwright-msw library. This library utilises fixtures with routes to facilitate mocking API calls on a per test basis instead of the page.evaluate method as described in @kettanaito's answer: #1322 (reply in thread). This library effectively hoists the mocking into the playwright layer, which means we can not only avoid dealing with the serialization limitations, we can also build, test and deploy the exact same production bundle using a CI/CD pipeline, without having to run a separate dev server with MSW running in it.

An example of what this mocking looks like can be seen in the docs:

test.describe.parallel("A demo of playwright-msw's functionality", () => {
  test("should use the default handlers without requiring handlers to be specified on a per-test basis", async ({
    page,
  }) => {
    await page.goto("/");
    await expect(page.locator('text="Alessandro Metcalfe"')).toBeVisible();
  });

  test.only("should allow mocks to be overridden on a per test basis", async ({
    page,
    worker,
  }) => {
    await worker.use(
      rest.get("/api/users", (_, response, context) =>
        response(context.delay(250), context.status(403))
      )
    );
    await page.goto("/");
    await expect(page.locator('text="Alessandro Metcalfe"')).toBeHidden();
    await expect(page.locator('text="Failed to load users"')).toBeVisible();
  });
});

If you're interested, feel free to try the library out and reach out if you have any questions 🙂

[chrisb2244]

Possibly silly question, given that I think this is the exact purpose of your library (I hope...) but does this allow me to handle the following situation (I tried below with just MSW but failed, but if you tell me it should work either with playwright-msw, or just msw, then I'll be more confident actually continuing... (and choosing the correct library/ies)

I have an internal library call that I want to replace, this is internally called by an API route (using Next).
I'd like the API route to run normally (or as normally as possible, below I have an if which is changing the behaviour, undesirable but :/ ) but the library call to be replaced with something I can receive in the Playwright test.

Something like

// my-api-route.tsx
import { myLibraryFunction } from '@/lib/functionFile'

const handler: NextApiHandler = async (req, res) => {
    // check stuff with req, blah blah
    const IS_ONLY_FOR_TESTING = req.headers.test_only_header_here
    const TEST_ENDPOINT_URL = req.headers.test_only_header_here as string // undefined if above is false

    // This is ugly, but it seems to work. A better alternative would be great if you know one...
    if (IS_ONLY_FOR_TESTING) { 
        // TEST_ENDPOINT_URL is a string
        console.log('Running the test alternative') // Shows up in the 'next' log
        await fetch(TEST_ENDPOINT_URL, {
            method: 'POST',
            body: JSON.stringify(content) // <-- This is fine, but a workaround
        })
    } else {
        myLibraryFunction(content) // <-- This is the content I want to get in the test
    }
}

// .../lib/functionFile.ts
// Don't want this available in general, so don't want to make this method a separate
// API route (or you could call it directly without the handler's validation code above)
// (even as an API route, you still can't get the KEY on the client, but you could trigger the method)
const API_KEY = process.env.SECRET_KEY 

export const myLibraryFunction = async (data: DataType) => {
   // do stuff with API_KEY
}

Conceivably I could check process.env.PLAYWRIGHT in this file above, and then have different behaviour, but I'd prefer not to - and that would also a) still require a way to get data to the test, and b) probably be harder to change for different tests.

// test-file.spec.ts
import { expect } from '@playwright/test'
import test from './my-fixture' // Adds the MSW handler, looks like I'm doing this wrong?

test('blah', async ({page, baseURL, requestInterceptor, rest}) => {
  const dummyRoute = 'this-doesnt-really-matter'
  const dummyEndpoint = baseURL + dummyRoute
  const requests: any[] = []
  
  await page.route('/api/my-api-route', (route, request) => {
    console.log('Routed via Playwright') // Shows up as expected
    route.continue({
      headers: {
        ...request.headers(),
        // headers are converted to lower case... write in lower case to avoid confusion
        test_only_header_here: dummyEndpoint
      }
    })
  });

  // Can't get this bit to work :/
  routeInterceptor.use(
    rest.post(dummyEndpoint, (req, res, ctx) => {
        console.log('Caught post request: ', req.url)
        req.json().then(data => {
          requests.push(data)
          console.log(data)
        })
        return res(ctx.status(200))
    })
  )

  // check the content of requests: any[], always empty when should have length 1.

}

// my-fixture.ts
import { test as base } from '@playwright/test'
import { rest } from 'msw'
import type { SetupServerApi } from 'msw/node'
import { server as requestInterceptor } from './mocks/server'

const test = base.extend<{
  requestInterceptor: SetupServerApi
  rest: typeof rest
}>({
  requestInterceptor: [
    async ({}, use) => {
      console.log('line before')
      console.log(requestInterceptor)
      console.log('line after')
      await use(requestInterceptor)
    }, {
      //@ts-ignore
      scope: 'worker', // test?
    }
  ],
  rest,
})

export default test

Adding the handlers is done as shown in https://github.com/vercel/next.js/tree/canary/examples/with-msw and I've added matching for both '/api/this-doesnt-really-matter' and baseURL + '/api/this-doesnt-really-matter' and similar, both in the test (where I'd like to add it) and in the handlers file they describe there (in case the problem was having the startServer(...handlers) not pick it up appropriately.

The console lines in the fixture seem to be fine, and do reflect an object with listen, use, restoreHandlers functions, etc (which are also available then in the test as requestInterceptor).

With this in my _app.tsx file, the 'loading mocks' appears as expected (in the next dev instance, running in a Docker container (also, killing that breaks all the tests, so it does seem to be connecting to the expected site/URL/port)):

if (process.env.PLAYWRIGHT === '1') {
  console.log('loading mocks')
  require('../../playwright/mocks')
} else {
  console.log('not loading mocks')
}

[chrisb2244]

Somewhat confusingly (since my paths are not relative to some basePath/baseURL), at least to me, adding the headers specified here #690 (comment) allowed the server to provide handlers. That doesn't get my response into the test yet, but it did allow at least some part of MSW to catch the fetch (which makes me believe perhaps I just need to include something differently, probably in the test code?)

[valendres]

@chrisb2244, it might be better to raise this a discussion post or issue on https://github.com/valendres/playwright-msw if you're asking specifically about how to integrate this library with next.js.

I'll be honest, I'm not very familiar with next.js, so my ability to help here is rather limited. From what I'm understanding, you're wanting to intercept the API call using playwright so that you can add some special headers, then allow that request to be handled by your next.js server. Then within the next.js server, you're performing an API call that you wish to intercept and mock. If that's the case, then it's not possible to rely on playwright-msw (or potentially even msw directly) for this use case. playright-msw is designed to intercept API calls performed by your browser, not those that are performed by a server that your browser is actually hitting.

What I'd recommend doing is setting up your requestInterceptor so that it's explicitly using the test scope:

import { rest } from "msw";
import type { MockServiceWorker } from "playwright-msw";
import { createServer } from "playwright-msw";

import handlers from "../../mocks/handlers";

const test = base.extend<{
  requestInterceptor: MockServiceWorker;
  rest: typeof rest;
}>({
  requestInterceptor: [
    async ({ page }, use): Promise<void> => {
      const server = await createServer(page, ...getHandlers());
      await use(server);
    },
    {
      /**
       * Scope this fixture on a per test basis to ensure that each test has a
       * fresh copy of MSW.
       */
      scope: "test",
      /**
       * By default, fixtures are lazy; they will not be initalised unless they're
       * used by the test. Setting `true` here means that the fixture will be auto-
       * initialised even if the test doesn't specifically.
       */
      auto: true,
    },
  ],
  rest,
});

export default test

Once you have done that, use the requestInterceptor to intercept/mock API calls performed by the browser. My recommendation would be to mock the entire endpoint and not manipulate the behaviour based on special headers or detecting whether playwright is currently running. If you need to do special behaviour for playwright, do it within the mock handler, not on the server.

  routeInterceptor.use(
    // Replace the full implementation of '/api/my-api-route' so that we can add custom behaviour
    rest.post('/api/my-api-route', async (req, res, ctx) => {
       // Record the data from the request
       const data = await request.json();
       requests.push(data)

       // Insert some custom behaviour here
       await doSomethingSpecial();

        return res(ctx.status(200))
    })
  )

IMO, one should try to avoid adding playwright or test specific logic within their UI or API as much as possible. As doing so can result in security vulnerabilities. It's often better to make your application behave the same way as the user would use it, and leverage playwright-msw to intercept/manipulate API calls performed by the browser where appropriate.

[chrisb2244]

@valendres Thanks for the pointers. I now have a better understanding of at least part of how this works :) I suspect the problem I'm having is related to either an endpoint that does too much, or a desire to change only small parts of a larger system.

I managed to get something working by setting up an HTTP server in my test code, and then passing that server's endpoint URL via a header, but this does mean including test code in the real system, which as you pointed out, is pretty undesirable.
Example code, if curious, is below:

// utils file
import { IncomingMessage } from 'http';
import { networkInterfaces } from 'os';

const results = Object.create(null);
const nets = networkInterfaces()
for (const name of Object.keys(nets)) {
  for (const net of nets[name]) {
    const familyV4Value = typeof net.family === 'string' ? 'IPv4' : 4
      if (net.family === familyV4Value && !net.internal) {
          if (!results[name]) {
              results[name] = [];
          }
          results[name].push(net.address);
      }
  }
}

export const reqToBody = (req: IncomingMessage, callback: (body: string) => void) => {
  let body = ''
  req.on('data', (chunk) => {
    body += chunk
  })
  req.on('end', () => {
    callback(body)
  })
}

export const localIP = results['eth0'][0]

//playwright test file
import http from 'http'
import { localIP, reqToBody as parseRequestBody } from './utils';

const dummyServer = http.createServer()
// This uses beforeAll(), might need beforeEach and a dynamic port for parallel tests, or something...
test.beforeAll(() => {
  dummyServer.listen(3001)
})
test.afterAll(() => {
  dummyServer.close()
})

test('User can log-in', async ({page}) => {
  const testAddress = 'http://' + localIP + ':3001' + '/testEndpoint'
  const requests: any[] = [];

  dummyServer.addListener('request', (req, res) => {
    console.log('Caught with dummyServer')
    parseRequestBody(req, (body) => {
      const jbody = JSON.parse(body)
      requests.push(jbody)
    })
    res.writeHead(200)
    return res.end()
  })

  await page.route('/api/auth_links/*', (route, request) => {
    console.log('Routed auth_links via PW')
    route.continue({
      headers: {
        ...request.headers(),
        // headers are converted to lower case... write in lower case to avoid confusion
        test_only_headers_blocked: testAddress
      }
    })
  });

  await page.goto('/');
  // ... do test stuff
  expect(requests).toHaveLength(1)
  // assert something about the content of the JSON object in requests[0]
}

// real API route (containing test code - problem...)
const handler: NextApiHandler = async (req, res) => {
  const IS_TEST_ONLY_DO_NOT_SEND_EMAILS = typeof(req.headers.test_only_headers_blocked) !== 'undefined'
  const TEST_EMAIL_ENDPOINT_URL = req.headers.test_only_headers_blocked as string // This is actually undefined if IS_TEST_ONLY... is not true
  console.log(`This method is being executed in ${IS_TEST_ONLY_DO_NOT_SEND_EMAILS ? 'test' : 'production'}`)

  // ... lots more stuff

      if (IS_TEST_ONLY_DO_NOT_SEND_EMAILS) {
        console.log('Not sending email - testing only due to header')
        console.log('Attempting to post to: ' + TEST_EMAIL_ENDPOINT_URL)
        await fetch(TEST_EMAIL_ENDPOINT_URL, {
          method: 'POST',
          body: JSON.stringify(content)
        })
        return {
          status: null,
          user
        }
      } else {
        return {
          status: await sendMailApi(content),
          user
        }
      }

Indeed, writing this up and reading through, I can see the obvious security hole, so ensuring this was excluded from production-deployed code would be important... (although there are some more checks in this endpoint on authentication, but still - in the way written here, anyone can have the content sent to anywhere they like, simply by adding a header).
A simple block for that is to include a check for something like process.env.NODE_ENV === 'test', but reworking to use MSW or similar would be nicer.

[thaynarbo]

The application I'm currently working uses react query, if an action is triggered to change the status of a card and it is sucessful, I invalidate the query for the list to refetch, and then I wanted the new data to show. I tried to use the dynamic mock scenarios, but then the first request to the list would come with the status I wanted after triggering the action. To solve this problem, I used playwright addExtraHeaders method from the fixture
ex: await page.setExtraHTTPHeaders({})
I only add the extraHTTPHeaders before the action is triggered so first the list comes with all the options I have as default, then I add the extra headers before the click that triggers the action and then when the action is successful and calls the list again, the headers are there and the return from the handler works.

I had to add page.setExtraHTTPHeaders({}) at the end of my test otherwise other tests would use those headers and the list would be different for other assertions, causing some tests to fail.

Hope that helps anyone who came to this discussion because tried worker.use() inside playwright