Playwright Test (JS/TS) 官方文档精要

TS) 官方文档精要 是做什么的？

概述

本技能汇集了 Playwright 文档中容易出错的内容：自动等待规则、严格性、不会按预期堆叠的超时、模拟盲点、快照更新模式、CI 设置以及已移除的 API。不包含通用测试建议。每一条断言都附带了来源的文档 URL，便于查验。

涵盖版本

Playwright Test 1.64.1 for Node.js 和 TypeScript (@playwright/test)。不包含 Python、Java 和 .NET 内容。如果安装的版本较旧，在应用更新的 API 之前，请查看 references/version-changes.md 中的版本表。

导航方式

1. 阅读下面的快速入门。它涵盖了大多数测试中重要的规则。
2. 根据任务领域，打开末尾表格中对应的参考文件。
3. 在审查旧代码或升级之前，请阅读下方的“旧模式”和 references/version-changes.md。

快速入门

定位器

• 默认使用：page.getByRole(role, { name })。其次是 getByLabel、getByText（仅限非交互元素）、getByTestId 作为基于契约的备用方案。仅当没有用户可见的定位方式时，才使用 CSS 或 XPath。 https://playwright.dev/docs/locators#quick-guide
• 定位器是严格的：对匹配 2 个元素的定位器执行操作会抛出异常。使用 filter({ hasText })、filter({ has }) 或 inner.within(outer) 来缩小范围，而不是使用 first() / nth()。 https://playwright.dev/docs/locators#strictness
• filter({ has }) 内部的定位器是从外部匹配结果中解析的，而不是从页面根节点。 https://playwright.dev/docs/locators#filter-by-childdescendant
• 文本匹配默认是子字符串且不区分大小写的，并且始终会规范化空白字符，即使使用了 exact: true。 https://playwright.dev/docs/locators#locate-by-text

动作与等待

• 动作会自动等待元素可操作。不要在点击前添加 waitForTimeout 或手动等待页面加载。 https://playwright.dev/docs/actionability#introduction 和 https://playwright.dev/docs/navigations#when-is-the-page-loaded
• fill() 是文本输入的默认方法。pressSequentially() 仅用于逐键处理。 https://playwright.dev/docs/input#type-characters
• 事件（popup、download、filechooser、response）：在点击之前创建等待 promise，在点击之后等待它。

  const downloadPromise = page.waitForEvent('download');
  await page.getByText('Download file').click();
  const download = await downloadPromise;
  

  https://playwright.dev/docs/downloads#introduction
• 既不接受也不拒绝的 dialog 监听器会使页面挂起。如果没有监听器，对话框会自动关闭。 https://playwright.dev/docs/dialogs#alert-confirm-prompt-dialogs

断言

• 始终使用 await expect(locator).toX()。不要使用 expect(await locator.isVisible()).toBe(true)，后者只检查一次。 https://playwright.dev/docs/best-practices#use-web-first-assertions
• 断言超时时间为 5 秒，与 30 秒的测试超时时间分开。 https://playwright.dev/docs/test-timeouts
• 没有匹配的匹配器时，默认使用 expect.poll。expect(...).toPass() 默认没有超时，因此需要传入一个。 https://playwright.dev/docs/test-assertions#expecttopass
• 使用 Playwright 的 expect，而不是 Jest 的。 https://playwright.dev/docs/test-assertions#compatibility-with-expect-library

结构与配置

• 运行器选项放在 defineConfig 的顶层，浏览器和上下文选项放在 use 内部。 https://playwright.dev/docs/test-configuration#introduction
• 优先使用 Fixtures 而不是 before/after hook 对。测试从 fixtures 文件中导入 test。 https://playwright.dev/docs/test-fixtures#with-fixtures
• beforeAll 在每个 worker 中运行一次，并且 worker 在每次失败后重启，因此 beforeAll 可能运行多次。 https://playwright.dev/docs/test-retries#failures
• 在设置项目中通过 dependencies 登录一次，在等待最终 URL 后保存 storageState，并在 .gitignore 中添加 playwright/.auth。 https://playwright.dev/docs/auth#basic-shared-account-in-all-tests
• 先使用设备配置（spread），再覆盖 viewport，因为一个设备也定义了自己的 viewport。 https://playwright.dev/docs/emulation#viewport
• Playwright 不做类型检查。在 CI 上运行 tsc --noEmit，并使用 @typescript-eslint/no-floating-promises 进行 lint。 https://playwright.dev/docs/test-typescript#introduction 和 https://playwright.dev/docs/best-practices#lint-your-tests

网络

• 在 page.goto 之前注册 page.route。glob 模式必须匹配完整的 URL，并且 ? 只匹配字面问号。 https://playwright.dev/docs/mock#mock-api-requests 和 https://playwright.dev/docs/network#glob-url-patterns
• 路由会错过 service worker 提供服务的请求。设置 serviceWorkers: 'block'。 https://playwright.dev/docs/network#missing-network-events-and-service-workers
• page.request 共享浏览器 cookies。request.newContext() 是隔离的，并且必须被释放。 https://playwright.dev/docs/api-testing#context-request-vs-global-request

CI

• forbidOnly: !!process.env.CI，retries: process.env.CI ? 2 : 0，workers: process.env.CI ? 1 : undefined，trace: 'on-first-retry'，并且始终设置一个 globalTimeout，否则挂起的运行不会生成报告。 https://playwright.dev/docs/test-configuration#basic-configuration 和 https://playwright.dev/docs/ci#global-timeout
• 在 npm ci 之后和每次升级之后运行 npx playwright install --with-deps。不要缓存浏览器。 https://playwright.dev/docs/ci#caching-browsers
• 使用 fullyParallel: true 进行分片，并合并 blob 报告。 https://playwright.dev/docs/test-sharding#balancing-shards
• 对于共享资源的测试，使用锁进行序列化，而不是串行模式：test('x', { lock: 'db' }, ...)。 https://playwright.dev/docs/test-parallel#test-locks

快照

• 如果没有 -u，缺失的快照会被写入并且测试失败。--update-snapshots=missing 会写入并通过测试。-u 表示 changed。 https://playwright.dev/docs/aria-snapshots#updating-snapshots-with-playwrighttest-and-the---update-snapshots-flag
• 截图基线是每个浏览器和操作系统独立的。在比较它们的地方生成它们。 https://playwright.dev/docs/test-snapshots#introduction

旧模式

旧模式	当前模式	来源
locator.type()，page.type()	locator.fill()，或 pressSequentially()	https://playwright.dev/docs/release-notes#version-138
page.$()，ElementHandle，page.$eval + 通用 expect	定位器 + Web 优先断言	https://playwright.dev/docs/handles#locator-vs-elementhandle
expect(await locator.isVisible()).toBe(true)	await expect(locator).toBeVisible()	https://playwright.dev/docs/best-practices#dont-use-manual-assertions
:visible 伪类	locator.visible()	https://playwright.dev/docs/release-notes#version-163
text=Log in，id=，data-testid= 选择器	getByText，getByTestId	https://playwright.dev/docs/other-locators#legacy-text-locator
:right-of()，:near() 布局选择器	用户可见定位器	https://playwright.dev/docs/other-locators#css-matching-elements-based-on-layout
_react，_vue 选择器	标准定位器	https://playwright.dev/docs/release-notes#version-158
page.accessibility	@axe-core/playwright	https://playwright.dev/docs/release-notes#version-157
用于登录或数据初始化的 globalSetup	使用 dependencies 的设置项目	https://playwright.dev/docs/test-global-setup-teardown#introduction
用于共享资源的 test.describe.configure({ mode: 'serial' })	测试锁	https://playwright.dev/docs/test-parallel#test-locks
webServer.port	webServer.url	https://playwright.dev/docs/test-webserver#configuring-a-web-server
videosPath，videoSize	recordVideo，或者在运行器中使用 use.video	https://playwright.dev/docs/release-notes#version-160
devtools: true 启动选项	args: ['--auto-open-devtools-for-tabs']	https://playwright.dev/docs/release-notes#version-158
-gv 标志	--grep-invert 或 -G	https://playwright.dev/docs/release-notes#version-154
用于录制的 npx playwright open	npx playwright codegen	https://playwright.dev/docs/release-notes#version-154
用于刷新已更改快照的 updateSnapshots: 'all'	'changed'（'all' 重写所有内容）	https://playwright.dev/docs/release-notes#version-150
waitUntil: 'networkidle'	自动等待和 Web 优先断言	https://playwright.dev/docs/puppeteer#automation-example
使用 JSX mount(<C />) 的 @playwright/experimental-ct-*	来自 @playwright/test 的 stories + mount('Story/Id', props)	https://playwright.dev/docs/test-components#migration-from-the-experimental-packages
通过 npm install 下载的浏览器	npx playwright install --with-deps	https://playwright.dev/docs/release-notes#version-138

参考文件

文件	适用场景
references/locators.md	定位器优先级、文本匹配、严格性、filter、within、and / or、visible()、Shadow DOM、框架、遗留选择器
references/actions-and-events.md	每个动作的可操作性检查、force、输入、拖放、对话框、下载、上传、弹出窗口、导航、水合、evaluate、初始化脚本、句柄
references/assertions.md	Web 优先与通用匹配器、断言超时、expect.poll、toPass、软断言、自定义匹配器、test.step
references/snapshots-and-accessibility.md	快照更新模式、aria 快照、toHaveScreenshot 容差和命名、非图像快照、axe 扫描
references/configuration.md	配置结构、use 作用域和默认值、项目和依赖项、设备和模拟、TypeScript 处理、webServer
references/timeouts-retries-annotations.md	所有超时及其默认值、重试和 worker 重启、串行模式、skip / fail / fixme、标签、参数化测试和项目
references/fixtures-and-auth.md	隔离、自定义 fixtures、作用域、选项、执行顺序、全局 hooks、设置项目、页面对象、storageState 认证、角色、每个 worker 的账户
references/network-and-mocking.md	route、glob 规则、route 无法触及的标头和重定向、HAR 记录和回放、WebSocket 模拟、浏览器 API 模拟、service worker
references/api-testing-and-clock.md	request fixture、共享与隔离的 cookies、释放上下文、page.clock 方法和顺序
references/ci-parallel-sharding.md	CI 基线、GitHub Actions 和其他提供商、workers、fullyParallel、测试锁、分片、blob 报告合并
references/browsers-and-docker.md	浏览器安装和缓存、Chromium 渠道、代理和镜像、Docker 镜像、Chrome 扩展、WebView2、Selenium Grid
references/debugging-and-reporting.md	CLI 标志、--debug、Inspector、跟踪和视频模式、跟踪查看器、UI 模式、报告器
references/component-testing-and-migration.md	stories 和画廊组件测试、从实验性 ct 包迁移、Testing Library、Protractor、Puppeteer
references/codegen-and-agent-tooling.md	codegen、Library 与 Test、发布渠道、Test Agents、playwright-cli、Playwright MCP
references/version-changes.md	破坏性行为变更、已移除和弃用的 API 及其替代方案、平台支持变更

来源和获取详情列在 SOURCES.md 中。