test(instant-validation): document usePathname() stack-trace attribution today

test/e2e/app-dir/instant-validation-build/app/(default)/pathname/invalid-use-pathname-deep-component/[one]/[two]/inner-wrapper.tsx

@@ -0,0 +1,11 @@
+'use client'
+
+import { PathnameReader } from './pathname-reader'
+
+export function InnerWrapper() {
+  return (
+    <p>
+      Current path: <PathnameReader />
+    </p>
+  )
+}

test/e2e/app-dir/instant-validation-build/app/(default)/pathname/invalid-use-pathname-deep-component/[one]/[two]/middle-wrapper.tsx

@@ -0,0 +1,11 @@
+'use client'
+
+import { InnerWrapper } from './inner-wrapper'
+
+export function MiddleWrapper() {
+  return (
+    <div>
+      <InnerWrapper />
+    </div>
+  )
+}

test/e2e/app-dir/instant-validation-build/app/(default)/pathname/invalid-use-pathname-deep-component/[one]/[two]/outer-wrapper.tsx

@@ -0,0 +1,11 @@
+'use client'
+
+import { MiddleWrapper } from './middle-wrapper'
+
+export function OuterWrapper() {
+  return (
+    <section>
+      <MiddleWrapper />
+    </section>
+  )
+}

test/e2e/app-dir/instant-validation-build/app/(default)/pathname/invalid-use-pathname-deep-component/[one]/[two]/page.tsx

@@ -0,0 +1,26 @@
+import type { Instant } from 'next'
+import { OuterWrapper } from './outer-wrapper'
+
+export const unstable_instant: Instant = {
+  level: 'experimental-error',
+  unstable_samples: [
+    {
+      params: {
+        one: '123',
+        // two: <missing>
+      },
+    },
+  ],
+}
+
+export default function Page() {
+  return (
+    <main>
+      <p>
+        usePathname() nested three wrappers deep should still point at the
+        actual call site.
+      </p>
+      <OuterWrapper />
+    </main>
+  )
+}

test/e2e/app-dir/instant-validation-build/app/(default)/pathname/invalid-use-pathname-deep-component/[one]/[two]/pathname-reader.tsx

@@ -0,0 +1,8 @@
+'use client'
+
+import { usePathname } from 'next/navigation'
+
+export function PathnameReader() {
+  const pathname = usePathname()
+  return <span data-testid="pathname">{pathname}</span>
+}

test/e2e/app-dir/instant-validation-build/app/(default)/pathname/invalid-use-pathname-missing-params-no-wrapper/[one]/[two]/page.tsx

@@ -0,0 +1,26 @@
+import type { Instant } from 'next'
+import { PathnameReader } from './pathname-reader'
+
+export const unstable_instant: Instant = {
+  level: 'experimental-error',
+  unstable_samples: [
+    {
+      params: {
+        one: '123',
+        // two: <missing>
+      },
+    },
+  ],
+}
+
+export default function Page() {
+  return (
+    <main>
+      <p>
+        usePathname() without an ensureThrows wrapper should point at the call
+        site in the user&apos;s source.
+      </p>
+      <PathnameReader />
+    </main>
+  )
+}

test/e2e/app-dir/instant-validation-build/app/(default)/pathname/invalid-use-pathname-missing-params-no-wrapper/[one]/[two]/pathname-reader.tsx

@@ -0,0 +1,8 @@
+'use client'
+
+import { usePathname } from 'next/navigation'
+
+export function PathnameReader() {
+  const pathname = usePathname()
+  return <span data-testid="pathname">{pathname}</span>
+}

test/e2e/app-dir/instant-validation-build/instant-validation-build.test.ts

@@ -816,6 +816,69 @@ describe('instant-validation-build', () => {
       expect(result.cliOutput).not.toContain('AssertionError')
       expect(result.exitCode).toBe(1)
     })
+
+    it('error - usePathname() at the top of a Client Component body (no ensureThrows wrapper)', async () => {
+      const result = await prerender(
+        '/(default)/pathname/invalid-use-pathname-missing-params-no-wrapper/[one]/[two]'
+      )
+      // Today the function name is `<unknown>` instead of `PathnameReader`.
+      expect(extractBuildValidationError(result.cliOutput))
+        .toMatchInlineSnapshot(`
+       "Error: Route "/pathname/invalid-use-pathname-missing-params-no-wrapper/[one]/[two]" called usePathname() but param "two" is not defined in the \`unstable_samples\` of \`unstable_instant\`. usePathname() requires all route params to be provided.
+           at <unknown> (app/(default)/pathname/invalid-use-pathname-missing-params-no-wrapper/[one]/[two]/pathname-reader.tsx:6:20)
+         4 |
+         5 | export function PathnameReader() {
+       > 6 |   const pathname = usePathname()
+           |                    ^
+         7 |   return <span data-testid="pathname">{pathname}</span>
+         8 | }
+         9 | {
+         digest: 'INSTANT_VALIDATION_ERROR'
+       }
+       Build-time instant validation failed for route "/pathname/invalid-use-pathname-missing-params-no-wrapper/[one]/[two]".
+       To get a more detailed stack trace and pinpoint the issue, try one of the following:
+         - Start the app in development mode by running \`next dev\`, then open "/pathname/invalid-use-pathname-missing-params-no-wrapper/[one]/[two]" in your browser to investigate the error.
+         - Rerun the production build with \`next build --debug-prerender\` to generate better stack traces.
+       Stopping prerender due to instant validation errors."
+      `)
+      expect(result.cliOutput).not.toContain('AssertionError')
+      expect(result.exitCode).toBe(1)
+    })
+
+    it('error - usePathname() called from a Client Component nested three wrappers deep', async () => {
+      const result = await prerender(
+        '/(default)/pathname/invalid-use-pathname-deep-component/[one]/[two]'
+      )
+      // The minified function name is not deterministic, so normalize it.
+      const error = extractBuildValidationError(result.cliOutput).replace(
+        /at [a-z] \(app\/\(default\)/g,
+        'at <minified> (app/(default)'
+      )
+      expect(error).toMatchInlineSnapshot(`
+       "Error: Route "/pathname/invalid-use-pathname-deep-component/[one]/[two]" called usePathname() but param "two" is not defined in the \`unstable_samples\` of \`unstable_instant\`. usePathname() requires all route params to be provided.
+           at <minified> (app/(default)/pathname/invalid-use-pathname-deep-component/[one]/[two]/pathname-reader.tsx:6:20)
+         4 |
+         5 | export function PathnameReader() {
+       > 6 |   const pathname = usePathname()
+           |                    ^
+         7 |   return <span data-testid="pathname">{pathname}</span>
+         8 | }
+         9 | {
+         digest: 'INSTANT_VALIDATION_ERROR'
+       }
+       Build-time instant validation failed for route "/pathname/invalid-use-pathname-deep-component/[one]/[two]".
+       To get a more detailed stack trace and pinpoint the issue, try one of the following:
+         - Start the app in development mode by running \`next dev\`, then open "/pathname/invalid-use-pathname-deep-component/[one]/[two]" in your browser to investigate the error.
+         - Rerun the production build with \`next build --debug-prerender\` to generate better stack traces.
+       Stopping prerender due to instant validation errors."
+      `)
+      const rawError = extractBuildValidationError(result.cliOutput)
+      expect(rawError).not.toContain('outer-wrapper.tsx')
+      expect(rawError).not.toContain('middle-wrapper.tsx')
+      expect(rawError).not.toContain('inner-wrapper.tsx')
+      expect(result.cliOutput).not.toContain('AssertionError')
+      expect(result.exitCode).toBe(1)
+    })
   })
 
   describe('root params', () => {

test/e2e/app-dir/instant-validation/app/default/invalid-use-pathname-no-samples/[slug]/page.tsx

@@ -0,0 +1,9 @@
+import { PathnameLabel } from './pathname-label'
+
+export default function Page() {
+  return (
+    <main>
+      <PathnameLabel />
+    </main>
+  )
+}

test/e2e/app-dir/instant-validation/app/default/invalid-use-pathname-no-samples/[slug]/pathname-label.tsx

@@ -0,0 +1,8 @@
+'use client'
+
+import { usePathname } from 'next/navigation'
+
+export function PathnameLabel() {
+  const pathname = usePathname()
+  return <span data-testid="pathname-label">{pathname}</span>
+}

test/e2e/app-dir/instant-validation/app/default/page.tsx

@@ -14,6 +14,9 @@ export default async function Page() {
         <li>
           <DebugLinks href="/default/static/valid-blocking-inside-static" />
         </li>
+        <li>
+          <DebugLinks href="/default/invalid-use-pathname-no-samples/123" />
+        </li>
       </ul>
     </main>
   )

test/e2e/app-dir/instant-validation/instant-validation.test.ts

@@ -1893,6 +1893,37 @@ describe('instant validation', () => {
           expectNoBuildValidationErrors(result)
         }
       })
+
+      // Today the dev overlay misattributes usePathname() errors to the
+      // parent's JSX line instead of the actual hook call site. When the
+      // URL-hook factory lands, this test will start passing and
+      // `it.failing` will itself fail — flip it back to `it`.
+      /* eslint-disable jest/no-standalone-expect */
+      ;(isNextDev && !isClientNav ? it.failing : it)(
+        'invalid - usePathname() in a client component on a route with a fallback param',
+        async () => {
+          if (!isNextDev || isClientNav) {
+            return
+          }
+          const browser = await navigateTo(
+            '/default/invalid-use-pathname-no-samples/123'
+          )
+          await expect(browser).toDisplayCollapsedRedbox(`
+           {
+             "description": "Next.js encountered uncached data during prerendering.",
+             "environmentLabel": "Server",
+             "label": "Blocking Route",
+             "source": "app/default/invalid-use-pathname-no-samples/[slug]/pathname-label.tsx (6:20) @ PathnameLabel
+           > 6 |   const pathname = usePathname()
+               |                    ^",
+             "stack": [
+               "PathnameLabel app/default/invalid-use-pathname-no-samples/[slug]/pathname-label.tsx (6:20)",
+             ],
+           }
+          `)
+        }
+      )
+      /* eslint-enable jest/no-standalone-expect */
     })
 
     describe('client errors', () => {