[test] Use --debug-build-paths instead of NEXT_PRIVATE_APP_PATHS

With `--debug-build-paths` being added in #85052, we can now use this
CLI flag in tests, instead of setting the private environment variable
`NEXT_PRIVATE_APP_PATHS`.

Related to this change, this PR fixes how we print the dev, start and
build commands during tests, by properly escaping the CLI arguments.
This ensures that the command is copy-pasteable even when the args
contain escaped characters.

Author: unstubbable

package.json

@@ -165,6 +165,7 @@
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",
     "@types/relay-runtime": "14.1.13",
+    "@types/shell-quote": "1.7.1",
     "@types/string-hash": "1.1.1",
     "@types/trusted-types": "2.0.3",
     "@vercel/devlow-bench": "workspace:*",

pnpm-lock.yaml

@@ -119,9 +119,7 @@ describe.skip('cache-components - Console Dimming - Validation', () => {
     } else {
       try {
         await next.build({
-          env: {
-            NEXT_PRIVATE_APP_PATHS: `["${path === '/' ? '' : path}/page.tsx"]`,
-          },
+          args: ['--debug-build-paths', `app${path}/page.tsx`],
         })
       } catch (err) {
         const error = new Error(
@@ -309,9 +307,7 @@ describe.skip('cache-components - Logging after Abort', () => {
       } else {
         try {
           await next.build({
-            env: {
-              NEXT_PRIVATE_APP_PATHS: `["${path === '/' ? '' : path}/page.tsx"]`,
-            },
+            args: ['--debug-build-paths', `app${path}/page.tsx`],
           })
         } catch (err) {
           const error = new Error(
@@ -480,9 +476,7 @@ describe.skip('cache-components - Logging after Abort', () => {
       } else {
         try {
           await next.build({
-            env: {
-              NEXT_PRIVATE_APP_PATHS: `["${path === '/' ? '' : path}/page.tsx"]`,
-            },
+            args: ['--debug-build-paths', `app${path}/page.tsx`],
           })
         } catch (err) {
           const error = new Error(
@@ -632,9 +626,7 @@ describe.skip('cache-components - Logging after Abort', () => {
       } else {
         try {
           await next.build({
-            env: {
-              NEXT_PRIVATE_APP_PATHS: `["${path === '/' ? '' : path}/page.tsx"]`,
-            },
+            args: ['--debug-build-paths', `app${path}/page.tsx`],
           })
         } catch (err) {
           const error = new Error(
@@ -728,9 +720,7 @@ describe.skip('cache-components - Logging after Abort', () => {
       } else {
         try {
           await next.build({
-            env: {
-              NEXT_PRIVATE_APP_PATHS: `["${path === '/' ? '' : path}/page.tsx"]`,
-            },
+            args: ['--debug-build-paths', `app${path}/page.tsx`],
           })
         } catch (err) {
           const error = new Error(

test/e2e/app-dir/cache-components-console/cache-components.console.test.ts

@@ -64,18 +64,19 @@ describe('Cache Components Errors', () => {
     })
 
     const prerender = async (pathname: string) => {
-      const args = ['--experimental-build-mode', 'generate']
+      const args = [
+        '--experimental-build-mode',
+        'generate',
+        '--debug-build-paths',
+        // Escape square brackets for pathnames with dynamic segments.
+        `app${pathname.replace(/([[\]])/g, '\\$1')}/page.tsx`,
+      ]
 
       if (isDebugPrerender) {
         args.push('--debug-prerender')
       }
 
-      await next.build({
-        env: {
-          NEXT_PRIVATE_APP_PATHS: JSON.stringify([`${pathname}/page.tsx`]),
-        },
-        args,
-      })
+      await next.build({ args })
     }
 
     describe('Dynamic Metadata - Static Route', () => {

test/e2e/app-dir/cache-components-errors/cache-components-errors.test.ts

@@ -203,11 +203,7 @@ describe('use-cache-search-params', () => {
 
     it('should resume a cached page that does not access search params without hydration errors', async () => {
       await next.build({
-        env: {
-          NEXT_PRIVATE_APP_PATHS: JSON.stringify([
-            '/search-params-unused/page.tsx',
-          ]),
-        },
+        args: ['--debug-build-paths', 'app/search-params-unused/page.tsx'],
       })
 
       await next.start({ skipBuild: true })

test/e2e/app-dir/use-cache-search-params/use-cache-search-params.test.ts

@@ -3,6 +3,7 @@ import { Span } from 'next/dist/trace'
 import { NextInstance } from './base'
 import { retry, waitFor } from 'next-test-utils'
 import stripAnsi from 'strip-ansi'
+import { quote as shellQuote } from 'shell-quote'
 
 export class NextDevInstance extends NextInstance {
   private _cliOutput: string = ''
@@ -50,7 +51,7 @@ export class NextDevInstance extends NextInstance {
       }
     }
 
-    console.log('running', startArgs.join(' '))
+    console.log('running', shellQuote(startArgs))
     await new Promise<void>((resolve, reject) => {
       try {
         this.childProcess = spawn(startArgs[0], startArgs.slice(1), {
@@ -130,7 +131,7 @@ export class NextDevInstance extends NextInstance {
         }
         this.on('stdout', readyCb)
       } catch (err) {
-        require('console').error(`Failed to run ${startArgs.join(' ')}`, err)
+        require('console').error(`Failed to run ${shellQuote(startArgs)}`, err)
         setTimeout(() => process.exit(1), 0)
       }
     })

test/lib/next-modes/next-dev.ts

@@ -4,6 +4,7 @@ import { NextInstance } from './base'
 import spawn from 'cross-spawn'
 import { Span } from 'next/dist/trace'
 import stripAnsi from 'strip-ansi'
+import { quote as shellQuote } from 'shell-quote'
 
 export class NextStartInstance extends NextInstance {
   private _buildId: string
@@ -64,7 +65,7 @@ export class NextStartInstance extends NextInstance {
 
     if (!options.skipBuild) {
       const buildArgs = this.getBuildArgs()
-      console.log('running', buildArgs.join(' '))
+      console.log('running', shellQuote(buildArgs))
       await new Promise<void>((resolve, reject) => {
         try {
           this.childProcess = spawn(buildArgs[0], buildArgs.slice(1), spawnOpts)
@@ -80,7 +81,10 @@ export class NextStartInstance extends NextInstance {
             else resolve()
           })
         } catch (err) {
-          require('console').error(`Failed to run ${buildArgs.join(' ')}`, err)
+          require('console').error(
+            `Failed to run ${shellQuote(buildArgs)}`,
+            err
+          )
           setTimeout(() => process.exit(1), 0)
         }
       })
@@ -99,7 +103,7 @@ export class NextStartInstance extends NextInstance {
       ).trim()
     }
 
-    console.log('running', startArgs.join(' '))
+    console.log('running', shellQuote(startArgs))
     await new Promise<void>((resolve, reject) => {
       try {
         this.childProcess = spawn(startArgs[0], startArgs.slice(1), spawnOpts)
@@ -141,7 +145,7 @@ export class NextStartInstance extends NextInstance {
         }
         this.on('stdout', readyCb)
       } catch (err) {
-        require('console').error(`Failed to run ${startArgs.join(' ')}`, err)
+        require('console').error(`Failed to run ${shellQuote(startArgs)}`, err)
         setTimeout(() => process.exit(1), 0)
       }
     })
@@ -207,7 +211,7 @@ export class NextStartInstance extends NextInstance {
       const spawnOpts = this.getSpawnOpts(options.env)
       const buildArgs = this.getBuildArgs(options.args)
 
-      console.log('running', buildArgs.join(' '))
+      console.log('running', shellQuote(buildArgs))
 
       this.childProcess = spawn(buildArgs[0], buildArgs.slice(1), spawnOpts)
       this.handleStdio(this.childProcess)