Playwright Java 测试编写指南：Web-First 断言、Locator 定位与测试隔离实践

本篇技术文章基于 Playwright 官方文档 Writing tests (Java)，面向使用 Java 生态（JUnit 等）的自动化测试开发者。文章完整覆盖原文档的核心内容——一个可运行的完整 Java 测试示例、自动重试的 Web-First 断言、基于 Locator 的元素定位，以及基于 BrowserContext 的测试隔离机制，并结合仓库中的断言 API 参考与 JUnit 集成文档补充了超时配置、可用断言清单和源码级依据。读完后你将掌握：如何在 Java 中编写带自动等待的重试断言、如何选择不同种类的 Locator、如何为每个测试构造隔离的浏览器环境。

概述：为什么 Playwright 的 Java 测试"更稳"

Playwright 的断言是专门为动态 Web 场景设计的：检查（assertion）会自动重试，直到预期条件成立为止。Playwright 内置了 auto-wait（自动等待），在执行操作前会先等待元素进入可操作状态（actionable state）。同时，Playwright 提供了 assertThat 重载方法族，用于编写针对页面、元素、API 响应的断言。

这一设计解决了传统测试框架最常见的痛点：页面元素尚未渲染完成就去查找它，导致偶发性失败（flaky test）。在 Java 中，你只需要调用 PlaywrightAssertions 提供的 assertThat 静态方法，重试与等待逻辑由框架自动完成，而无需手写 Thread.sleep 或轮询循环。

先看一个完整的入门测试，它演示了如何在 Java 中组合使用 Web-First 断言、Locator 与选择器（以下代码继承自 writing-tests-java.md，保持原样可运行）：

package org.example;

import java.util.regex.Pattern;
import com.microsoft.playwright.*;
import com.microsoft.playwright.options.AriaRole;

import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;

public class App {
    public static void main(String[] args) {
        try (Playwright playwright = Playwright.create()) {
            Browser browser = playwright.chromium().launch();
            Page page = browser.newPage();
            page.navigate("https://playwright.dev");

            // Expect a title "to contain" a substring.
            assertThat(page).hasTitle(Pattern.compile("Playwright"));

            // create a locator
            Locator getStarted = page.getByRole(AriaRole.LINK, new Page.GetByRoleOptions().setName("Get Started"));

            // Expect an attribute "to be strictly equal" to the value.
            assertThat(getStarted).hasAttribute("href", "/docs/intro");

            // Click the get started link.
            getStarted.click();

            // Expects page to have a heading with the name of Installation.
            assertThat(page.getByRole(AriaRole.HEADING,
               new Page.GetByRoleOptions().setName("Installation"))).isVisible();
        }
    }
}

这个示例覆盖了 Java 写测试的三个基本要素：

• Playwright.create() 与 try-with-resources：Java 客户端资源是可关闭的，try 语句结束时会自动释放浏览器进程，保证进程不泄漏。
• assertThat(page).hasTitle(...)：对页面标题做断言，支持 java.util.regex.Pattern 正则匹配，且会自动重试。
• page.getByRole(...) 创建 Locator：按 ARIA role 加名称定位元素，是原文档推荐的核心定位方式之一。
• locator.click()：动作方法本身也带 auto-wait，点击前会等待元素可见、稳定、可接收事件。

断言：assertThat 与自动重试

Playwright 提供 assertThat 重载，这些断言会持续重试直到预期条件满足或超时。最小示例：

import java.util.regex.Pattern;
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;

assertThat(page).hasTitle(Pattern.compile("Playwright"));

从 class-playwrightassertions.md 的 API 参考可以确认其底层机制：Playwright 会"反复重新获取该节点并检查，直到条件满足或超时"（原文：It will be re-fetching the node and checking it over and over, until the condition is met or until the timeout is reached）。也就是说，断言失败时框架不是立即抛错，而是循环执行"取元素 → 求值 → 再取"，直到条件成立。

在 Java 中，assertThat 是 PlaywrightAssertions 类的静态导入别名，根据 API 参考（该文档标注 alias-java: assertThat），它对应三类断言工厂方法：

工厂方法（JS 侧命名）	返回类型	Java 用法
expectPage	PageAssertions	assertThat(page).hasTitle("News") / hasURL(...)
expectLocator	LocatorAssertions	assertThat(locator).isVisible() / hasText(...) / hasAttribute(...)
expectAPIResponse	APIResponseAssertions	assertThat(response).isOK()

此外，Playwright 内置了一套 Web 专用断言集合（Java 中以 has* / is* 命名），完整的可重试断言列表见 Assertions 文档，核心项包括：

• 可见性/状态类：toBeVisible / toBeHidden / toBeAttached / toBeChecked / toBeDisabled / toBeEnabled / toBeEditable / toBeEmpty / toBeFocused / toBeInViewport；
• 文本/属性类：toHaveText / toContainText / toHaveAttribute / toHaveId / toHaveValue / toHaveValues / toHaveCount / toHaveCSS / toHaveClass / toContainClass / toHaveJSProperty；
• 可访问性类：toHaveRole / toHaveAccessibleName / toHaveAccessibleDescription / toMatchSnapshot（Aria 快照）；
• 页面级：PageAssertions.toHaveTitle / toHaveURL；
• API 级：APIResponseAssertions.toBeOK。

默认超时与自定义超时

根据 test-assertions-csharp-java-python.md 与 class-playwrightassertions.md，断言的默认超时为 5 秒，与动作（如 click）的默认超时相互独立。Java 中可通过两种方式覆盖：

全局默认超时——setDefaultAssertionTimeout 自 v1.25 起提供，把所有断言的默认超时从 5 秒改为指定值（单位毫秒）：

import com.microsoft.playwright.assertions.PlaywrightAssertions;

PlaywrightAssertions.setDefaultAssertionTimeout(10_000);

单条断言超时——通过各断言方法的 Options 参数指定 timeout：

import com.microsoft.playwright.assertions.LocatorAssertions;

import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;

assertThat(page.getByText("Name")).isVisible(
    new LocatorAssertions.IsVisibleOptions().setTimeout(10_000));

Locators：自动等待与重试的核心

Locators 是 Playwright auto-waiting 与 retry-ability 的核心构件。Locator 表示"在任意时刻找到页面上一个或多个元素"的方式，并用于执行 .click()、.fill() 等元素操作。可以用 [method: Page.locator] 基于选择器自定义 Locator：

import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;

Locator getStarted = page.locator("text=Get Started");

assertThat(getStarted).hasAttribute("href", "/docs/intro");
getStarted.click();

Playwright 支持多种内置定位方式，包括 按 role 定位、按文本定位、按 test id 定位 等。更完整的 Locator 种类与选型建议见 Locator 专题指南。例如直接对定位器做可见性断言：

import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;

assertThat(page.locator("text=Installation")).isVisible();

原文档推荐的定位方式优先级隐含在示例中：优先使用语义化定位（getByRole、getByTestId 等），因为它们对页面 DOM 结构变化更健壮；page.locator("text=...") 这类选择器字符串则用于快速定位或无法用 role 表达的场景。Java 客户端的选择器语法（如 text=、css=、xpath=）与 JS 版本一致，可在 locators.md 中查阅完整规则。

测试隔离：每个测试一个 BrowserContext

Playwright 引入了 BrowserContext 的概念：一个内存中的、隔离的浏览器配置文件（等价于"隐身窗口"，Cookie、localStorage、缓存等互不影响）。官方建议在每个测试创建新的 BrowserContext，确保测试之间互不干扰：

Browser browser = playwright.chromium().launch();
BrowserContext context = browser.newContext();
Page page = context.newPage();

这个模式的资源权衡是：Browser 进程重量级、启动慢，适合跨测试共享；BrowserContext 轻量级、创建快，适合作为测试隔离边界。仓库中的 JUnit 集成文档（experimental）给出了这一隔离模型在 JUnit 5 中的落地方式：通过 @UsePlaywright 注解启用 fixture，其中 page 和 browserContext 是每个测试独立的，而 browser 和 playwright 实例则跨测试共享以优化资源：

Fixture	类型	说明
page	Page	本次测试运行专属的隔离页面
browserContext	BrowserContext	本次测试运行专属的隔离上下文，page 归属于该上下文
browser	Browser	浏览器在测试间共享，以优化资源
playwright	Playwright	同一线程上运行的测试间共享 Playwright 实例
request	APIRequestContext	本次测试运行专属的隔离 API 请求上下文

对应的 JUnit 测试示例（来自 junit-java.md）：

@UsePlaywright
public class TestExample {

  @Test
  void basicTest(Page page) {
    page.navigate("https://playwright.dev/");

    assertThat(page).hasTitle(Pattern.compile("Playwright"));
  }
}

需要说明的适用前提：JUnit fixture 功能在文档中标注为 experimental；由于 Playwright 对象不可安全地跨线程共享，官方建议并行执行时每个线程创建独立的 Playwright 实例（junit-java.md 给出了 JUnit 5.3+ 的并行配置参数示例）。

验证要点与源码级依据

结合仓库内文档与工具链可以确认以下实现事实：

• 断言类的 API 契约定义在 docs/src/api/class-playwrightassertions.md、docs/src/api/class-locatorassertions.md、docs/src/api/class-pageassertions.md、docs/src/api/class-apiresponseassertions.md，其中 PlaywrightAssertions 自 v1.17 引入，setDefaultAssertionTimeout 自 v1.25 引入，Java 侧统一以 assertThat 作为入口别名。
• 文档中所有 Java 代码片段在仓库构建时会经过语法与 API 校验：仓库的 doclint 工具 utils/doclint/linting-code-snippets/java/src/main/java/JavaSyntaxChecker.java 负责检查 Java 片段的正确性，而 utils/doclint 目录则保障文档与 API 的一致性。
• Java 代码生成的定位器建议来自 packages/isomorphic/codegen/java.ts，与本文推荐的 getByRole / locator 写法一致。
• 动作方法（click、fill 等）的 auto-wait 行为由协议层统一实现，机制说明见 actionability.md。

What's Next

按原文档的"下一步"指引（已转换为仓库相对路径）：

• 运行单个/多个测试、有头模式；
• 使用 Codegen 生成测试；
• 查看测试的 Trace；
• 延伸阅读：Java 可访问性测试、Java API 测试、测试断言全表。