Playwright 各语言的运行器对照：JS 用自带，其它接谁

有个场景大概每个非 JS 团队都遇到过：看完 Playwright 的入门文档，照着写了几个用例，觉得挺顺；等到要把几百个用例塞进 CI、要开并行、要把登录态抽出来复用的时候，才发现文档里那些 fullyParallel、test.extend、--shard 全都带着 -js 后缀，自己这门语言根本没有对应的页面。

这不是文档漏写。Playwright 仓库 docs/src/languages.md 里就直说了：所有语言共享同一套底层实现，浏览器自动化的核心能力四种语言都支持，但测试生态的集成方式是不同的，建议按各语言推荐的运行器来选。换句话说，「浏览器怎么操作」是同一份东西，「测试怎么组织与执行」是四份东西。

下面这条对照只走仓库里写明的机制，四条路各自把边界划在哪、什么时候会咬到你。

第一层分岔：运行器归谁管

先把归属关系摆清楚，后面所有差异都是从这里长出来的。

语言	测试怎么跑	文档出处
JavaScript / TypeScript	Playwright 自带的 Test Runner（@playwright/test）	docs/src/languages.md、docs/src/library-js.md
Python	Playwright 提供的 pytest 插件，挂在 pytest 上跑	docs/src/test-runners-python.md
Java	你自己选 JUnit 或 TestNG，Playwright 只提供对象	docs/src/test-runners-java.md
.NET	Playwright 提供 MSTest / NUnit / xUnit / xUnit v3 的基类	docs/src/test-runners-csharp.md

docs/src/library-js.md 把 JS 这条的两分法说得最直白：playwright（Library）只提供启动和操作浏览器的统一 API，@playwright/test（Test）在此之上再加一整套托管的端到端运行器；文档建议端到端测试用后者，而不是直接用前者。

其它三门语言里，.NET 那边是按运行器逐个发包的——docs/src/test-runners-csharp.md 逐字列了 Microsoft.Playwright.NUnit、Microsoft.Playwright.MSTest、Microsoft.Playwright.Xunit、Microsoft.Playwright.Xunit.v3，四个包对应四个运行器，但它们提供的是基类，不是运行器本身，跑测试还是 dotnet test。Python 那边是一个 pytest 插件（异步 fixture 另有 pytest-playwright-asyncio，见 docs/src/test-runners-python.md 的 Async Fixtures 一节）。Java 那边最朴素：docs/src/test-runners-java.md 的开场就是「用几行代码把 Playwright 挂到你喜欢的 Java 测试运行器上」，示例里 Playwright.create()、browser.newContext() 全是你自己在 @BeforeAll / @BeforeEach 里写的，文档没有给额外的测试集成依赖。

这一层的实际影响是：JS 之外，运行器的脾气不归 Playwright 管。报告长什么样、失败怎么重跑、用例怎么筛，都是 pytest / JUnit / TestNG / MSTest 各自的事。

第二层：并行能力从哪来

这是四条路差得最远的一处，也是最容易踩坑的一处。

JS：并行是 Playwright Test 自己实现的。docs/src/test-parallel-js.md 写明它跑多个 worker 进程，默认粒度是测试文件并行、单个文件内顺序执行；worker 之间不能通信，且一旦有测试失败，worker 会被关掉以保证后续测试环境干净。粒度可以调：

npx playwright test --workers 4

单文件内并行用 test.describe.configure({ mode: 'parallel' })，整个项目全并行用配置里的 fullyParallel。反向也有 mode: 'serial'，但文档自己标了不推荐，理由是让测试相互隔离通常更好。

Python：插件本身不提供并行。docs/src/test-runners-python.md 给的方案是装 pytest-xdist：

# install dependency
pip install pytest-xdist
# use the --numprocesses flag
pytest --numprocesses auto

同一段还带了一句边界：numprocesses 可以设到 2 到机器核数之间，设得太高可能出现预期外的行为。原文就是这么留白的，没有给判定方法。

Java：并行是 JUnit 的能力，不是 Playwright 的。文档写明 JUnit 默认单线程顺序跑，从 JUnit 5.3 起可以改成并行；而因为「多线程共用同一批 Playwright 对象在没有额外同步的情况下并不安全」，文档建议每个线程建一个 Playwright 实例、只在该线程上用。配套写法是给测试类加 @TestInstance(TestInstance.Lifecycle.PER_CLASS)，把 Playwright 和 Browser 放到实例字段上，然后按类并行：

junit.jupiter.execution.parallel.enabled = true
junit.jupiter.execution.parallel.mode.default = same_thread
junit.jupiter.execution.parallel.mode.classes.default = concurrent
junit.jupiter.execution.parallel.config.strategy=dynamic
junit.jupiter.execution.parallel.config.dynamic.factor=0.5

这一段的背景在另一个文件里：docs/src/threading-java.md 开门见山写着 Playwright Java 不是线程安全的，由它创建的 BrowserContext、Browser、Page 等对象都应当在创建 Playwright 对象的那个线程上调用，但「每个线程各自创建一个 Playwright 实例」是可以的。两处放在一起看就明白了：Java 侧的并行度上限不是由 Playwright 给的，而是由你愿意开几个独立实例决定的。

.NET：并行归各运行器管，而且有明确写死的不支持项，这是四条路里唯一把限制写进文档的：

• NUnit 默认文件级并行、文件内顺序，只支持 ParallelScope.Self；worker 数用 dotnet test -- NUnit.NumberOfTestWorkers=5 调。
• MSTest 默认类级并行（ExecutionScope.ClassLevel），方法级并行（ExecutionScope.MethodLevel）不支持；参数是 MSTest.Parallelize.Workers。
• xUnit 与 xUnit v3 默认类级并行，参数是 xUnit.MaxParallelThreads。文档对 xUnit 那一栏加了备注，建议用 xUnit 2.8+，它默认走 conservative 并行算法；xUnit v3 那一栏写的是默认就用该算法。

上面这些参数名与「不支持」的表述都逐字来自 docs/src/test-runners-csharp.md，该项目持续更新，以仓库最新内容为准。

顺带一个容易被忽略的对照：docs/src/library-python.md 的已知问题一节也写了 Playwright 的 API 不是线程安全的、多线程环境下应当每线程一个实例。也就是说 Python 与 Java 在这条约束上是一致的，只不过 Python 侧给出的并行方案是多进程（pytest-xdist），绕开了这个约束。

第三层：fixture 的对应物是什么

「把登录态、测试数据、外部服务抽出来复用」这件事，四条路的做法完全不是一回事。

JS 是原生 fixture 模型。内置的 page、context、browser、browserName、request 直接以解构参数的形式注入，自定义靠 base.extend。这里有一个别的语言都没有的东西：worker 级 fixture。docs/src/test-fixtures-js.md 写明要用元组式写法传 { scope: 'worker' }，这样这个 fixture 在每个 worker 进程里只建一次；文档同时说明 worker 级 fixture 有一个独立的超时，等于默认的测试超时。文档里那个 account 示例就是用 workerInfo.workerIndex 生成每个 worker 唯一的账号——注意那只是仓库里的示例代码。

Python 的对应物就是 pytest 的 fixture，插件把它们分成了两档，这是文档里写死的作用域划分：

• function scope：context、page、new_context
• session scope：playwright、browser_type、browser、browser_name、browser_channel、is_chromium / is_webkit / is_firefox

要改启动参数和上下文参数，不是写配置文件，而是覆盖对应的 fixture：browser_type_launch_args、browser_context_args、connect_options，三者都要求返回一个 Dict。文档里覆盖视口的写法是这样的：

import pytest

@pytest.fixture(scope="session")
def browser_context_args(browser_context_args):
    return {
        **browser_context_args,
        "viewport": {
            "width": 1920,
            "height": 1080,
        }
    }

单个用例要改则用 @pytest.mark.browser_context_args(...) 这个 marker。另外有一条边界值得记住：CLI 参数（--headed、--browser、--tracing 这些）只作用于默认的 browser / context / page fixture，你若自己调 Browser.newContext 建出来的上下文，CLI 参数不会生效。

Java 的默认路径里根本没有 fixture——@BeforeAll 建 Playwright 和 Browser、@BeforeEach 建 context 和 page、@AfterEach 关 context，全是手写的生命周期。想要 fixture 就得走另一个文件：docs/src/junit-java.md，标题逐字写着 JUnit (experimental)。给测试类加 @UsePlaywright 之后，Page、BrowserContext、Browser、Playwright、APIRequestContext 就能作为方法参数注入；改选项要实现 OptionsFactory：

@UsePlaywright(MyTest.CustomOptions.class)
public class MyTest {

  public static class CustomOptions implements OptionsFactory {
    @Override
    public Options getOptions() {
      return new Options()
          .setHeadless(false)
          .setContextOption(new Browser.NewContextOptions()
              .setBaseURL("https://github.com"))
          .setApiRequestOptions(new APIRequest.NewContextOptions()
              .setBaseURL("https://playwright.dev"));
    }
  }
}

这段是 docs/src/junit-java.md 里的示例代码，其中的 URL 是仓库示例值，不是推荐配置。整个 JUnit 集成被官方标为 experimental，要不要压在它上面自己掂量；接口语义以仓库最新代码为准。

.NET 用的是继承，不是注入。docs/src/test-runners-csharp.md 列了四个基类：PageTest（每个测试拿到独立 BrowserContext 里的新 Page）、ContextTest（每个测试拿到干净的 BrowserContext，页可以自己开多个）、BrowserTest（拿到 browser，自己建 context 也自己清理）、PlaywrightTest（只给 Playwright 对象，浏览器你自己起停）。改上下文选项是覆写方法：public override BrowserNewContextOptions ContextOptions()。启动选项则走 .runsettings 文件或者 dotnet test -- 后面的 run settings 参数。

四条路的落差在这一层最明显：JS 的复用单位是 fixture 且能落到 worker 级，Python 的复用单位是 pytest fixture 且分 function / session 两档，.NET 的复用单位是类继承层次，Java 默认没有复用单位、要靠实验性注解才有。

有些维度我们没有依据，不比

• retries、sharding、UI 模式：docs/src/ 里这三块只有 test-retries-js.md、test-sharding-js.md、test-ui-mode-js.md 这几个 -js 后缀的文件，另外三种语言我们没有找到对应的运行器级说明。它们各自的运行器可能有自己的重跑机制，但那不是 Playwright 仓库的内容，本文不猜。
• 报告器：test-reporters-js.md 与 docs/src/test-reporter-api/ 同样只覆盖 JS 一侧。
• 谁跑得快：本文不涉及。我们没有跑过任何一条路。

一处能比的：产物的开关位置不同。Python 侧 trace、video、screenshot 是 pytest 的命令行参数：docs/src/test-runners-python.md 写明 --tracing 与 --video 的取值是 on / off / retain-on-failure，而 --screenshot 的第三个取值逐字写的是 only-on-failure，两处措辞不一样，别照着记混；Java 与 .NET 侧则是在代码里调 tracing 的 API 起停（docs/src/trace-viewer.md 的 Java 段是 context.tracing().start(...)，C# 段是 await Context.Tracing.StartAsync(...)）。也就是说非 Python 的两条路里，「失败才留 trace」这件事得你自己在 teardown 里判断。

Windows 侧几个具体的坑

本站读者以 Windows 居多，这几处得单独说。

Java 那条路，仓库给的 Gradle 命令是 ./gradlew run 和 ./gradlew playwright --args="help" 这种 POSIX 写法；Windows 下 Gradle wrapper 的调用方式与之不同，仓库文档里没有给 Windows 版本的写法，按你本地 wrapper 的实际情况来。

Python 那条路，docs/src/library-python.md 的已知问题里写明：Playwright 把 driver 跑在子进程里，所以在 Windows 上需要 asyncio 的 ProactorEventLoop，SelectorEventLoop 不支持异步子进程。同一节还写了 Windows 上 Python 3.7 时 Playwright 会把默认事件循环设成 ProactorEventLoop，因为 3.8+ 本来就是默认值。你要是在 Windows 上自己接管了事件循环，这一条会咬到你。

.NET 那条路的 .runsettings 在 Visual Studio 里跑测试时可用，文档里给的是这个用法；dotnet test --settings:.runsettings 则是命令行侧的写法。

一条决策路径

倒着推，比对着参数表挑要快：

1. 能选语言吗？ 能选、且是新项目 —— docs/src/languages.md 建议按各语言的推荐运行器走；JS 侧的运行器级能力（worker fixture、retries、sharding、UI 模式、报告器 API）在仓库文档里是唯一齐的，这一点是事实，不是评价。
2. 不能选语言，是 Python？ 你拿到的是一套 pytest fixture。先确认两件事：并行要另装 pytest-xdist；CLI 参数只管默认的三个 fixture，自己建的上下文管不着。
3. 不能选语言，是 .NET？ 先去 docs/src/test-runners-csharp.md 确认你那个运行器的并行限制——NUnit 只支持 ParallelScope.Self、MSTest 不支持方法级并行，这两条是写死的。然后按「测试要几个页 / 几个上下文」从四个基类里挑。
4. 不能选语言，是 Java？ 决策点只有一个：要不要用标着 experimental 的 @UsePlaywright。不用，就得手写 @BeforeAll / @BeforeEach 那一套生命周期；用，就得接受它的实验状态。并行方案两边都一样：JUnit 5.3+ 的并行配置，加上每线程一个 Playwright 实例。

最后提醒一句本文范围内的安全边界：这四条路在执行时都会启动真实浏览器、加载并执行页面脚本、按你的配置读写存储状态与产物目录，隔离的是浏览器上下文，不是你的机器。CI 上跑第三方页面时该怎么隔离，请按自己环境评估。

---

本文依据 github.com/microsoft/playwright 仓库于 2026-08-18 的公开内容整理， 事实来自仓库内的文档与源码。我们没有对文中涉及的功能做过实测， 因此不涉及运行速度、稳定性与实际表现的任何描述。 该项目迭代频繁，文中涉及的 API 签名、配置项与默认值随版本变动，请以仓库最新内容为准。 本文不涉及浏览器版本矩阵与版本清单，相关信息请以官方发布说明为准。

本文对照的是同一项目内的四种语言绑定，依据均为上述仓库内容，不对它们做优劣排名， 选型结论只在仓库文档写明的能力边界内成立。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。