router-act

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

// 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 () => { ... })