Marko Virtual 浏览器测试基座实战:一个应用、一个服务器、一个 Playwright 配置
Marko Virtual 浏览器测试基座实战:一个应用、一个服务器、一个 Playwright 配置
本指南深入解析 @tanstack/marko-virtual 包的端到端(E2E)测试应用 —— 位于 packages/marko-virtual/e2e/app 的浏览器测试基座(test harness)。它并非对外发布的示例,而是把整个 Marko 浏览器测试套件收敛为"一个应用、一个服务器、一个 Playwright 配置"的统一运行单元:每个场景是一条路由,每条 spec 驱动自己的路由,npm run test:e2e 一键完成构建、起服、跑测、拆除。读完本文,你将掌握这套单应用测试架构的完整设计动机、路由组织方式、三层测试策略(jsdom / 真实浏览器 / 弱断言)、源码级 SSR 切片原理,以及绕开 pnpm 符号链接环与 nx 构建竞态等工程陷阱的实战方案。
一、整体架构:为什么是"一个应用"
npm run test:e2e 的完整生命周期是:构建应用 → 启动服务器 → 跑完所有 spec → 拆除。整条流水线全部收敛在这一个应用目录里,由 packages/marko-virtual/e2e/app/package.json 中的脚本驱动:
{
"scripts": {
"dev": "marko-run dev",
"build": "marko-run build",
"preview": "marko-run preview",
"test:e2e": "playwright test",
"test:types": "marko-type-check"
}
}
目录下存在两类路由,共同构成套件覆盖的全部页面:
- Option gates(选项门):
enabled、rtl、scroll-margin、cached、lanes-mode、measure-element、debug、scroll-events、window-horizontal、window-initial-offset、window-example。它们是刻意人为构造的页面,一页对应一个选项,断言该选项确实可观察地改变了行为; - Example fixtures(示例夹具):
chat、table、ssr-slice、window等,是极薄的封装,直接 import 并渲染 examples/marko 下的真实页面。
从 e2e 目录 可以看到完整的 spec 清单:chat、chat-pretext、dynamic、fixed、grid、infinite-scroll、option-gates、padding、pretext、scroll-padding、smooth-scroll、ssr、ssr-fetch、ssr-restore、ssr-slice、sticky、table、variable、window、window-ssr-slice,外加专用的 option-gates.spec.ts —— 每个示例对应一个文件,驱动自己的路由。
示例夹具:import,绝不复制
示例夹具的典型写法,见 固定尺寸示例夹具:
import Page from "../../../../../../../examples/marko/fixed/src/routes/+page.marko"
<Page/>
这段 import 向上穿越七层目录到达仓库根,再进入 examples/marko/fixed。选择 import 而非复制有明确工程理由:被测试的就是发布出去的示例本身,夹具不可能与它测试的示例产生漂移(drift)。同理,api/reply/+handler.ts 从 chat 示例 re-export 流式回复处理器:
export { POST } from '../../../../../../../../examples/marko/chat/src/routes/api/reply/+handler'
两个 chat 夹具都向绝对路径 /api/reply 发起 POST,因此该处理器在应用根路由处只挂载一次,两方共享。这样对示例流式响应形状的改动,会立刻在这套套件中被验证,而不会出现示例与测试各持一份副本、逐步分叉的问题。
二、为什么收敛成一个应用:19 台 dev server 的教训
README 明确记录了这段历史重构的背景:过去每个示例自带一套 e2e 配置——自己的 e2e/、自己的 playwright.config.ts、自己的端口(4173–4191),结果是每次 CI 要拉起 19 台 dev server、19 份配置副本,还存在一个会整体击垮套件的构建顺序耦合:
- 示例通过
@tanstack/marko-virtual解析标签,而该包的marko.json指向./dist/tags; - 包未构建时每个页面都会 500 报错;
- 由于 marko-run 在请求端口被占用时会静默回退到随机空闲端口,这个错误只会表现为
Timed out waiting 120000ms from config.webServer,真实错误却不在日志里——排障极其痛苦。
新的单应用方案从根上消灭了这类问题:vite alias 把适配器和 core 直接解析到源码,套件完全不需要预先构建。见 vite.config.ts:
export default defineConfig({
plugins: [marko() as any],
resolve: {
alias: {
'@tanstack/marko-virtual': path.resolve(__dirname, '../../src/index.ts'),
'@tanstack/virtual-core': path.resolve(
__dirname,
'../../../virtual-core/src/index.ts',
),
},
},
})
这两个 alias 是路径别名而非依赖:把包解析到 src/index.ts,把 core 解析到 virtual-core 源码,因此修改 core 或适配器后只需改源码即可验证,不需要任何构建步骤。适配器 alias 还覆盖了示例夹具中对包 JS API 的 import(例如 sticky 的 defaultRangeExtractor)——没有它,这类 import 会解析到 dist/,套件会再次悄悄变成"构建依赖",重蹈先前 dist/tags 缺失只表现为 120s 超时的覆辙。
与此同时,nx.json 在根级声明 test:e2e 的 dependsOn: ["^build"],确保依赖包先构建,让其他任何场景都不可能再掉进同样的坑。
三、布局约束:相对路径的硬性约定
app/README.md 强调:所有相对路径都精确假设了这一目录深度,移动本文件夹意味着要同步更新它们全部:
- marko.json →
../../src/tags:即{ "tags-dir": "../../src/tags" },指向包内的标签源码目录 src/tags; - vite alias →
../../src/index.ts与../../../virtual-core/src/index.ts; - 夹具 import → 向上七层到达仓库根。
安装层面由仓库级 pnpm install 通过 workspace glob packages/marko-virtual/e2e/* 覆盖(见 pnpm-workspace.yaml)。首次运行浏览器测试可能需要先执行:
npx playwright install chromium
四、dev / build / preview 脚本与 nx 目标图的关系
dev、build、preview 三个脚本只为 Playwright 的 webServer 命令和本地调试服务,不进入 nx 的目标图——e2e/app/package.json 用 includedScripts 把它们排除在外:
"nx": {
"includedScripts": ["test:e2e", "test:types"],
"implicitDependencies": ["@tanstack/marko-virtual"],
"targets": {
"test:e2e": {
"inputs": ["default", "^production", "{workspaceRoot}/examples/marko/**/*"]
}
}
}
这里有一个值得记录的构建竞态教训:如果把 build 暴露给 nx,CI 会把 marko-run build 当作 test:e2e 的并行同级任务执行,而 test:e2e 的 webServer 又在同一目录自己跑一次 marko-run build——两者在 dist/ 目录互相竞争,其中一方会在写入中途因 ENOENT ... dist/index.mjs 崩溃。因此明确约定:构建这件事由 Playwright 独占。
五、Playwright 配置设计:面向滚动/测量断言的取舍
playwright.config.ts 的每一项设置都服务于"滚动偏移与尺寸测量"这类断言的特殊需求:
const PORT = Number(process.env.MARKO_E2E_PORT ?? 4199)
const baseURL = `http://localhost:${PORT}`
export default defineConfig({
testDir: './e2e',
timeout: 60_000,
retries: 0, // 不加重试
workers: 1, // 串行执行
use: {
baseURL,
trace: 'retain-on-failure',
},
webServer: {
command: `npm run build && npm run preview -- --port ${PORT}`,
url: baseURL,
reuseExistingServer: !process.env.CI,
stdout: 'pipe',
stderr: 'pipe',
timeout: 120_000,
},
})
设计动机逐条对应:
retries: 0:这些是滚动/测量断言,如果重试能把"红"变"绿",恰好会掩盖套件存在的意义——时序回归。nx 会把"仅在重跑时通过"的任务标记为 flaky 来兜底;workers: 1:spec 断言的是对机器负载敏感的滚动偏移和测量尺寸,单 worker 能保证失败是有意义的;整套套件约 45 秒,串行没有可牺牲的并行收益;trace: 'retain-on-failure':CI 上的失败若只有堆栈没有页面状态,对这类套件等于没有诊断信息——滚动偏移出错那一刻的 DOM 就是全部线索。trace 自带截图,因此无需单独的截图配置;- webServer 用
build && preview而非 dev server:这是用户最终部署的生产 SSR/resume 路径,不会向 console-error 断言注入 HMR 客户端;且每条路由预编译完毕,不会让某个测试在断言中途为冷启动的 Marko 编译买单(冷树上 chat 和 window-ssr-slice 曾因此间歇性失败,即 CI 上的情形)。构建约 2 秒,且与 react-virtual 套件的运行方式一致; reuseExistingServer: !process.env.CI:本地可复用已手动启动的服务器;stdout/stderr: 'pipe':让 dev server 输出直接出现在测试终端,崩溃或慢编译的服务器一眼可见,而不是静默卡死。
三层测试策略的分工
README 中反复出现"Tier 1 / Tier 2 / Tier 3"的层次概念,这套分层正是整个包测试设计的核心骨架:
- Tier 1(jsdom 转发):位于包的 tests/options.test.ts,对每个选项做输入 → virtual-core 选项映射的转发测试,不需要 DOM;
- Tier 2(真实浏览器行为证明):即本应用的
option-gates.spec.ts等文件,对行为可观察的选项做真浏览器断言; - Tier 3(弱断言):
debug只断言"不干扰渲染",useAnimationFrameWithResizeObserver仅做转发测试且明确标注 UNPROVEN(未证实)。
为什么 debug 在浏览器里只做弱断言?core 的调试日志写在 process.env.NODE_ENV !== 'production' 分支里,生产构建(本套件正是跑生产构建)根本不包含这行日志。因此对 debug 的日志级证明放在 vitest 层(tests/options.test.ts 中的 "debug=true makes core emit its timing logs",断言输出包含 ⏱ 计时标记),而浏览器门只验证"打开该选项不改变用户看到的东西"。
六、Option Gates:逐项行为的浏览器级证明
option-gates.spec.ts 是 Tier 2 行为证明的集中地,每个 gate 路由对应一个真实浏览器断言。以下是各选项门的核心验证点:
scroll-margin:可见性相对列表而非滚动容器顶部计算
门路由 scroll-margin/+page.marko 在滚动容器内放置了一个 300px 的 header,然后以 scrollMargin=300 渲染虚拟列表。断言要点:
- 在 scrollTop 为 0 时,row 0 必须恰好位于 header 正下方(
item.start已包含 margin,transform 再减去它); data-start="300":row 0 的item.start包含 margin;- 滚动到 header(300) + 20 行 × 35px 处时,窗口必须以 index 20 为中心锚定,index 0 必须离开 DOM——没有
scrollMargin时数学会把列表起点当成滚动容器顶部,导致低索引行被错误保留。
enabled:暂停开关的真实契约
门路由 enabled/+page.marko 用 <let/on=true/> 加一个 toggle 按钮切换 enabled 选项。其 spec 揭示了 core 的真实禁用契约:enabled=false 不是冻结——core 会清除测量(measurementsCache = []、缓存清空)、getSize() 与 getScrollOffset() 返回 0、渲染窗口坍缩;重新启用后从元素当前滚动位置重新观测、重新开窗。断言链完整覆盖了:深滚动后窗口推进 → 禁用后深窗口消失(空或仅剩 offset 0 处一个坍缩行)→ 滚动元素本身并未卸载(暂停开关不拆除 DOM)→ 回到顶部重新启用后从 offset 0 重开窗。
isRtl:右向左横向列表
在 RTL 下,向列表末端滚动意味着 scrollLeft 走向负值。spec 将 scrollLeft 设为 -(50 * 100)(50 列处),断言窗口推进到约 index 45+(50 减 overscan)。
measure-element:自定义测量器生效
行实际渲染 30px 高,自定义测量器返回 offsetHeight + 10 = 40,而估算值为 50——spec 断言 data-size="40",明确锁定这是自定义测量器的数字。
useCachedMeasurements:冻结尺寸
对照实验:控制组(默认测量器)读取 DOM,行真实渲染 90px,data-size 变为 90;冻结组(useCachedMeasurements)的测量器返回缓存/估算尺寸、永不读取 DOM,data-size 保持 50px 估算值。
laneAssignmentMode "measured":三列瀑布流
3 车道 masonry 必须三列全部填充、列内无重叠。spec 等待测量尺寸稳定后,断言车道集合恰为 {0, 1, 2},且每一列按 top 排序后相邻两项 top >= 前一项 bottom - 1。
useScrollendEvent + isScrollingResetDelay:回归冒烟
只断言"滚动仍会重新开窗"(时序本身不测),滚动到 index 200 后窗口推进,回滚后恢复。
debug=true:不干扰渲染与开窗
滚动到 50×35 处后断言 index 50 可见——证明打开选项不会卡死或空白(日志本身的证明在 vitest 层)。
window-horizontal:页面横向滚动
window.scrollTo(60 * 100, 0) 后列窗口跟随推进,首索引 ≥ 55。
window-initial-offset:服务端在指定位置绘制切片
门路由 window-initial-offset/+page.marko 传入 initialRect=({ width: 1280, height: 700 }) 与 initialOffset=3500,35px 行高意味着服务端应绘制 index 100 附近的切片而非 index 0。spec 直接请求原始 HTML 做 view-source 级断言(注意 Marko 渲染属性不加引号,如 data-index=100,因此用边界正则 /data-index=100[\s">]/ 匹配),再验证页面加载时这些行已在 DOM 中、无需任何客户端滚动。
window-example:实测 scrollMargin 的窗口定位
直接测试发布的 window 示例:页面标题与正文把列表推下 listOffset 像素,scrollMargin 在挂载时测量并传入。断言 row 0 恰好落在列表包裹容器顶部;深滚动 500 行后渲染窗口跟踪列表可见性(495–500 区间),且靠近 500 的行位于视口顶部附近——证明 start - listOffset 的定位数学自洽。
七、SSR 切片:源码级原理与线级验证
README 强调示例夹具覆盖了 SSR 场景(ssr、ssr-fetch、ssr-restore、ssr-slice、window-ssr-slice)。SSR 切片的底层实现位于 src/tags/virtualizer/options.ts 的 renderSlice:
export function renderSlice(input: VirtualizerInput) {
// 无 initialRect 时无服务端切片:返回平凡窗口
if (!input.initialRect) {
return { items: [], size: 0, range: null }
}
const probe = new Virtualizer<Element, Element>(
buildOptions({ ...input, getScrollElement: () => null }, () => {}),
)
const items = probe.getVirtualItems()
return { items, size: probe.getTotalSize(), range: probe.range }
}
关键设计:
- 临时实例:构造一个 transient virtual-core 实例,把初始窗口读成纯数据后立即丢弃——没有存活对象,就没有可被序列化的存活状态,resume 时这些值能原样重算;
- SSR 安全:构造函数与
getVirtualItems()/getTotalSize()不触碰 DOM;getScrollElement被强制为 null,探针永远不会访问服务端不存在的滚动元素; - 可选性:不给
initialRect就返回平凡窗口(空容器 + 正确总高),使所有不传它的示例与纯客户端构建逐字节一致。window-virtualizer的 对应实现 同理,且其initialOffset默认是一个函数:客户端读window.scrollY(横向读window.scrollX)、服务端返回 0,消费者传入的数字/函数会覆盖默认值。
标签层在 index.marko 中把 renderSlice 的输出作为 <const/seed> 直接参与首屏渲染(无 <if=mounted> 守卫),随后 onMount 才构建真实观测实例、onUpdate 通过 setOptions 合并新选项并通知更新、onDestroy 执行清理。
wire 级证据:流式切片
ssr-slice.spec.ts 提供了层层递进的证明:
- 服务端 HTML 含切片:首行与
person1@example.com存在,深行person500@example.com不存在(仅存在于序列化 resume 载荷中,因此用行标记断言缺失、且先做正对照防止空真通过),包裹容器携带真实总高height: 48000px(1000 × 48); - 无 JS 的契约刻画:
<try>/<await>的流式内容乱序输出并由内联脚本换位,禁用 JS 后服务端绘制的行存在于 DOM,但占位符仍停留在屏幕上——这是平台契约:乱序<await>页面不是 no-JS 页面; - 客户端 resume 接管:滚动到 700×48 处出现 person701、person1 消失,回顶后原始切片重渲染(往返完整);
- 原始 HTTP 流式探针:用
fetch+getReader()逐块读响应,证明占位符标记先于首个绘制行出现在字节流中、首个 chunk 只含占位符、绘制行出现在后续 chunk——这是"虚拟化器在流式<await>内把服务端切片渲染进 mid-stream chunk"的线级铁证。
八、示例级 E2E:从固定尺寸到流式聊天
示例夹具的测试同样值得逐一审视,它们共同验证了标签面(tag surface)在真实页面中的行为。
fixed:三台虚拟化器共享一个页面
fixed.spec.ts 覆盖 固定尺寸示例 中的三块:行(count=10000, estimateSize=() => 35)、列(horizontal=true, estimateSize=() => 100)、以及共享同一滚动元素的 1000×1000 网格(两个虚拟化器分别管行列)。断言初始窗口渲染、深滚动重新开窗(行到 300×35、列到 50×100、网格到 100,40 单元格),且原点行全部离开 DOM。
table:语义表格与"索引 vs 数据"
table.spec.ts 验证语义表格虚拟化(真实 tr/tbody + translateY(start - K*34) 流式补偿技巧):渲染行数 < 80(数据 5 万行)、无滚动时每行 translateY 为 0、深滚动 25000 行后相邻两行屏幕间距仍精确为 34px、sticky thead 在 85 万像素深处仍钉在容器顶部。排序测试还讲了一个关键概念课:排序把数据换到静止窗口之下——断言滚动位置不变、索引列表不变(同一批可见"位置"),而 data-id 列表改变(不同的"数据")。注意 spec 里用原生 DOM click 而非 Playwright 的 actionability 自动滚动,因为后者会被深层滚动大容器中的 position:sticky 表头误导而拽动 scrollTop。
chat:滚动行为簇的浏览器证明
chat.spec.ts 是"jsdom 测不了、必须真浏览器"的滚动行为集中地:
- 初次加载钉在最新消息、状态为
At latest(scrollToEnd经v.range守卫触发,旧历史被虚拟化掉); followOnAppend:末尾追加时保持钉住;而阅读历史时不跟随追加(滚动到中间、状态变Reading history,追加后 scrollTop 位移 ≤ 1px);- 前插锚定:加载更早历史后,可见消息的屏幕位置位移 ≤ 2px(依赖
getItemKey提供稳定身份); - 顶部附近自动加载:滚动到 700px(在约 1.5 视口的 load-ahead 区内但远离旧硬触发点)时内容增长;
- 流式回复:POST
/api/reply后,第一 chunk 先渲染、后续内容随后增长同一行,且全程保持钉住。文件里还注明test.fixme的 FIXME(#1267) 竞态与 250ms 预加载武装延时等已知边界。
window-ssr-slice:页面级 SSR 切片
window-ssr-slice.spec.ts 是 ssr-slice 的窗口对应物:<window-virtualizer> 以 initialRect=({ width: 1280, height: 800 }) 在服务端绘制初始行(48px 行高 + overscan 约覆盖 id 1..22),断言服务端 HTML 含切片与真实总高、无 JS 时切片在 DOM 中、客户端 resume 后 window.scrollTo 驱动重新开窗并可往返顶部。
九、依赖注意:为什么这里绝不能重加 @tanstack/marko-virtual
README 给出了一条近乎"红线"的工程约束:本应用位于包内部,向祖先包声明 workspace 依赖会形成符号链接环。机制如下:
- pnpm 会创建
node_modules/@tanstack/marko-virtual → ../../..,形成 symlink cycle; @marko/vite的生产专用 known-templates 扫描会用**/*.markoglob 跟随符号链接且无环检测,任何链接了该包的应用执行marko-run build都会以ENAMETOOLONG崩溃;- 该依赖本身也没有必要:标签经由相对 taglib 路径解析,适配器与 core 经由 vite alias 解析。
nx 图所需的构建顺序边与缓存失效边,改由 e2e/app/package.json 中的 implicitDependencies: ["@tanstack/marko-virtual"] 声明——零符号链接成本。若将来确实需要对该包做真实 JS import,正确做法是使用 pnpm 的 dependenciesMeta injected 模式(它打包一份尊重 files 字段的副本,e2e/ 被排除在外,不会形成环),而不是普通 workspace 依赖。
发布不受影响
包的 files 字段 只发布 dist、marko.json、README.md,因此 e2e/ 下的一切都不会进入 npm 包——测试基座与发布产物彻底隔离。
十、已知 bug 记录:enabled 门的 250ms settle 等待
README 末尾记录了当前套件中唯一一处"为上游 bug 让路"的等待逻辑:enabled 门带有一个有文档记录的 250ms settle 等待,规避 core 的一个上游 bug——滚动结束的 debounce 定时器在 observeOffset 退订后仍然存活,并把过期的 offset 触发到存活实例上。当可取消 debounce 的 core 修复落地后应移除该等待;spec 注释中标出了确切位置。
十一、实战速查
在本仓库中运行与调试这套 Marko 浏览器套件的完整工作流:
# 全量:构建 → 起服 → 跑全部 spec → 拆除
npm run test:e2e
# 交互式调试:HMR 起 dev server(另一终端)
npm run dev -- --port 4199
# 或生产预览(另一终端)
npm run preview
# 重跑套件 —— 本地会复用已在运行的服务器(CI 除外)
npm run test:e2e
# 指定端口运行
MARKO_E2E_PORT=4299 npm run test:e2e
# 首次运行浏览器套件前安装 Chromium
npx playwright install chromium
记住三条铁律:构建由 Playwright 独占(别把 build 暴露给 nx);不要在本应用里重加 @tanstack/marko-virtual 依赖(符号链接环 + ENAMETOOLONG);选项转发证明看 vitest 层、行为证明看本套件、日志级证明只在非生产构建存在。这套单应用基座把"一个仓库、21 个页面、数十条滚动与测量断言"收敛成了一条可复现、可排障、可增量扩展的流水线,也是理解 @tanstack/marko-virtual 全部选项语义最直接的入口。