Concept: test mode for Playwright and similar integration tools (vercel#52520)

An experimental test mode that enables integration tests to mock server-side fetch requests in Playwright tests.

For explanation on how this works, see the [`next-playwright/README.md`](https://github.com/vercel/next.js/pull/52520/files#diff-3b8da7782c16f015df5afafe0ac11247f5b8e5a1c0dbede341ca2b5124dfd924).

Author: dvoytenko

packages/next/experimental/testmode/playwright.d.ts

@@ -0,0 +1 @@
+export * from '../../dist/experimental/testmode/playwright'

packages/next/experimental/testmode/playwright.js

@@ -0,0 +1 @@
+module.exports = require('../../dist/experimental/testmode/playwright')

packages/next/experimental/testmode/playwright/msw.d.ts

@@ -0,0 +1 @@
+export * from '../../../dist/experimental/testmode/playwright/msw'

packages/next/experimental/testmode/playwright/msw.js

@@ -0,0 +1 @@
+module.exports = require('../../../dist/experimental/testmode/playwright/msw')

packages/next/experimental/testmode/proxy.d.ts

@@ -0,0 +1 @@
+export * from '../../dist/experimental/testmode/proxy'

packages/next/experimental/testmode/proxy.js

@@ -0,0 +1 @@
+module.exports = require('../../dist/experimental/testmode/proxy')

packages/next/package.json

@@ -61,7 +61,13 @@
     "headers.d.ts",
     "navigation-types",
     "web-vitals.js",
-    "web-vitals.d.ts"
+    "web-vitals.d.ts",
+    "experimental/testmode/playwright.js",
+    "experimental/testmode/playwright.d.ts",
+    "experimental/testmode/playwright/msw.js",
+    "experimental/testmode/playwright/msw.d.ts",
+    "experimental/testmode/proxy.js",
+    "experimental/testmode/proxy.d.ts"
   ],
   "bin": {
     "next": "./dist/bin/next"
@@ -143,6 +149,7 @@
     "@next/react-refresh-utils": "13.4.15",
     "@next/swc": "13.4.15",
     "@opentelemetry/api": "1.4.1",
+    "@playwright/test": "^1.35.1",
     "@segment/ajv-human-errors": "2.1.2",
     "@taskr/clear": "1.1.0",
     "@taskr/esnext": "1.1.0",
@@ -245,6 +252,7 @@
     "lru-cache": "5.1.1",
     "micromatch": "4.0.4",
     "mini-css-extract-plugin": "2.4.3",
+    "msw": "^1.2.2",
     "nanoid": "3.1.32",
     "native-url": "0.3.4",
     "neo-async": "2.6.1",
@@ -283,6 +291,7 @@
     "stacktrace-parser": "0.1.10",
     "stream-browserify": "3.0.0",
     "stream-http": "3.1.1",
+    "strict-event-emitter": "0.5.0",
     "string-hash": "1.1.3",
     "string_decoder": "1.3.0",
     "strip-ansi": "6.0.0",

packages/next/src/cli/next-dev.ts

@@ -189,6 +189,7 @@ const nextDev: CliCommand = async (argv) => {
     '--hostname': String,
     '--turbo': Boolean,
     '--experimental-turbo': Boolean,
+    '--experimental-test-proxy': Boolean,
 
     // To align current messages with native binary.
     // Will need to adjust subcommand later.
@@ -274,13 +275,15 @@ const nextDev: CliCommand = async (argv) => {
   // some set-ups that rely on listening on other interfaces
   const host = args['--hostname']
   config = await loadConfig(PHASE_DEVELOPMENT_SERVER, dir)
+  const isExperimentalTestProxy = args['--experimental-test-proxy']
 
   const devServerOptions: StartServerOptions = {
     dir,
     port,
     allowRetry,
     isDev: true,
     hostname: host,
+    isExperimentalTestProxy,
   }
 
   if (args['--turbo']) {

packages/next/src/cli/next-start.ts

@@ -14,6 +14,7 @@ const nextStart: CliCommand = async (argv) => {
     '--port': Number,
     '--hostname': String,
     '--keepAliveTimeout': Number,
+    '--experimental-test-proxy': Boolean,
 
     // Aliases
     '-h': '--help',
@@ -46,6 +47,8 @@ const nextStart: CliCommand = async (argv) => {
   const host = args['--hostname']
   const port = getPort(args)
 
+  const isExperimentalTestProxy = args['--experimental-test-proxy']
+
   const keepAliveTimeoutArg: number | undefined = args['--keepAliveTimeout']
   if (
     typeof keepAliveTimeoutArg !== 'undefined' &&
@@ -66,6 +69,7 @@ const nextStart: CliCommand = async (argv) => {
   await startServer({
     dir,
     isDev: false,
+    isExperimentalTestProxy,
     hostname: host,
     port,
     keepAliveTimeout,

packages/next/src/experimental/testmode/playwright/README.md

@@ -0,0 +1,96 @@
+# Experimental test mode for Playwright
+
+### Prerequisites
+
+You have a Next.js project.
+
+### Install `@playwright/test` in your project
+
+```sh
+npm install -D @playwright/test
+```
+
+### Optionally install MSW in your project
+
+[MSW](https://mswjs.io/) can be helpful for fetch mocking.
+
+```sh
+npm install -D msw
+```
+
+### Update `playwright.config.ts`
+
+```javascript
+import { defineConfig } from 'next/experimental/testmode/playwright'
+
+export default defineConfig({
+  webServer: {
+    command: 'npm dev -- --experimental-test-proxy',
+    url: 'http://localhost:3000',
+  },
+})
+```
+
+### Use the `next/experimental/testmode/playwright` to create tests
+
+```javascript
+import { test, expect } from 'next/experimental/testmode/playwright'
+
+test('/product/shoe', async ({ page, next }) => {
+  next.onFetch((request) => {
+    if (request.url === 'http://my-db/product/shoe') {
+      return new Response(
+        JSON.stringify({
+          title: 'A shoe',
+        }),
+        {
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        }
+      )
+    }
+    return 'abort'
+  })
+
+  await page.goto('/product/shoe')
+
+  await expect(page.locator('body')).toHaveText(/Shoe/)
+})
+```
+
+### Or use the `next/experimental/testmode/playwright/msw`
+
+```javascript
+import { test, expect, rest } from 'next/experimental/testmode/playwright/msw'
+
+test.use({
+  mswHandlers: [
+    rest.get('http://my-db/product/shoe', (req, res, ctx) => {
+      return res(
+        ctx.status(200),
+        ctx.json({
+          title: 'A shoe',
+        })
+      )
+    }),
+  ],
+})
+
+test('/product/shoe', async ({ page, msw }) => {
+  msw.use(
+    rest.get('http://my-db/product/boot', (req, res, ctx) => {
+      return res.once(
+        ctx.status(200),
+        ctx.json({
+          title: 'A boot',
+        })
+      )
+    })
+  )
+
+  await page.goto('/product/boot')
+
+  await expect(page.locator('body')).toHaveText(/Boot/)
+})
+```