Skip to main content

安装

介绍​

¥Introduction

Playwright Test 是一个适用于现代 Web 应用的端到端测试框架。它打包了测试运行器、断言、隔离、并行化和丰富的工具。Playwright 支持 Windows、Linux 和 macOS 上的 Chromium、WebKit 和 Firefox，支持本地或持续集成 (CI)、无头或有头模式，并为 Chrome (Android) 和 Mobile Safari 提供原生移动模拟。

¥Playwright Test is an end-to-end test framework for modern web apps. It bundles test runner, assertions, isolation, parallelization and rich tooling. Playwright supports Chromium, WebKit and Firefox on Windows, Linux and macOS, locally or in CI, headless or headed, with native mobile emulation for Chrome (Android) and Mobile Safari.

你将学习

¥You will learn

安装 Playwright​

¥Installing Playwright

首先使用以下方法之一安装 Playwright。

¥Get started by installing Playwright using one of the following methods.

使用 npm、yarn 或 pnpm​

¥Using npm, yarn or pnpm

以下命令可初始化新项目或将 Playwright 添加到现有项目。

¥The command below either initializes a new project or adds Playwright to an existing one.

npm init playwright@latest

出现提示时，请选择/确认：

¥When prompted, choose / confirm:

  • TypeScript 或 JavaScript（默认：TypeScript）

    ¥TypeScript or JavaScript (default: TypeScript)

  • 测试文件夹名称（默认值：tests，如果 tests 已存在，则为 e2e）

    ¥Tests folder name (default: tests, or e2e if tests already exists)

  • 添加 GitHub Actions 工作流程（推荐用于 CI）

    ¥Add a GitHub Actions workflow (recommended for CI)

  • 安装 Playwright 浏览器（默认：是）

    ¥Install Playwright browsers (default: yes)

你可以稍后重新运行该命令；它不会覆盖现有测试。

¥You can re-run the command later; it does not overwrite existing tests.

使用 VS Code 扩展程序​

¥Using the VS Code Extension

你还可以使用 VS Code 扩展 创建和运行测试。

¥You can also create and run tests with the VS Code Extension.

安装了什么​

¥What's Installed

Playwright 会下载所需的浏览器二进制文件并创建以下脚手架。

¥Playwright downloads required browser binaries and creates the scaffold below.

playwright.config.ts         # Test configuration
package.json
package-lock.json            # Or yarn.lock / pnpm-lock.yaml
tests/
  example.spec.ts            # Minimal example test
tests-examples/
  demo-todo-app.spec.ts      # Richer example tests

playwright.config 集中配置：目标浏览器、超时、重试、项目、报告器等。在现有项目中，依赖会添加到你当前的 package.json 中。

¥The playwright.config centralizes configuration: target browsers, timeouts, retries, projects, reporters and more. In existing projects dependencies are added to your current package.json.

tests/ 包含一个最小的入门测试。tests-examples/ 提供了更丰富的示例（例如待办事项应用）来探索模式。

¥tests/ contains a minimal starter test. tests-examples/ provides richer samples (e.g. a todo app) to explore patterns.

运行示例测试​

¥Running the Example Test

默认情况下，测试在 Chromium、Firefox 和 WebKit 上以无头模式并行运行（可在 playwright.config 中配置）。输出和汇总结果将显示在终端中。

¥By default tests run headless in parallel across Chromium, Firefox and WebKit (configurable in playwright.config). Output and aggregated results display in the terminal.

npx playwright test

提示：

¥Tips:

  • 查看浏览器窗口：添加 --headed。

    ¥See the browser window: add --headed.

  • 运行单个项目/浏览器：--project=chromium。

    ¥Run a single project/browser: --project=chromium.

  • 运行单个文件：npx playwright test tests/example.spec.ts。

    ¥Run one file: npx playwright test tests/example.spec.ts.

  • 打开测试界面：--ui。

    ¥Open testing UI: --ui.

有关筛选、标题模式、分片和重试的详细信息，请参阅 运行测试。

¥See Running Tests for details on filtering, headed mode, sharding and retries.

HTML 测试报告​

¥HTML Test Reports

测试运行后，HTML 报告器 会提供一个可通过浏览器筛选的仪表板，显示通过、失败、跳过、不稳定等信息。点击一个测试即可检查错误、附件和步骤。它仅在发生故障时自动打开；使用以下命令手动打开。

¥After a test run, the HTML Reporter provides a dashboard filterable by the browser, passed, failed, skipped, flaky and more. Click a test to inspect errors, attachments and steps. It auto-opens only when failures occur; open manually with the command below.

npx playwright show-report

在 UI 模式下运行示例测试​

¥Running the Example Test in UI Mode

使用 用户界面模式 运行测试，即可使用监视模式、实时步骤视图、时间旅行调试等功能。

¥Run tests with UI Mode for watch mode, live step view, time travel debugging and more.

npx playwright test --ui

有关监视过滤器、步骤详细信息和跟踪集成的信息，请参阅 UI 模式详细指南。

¥See the detailed guide on UI Mode for watch filters, step details and trace integration.

更新 Playwright​

¥Updating Playwright

更新 Playwright 并下载新的浏览器二进制文件及其依赖：

¥Update Playwright and download new browser binaries and their dependencies:

npm install -D @playwright/test@latest
npx playwright install --with-deps

检查你安装的版本：

¥Check your installed version:

npx playwright --version

系统要求​

¥System requirements

  • Node.js：最新的 20.x、22.x 或 24.x。

    ¥Node.js: latest 20.x, 22.x or 24.x.

  • Windows 10+、Windows Server 2016+ 或适用于 Linux 的 Windows 子系统 (WSL)。

    ¥Windows 10+, Windows Server 2016+ or Windows Subsystem for Linux (WSL).

  • macOS 14 (Ventura) 或更高版本。

    ¥macOS 14 (Ventura) or later.

  • Debian 12 / 13、Ubuntu 22.04 / 24.04（x86-64 或 arm64）。

    ¥Debian 12 / 13, Ubuntu 22.04 / 24.04 (x86-64 or arm64).

下一步是什么​

¥What's next