Marko Virtual 浏览器测试基座实战:一个应用、一个服务器、一个 Playwright 配置

原创2026-10-05 11:27:581,344 阅读
文章标签:前端UI组件

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"
  }
}

目录下存在两类路由,共同构成套件覆盖的全部页面:

  1. Option gates(选项门):enabled、rtl、scroll-margin、cached、lanes-mode、measure-element、debug、scroll-events、window-horizontal、window-initial-offset、window-example。它们是刻意人为构造的页面,一页对应一个选项,断言该选项确实可观察地改变了行为;
  2. 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 提供了层层递进的证明:

  1. 服务端 HTML 含切片:首行与 person1@example.com 存在,深行 person500@example.com 不存在(仅存在于序列化 resume 载荷中,因此用行标记断言缺失、且先做正对照防止空真通过),包裹容器携带真实总高 height: 48000px(1000 × 48);
  2. 无 JS 的契约刻画:<try>/<await> 的流式内容乱序输出并由内联脚本换位,禁用 JS 后服务端绘制的行存在于 DOM,但占位符仍停留在屏幕上——这是平台契约:乱序 <await> 页面不是 no-JS 页面;
  3. 客户端 resume 接管:滚动到 700×48 处出现 person701、person1 消失,回顶后原始切片重渲染(往返完整);
  4. 原始 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 扫描会用 **/*.marko glob 跟随符号链接且无环检测,任何链接了该包的应用执行 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 全部选项语义最直接的入口。

登录后查看全文
virtual