Playwright 多语言支持详解：JavaScript、Python、Java、.NET 四套 SDK 如何共享同一核心，以及如何选择测试语言

Playwright 官方支持 JavaScript/TypeScript、Python、Java 和 .NET 四种语言，它们共享同一套底层实现：所有浏览器自动化核心能力在每种语言中均可用，差异主要集中在各自的测试框架集成与工具生态上。本篇基于仓库文档 docs/src/languages.md 展开，结合协议规范与各语言入门文档中的实际参数与命令，帮助你在开始编写端到端测试之前，依据团队技术栈、测试框架偏好和项目约束选定合适的语言，并了解每种语言下 Playwright 的推荐用法与系统要求。

同一核心、四种语言：整体设计图景

官方文档给出的核心论断是：Playwright 可用多种语言编写，且共享同一底层实现；所有浏览器自动化的核心功能在所有语言中都受支持，而测试生态集成则各不相同。选择语言时应依据团队经验、对测试生态的熟悉程度和项目约束，并优先选择官方为每种语言推荐的测试运行器以获得最佳体验。

从源码结构可以印证这一设计的两个关键事实：

1. 协议层面明确定义了四种 SDK 语言。协议规范文件 packages/protocol/spec/core.yml 中定义了 SDKLanguage 枚举：

SDKLanguage:
  type: enum
  literals:
  - javascript
  - python
  - java
  - csharp

2. 所有语言共用同一份协议规范目录。packages/protocol/spec/ 下有 19 个 yml 文件（api.yml、browser.yml、page.yml、network.yml、tracing.yml、worker.yml 等），描述了浏览器驱动的完整命令面。各语言客户端（如仓库中的 packages/playwright-client 被明确描述为 "A thin client for Playwright" 的轻量 Node 客户端）通过该协议与核心通信；非 Node 环境（Python、Java、.NET）则由内嵌的 Node 运行时 + 协议服务器（见 packages/playwright-core/src/remote/ 下的 playwrightServer.ts、playwrightWebSocketServer.ts、playwrightPipeServer.ts 等）承载驱动逻辑。

这意味着你写的 Playwright 测试在 JavaScript 和 Python 之间的 API 语义基本一一对应，例如 page.goto()、page.get_by_role() / page.getByRole()、expect(page).to_have_title() 等在不同语言中命名风格不同但行为一致。语言选择因此是一个"生态选择"而非"能力选择"。

JavaScript 和 TypeScript：配套自有测试运行器

Playwright for Node.js 自带一个完整的 test runner，这是四种语言中工具链最厚的一档。它开箱提供的能力包括：

• 优秀的并行化机制：按 worker 进程分发测试，支持 shard 分片；
• 截图断言：expect(locator).toHaveScreenshot() 内建视觉对比；
• HTML reporter：可过滤的仪表盘式报告，支持按浏览器、passed/failed/flaky 等维度筛选；
• 自动 tracing：失败测试自动捕获 trace，可用 trace viewer 做时间旅行式调试。

官方文档入口为 docs/src/intro-js.md，完整安装方式为：

npm init playwright@latest      # 或 yarn create playwright / pnpm create playwright

交互式提示让你确认：TypeScript 或 JavaScript（默认 TypeScript）、测试目录名（默认 tests）、是否添加 CI workflow、是否安装浏览器（默认是）。随后 npx playwright test 默认在 headless 模式下跨 Chromium、Firefox、WebKit 三个浏览器并行执行。

系统要求（以仓库文档为准）：Node.js 最新 22.x、24.x 或 26.x；操作系统支持 Windows 11+ / Windows Server 2019+ / WSL、macOS 14 (Sonoma)+、Debian 12/13、Ubuntu 22.04/24.04/26.04（x86-64 或 arm64），见 docs/src/intro-js.md。

相关深入文档：Running Tests、test 配置、test 报告器、web-first 断言。

Python：推荐的 Pytest 插件

Python 侧官方推荐通过 Playwright Pytest 插件运行端到端测试。它开箱提供：

• 上下文隔离：每个测试独立 BrowserContext，避免状态串扰；
• 多浏览器配置并行运行：通过 CLI 选项切换 chromium/firefox/webkit 及不同 project 配置；
• 同步与异步双 API：playwright.sync_api 与 playwright.async_api 均可用于通用浏览器自动化（库形态），Pytest 插件则覆盖测试场景。

入门流程（摘自 docs/src/intro-python.md）：

pip install pytest-playwright    # 或 poetry add pytest-playwright / uv add pytest-playwright
playwright install               # 下载浏览器二进制

示例测试遵循 test_ 前缀约定：

# test_example.py
import re
from playwright.sync_api import Page, expect

def test_has_title(page: Page):
    page.goto("https://playwright.dev/")
    # 期望标题包含子串
    expect(page).to_have_title(re.compile("Playwright"))

def test_get_started_link(page: Page):
    page.goto("https://playwright.dev/")
    page.get_by_role("link", name="Get started").click()
    expect(page.get_by_role("heading", name="Installation")).to_be_visible()

运行命令为 pytest；默认在 Chromium 上以 headless 模式执行，可通过 CLI 选项调整浏览器、headed 模式等。系统要求：Python 3.8+，操作系统要求同上（见 docs/src/intro-python.md）。

更多文档：test runner、API testing、running tests。

Java：自由选择测试框架

Java 版 Playwright 以 Maven 模块形式分发，文档没有绑定特定测试框架——你可以按项目要求任选 JUnit 或 TestNG。入门依赖只需在 pom.xml 中添加一个：

<dependency>
  <groupId>com.microsoft.playwright</groupId>
  <artifactId>playwright</artifactId>
  <version>%%VERSION%%</version>
</dependency>

最小示例（摘自 docs/src/intro-java.md）：

package org.example;

import com.microsoft.playwright.*;
import java.nio.file.Paths;

public class App {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      Browser browser = playwright.webkit().launch();
      Page page = browser.newPage();
      page.navigate("https://playwright.dev/");
      page.screenshot(new Page.ScreenshotOptions().setPath(Paths.get("example.png")));
    }
  }
}

运行 mvn compile exec:java -D exec.mainClass="org.example.App" 会自动下载 Playwright 包并安装 Chromium、Firefox、WebKit 三个浏览器二进制。浏览器默认 headless 启动，可通过 new BrowserType.LaunchOptions().setHeadless(false) 看到浏览器界面，setSlowMo(50) 可放慢执行。系统要求：Java 8+（见 docs/src/intro-java.md）。

更多文档：JUnit 集成、test runner、API testing、threading 支持。

.NET：四种 base class 任选

Playwright for .NET 随包提供 MSTest、NUnit、xUnit 和 xUnit v3 四套 base classes，用于编写端到端测试。这些基类（如 PageTest）开箱支持：在多种浏览器引擎上运行、测试并行化、调整 launch/context 选项，以及每个测试自动获得独立的 Page / BrowserContext 实例。

典型流程（摘自 docs/src/intro-csharp.md）：

dotnet new nunit -n PlaywrightTests        # 或 mstest / xunit / xunit3
cd PlaywrightTests
dotnet add package Microsoft.Playwright.NUnit   # 对应 Microsoft.Playwright.MSTest / .Xunit / .Xunit.v3
dotnet build
pwsh bin/Debug/net8.0/playwright.ps1 install   # 安装浏览器，按实际 TFM 调整路径

示例测试：

using Microsoft.Playwright;
using Microsoft.Playwright.NUnit;
using NUnit.Framework;

[Parallelizable(ParallelScope.Self)]
[TestFixture]
public class ExampleTest : PageTest
{
    [Test]
    public async Task HasTitle()
    {
        await Page.GotoAsync("https://playwright.dev");
        // 期望标题包含子串
        await Expect(Page).ToHaveTitleAsync(new Regex("Playwright"));
    }
}

运行命令为 dotnet test；默认在 Chromium 上以 headless 模式执行，可通过 BROWSER 环境变量或 launch configuration 调整。系统要求：Playwright 以 .NET Standard 2.0 库形式分发，官方推荐 .NET 8（见 docs/src/intro-csharp.md）。

更多文档：test runner base classes、API testing、CI 集成。

四种语言对比与选型建议

汇总各语言在仓库文档中声明的关键差异，选型时可对照下表：

维度	JavaScript/TypeScript	Python	Java	.NET
推荐测试框架	自带 test runner（@playwright/test）	Pytest 插件	自选 JUnit / TestNG	MSTest / NUnit / xUnit / xUnit v3 base classes
运行时要求	Node.js 22.x / 24.x / 26.x	Python 3.8+	Java 8+	.NET Standard 2.0（推荐 .NET 8）
安装方式	npm init playwright@latest	pip install pytest-playwright + playwright install	Maven 依赖	dotnet add package + playwright.ps1 install
特色能力	并行分片、截图断言、HTML reporter、自动 tracing	上下文隔离、多浏览器配置	与 JVM 测试生态无缝融合	每测试独立 Page/BrowserContext、内置并行

选型建议（与官方文档立场一致）：

• 团队主力技术栈是 Node/前端工程，或希望获得最完整的工具链（tracing、UI mode、codegen、sharding）时，选 JavaScript/TypeScript；
• 团队以 Python 为主、习惯 pytest 的组织，选 Python，其 Pytest 插件提供开箱的上下文隔离；
• 企业级 JVM 项目、已有 JUnit/TestNG 基础设施的，选 Java，保持测试框架连续性；
• .NET 技术栈团队选 .NET 版本，直接继承现有 MSTest/NUnit/xUnit 工程结构。

无论选哪种语言，浏览器支持范围一致：Chromium、WebKit、Firefox，跨 Windows/Linux/macOS，headless 或 headed，并原生支持 Chrome (Android) 与 Mobile Safari 的移动模拟。

仓库内对多语言一致性的工程保障

• 协议规范统一：如前所述，packages/protocol/spec/ 中的 19 个 yml 文件是四种语言客户端的共同契约，SDKLanguage 枚举保证行为差异可以在协议层被区分（如 core.yml）。
• 文档跨语言校验：utils/doclint/ 目录中包含 JS、C#（.cs/.csproj）、Java、Python 等多种语言的校验脚本，用于校验各语言 API 文档与实现的一致性，从工具层面维护四套文档的同步。
• 分语言文档齐全：docs/src/ 下每种语言都有独立的写作指南（如 writing-tests-js.md、writing-tests-java.md）、运行指南（running-tests-csharp.md 等四份）、API testing 指南与发布说明（如 release-notes-java.md），可分别深入。
• 测试基础设施本身用 TypeScript 编写：本仓库的 tests/ 目录（library、page、playwright-test 等子目录）即是 Playwright 自身跨三浏览器、跨配置的测试套件，其配置结构（tests/config/baseTest.ts、tests/config/browserTest.ts）也反映了"同一用例矩阵、多浏览器 project"的组织方式。

小结

Playwright 的多语言支持并非四套独立实现，而是"一个核心驱动 + 一套协议规范 + 四个语言客户端"的架构：浏览器自动化能力（导航、定位器、web-first 断言、tracing、下载、视频、模拟等）在所有语言中完整对齐，真正的选择空间在于测试生态——JS 有功能最全的自有 runner，Python 有 Pytest 插件的上下文隔离，Java 保持测试框架自由，.NET 提供四套框架 base class。选定语言后，遵循该语言的入门文档完成安装与浏览器下载，即可在 Chromium、WebKit、Firefox 三个引擎上编写跨平台端到端测试。