用途
该技能用于生成生产级、企业级的 Playwright Java 测试代码，强制采用 Page Object Model（POM）、严格的定位器策略、线程安全的并行执行以及完整的 Allure 报告集成。目标环境为 Java 17+ 与 Playwright 1.44+。
主要能力
- 从零搭建 Playwright Java 项目脚手架。
- 编写 Page Object 类与 JUnit 5 测试类。
- 支持跨浏览器测试、并行执行与 Allure 报告。
- 修复不稳定测试，用合适的等待替换 Thread.sleep()。
- 在 CI/CD 流水线（GitHub Actions、Jenkins、Docker）中配置 Playwright。
- 在单个测试中结合 API 调用与 UI 断言（混合测试）。
- 涉及 “POM pattern”、“BrowserContext”、“Playwright fixtures” 或 “traces” 等主题。
使用方式
-
先决定方案：新项目从零搭建参考 references/config.md；单一功能测试采用 POM 页面类加 JUnit5 测试类；API 与 UI 混合使用 APIRequestContext 配合 Page；跨浏览器使用 @MethodSource 按浏览器名参数化；修复不稳定测试用 waitFor / waitForResponse 替换 sleep；CI 集成在流水线中执行 playwright install --with-deps；并行执行使用 junit-platform.properties 加 ThreadLocal；丰富报告使用 Allure 加 Playwright trace 与视频录制。
-
搭建项目结构：采用 src/test/java/com/company/tests/ 下分 base、pages、tests、utils、config 目录，resources 下放置 test.properties、junit-platform.properties、testdata/users.json，以及 pom.xml。
-
设置线程安全的 BaseTest：使用 ThreadLocal 保存 Playwright、Browser、BrowserContext、Page，在 @BeforeEach 中创建并启动追踪，在 @AfterEach 中停止追踪并关闭资源，通过系统属性 browser 解析浏览器类型。
-
构建 Page Object 类：所有定位器声明为字段，不在动作方法中内联；导航方法返回下一个 Page Object 以支持链式调用。
-
编写带 Allure 注解的测试：使用 @ExtendWith(AllureJunit5.class)、@Severity、@DisplayName，结合 SoftAssertions 与参数化测试。
示例涵盖 API 与 UI 混合测试、网络模拟、并行跨浏览器测试、并行执行配置以及 GitHub Actions CI 流水线。
最佳实践
使用 ThreadLocal<Page> 保证并行安全；在 Page Object 顶部声明所有 Locator 字段；导航方法返回下一个 Page Object；使用 assertThat(locator) 自动重试；优先使用 getByRole、getByLabel、getByTestId；在 @BeforeEach 启动追踪并在 @AfterEach 以文件路径停止；单页多字段校验使用 SoftAssertions；使用 storageState 保存认证状态以跳过登录。避免使用 Thread.sleep()、硬编码基础 URL、在 Page Object 内创建 Playwright 实例，以及对动态元素使用 XPath。
常见问题
并行模式下随机失败需确保每个测试通过 ThreadLocal 创建独立的 Playwright 到 Page 链；断言超时可增大超时或设置默认超时；仍不稳定应改用 waitForResponse 或自动轮询断言；trace 为空需确保追踪在测试动作前启动并在 @AfterEach 停止；Allure 报告空白需在 maven-surefire-plugin 的 argLine 中添加 AspectJ agent；storageState 过期需重新生成认证状态文件。
适用场景
适用于 Java 技术栈的端到端测试开发、测试框架搭建、CI/CD 测试集成以及需要跨浏览器与并行执行的测试项目。
限制
仅当任务明确匹配上述范围时使用。输出不能替代针对具体环境的验证、测试或专家评审。若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。此外，本目录副本未包含以下支持路径：references/config.md、references/page-objects.md、references/assertions.md、references/fixtures.md、templates/BaseTest.java、templates/BasePage.java、src/test/resources/junit-platform.properties。这些是外部前置条件而非捆绑文件，使用依赖这些路径的步骤前需先获取原始支持材料或已有安装，并相对于该安装解析路径、检查内容、验证许可与执行前提；在所需文件存在前不要运行命令或声称已执行相关流程，也不要伪造缺失脚本或用同名无关文件替代。