Add next experimental-test command

packages/next/src/bin/next.ts

@@ -10,6 +10,8 @@ import { bold, cyan, italic } from '../lib/picocolors'
 import { formatCliHelpOutput } from '../lib/format-cli-help-output'
 import { NON_STANDARD_NODE_ENV } from '../lib/constants'
 import { myParseInt } from '../server/lib/utils'
+import { SUPPORTED_TEST_RUNNERS_LIST } from '../cli/next-test.js'
+import { getProjectDir } from '../lib/get-project-dir'
 
 if (
   semver.lt(process.versions.node, process.env.__NEXT_REQUIRED_NODE_VERSION!)
@@ -343,6 +345,56 @@ program
       mod.nextTelemetry(options, arg)
     )
   )
-  .usage('[options]')
+
+program
+  .command('experimental-test')
+  .description(
+    `Execute \`next/experimental/testmode\` tests using a specified test runner. Any arguments or options after the optional ${italic(
+      '[directory]'
+    )} and ${italic(
+      '[test runner]'
+    )} arguments will be passed through to the ${italic('[test runner]')}.`
+  )
+  .argument(
+    '[directory]',
+    `A Next.js project directory to execute the test runner on. ${italic(
+      'If no directory is provided, the current directory will be used.'
+    )}`
+  )
+  .option(
+    '-t, --test-runner',
+    `Any supported test runner. Options: ${bold(
+      SUPPORTED_TEST_RUNNERS_LIST.join(', ')
+    )}. ${italic(
+      "If no test runner is provided, the Next.js config option `experimental.defaultTestRunner`, or 'playwright' will be used."
+    )}`
+  )
+  .option(
+    '-a, --test-runner-args [args...]',
+    'Arguments to pass through to the test runner'
+  )
+  .action((directory, options, command) =>
+    import('../cli/next-test.js').then((mod) => {
+      mod.nextTest(directory, options, command)
+    })
+  )
+  .usage('[directory] [options]')
 
 program.parse(process.argv)
+
+/*
+// run default test runner in current directory
+next test
+// run default test runner in `my-project` directory
+next test my-project
+// run `playwright` test runner in current directory
+next test playwright
+// run `playwright` test runner in `my-project` directory
+next test my-project playwright
+// run command `show-report` for default test runner in current directory
+next test show-report
+// run command `show-report` for default test runner in `my-project` directory
+next test my-project show-report
+// run command `show-report` for `playwright` in `my-project` directory
+next test my-project playwright show-report
+*/

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

@@ -0,0 +1,229 @@
+import { existsSync, writeFileSync } from 'fs'
+import { getProjectDir } from '../lib/get-project-dir'
+import { printAndExit } from '../server/lib/utils'
+import loadConfig from '../server/config'
+import { PHASE_PRODUCTION_BUILD } from '../shared/lib/constants'
+import {
+  hasNecessaryDependencies,
+  type MissingDependency,
+} from '../lib/has-necessary-dependencies'
+import { installDependencies } from '../lib/install-dependencies'
+import type { NextConfigComplete } from '../server/config-shared'
+import findUp from 'next/dist/compiled/find-up'
+import { warn } from '../build/output/log'
+import { bold, cyan } from '../lib/picocolors'
+import { findPagesDir } from '../lib/find-pages-dir'
+import { verifyTypeScriptSetup } from '../lib/verify-typescript-setup'
+import path from 'path'
+import {
+  getPkgManager,
+  type PackageManager,
+} from '../lib/helpers/get-pkg-manager'
+import type { Command } from 'commander'
+
+export interface NextTestOptions {
+  testRunner?: string
+  testRunnerArgs?: string[]
+}
+
+export const SUPPORTED_TEST_RUNNERS_LIST = ['playwright'] as const
+export type SUPPORTED_TEST_RUNNERS =
+  (typeof SUPPORTED_TEST_RUNNERS_LIST)[number]
+
+const requiredPackagesByTestRunner: {
+  [k in SUPPORTED_TEST_RUNNERS]: MissingDependency[]
+} = {
+  playwright: [
+    { file: 'playwright', pkg: '@playwright/test', exportsRestrict: false },
+  ],
+}
+
+function isSupportedTestRunner(
+  testRunner: string
+): testRunner is SUPPORTED_TEST_RUNNERS {
+  return testRunner in requiredPackagesByTestRunner
+}
+
+export async function nextTest(
+  directory?: string,
+  options?: NextTestOptions,
+  command?: Command
+) {
+  console.log('directory', directory, 'options', options)
+
+  process.exit(0)
+  // get execution directory
+  const baseDir = getProjectDir(directory)
+
+  // Check if the directory exists
+  if (!existsSync(baseDir)) {
+    printAndExit(`> No such directory exists as the project root: ${baseDir}`)
+  }
+
+  // find nextConfig
+  const nextConfig = await loadConfig(PHASE_PRODUCTION_BUILD, baseDir)
+
+  // set the test runner. priority is CLI option > next config > default 'playwright'
+  const configuredTestRunner =
+    options?.testRunner ??
+    nextConfig.experimental.defaultTestRunner ??
+    'playwright'
+
+  switch (configuredTestRunner) {
+    case 'playwright':
+      return runPlaywright(baseDir, nextConfig, options)
+    default:
+      return printAndExit(
+        `Test runner ${configuredTestRunner} is not supported.`
+      )
+  }
+}
+
+async function checkRequiredDeps(
+  baseDir: string,
+  testRunner: SUPPORTED_TEST_RUNNERS
+) {
+  const deps = await hasNecessaryDependencies(
+    baseDir,
+    requiredPackagesByTestRunner[testRunner]
+  )
+  if (deps.missing.length > 0) {
+    await installDependencies(baseDir, deps.missing, true)
+  }
+}
+
+async function runPlaywright(
+  baseDir: string,
+  nextConfig: NextConfigComplete,
+  options: unknown
+) {
+  await checkRequiredDeps(baseDir, 'playwright')
+
+  const playwrightConfigFile = await findUp(
+    ['playwright.config.js', 'playwright.config.ts'],
+    {
+      cwd: baseDir,
+    }
+  )
+
+  if (!playwrightConfigFile) {
+    const { pagesDir, appDir } = findPagesDir(baseDir)
+
+    const { version: typeScriptVersion } = await verifyTypeScriptSetup({
+      dir: baseDir,
+      distDir: nextConfig.distDir,
+      intentDirs: [pagesDir, appDir].filter(Boolean) as string[],
+      typeCheckPreflight: false,
+      tsconfigPath: nextConfig.typescript.tsconfigPath,
+      disableStaticImages: nextConfig.images.disableStaticImages,
+      hasAppDir: !!appDir,
+      hasPagesDir: !!pagesDir,
+    })
+
+    const isUsingTypeScript = !!typeScriptVersion
+
+    const playwrightConfigFilename = isUsingTypeScript
+      ? 'playwright.config.ts'
+      : 'playwright.config.js'
+
+    const packageManager = getPkgManager(baseDir)
+
+    writeFileSync(
+      path.join(baseDir, playwrightConfigFilename),
+      defaultPlaywrightConfig(isUsingTypeScript, packageManager)
+    )
+  }
+
+  return
+}
+
+const defaultPlaywrightConfig = (
+  typescript: boolean,
+  packageManager: PackageManager
+) => `
+${
+  typescript
+    ? "import { defineConfig, devices } from 'next/experimental/testmode/playwright'"
+    : "const { defineConfig, devices } = require('next/experimental/testmode/playwright')"
+};
+
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// require('dotenv').config();
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+${
+  typescript
+    ? 'export default definedConfig({'
+    : 'module.exports = defineConfig({'
+}
+  /* Match all co-located test files within app and pages directories*/
+  testMatch: '{app,pages}/**/*.spec.{t,j}s',
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Opt out of parallel tests on CI. */
+  workers: process.env.CI ? 1 : undefined,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: 'html',
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like \`await page.goto('/')\`. */
+    baseURL: 'http://127.0.0.1:3000',
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: 'on-first-retry',
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    /* Test against mobile viewports. */
+    // {
+    //   name: 'Mobile Chrome',
+    //   use: { ...devices['Pixel 5'] },
+    // },
+    // {
+    //   name: 'Mobile Safari',
+    //   use: { ...devices['iPhone 12'] },
+    // },
+
+    /* Test against branded browsers. */
+    // {
+    //   name: 'Microsoft Edge',
+    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+    // },
+    // {
+    //   name: 'Google Chrome',
+    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+    // },
+  ],
+
+  /* Run your local dev server before starting the tests */
+  webServer: {
+    command: '${packageManager === 'npm' ? 'npm run' : packageManager} dev',
+    url: 'http://127.0.0.1:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+});`

packages/next/src/server/config-schema.ts

@@ -16,6 +16,7 @@ import type {
   RouteHas,
   Redirect,
 } from '../lib/load-custom-routes'
+import { SUPPORTED_TEST_RUNNERS_LIST } from '../cli/next-test'
 
 // A custom zod schema for the SizeLimit type
 const zSizeLimit = z.custom<SizeLimit>((val) => {
@@ -390,6 +391,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
         missingSuspenseWithCSRBailout: z.boolean().optional(),
         useEarlyImport: z.boolean().optional(),
         testProxy: z.boolean().optional(),
+        defaultTestRunner: z.enum(SUPPORTED_TEST_RUNNERS_LIST).optional(),
       })
       .optional(),
     exportPathMap: z

packages/next/src/server/config-shared.ts

@@ -11,6 +11,7 @@ import type { WEB_VITALS } from '../shared/lib/utils'
 import type { NextParsedUrlQuery } from './request-meta'
 import type { SizeLimit } from '../../types'
 import type { SwrDelta } from './lib/revalidate'
+import type { SUPPORTED_TEST_RUNNERS } from '../cli/next-test'
 
 export type NextConfigComplete = Required<NextConfig> & {
   images: Required<ImageConfigComplete>
@@ -440,9 +441,14 @@ export interface ExperimentalConfig {
   useEarlyImport?: boolean
 
   /**
-   * Enables `fetch` requests to be proxied to the experimental text proxy server
+   * Enables `fetch` requests to be proxied to the experimental test proxy server
    */
   testProxy?: boolean
+
+  /**
+   * Set a default test runner to be used by `next experimental-test`.
+   */
+  defaultTestRunner?: SUPPORTED_TEST_RUNNERS
 }
 
 export type ExportPathMap = {

packages/next/src/server/lib/utils.ts

@@ -7,7 +7,7 @@ export function printAndExit(message: string, code = 1) {
     console.error(message)
   }
 
-  process.exit(code)
+  return process.exit(code)
 }
 
 export const getDebugPort = () => {