router-act by vercel/next.js
npx skills add https://github.com/vercel/next.js --skill router-act在编写或修改涉及预取请求、客户端路由器导航或段缓存的测试时,请使用此技能。来自 test/lib/router-act.ts 的 createRouterAct 工具允许您以端到端的方式断言预取和导航响应,而无需耦合到确切的请求数量或协议细节。这就是为什么大多数与客户端路由器相关的测试都使用这种模式。
act如果您不需要控制网络响应——无论是为了控制它们的时机还是断言其中包含的内容——那么就不必使用 act。如果您所做的只是在导航后等待 UI 的某个部分出现,那么常规的 Playwright 助手,如 browser.elementById()、browser.elementByCss() 和 browser.waitForElementByCss() 就足够了。
LinkAccordion 来控制预取何时发生。 绝不要让链接在 作用域外可见。广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
act'no-requests'。当数据应从缓存中提供时,这是最强的断言——它证明了缓存正在工作。act 工具的存在正是为了替代本质上不稳定的模式,例如用于等待网络活动的 retry() 循环或 setTimeout 等待。如果您发现自己想要轮询,那么您可能没有正确使用 act。block 功能。 它容易产生假阴性。请改用 includes 和 'no-requests' 断言。// 断言没有发起路由器请求(数据来自缓存)。
// 尽可能优先使用此选项——这是最强的断言。
await act(async () => { ... }, 'no-requests')
// 期望至少有一个响应包含此子字符串
await act(async () => { ... }, { includes: '页面内容' })
// 期望多个响应(按顺序检查)
await act(async () => { ... }, [
{ includes: '第一个响应' },
{ includes: '第二个响应' },
])
// 断言相同的内容出现在两个独立的响应中
await act(async () => { ... }, [
{ includes: '重复内容' },
{ includes: '重复内容' },
])
// 期望至少有一个请求,不对内容进行断言
await act(async () => { ... })
includes 匹配的工作原理includes 子字符串与 HTTP 响应体进行匹配。使用在渲染输出中字面出现的文本内容(例如 '动态内容(过期时间 60 秒)')。includes 断言的额外响应会被静默忽略——您只需要断言您关心的响应。这使得测试与路由器发起的精确请求数量解耦。includes 期望恰好对应一个响应。如果相同的子字符串出现在 N 个独立的响应中,请提供 N 个独立的 { includes: '...' } 条目。act 的内部工作原理act 拦截作用域内发起的所有路由器请求——预取、导航和服务器操作:
requestIdleCallback(捕获由 IntersectionObserver 触发的预取)响应会被缓冲,只有在作用域函数返回后才转发给浏览器。这意味着您无法导航到新页面并在同一作用域内等待其渲染——那会导致死锁。触发导航(点击链接)并让 act 处理其余部分。在 act 返回之后读取目标页面内容:
await act(
async () => {
/* 切换手风琴,点击链接 */
},
{ includes: '页面内容' }
)
// 在 act 返回后读取内容,而不是在作用域内
expect(await browser.elementById('my-content').text()).toBe('页面内容')
LinkAccordion 控制 <Link> 组件何时进入 DOM。Next.js 的 <Link> 在进入视口时(通过 IntersectionObserver)会触发预取。通过将链接隐藏在复选框切换后面,您可以精确控制预取何时发生——只有当您在 act 作用域内显式切换手风琴时才会发生。
// 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}(链接已隐藏)`
)}
</>
)
}
始终在同一 act 作用域内切换手风琴并点击链接:
await act(
async () => {
// 1. 切换手风琴 —— Link 进入 DOM,触发预取
const toggle = await browser.elementByCss(
'input[data-link-accordion="/target-page"]'
)
await toggle.click()
// 2. 点击现在可见的链接 —— 触发导航
const link = await browser.elementByCss('a[href="/target-page"]')
await link.click()
},
{ includes: '期望的页面内容' }
)
browser.back() 且手风琴处于打开状态不要使用 browser.back() 返回到之前手风琴已打开的页面。BFCache 会恢复完整的 React 状态,包括 useState 值,因此之前打开的链接会立即可见。这会在任何 act 作用域外触发 IntersectionObserver 回调——如果缓存的数据已过期,不受控制的重新预取会触发并破坏后续的 no-requests 断言。
唯一安全使用 browser.back()/browser.forward() 的情况是专门测试 BFCache 行为时。
修复方法: 改为向前导航到一个新的枢纽页面。参见枢纽页面。
act 作用域外使用可见的 <Link> 组件视口中任何可见的 <Link> 都可能随时通过 IntersectionObserver 触发预取。如果这发生在 act 作用域外,请求将不受控制,并可能干扰后续的断言。始终将链接隐藏在 LinkAccordion 后面,并且只在 act 内部切换它们。
使用 retry()、setTimeout 或任何轮询模式来等待预取或导航完成,本质上是不稳定的。act 会确定性地等待所有路由器请求完成后再返回。
act 作用域内导航并等待渲染响应在作用域退出之前会被缓冲。点击链接然后在同一作用域内读取目标内容会导致死锁。改为在 act 返回后读取页面内容。
当您需要离开一个页面并返回以测试过期状态时,请使用“枢纽”页面而不是 browser.back()。每个枢纽都是一个新页面,拥有自己的 LinkAccordion 组件,且初始状态为关闭。
枢纽页面使用 connection() 来确保它们是动态渲染的。这保证了导航到枢纽总是会产生一个路由器请求,这使得 act 能够正确地管理导航并等待页面完全渲染后再继续。
枢纽页面模式:
// app/my-test/hub-a/page.tsx
import { Suspense } from 'react'
import { connection } from 'next/server'
import { LinkAccordion } from '../../components/link-accordion'
async function Content() {
await connection()
return <div id="hub-a-content">枢纽 A</div>
}
export default function Page() {
return (
<>
<Suspense fallback="加载中...">
<Content />
</Suspense>
<ul>
<li>
<LinkAccordion href="/my-test/target-page">目标页面</LinkAccordion>
</li>
</ul>
</>
)
}
目标页面也通过 LinkAccordion 链接到枢纽页面:
// 在目标页面上,添加指向枢纽页面的 LinkAccordion 链接
<LinkAccordion href="/my-test/hub-a">枢纽 A</LinkAccordion>
测试流程:
// 1. 导航到目标页面(首次访问)
await act(
async () => {
/* 切换手风琴,点击链接 */
},
{ includes: '目标内容' }
)
// 2. 导航到 hub-a(新页面,所有手风琴关闭)
await act(
async () => {
const toggle = await browser.elementByCss(
'input[data-link-accordion="/my-test/hub-a"]'
)
await toggle.click()
const link = await browser.elementByCss('a[href="/my-test/hub-a"]')
await link.click()
},
{ includes: '枢纽 a' }
)
// 3. 推进时间
await page.clock.setFixedTime(startDate + 60 * 1000)
// 4. 从枢纽导航回目标页面(受控的预取)
await act(async () => {
const toggle = await browser.elementByCss(
'input[data-link-accordion="/my-test/target-page"]'
)
await toggle.click()
const link = await browser.elementByCss('a[href="/my-test/target-page"]')
await link.click()
}, 'no-requests') // 或者如果数据已过期,使用 { includes: '...' }
段缓存过期测试使用 Playwright 的时钟 API 来控制 Date.now():
async function startBrowserWithFakeClock(url: string) {
let page!: Playwright.Page
const startDate = Date.now()
const browser = await next.browser(url, {
async beforePageLoad(p: Playwright.Page) {
page = p
await page.clock.install()
await page.clock.setFixedTime(startDate)
},
})
const act = createRouterAct(page)
return { browser, page, act, startDate }
}
setFixedTime 改变 Date.now() 的返回值,但计时器仍以真实时间运行Date.now() 进行过期检查setFixedTime 不会触发待处理的 setTimeout/setInterval 回调createRouterAct: test/lib/router-act.tsLinkAccordion: test/e2e/app-dir/segment-cache/staleness/components/link-accordion.tsxtest/e2e/app-dir/segment-cache/staleness/每周安装量
76
仓库
GitHub 星标
138.5K
首次出现
9 天前
安全审计
安装于
opencode73
cursor73
kimi-cli72
gemini-cli72
amp72
cline72
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.
actDon'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.
LinkAccordion to control when prefetches happen. Never let links be visible outside an act scope.'no-requests' whenever the data should be served from cache. This is the strongest assertion — it proves the cache is working.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.block feature. It's prone to false negatives. Prefer includes and 'no-requests' assertions instead.// 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 () => { ... })
includes Matching Worksincludes 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)').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.includes expectation claims exactly one response. If the same substring appears in N separate responses, provide N separate { includes: '...' } entries.act Does Internallyact intercepts all router requests — prefetches, navigations, and Server Actions — made during the scope:
requestIdleCallback (captures IntersectionObserver-triggered prefetches)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:
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 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.
// 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)`
)}
</>
)
}
Always toggle the accordion and click the link inside the same act scope:
await act(
async () => {
// 1. Toggle accordion — Link enters DOM, triggers prefetch
const toggle = await browser.elementByCss(
'input[data-link-accordion="/target-page"]'
)
await toggle.click()
// 2. Click the now-visible link — triggers navigation
const link = await browser.elementByCss('a[href="/target-page"]')
await link.click()
},
{ includes: 'Expected page content' }
)
browser.back() with open accordionsDo not use browser.back() to return to a page where accordions were previously opened. BFCache restores the full React state including useState values, so previously-opened Links are immediately visible. This triggers IntersectionObserver callbacks outside any act scope — if the cached data is stale, uncontrolled re-prefetches fire and break subsequent no-requests assertions.
The only safe use of browser.back()/browser.forward() is when testing BFCache behavior specifically.
Fix: navigate forward to a fresh hub page instead. See Hub Pages.
<Link> components outside act scopesAny <Link> visible in the viewport can trigger a prefetch at any time via IntersectionObserver. If this happens outside an act scope, the request is uncontrolled and can interfere with subsequent assertions. Always hide links behind LinkAccordion and only toggle them inside act.
retry(), setTimeout, or any polling pattern to wait for prefetches or navigations to settle is inherently flaky. act deterministically waits for all router requests to complete before returning.
act scopeResponses are buffered until the scope exits. Clicking a link then reading destination content in the same scope deadlocks. Read page content after act returns instead.
When you need to navigate away from a page and come back to test staleness, use "hub" pages instead of browser.back(). Each hub is a fresh page with its own LinkAccordion components that start closed.
Hub pages use connection() to ensure they are dynamically rendered. This guarantees that navigating to a hub always produces a router request, which lets act properly manage the navigation and wait for the page to fully render before continuing.
Hub page pattern:
// app/my-test/hub-a/page.tsx
import { Suspense } from 'react'
import { connection } from 'next/server'
import { LinkAccordion } from '../../components/link-accordion'
async function Content() {
await connection()
return <div id="hub-a-content">Hub a</div>
}
export default function Page() {
return (
<>
<Suspense fallback="Loading...">
<Content />
</Suspense>
<ul>
<li>
<LinkAccordion href="/my-test/target-page">Target page</LinkAccordion>
</li>
</ul>
</>
)
}
Target pages link to hubs via LinkAccordion too:
// On target pages, add LinkAccordion links to hub pages
<LinkAccordion href="/my-test/hub-a">Hub A</LinkAccordion>
Test flow:
// 1. Navigate to target (first visit)
await act(
async () => {
/* toggle accordion, click link */
},
{ includes: 'Target content' }
)
// 2. Navigate to hub-a (fresh page, all accordions closed)
await act(
async () => {
const toggle = await browser.elementByCss(
'input[data-link-accordion="/my-test/hub-a"]'
)
await toggle.click()
const link = await browser.elementByCss('a[href="/my-test/hub-a"]')
await link.click()
},
{ includes: 'Hub a' }
)
// 3. Advance time
await page.clock.setFixedTime(startDate + 60 * 1000)
// 4. Navigate back to target from hub (controlled prefetch)
await act(async () => {
const toggle = await browser.elementByCss(
'input[data-link-accordion="/my-test/target-page"]'
)
await toggle.click()
const link = await browser.elementByCss('a[href="/my-test/target-page"]')
await link.click()
}, 'no-requests') // or { includes: '...' } if data is stale
Segment cache staleness tests use Playwright's clock API to control Date.now():
async function startBrowserWithFakeClock(url: string) {
let page!: Playwright.Page
const startDate = Date.now()
const browser = await next.browser(url, {
async beforePageLoad(p: Playwright.Page) {
page = p
await page.clock.install()
await page.clock.setFixedTime(startDate)
},
})
const act = createRouterAct(page)
return { browser, page, act, startDate }
}
setFixedTime changes Date.now() return value but timers still run in real timeDate.now() for staleness checkssetFixedTime does NOT fire pending setTimeout/setInterval callbackscreateRouterAct: test/lib/router-act.tsLinkAccordion: test/e2e/app-dir/segment-cache/staleness/components/link-accordion.tsxtest/e2e/app-dir/segment-cache/staleness/Weekly Installs
76
Repository
GitHub Stars
138.5K
First Seen
9 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode73
cursor73
kimi-cli72
gemini-cli72
amp72
cline72
Vue 3 调试指南:解决响应式、计算属性与监听器常见错误
11,900 周安装