e2e视口配置完全指南：多分辨率Web测试最佳实践
【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e
e2e 视口（viewport）配置是这套开源 AI 端到端测试框架中做多分辨率 Web 测试的核心手段。只需在 target 上声明一个viewport尺寸，或写一行viewport: null，就能让整套测试在手机、平板、桌面三种屏幕上分别运行。本指南用大白话讲清楚：e2e 视口是什么、默认值是多少、如何为每个尺寸建一个 target、如何在测试中途动态改窗口大小，以及常见坑有哪些。
为什么视口配置是 Web 测试的关键
现代网页要同时服务桌面浏览器、平板和手机。视口就是浏览器可视区域的大小——CSS 媒体查询、响应式布局、菜单折叠，全都由它触发。视口配置没做对，你测的就只是"某一个尺寸下的网页"，而不是"所有用户看到的网页"。
e2e 框架把这件事拆成了两种简单方式：
- 静态视口：在
e2e.config.ts里给 target 配一个viewport尺寸，整个测试套件都按这个尺寸跑； - 动态视口：测试执行中调用
browser.setViewport()，中途把窗口改到另一个尺寸。
官方文档 docs/web.mdx 的 Viewports 章节和参考手册 docs/reference/web.mdx 是这两个机制的权威说明。
静态视口：一个尺寸建一个 target
静态视口是最推荐的做法。e2e 的默认视口是1280 × 720，见 docs/reference/web.mdx 中viewport选项的定义：
viewport：每次尝试（attempt）页面的初始尺寸，单位是像素；viewport: null：不指定尺寸，页面填满整个浏览器窗口。
e2e 的用法是"每个尺寸一个 target"，每个 target 各自命名、各自配尺寸：
targets: [ { name: 'desktop', engine: web(), app }, { name: 'tablet', engine: web({ viewport: { width: 820, height: 1180 } }), app }, { name: 'phone', engine: web({ browser: 'webkit', viewport: { width: 390, height: 844 } }), app }, ]这样配置后：
- 每个测试会在每个 target 上各跑一次，结果分别标注为
desktop、tablet、phone，报告一目了然； - 想只跑某一档尺寸，运行时加
npx e2e run --target phone即可； - 用
npx e2e list可以列出当前选中的"测试 × target"组合。
💡 小技巧：让所有 target 声明相同的app.command，运行器会只为全部尺寸共享启动一个开发服务器进程，而不是每个尺寸各起一个。
快速上手：在示例项目里看视口配置
仓库自带了多个可直接跑的示例应用。以 Next.js 示例为例，examples/with-next/e2e.config.ts 展示了 target 与web()引擎的基本写法，测试入口在examples/with-next/tests/目录下：
上图就是默认桌面视口下的渲染效果。若把示例里的 target 改成viewport: { width: 390, height: 844 }，同一页面会以手机宽度渲染，响应式布局会随之切换。Vite 示例 examples/with-vite/ 的结构完全相同，可作为第二套参照：
动态视口：在测试中途改窗口大小
有些断言必须"先桌面后手机"地对比同一页面，这时用browser.setViewport()：
await app.open('/'); await expect(screen.getByRole('navigation')).toBeVisible(); await browser.setViewport({ width: 390, height: 844 }); await expect(screen.getByRole('button', 'Menu')).toBeVisible();动态视口有 3 个实用细节（详见 docs/web.mdx）：
- 改完就保持：尺寸会在整个 attempt 内生效，包括经过
app.restart()和app.clearState()之后，每次重试也都会从 target 配置的尺寸重新开始； - 在
app.open之前调用：可让第一屏就以手机尺寸渲染，避免应用先渲染出桌面布局再跳变； - 验证真实宽度：用
browser.evaluate(() => window.innerWidth)从页面内读出实际宽度做精确断言。
⚠️ 注意：如果整条测试链路都要换尺寸，请优先建独立 target，而不是在测试里频繁setViewport——前者结果更清晰、报告分列展示。
AI Agent 看到的也是当前视口
e2e 的一大特色是内置 AI Agent。视口配置对 Agent 同样生效：
- Agent 每次观察（observation）都会收到当前视口尺寸，截图也只覆盖当前视口范围；
- 屏幕外的元素仍会出现在元素树中，Agent 会先滚动使其可见再操作；
- 想在手机尺寸下让 Agent 执行任务，必须先
setViewport再agent.act——Agent 自己不能改窗口大小。
await browser.setViewport({ width: 390, height: 844 }); await app.open('/'); await agent.act('open the navigation menu and go to Pricing');视口配置的边界与常见误区
新手最容易踩的坑，官方在 docs/web.mdx 的 Limits 小节说得很直白：
- 窄视口 ≠ 真手机：
viewport: { width: 390, height: 844 }只是缩小了窗口，用的仍是桌面浏览器——缩放系数为 1、桌面指针行为、原样 User-Agent。它不会模拟触摸、深色模式或减弱动态效果。要测真机模拟/模拟器，请使用 e2e 的 mobile 引擎（见 docs/mobile.mdx）。 - Playwright 迁移者注意：
use.viewport迁移为web({ viewport })，page.setViewportSize()对应browser.setViewport()，但devices['iPhone 15']这类带deviceScaleFactor、hasTouch的设备预设目前尚未支持，详见迁移对照表 docs/migrate/playwright.mdx。 viewport: null的正确用途：本地有头（headed）运行或托管浏览器的实时画面里，页面会填满窗口而不是固定 1280×720 挤在角落；录屏尺寸会跟随窗口，需要固定尺寸时用web({ screencast: { size } })。- 按尺寸跳过测试：
platforms和requires无法筛选视口，正确做法是在测试里读取window.innerWidth后用test.skip跳过不适用的尺寸。
总结：多分辨率测试的三步清单
- ✅ 在
e2e.config.ts中为桌面、平板、手机各建一个带name的 target，尺寸写在web({ viewport })里； - ✅ 需要"同一页面前后对比"的场景，用
browser.setViewport()动态改尺寸，并在app.open之前调用； - ✅ 需要触摸模拟、真实设备行为时切换到 mobile 引擎，而不是靠窄视口硬凑。
掌握这三步，你的 e2e 视口配置就覆盖了绝大多数多分辨率 Web 测试需求。更多细节可查阅 docs/browser.mdx 中关于浏览器与初始视口选项的说明。
【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
