Java自动化测试新选择：Playwright核心优势与实战指南-尧图网络科技

1. 项目概述：为什么是 Playwright for Java？

如果你是一名 Java 后端开发，或者正在向测试开发、自动化方向转型，最近可能频繁听到一个词：Playwright。尤其是在自动化测试、网页数据抓取（RPA）这些场景里，它几乎成了新的“网红”框架。但网上的教程和讨论，十有八九都是围绕 Python 或 Node.js 版本的，这让很多 Java 技术栈的团队和个人感到困惑：Playwright for Java 到底行不行？它和 Selenium 比优势在哪？现在入坑是不是好时机？

作为一个在自动化领域摸爬滚打多年的老手，我可以很负责任地告诉你：Playwright for Java 不仅完全可行，而且正当时。它绝不是 Python 版本的简单移植或“二等公民”。微软官方对 Java 绑定的支持非常到位，其核心的跨浏览器、自动等待、网络拦截等强大能力，在 Java 中都能得到原生、高效的使用。对于长期受困于 Selenium WebDriver 的 flaky tests（不稳定的测试）、复杂配置和性能问题的 Java 团队来说，Playwright 带来的是一种“降维打击”式的体验提升。

简单来说，Playwright for Java 是一个由微软开源的浏览器自动化库，它允许你通过 Java 代码来控制 Chromium、Firefox 和 WebKit（Safari 内核）浏览器，进行自动化测试、网页截图、PDF 生成、单页应用（SPA）的端到端测试以及数据抓取等工作。它的设计哲学是“为现代 Web 而生”，天生支持 iframe、Shadow DOM、网络请求模拟、文件上传下载等现代 Web 开发中的常见且棘手的问题。

那么，它适合谁呢？首先，当然是测试工程师和测试开发工程师，尤其是那些厌倦了与 Selenium 的隐式/显式等待斗智斗勇，或者需要做跨浏览器兼容性测试的团队。其次，是需要做网页数据采集或流程自动化的后端开发，比如定时抓取某些公开数据、自动填写表单等。Playwright 的稳定性和强大的选择器，比传统的 Jsoup（仅解析静态 HTML）或 HtmlUnit（无头浏览器但功能较弱）要强大和可靠得多。最后，它也适合任何对浏览器自动化感兴趣的 Java 开发者，作为一个提升技术广度和解决实际问题的利器。

2. 核心优势与 Selenium 的深度对比

在决定引入一项新技术前，我们总要问：它比现有的方案好在哪里？对于 Java 生态的浏览器自动化，Selenium 是绕不开的“老大哥”。因此，将 Playwright for Java 与 Selenium WebDriver 进行深度对比，是理解其价值的关键。

2.1 架构与执行模式的根本差异

这是两者最核心的区别，也决定了后续所有体验的不同。

Selenium WebDriver：采用的是Client-Server 架构。你的 Java 测试代码是 Client，它通过 HTTP 协议向一个独立的、作为 Server 的浏览器驱动（如 chromedriver、geckodriver）发送命令（遵循 W3C WebDriver 协议）。驱动再通过浏览器提供的调试协议（如 Chrome DevTools Protocol）来控制真实的浏览器。这个链条长，任何一环出问题（如驱动与浏览器版本不匹配、网络延迟）都可能导致测试失败或不稳定。
Playwright：采用的是Library 架构。Playwright 的核心库直接通过浏览器提供的调试协议（同样是 CDP 等）与浏览器进程通信。在 Java 中，它通过一个称为 “Playwright Java Client” 的库，与一个由 Playwright 管理的本地浏览器实例进行进程间通信。它没有中间驱动层。这意味着更少的依赖、更快的启动速度和更稳定的连接。

注意：正因为没有“驱动”这个概念，Playwright 安装后，你需要运行playwright install命令来下载它自己管理的浏览器版本。这些浏览器是专门为自动化优化过的，与你在系统里安装的 Chrome 或 Firefox 是隔离的，这保证了环境的一致性。

2.2 自动等待：从“玄学”到“科学”

等待问题是 Web 自动化中最常见的痛点。一个元素还没加载出来，代码就去点击，结果就是NoSuchElementException。

Selenium：你需要手动处理等待。虽然有ImplicitlyWait（隐式等待）和WebDriverWait（显式等待），但用起来并不省心。隐式等待是全局的，对某些操作可能不生效或导致不必要的等待；显式等待需要你为每个需要等待的操作编写额外的代码，繁琐且容易遗漏。
Playwright：内置了智能的自动等待机制。当你执行page.click(“button#submit”)时，Playwright 会自动执行一系列检查，直到这个按钮：1) 在 DOM 中存在；2) 可见；3) 可交互（未被禁用、未被其他元素遮挡）；4) 稳定（不再有动画效果）。只有所有这些条件都满足，它才会执行点击操作。这极大地减少了因时机问题导致的测试失败，让测试代码更简洁、更健壮。

2.3 选择器引擎：更强大，更抗变

定位元素是自动化的基础。Playwright 提供了多种强大的选择器引擎，远超 CSS 和 XPath。

文本选择器：page.click(“text=登录”)可以直接点击包含“登录”文本的元素。这在测试中文网站或文本经常变动的 UI 时非常有用。
React/Vue 组件选择器：如果你测试的是基于 React 或 Vue 开发的应用，可以直接通过组件名和属性来定位，如page.click(“_react=SubmitButton[enabled=true]”)。这使测试与前端实现细节解耦，更专注于业务逻辑。
布局选择器：可以基于元素的相对位置（如左、右、近）来定位，这在处理复杂或动态生成的列表时很有帮助。

这些选择器不仅强大，而且 Playwright 会记录足够多的上下文信息，当 UI 发生微小变化时（比如一个div变成了section），它的测试录制工具codegen能够给出更健壮的定位建议。

2.4 网络与上下文：全方位的控制力

现代 Web 应用高度依赖网络请求。Playwright 在这方面提供了 Selenium 难以企及的控制能力。

拦截和修改请求/响应：你可以轻松地拦截网络请求，修改其头信息、POST 数据，或者直接 mock 一个响应。这对于测试错误处理、模拟第三方 API 失败、或跳过某些耗时的资源加载（如图片、视频）以加速测试至关重要。
多上下文与认证隔离： Playwright 的BrowserContext概念类似于浏览器的“隐身会话”。你可以在一个浏览器实例中创建多个完全隔离的上下文，每个上下文有自己的 cookies、本地存储和缓存。这意味着你可以在一个测试套件中轻松模拟多个用户同时登录，而无需启动多个浏览器进程，资源消耗极小。
文件处理：上传文件不再需要找input[type=file]元素然后sendKeys。Playwright 允许你直接通过文件路径设置文件，甚至监听文件下载事件，并将下载的文件保存到指定位置。

实操心得：我曾经的一个项目需要测试一个依赖外部地图服务的功能。使用 Selenium 时，网络不稳定会导致测试超时失败。切换到 Playwright 后，我直接拦截了地图 API 的请求，返回一个静态的、预设好的成功响应，测试速度提升了 5 倍以上，且 100% 稳定。这种对网络层的掌控力，是提升测试稳定性和执行效率的“杀手锏”。

3. 环境搭建与核心 API 实战解析

理论说得再多，不如上手实操。我们来一步步搭建 Playwright for Java 环境，并深入解析其最核心的 API 如何使用。

3.1 项目初始化与依赖管理

假设你使用 Maven 作为构建工具。在你的pom.xml中添加以下依赖：

<dependency> <groupId>com.microsoft.playwright</groupId> <artifactId>playwright</artifactId> <version>1.43.0</version> <!-- 请使用最新稳定版本 --> </dependency>

如果你使用 Gradle，则在build.gradle的dependencies块中添加：

implementation ‘com.microsoft.playwright:playwright:1.43.0’

添加依赖后，你还需要安装 Playwright 管理的浏览器。有两种方式：

通过 Maven 插件自动安装（推荐）：在pom.xml的<build><plugins>部分添加：

<plugin> <groupId>com.microsoft.playwright</groupId> <artifactId>playwright-maven-plugin</artifactId> <version>1.43.0</version> <executions> <execution> <goals> <goal>install</goal> </goals> </execution> </executions> </plugin>

然后执行mvn compile，插件会自动下载浏览器。

手动命令行安装：在项目根目录下执行命令mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args=”install”。或者，如果你全局安装了 Playwright CLI，也可以直接运行playwright install。

注意：首次安装会下载几百MB的浏览器文件，请确保网络通畅。这些浏览器会安装在用户主目录下的缓存目录中，与系统浏览器互不干扰。

3.2 核心 API 四步曲：Playwright -> Browser -> Context -> Page

Playwright 的 API 设计层次清晰，遵循Playwright->Browser->BrowserContext->Page的创建顺序。理解每一层的作用是关键。

第一步：创建 Playwright 实例这是入口点。通常使用try-with-resources语法确保资源被正确关闭。

import com.microsoft.playwright.*; public class BasicExample { public static void main(String[] args) { // try-with-resources 自动管理 Playwright 和 Browser 的关闭 try (Playwright playwright = Playwright.create()) { // ... 后续代码 } } }

第二步：启动浏览器通过Playwright实例启动一个特定类型的浏览器。你可以选择chromium,firefox或webkit。launch()方法接受一个BrowserType.LaunchOptions对象，用于配置启动参数。

// 启动一个无头模式的 Chromium 浏览器（默认无头） Browser browser = playwright.chromium().launch(); // 启动一个有界面的浏览器，方便调试 Browser browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setHeadless(false)); // 启动一个慢速模式，方便观察操作 Browser browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setSlowMo(500));

第三步：创建浏览器上下文这是 Playwright 中非常强大的一个概念。一个BrowserContext相当于一个独立的浏览器会话，拥有独立的 cookies、缓存和本地存储。你可以在一个浏览器实例中创建多个上下文来模拟多个用户。

// 创建一个新的上下文 BrowserContext context = browser.newContext(); // 可以在此处为上下文设置一些初始状态，如视口大小、User-Agent、地理位置等 BrowserContext context = browser.newContext(new Browser.NewContextOptions() .setViewportSize(1920, 1080) .setUserAgent(“My Custom Agent”));

第四步：打开页面在上下文中创建新的标签页，即Page对象。绝大部分的自动化操作都发生在Page层面。

Page page = context.newPage(); // 导航到一个网址 page.navigate(“https://example.com");

一个完整的“Hello World”示例看起来是这样的：

import com.microsoft.playwright.*; public class HelloPlaywright { public static void main(String[] args) { try (Playwright playwright = Playwright.create()) { Browser browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setHeadless(false)); BrowserContext context = browser.newContext(); Page page = context.newPage(); page.navigate(“https://playwright.dev"); System.out.println(page.title()); // 输出：Fast and reliable end-to-end testing for modern web apps | Playwright page.screenshot(new Page.ScreenshotOptions().setPath(Paths.get(“screenshot.png”))); // 资源会在 try-with-resources 块结束时自动关闭 } } }

3.3 元素定位与交互：告别脆弱的 XPath

定位并操作元素是自动化的核心。Playwright 提供了多种稳健的方式。

基础定位与操作：

// 1. CSS 选择器 (最常用) page.click(“button.submit”); page.fill(“input#username”, “myUser”); // 2. 文本选择器 - 极其有用！ page.click(“text=登录”); // 点击任何包含“登录”文本的元素 page.click(“text=’精确文本’”); // 点击文本完全等于“精确文本”的元素 // 3. XPath (备用) page.click(“//button[@id=’submit’]”); // 组合使用，提高准确性 // 找到包含“购物车”文本的 span，然后找到它上层的 button 并点击 page.click(“button:has(span:text(‘购物车’))”);

处理复杂场景：

// 等待元素出现（虽然自动等待很强，但有时需要显式控制） page.waitForSelector(“div.success-message”, new Page.WaitForSelectorOptions().setState(WaitForSelectorState.VISIBLE)); // 获取元素属性或文本内容 String href = page.getAttribute(“a.link”, “href”); String textContent = page.textContent(“div.description”); // 处理下拉框 page.selectOption(“select#country”, “CN”); // 通过 value page.selectOption(“select#country”, new SelectOption().setLabel(“中国”)); // 通过显示文本 // 上传文件（非常简单！） page.setInputFiles(“input[type=file]”, Paths.get(“/path/to/myfile.pdf”)); // 处理弹窗/对话框 page.onDialog(dialog -> { System.out.println(“对话框信息：” + dialog.message()); dialog.accept(); // 点击“确定” // dialog.dismiss(); // 点击“取消” });

实操心得：在定位元素时，优先使用文本选择器和基于语义的 CSS 选择器（如[data-testid]），尽量避免使用依赖复杂 DOM 结构或绝对位置的 XPath。前者更贴近用户视角（用户看到的是文本），后者通常由前端开发特意为测试而设，稳定性最高。Playwright 的录制工具 (mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args=”codegen https://example.com“) 生成的代码通常会给出几种定位建议，是学习选择器用法的好帮手。

4. 高级特性与应用场景深度探索

掌握了基础操作，我们来看看 Playwright for Java 那些能真正解决痛点的“高级货”。这些特性将它从一个简单的浏览器控制器，变成了一个强大的 Web 自动化平台。

4.1 网络拦截与 Mock：让测试快如闪电且稳如磐石

这是 Playwright 相对于 Selenium 的“王牌”功能。通过page.route()方法，你可以拦截任何网络请求。

场景一：阻断不必要的资源，加速测试

// 拦截所有图片请求，直接中止，节省带宽和加载时间 page.route(“**/*.{png,jpg,jpeg,webp,gif}”, route -> route.abort()); // 或者，更精细地，只拦截特定模式的请求 page.route(“https://api.ads.com/**”, route -> route.abort());

场景二：修改请求或 Mock 响应

// 1. 修改请求头（例如，添加认证令牌） page.route(“https://api.example.com/**”, route -> { Map<String, String> headers = new HashMap<>(route.request().headers()); headers.put(“Authorization”, “Bearer fake-token-for-test”); route.resume(new Route.ResumeOptions().setHeaders(headers)); }); // 2. Mock一个API响应（用于测试前端在不同数据下的表现） page.route(“https://api.example.com/user/profile”, route -> { route.fulfill(new Route.FulfillOptions() .setStatus(200) .setContentType(“application/json”) .setBody(“{\”name\”: \”Mock User\”, \”role\”: \”admin\”}”)); }); // 3. 修改响应体（例如，在真实响应上打补丁） page.route(“https://news.site.com/list”, route -> { Response response = route.fetch(); // 先发起真实请求 String originalBody = response.text(); // 对 originalBody 进行 JSON 解析和修改... String modifiedBody = originalBody.replace(“someText”, “replacedText”); route.fulfill(new Route.FulfillOptions() .setResponse(response) .setBody(modifiedBody)); });

个人体会：在一个电商项目的测试中，支付回调是一个第三方服务，测试环境极不稳定。我们通过page.route()完全 Mock 了支付成功和失败的回调，使得整个下单-支付流程的测试可以在完全隔离的环境下运行，成功率从不到 70% 提升到了 100%，并且单次测试时间从分钟级降到秒级。

4.2 多上下文与认证状态隔离

利用BrowserContext，我们可以优雅地处理多用户场景和状态隔离。

try (Playwright playwright = Playwright.create()) { Browser browser = playwright.chromium().launch(); // 模拟用户A BrowserContext contextA = browser.newContext(); Page pageA = contextA.newPage(); pageA.navigate(“https://example.com/login”); pageA.fill(“#username”, “userA”); pageA.fill(“#password”, “passA”); pageA.click(“text=登录”); // pageA 现在处于已登录状态 // 模拟用户B - 完全独立的会话 BrowserContext contextB = browser.newContext(); Page pageB = contextB.newPage(); pageB.navigate(“https://example.com”); // pageB 是未登录状态，与 pageA 的 cookies 不共享 // 可以在同一个测试中同时操作两个用户 // 例如，测试用户A给用户B发送消息的功能 pageA.click(“text=联系人”); pageA.fill(“input[placeholder=’搜索’]”, “userB”); // ... pageB.waitForSelector(“text=您有一条新消息”); // 结束时关闭上下文 contextA.close(); contextB.close(); }

4.3 处理 iframe 和 Shadow DOM

现代 Web 应用，特别是那些使用微前端或第三方组件库的，iframe 和 Shadow DOM 无处不在。Playwright 处理它们非常直接。

处理 iframe：

// 通过名称或URL定位iframe Frame frame = page.frame(“frame-name”); // 或 Frame frame = page.frameByUrl(“**/widget.html”); // 在iframe内部进行操作 frame.click(“button”); frame.fill(“input”, “data”); // 更通用的方式：使用 frameLocator FrameLocator locator = page.frameLocator(“iframe.component”).locator(“text=提交”); locator.click();

处理 Shadow DOM：在 Selenium 中，穿透 Shadow DOM 需要执行 JavaScript。Playwright 简化了这一切，它的选择器引擎默认支持穿透 Shadow DOM。

// 假设有一个自定义组件 <my-button>，按钮在它的 shadow root 里 // 使用 `>>` 语法来穿透 shadow 边界 page.click(“my-button >> button”); // 如果有多层 shadow DOM，可以连续穿透 page.click(“custom-dialog >> custom-card >> div.content >> span”);

4.4 录制与调试：提升开发效率

Playwright 提供了强大的命令行工具来辅助开发和调试。

录制脚本 (Codegen)：这是入门和快速生成脚本的神器。运行mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args=”codegen https://your-site.com“，它会打开一个浏览器和一个录制窗口。你在浏览器里的所有操作都会被实时转换成 Java 代码。这不仅是学习 API 的好方法，也能快速创建基础测试脚本。
调试模式：在启动浏览器时设置setHeadless(false)可以观看执行过程。更强大的是，你可以使用playwright debug命令，或者在你的 IDE 中正常调试 Java 代码，浏览器会以可观察的模式运行。
追踪查看器 (Trace Viewer)：在测试失败时，光看日志和截图可能不够。Playwright 可以录制整个测试过程的追踪文件（trace）。
```
// 在测试开始时启动追踪 context.tracing().start(new Tracing.StartOptions().setScreenshots(true).setSnapshots(true)); // ... 执行测试操作 ... // 测试失败时保存追踪文件 context.tracing().stop(new Tracing.StopOptions().setPath(Paths.get(“trace.zip”)));
```
生成的trace.zip可以用 Playwright 的命令行工具playwright show-trace trace.zip打开，它是一个图形化界面，可以逐帧回放测试执行过程，查看每个时刻的 DOM 快照、网络请求、控制台日志，是排查偶发性问题的终极武器。

5. 集成测试框架与 CI/CD 实践

单独运行一段 Playwright 脚本和构建一个健壮的自动化测试体系是两回事。我们需要将其集成到标准的 Java 测试框架中，并融入 CI/CD 流程。

5.1 与 JUnit 5 深度集成

JUnit 5 是目前 Java 单元测试的事实标准。Playwright 与之集成非常顺畅。我们可以利用 JUnit 5 的扩展模型（如TestWatcher,ParameterResolver）来管理 Playwright 资源的生命周期。

基础集成示例：

import com.microsoft.playwright.*; import org.junit.jupiter.api.*; import java.nio.file.Paths; import static org.junit.jupiter.api.Assertions.*; @TestInstance(TestInstance.Lifecycle.PER_CLASS) // 便于共享资源 public class LoginTest { // 共享的资源 Playwright playwright; Browser browser; BrowserContext context; Page page; @BeforeAll public void setUpAll() { playwright = Playwright.create(); browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setHeadless(true)); // CI 环境通常无头 } @AfterAll public void tearDownAll() { if (browser != null) { browser.close(); } if (playwright != null) { playwright.close(); } } @BeforeEach public void setUp() { // 每个测试一个独立的上下文，保证隔离性 context = browser.newContext(); // 启动追踪，仅在失败时保存（节省空间） context.tracing().start(new Tracing.StartOptions().setScreenshots(true).setSnapshots(true)); page = context.newPage(); } @AfterEach public void tearDown(TestInfo testInfo) { // 如果测试失败，保存追踪文件和截图 if (testInfo.getExecutionException().isPresent()) { String traceName = String.format(“trace-%s.zip”, testInfo.getDisplayName()); context.tracing().stop(new Tracing.StopOptions().setPath(Paths.get(“target/traces/”, traceName))); // 截图 page.screenshot(new Page.ScreenshotOptions() .setPath(Paths.get(“target/screenshots/”, String.format(“%s-failed.png”, testInfo.getDisplayName()))) .setFullPage(true)); } else { context.tracing().stop(new Tracing.StopOptions().setPath(null)); // 成功则不保存 } if (context != null) { context.close(); } } @Test public void successfulLogin() { page.navigate(“https://the-internet.herokuapp.com/login”); page.fill(“#username”, “tomsmith”); page.fill(“#password”, “SuperSecretPassword!”); page.click(“button[type=’submit’]”); assertTrue(page.isVisible(“text=’Secure Area’”), “登录后应跳转到安全区域”); } }

进阶：创建自定义扩展：为了减少样板代码，可以创建一个 JUnit 5 扩展，自动注入Page对象并管理生命周期。

import com.microsoft.playwright.*; import org.junit.jupiter.api.extension.*; public class PlaywrightExtension implements BeforeAllCallback, AfterAllCallback, BeforeEachCallback, AfterEachCallback { private static Playwright playwright; private static Browser browser; private BrowserContext context; private Page page; @Override public void beforeAll(ExtensionContext context) { playwright = Playwright.create(); browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setHeadless(true)); } @Override public void afterAll(ExtensionContext context) { if (browser != null) browser.close(); if (playwright != null) playwright.close(); } @Override public void beforeEach(ExtensionContext context) { this.context = browser.newContext(); this.page = this.context.newPage(); // 将 page 存入当前测试上下文，方便测试方法获取 context.getStore(ExtensionContext.Namespace.GLOBAL).put(“page”, page); } @Override public void afterEach(ExtensionContext context) { if (this.context != null) this.context.close(); } // 提供一个静态方法供测试类获取 Page public static Page getPage(ExtensionContext context) { return context.getStore(ExtensionContext.Namespace.GLOBAL).get(“page”, Page.class); } } // 在测试类中使用 @ExtendWith(PlaywrightExtension.class) public class MyTest { @Test public void myTest(TestInfo testInfo) { Page page = PlaywrightExtension.getPage(ExtensionContextSupport.getContext(testInfo)); page.navigate(“https://example.com”); // ... } }

5.2 生成丰富的测试报告

清晰的测试报告对于团队协作至关重要。Playwright 可以与主流报告框架集成。

Allure 报告： Allure 是功能强大的测试报告框架。你需要添加 Allure 依赖和 Playwright 的 Allure 监听器。
1. 在pom.xml中添加 Allure 依赖和插件。
2. 在测试执行时，Playwright 会自动将步骤信息、截图（失败时）、追踪文件链接附加到 Allure 报告中。你需要配置 Allure 以识别这些附件。
3. 在 CI 中运行测试后，可以生成一个美观的 HTML 报告，其中包含每个测试的详细步骤和丰富的上下文信息。
HTML 报告： Playwright Test 的 Node.js 版本有内置的 HTML 报告器。对于 Java，社区有类似方案，或者你可以自己通过监听测试事件，收集截图和日志，用模板引擎（如 Thymeleaf）生成一个简单的 HTML 报告。

实操心得：在 CI 中运行 Playwright 测试，务必使用无头模式 (setHeadless(true))，并且考虑使用 Docker 容器来提供一致的浏览器环境。对于失败的测试，一定要配置自动保存追踪文件。我们团队曾花数小时排查一个只在 CI 上偶发的失败案例，最后通过分析追踪文件，发现是因为一个第三方字体加载超时，导致页面布局轻微变化，元素点击坐标偏移。没有追踪文件，这种问题几乎无法定位。

5.3 在 CI/CD 流水线中运行

将 Playwright 测试集成到 Jenkins、GitLab CI、GitHub Actions 等 CI/CD 工具中是标准操作。

以GitHub Actions为例，一个基本的.github/workflows/playwright.yml配置如下：

name: Playwright Tests on: [push, pull_request] jobs: test: timeout-minutes: 60 runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-java@v4 with: distribution: ‘temurin’ java-version: ‘17’ - name: Cache Maven dependencies uses: actions/cache@v3 with: path: ~/.m2 key: maven-${{ hashFiles(‘**/pom.xml’) }} restore-keys: | maven- - name: Cache Playwright browsers uses: actions/cache@v3 with: path: ~/.cache/ms-playwright key: playwright-${{ hashFiles(‘**/pom.xml’) }} - name: Install Playwright browsers run: mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args=”install –with-deps chromium” # ‘–with-deps’ 在 Linux 上安装必要的系统依赖 - name: Run Playwright tests run: mvn test - uses: actions/upload-artifact@v3 if: always() # 无论成功失败都上传 with: name: playwright-reports path: | target/screenshots/ target/traces/ retention-days: 7

这个配置做了几件关键事：1) 设置 Java 环境；2) 缓存 Maven 依赖和 Playwright 浏览器以减少构建时间；3) 安装浏览器及其系统依赖；4) 运行测试；5) 将截图和追踪文件上传为制品，供后续下载分析。

6. 常见问题排查与性能优化指南

即使有了强大的工具，在实际项目中还是会遇到各种问题。这里总结一些我踩过的坑和解决方案。

6.1 元素定位失败：最常见的问题

症状：TimeoutError: Timeout 30000ms exceeded.或Error: Element not found.

排查思路：

确认页面加载完成：在操作前，是否使用了page.waitForLoadState(LoadState.NETWORKIDLE)或page.waitForURL()确保页面处于稳定状态？
检查选择器：使用 Playwright DevTools（在录制模式或通过playwright open命令）检查你的选择器是否唯一匹配目标元素。浏览器的开发者工具里的 “Playwright Inspector” 面板非常有用。
处理动态内容/iframe：元素是否在 iframe 或 Shadow DOM 内？是否在某个动态加载的组件里？确保你的选择器路径正确，必要时使用page.frameLocator()或>>语法。
等待策略：虽然 Playwright 有自动等待，但某些极端动态的元素（如基于复杂 JS 计算后渲染）可能需要额外等待。尝试page.waitForFunction()等待一个特定的 JS 条件成立。
```
page.waitForFunction(() => document.querySelector(‘.spinner’) === null); // 等待加载动画消失
```

6.2 测试执行缓慢

可能原因与优化：

浏览器启动开销：避免每个测试都启动关闭浏览器。使用@BeforeAll启动浏览器，@BeforeEach创建新的上下文和页面。上下文创建比浏览器启动快几个数量级。
网络延迟：使用page.route()拦截并阻断不必要的资源（如图片、样式表、字体、分析脚本、广告）。这通常能带来最显著的提速。
操作等待时间：检查是否因某些操作（如page.waitForTimeout(5000)）引入了不必要的硬性等待。尽量用事件驱动的等待（waitForSelector,waitForResponse）替代。
并行执行： JUnit 5 支持并行测试。确保你的测试是相互独立的（使用独立的BrowserContext），然后配置junit-platform.properties启用并行执行。
```
# junit-platform.properties junit.jupiter.execution.parallel.enabled=true junit.jupiter.execution.parallel.mode.default=concurrent
```

6.3 在 CI 环境中的特殊问题

“No usable sandbox!” 错误：在 Docker 容器或某些 CI 环境中，Chromium 的沙箱可能不受支持。解决方法是在启动浏览器时禁用沙箱（仅限你完全信任测试代码的环境）。
```
browser = playwright.chromium().launch(new BrowserType.LaunchOptions() .setHeadless(true) .setArgs(Arrays.asList(“–no-sandbox”, “–disable-dev-shm-usage”))); // 后者解决内存问题
```
内存不足 (OutOfMemoryError)：长时间运行大量测试可能导致内存泄漏。确保在@AfterEach或@AfterAll中正确调用了context.close()和browser.close()。对于非常大规模的测试套件，可以考虑定期重启浏览器实例。
浏览器版本不匹配： CI 环境安装的浏览器版本应与本地开发环境一致。通过将 Playwright 版本和playwright install命令固化在 CI 配置中来解决。

6.4 与 Selenium 遗留代码共存与迁移

很多项目已有大量 Selenium 测试，重写成本高。过渡期可以共存。

渐进式迁移：为新功能或重写的模块编写 Playwright 测试。对于稳定的旧功能，暂时保留 Selenium 测试。
抽象层：可以创建一个抽象的 “BrowserDriver” 接口，然后分别用 Selenium 和 Playwright 实现。这样业务测试代码不依赖具体框架，便于未来切换。但这会引入额外的复杂度，需权衡。
重点迁移：优先迁移那些最不稳定、运行最慢的 Selenium 测试到 Playwright，以快速获得收益。

从 Selenium 迁移到 Playwright，最大的改变是思维模式：从“命令-响应”模式转向“声明-等待”模式。你不再需要频繁地写WebDriverWait，而是相信 Playwright 的自动等待，把精力更多放在业务逻辑和测试场景本身上。