router-act

Files (1)

• SKILL.md

SKILL.md (first lines)

# Router Act Testing

Use this skill when writing or modifying tests that involve prefetch requests, client router navigations, or the segment cache. The `createRouterAct` utility from `test/lib/router-act.ts` lets you assert on prefetch and navigation responses in an end-to-end way without coupling to the exact number of requests or the protocol details. This is why most client router-related tests use this pattern.

## When NOT to Use `act`

Don't bother with `act` if you don't need to instrument the network responses — either to control their timing or to assert on what's included in them. If all you're doing is waiting for some part of the UI to appear after a navigation, regular Playwright helpers like `browser.elementById()`, `browser.elementByCss()`, and `browser.waitForElementByCss()` are sufficient.

## Core Principles

1. **Use `LinkAccordion` to control when prefetches happen.** Never let links be visible outside an `act` scope.
2. **Prefer `'no-requests'`** whenever the data should be served from cache. This is the strongest assertion — it proves the cache is working.
3. **Avoid retry/polling timers.** The `act` utility exists specifically to replace inherently flaky patterns like `retry()` loops or `setTimeout` waits for network activity. If you find yourself wanting to poll, you're probably not using `act` correctly.
4. **Avoid the `block` feature.** It's prone to false negatives. Prefer `includes` and `'no-requests'` assertions instead.

## Act API

### Config Options

```typescript
// Assert NO router requests are made (data served from cache).
// Prefer this whenever possible — it's the strongest assertion.
await act(async () => { ... }, 'no-requests')

// Expect at least one response containing this substring
await act(async () => { ... }, { includes: 'Page content' })

// Expect multiple responses (checked in order)
await act(async () => { ... }, [
  { includes: 'First response' },
  { includes: 'Second response' },
])

// Assert the same content appears in two separate responses
await act(async () => { ... }, [
  { includes: 'Repeated content' },
  { includes: 'Repeated content' },
])

// Expect at least one request, don't assert on content
await act(async () => { ... })
```

### How `includes` Matching Works

- The `includes` substring is matched against the HTTP response body. Use text content that appears literally in the rendered output (e.g. `'Dynamic content (stale time 60s)'`).
- Extra responses that don't match any `includes` assertion are silently ignored — you only need to assert on the responses you care about. This keeps tests decoupled from the exact number of requests the router makes.
- Each `includes` expectation claims exactly one response. If the same substring appears in N separate responses, provide N separate `{ includes: '...' }` entries.

### What `act` Does Internally

`act` intercepts all router requests — prefetches, navigations, and Server Actions — made during the scope:

1. Installs a Playwright route handler to intercept router requests
2. Runs your scope function
3. Waits for a `requestIdleCallback` (captures IntersectionObserver-triggered prefetches)
4. Fulfills buffered responses to the browser
5. Repeats steps 3-4 until no more requests arrive
6. Asserts on the responses based on the config

Responses are buffered and only forwarded to the browser after the scope function returns. This means you cannot navigate to a new page and wait for it to render within the same scope — that would deadlock. Trigger the navigation (click the link) and let `act` handle the rest. Read destination page content _after_ `act` returns:

```typescript
await act(
  async () => {
    /* toggle accordion, click link */
  },
  { includes: 'Page content' }
)

// Read content after act returns, not inside the scope
expect(await browser.elementById('my-content').text()).toBe('Page content')
```

## LinkAccordion Pattern

### Why LinkAccordion Exists

`LinkAccordion` controls when `<Link>` components enter the DOM. A Next.js `<Link>` triggers a prefetch when it enters the viewport (via IntersectionObserver). By hiding the Link behind a checkbox toggle, you control exactly when prefetches happen — only when you explicitly toggle the accordion inside an `act` scope.

```tsx
// components/link-accordion.tsx
'use client'
import Link from 'next/link'
import { useState } from 'react'

export function LinkAccordion({ href, children, prefetch }) {
  const [isVisible, setIsVisible] = useState(false)
  return (
    <>
      <input
        type="checkbox"
        checked={isVisible}
        onChange={() => setIsVisible(!isVisible)}
        data-link-accordion={href}
      />
      {isVisible ? (
        <Link href={href} prefetch={prefetch}>
          {children}
        </Link>
      ) : (
        `${children} (link is hidden)`
      )}
    </>
  )
}
```

### Standard Navigation Pattern

Always toggle the accordion and click the link inside the same `act` scope:

```typescript
await act(
  async () => {
    // 1. Toggle accordion — Link enters DOM, triggers prefetch
    const toggle = await browser.elementByCss(
      'input[data-link-accordion="/target-page"]'
    )

From evgeshniyzik-dev/nextjs, MIT.

More from evgeshniyzik-dev/nextjs