# Playwright

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com.cn/help/idea/llms.txt).

> **Note:**
> 在 IntelliJ IDEA 中对 Playwright 的支持由 [Test Automation](https://plugins.jetbrains.com/plugin/20175-test-automation) 插件提供，本节中描述的大多数功能均依赖于该插件。 不过，基本功能如运行和调试 Playwright 测试在没有插件的情况下也能正常工作。

![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/javascript-impl.icons.playwright.svg) [Playwright](https://playwright.dev/) 是一个开源的测试自动化框架。 它提供了一个高级 API，用于自动化 Chrome、 Firefox 和 Safari 等网络浏览器。

## 创建一个新的 Playwright 项目

Playwright for JS/TS:

Procedure:

1. 在主菜单中，前往  `文件 | 新建 | 项目` 。

或者，如果在   欢迎   屏幕上，请点击   新建项目  。

2. 在左侧列表中，选择   Playwright  。

![创建一个新的 Playwright 项目](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ij_playwright_new_project.png)

3. 为新项目命名，并在必要时更改其位置。

4. 请指定   Node.js 运行时  。

5. 指定安装 Playwright 的命令。

6. 点击   创建  。

适用于 JVM 的 Playwright:

Procedure:

1. 在主菜单中，前往  `文件 | 新建 | 项目` 。

或者，如果在   欢迎   屏幕上，请点击   新建项目  。

2. 在左侧列表中，选择   适用于 JVM 的 Playwright  。

![创建新的 Playwright for JVM 项目](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ij_create_playwright_jvm_project.png)

3. 为新项目命名，并在必要时更改其位置。

4. （可选）启用   创建 Git 仓库   选项，将新项目置于版本控制之下。 如果现在不想执行此操作，稍后可随时进行。

5. 请选择您要使用的   语言  。

6. 请选择您想在项目中使用的构建系统： [Maven](maven-support.html) 或 [Gradle](gradle.html)。

7. 请选择您要用于测试用例管理的测试框架： [JUnit](junit.html) 或 [TestNG](testng.html)。

8. （可选）修改   组   和   工件   参数。

9. 从    JDK    列表中选择您想在项目中使用的 [JDK](sdk.html#jdk)。

* 如果已在计算机上安装 JDK，但未在 IDE 中定义，请选择 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.nodes.jdk.png) 从磁盘添加 JDK… 并指定 JDK 主目录的路径。​

* 如果您的计算机上没有必要的 JDK，请选择 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.download.svg) 下载 JDK 。

10. （可选）启用   添加示例代码   参数。

11. 点击   下一步  。

12. 点击   创建  。

适用于 Python 的 Playwright:

> **Note:**
> 只有在 [Python 插件](https://plugins.jetbrains.com/plugin/631-python) [已安装并启用](managing-plugins.html)的情况下，才能创建   适用于 Python 的 Playwright   项目。

Procedure:

1. 在主菜单中，前往  `文件 | 新建 | 项目` 。

或者，如果在   欢迎   屏幕上，请点击   新建项目  。

2. 在左侧列表中，选择   适用于 Python 的 Playwright  。

![为 Python 创建一个新的 Playwright 项目](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ij_playwright_python_virtualenv.png)

3. 为新项目命名，并在必要时更改其位置。

4. （可选）启用   创建 Git 仓库   选项，将新项目置于版本控制之下。 如果现在不想执行此操作，稍后可随时进行。

5. 选择是创建新的还是使用现有的   环境  ，并配置相应设置。

新建:

Virtualenv:

![配置新的 Virtualenv 环境](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ij_playwright_python_virtualenv.png)

* 从列表中选择基础解释器，或者点击 ![选择基础解释器](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.inline.browse.svg) 并在文件系统中找到 Python 可执行文件。

* 在 位置 字段中指定新虚拟环境的位置，或者点击 ![虚拟环境位置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.inline.browse.svg) 并在文件系统中浏览该位置。 新虚拟环境的目录应为空。

* 如果希望将计算机上全局 Python 中安装的所有软件包添加到将要创建的虚拟环境中，请选择 从基础解释器继承软件包 复选框。 此复选框对应 `--system-site-packages` 选项的 [virtualenv](http://www.virtualenv.org/en/latest/index.html) 工具。

有关详细信息，请参阅 [PyCharm 文档](https://www.jetbrains.com.cn/help/pycharm/creating-virtual-environment.html)。

Conda:

![配置新的 Conda 环境](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ij_playwright_python_conda.png)

* 在 位置 字段中指定新 Conda 环境的位置，或者点击 ![浏览…](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.inline.browse.svg) 并在文件系统中浏览该位置。 新 conda 环境的目录应为空。

* 从列表中选择 Python 版本。

* IntelliJ IDEA 将检测到 conda 安装。 如果 IntelliJ IDEA 未自动检测到该安装，请指定 conda 可执行文件的位置，或点击 ![Conda 可执行文件位置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.inline.browse.svg) 进行浏览。

有关详细信息，请参阅 [PyCharm 文档](https://www.jetbrains.com.cn/help/pycharm/conda-support-creating-conda-virtual-environment.html)。

Pipenv:

![配置一个新的 Pipenv 环境](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ij_playwright_python_pipenv.png)

* 从列表中选择基础解释器，或者点击 ![浏览…](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.inline.browse.svg) 并在文件系统中找到 Python 可执行文件。

* 如果您已将基础二进制目录添加到您的 `路径` 环境变量中，则无需设置任何其他选项：pipenv 可执行文件的路径将自动检测。 如果 IntelliJ IDEA 未检测到 pipenv 可执行文件，请点击 通过 pip 安装 pipenv 以允许 IntelliJ IDEA 自动为您安装。 或者，按照 [pipenv 安装过程](null)来查找可执行文件路径，然后在对话框中指定该路径。

有关详细信息，请参阅 [PyCharm 文档](https://www.jetbrains.com.cn/help/pycharm/pipenv.html)。

Poetry:

![配置一个新的 Poetry 环境](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ij_playwright_python_poetry.png)

* 从列表中选择基础解释器，或者点击 ![浏览…](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.inline.browse.svg) 并在文件系统中找到 Python 可执行文件。

有关详细信息，请参阅 [PyCharm 文档](https://www.jetbrains.com.cn/help/pycharm/poetry.html)。

现有:

![配置现有环境](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ij_playwright_python_existing_env.png)

* 从列表中选择解释器。 如果没有可用的解释器，请点击 添加解释器 ，并根据需要配置一个。

6. 点击   创建  。

将根据所选选项创建一个新项目。

## 初始化 Playwright 项目

> **Note:**
> 初始化仅适用于 [Playwright for JS/TS](#playwright-for-js-ts) 项目。

一旦项目创建完成，您需要初始化它。 在此过程中，您将选择所需的语言，安装 Playwright 浏览器，并指定其他设置。

![项目初始化](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_playwright_project_initialization.png)

开始项目初始化：

Procedure:

1. 在   运行工具窗口   `Alt+4` (Windows), `⌘ 4` (macOS), `⌘ 4` (IntelliJ IDEA Classic (macOS)), `⌘ 4` (macOS System Shortcuts), `Alt+4` (XWin), `Alt+4` (GNOME), `Alt+4` (KDE), `Alt+4` (Emacs), `Alt+4` (Sublime Text), `⌘ 4` (Sublime Text (macOS)), `Alt+4` (Visual Studio), `⌘ 4` (Visual Studio (macOS)), `Alt+4` (NetBeans), `Alt+4` (Eclipse), `⌘ 4` (Eclipse (macOS))中，按键盘上的上/下箭头按钮选择您要在项目中使用的语言。

2. 请输入您要放置端到端测试的文件夹名称。

3. 请指定是否要添加 [GitHub Actions 工作流](https://docs.github.com/en/actions/using-workflows)。

4. 指定是否要安装 Playwright 浏览器。

当您指定所有参数时，初始化开始。 系统将通知您，一旦流程完成：

![项目初始化成功](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_playwright_init_success.png)

## 基于角色的定位器支持

在 Playwright 中，您可以通过其 [角色](https://playwright.dev/docs/locators#locate-by-role)定位元素。 这有助于准确定位页面上的特定元素，无论是按钮、复选框、标题、链接或其他元素。

IntelliJ IDEA 可以生成这些定位器并将其添加到您的代码中，以便您在测试中使用它们。

![基于角色的定位器](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_locator_types.png)

## 添加元素到代码

Procedure:

1. 打开您要添加元素的文件。

2. 在右侧边栏点击 ![Web Inspector 按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua-plugin.icons.webInspector%4020x20.svg) 以打开   Web 检查器   工具栏窗口。

3. 请在地址栏中指定页面的 URL。

![地址栏控件](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_address_bar_controls.png)

4. 点击 ![页面中选择元素按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua-plugin.icons.browser.expui.selectWeb.svg)，然后在 Web Inspector 中选择要添加的元素。

![选择页面中的元素](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_select_element_in_page.png)

5. 选择元素后，点击 ![将元素添加到代码中。呵 wait alt no period? Need no period for UI label. ](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.add.svg) 将该元素添加到代码。

![“将元素添加到代码”按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_add_element_to_code.png)

要添加特定类型的选择器（  ID 、  名称 、  带类的标记  等），请点击 ![按以下方式将元素添加到代码](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.chevronDownLarge.svg) 并选择所需选项。

![按以下方式将元素添加到代码](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_locator_types.png)

> **Tip:**
> 在此，您还可以根据其角色将元素添加到代码中。

如果想专门在 CSS 和 XPath 定位器之间切换，请点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua-plugin.icons.locators.expui.css.svg) 并选择所需的定位器类型。

![选择定位器类型](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_locator_type_switcher.png)

因此，将生成一段代码并将其添加到代码编辑器中。

## 运行测试

Procedure:

* 要运行测试，请点击测试类或测试方法旁的 ![运行按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.gutter.run.svg) 装订区域图标，然后在列表中选择   运行   选项。

![运行测试](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ps_run_tests_playwright.png)

或者，将文本光标置于测试类处以运行该类中的所有测试，或置于测试方法处，然后按 `Ctrl+Shift+F10` (Windows), `⌃ ⇧ R` (macOS), `⌃ ⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌃ ⇧ R` (macOS System Shortcuts), `Ctrl+Shift+F10` (XWin), `Ctrl+Shift+F10` (GNOME), `Ctrl+Shift+F10` (KDE), `Ctrl+Shift+F10` (Emacs), `Ctrl+Shift+F10` (Sublime Text), `Ctrl+Shift+F10` (Sublime Text (macOS)), `Ctrl+Alt+F5` (Visual Studio), `⌃ ⌥ F5` (Visual Studio (macOS)), `Alt+Shift+F6` (NetBeans), `Ctrl+Shift+F10` (Eclipse), `⌃ ⇧ R` (Eclipse (macOS))。

可以使用运行/调试配置，以更可自定义的方式运行测试。 有关更多信息，请参见 [运行测试](performing-tests.html)。

### 在可见模式下运行测试

在有界模式下运行测试使您能够直观地展示 Playwright 如何与网站进行交互。

要在有头模式下运行测试：

Playwright for JS/TS:

Procedure:

1. 点击运行/调试配置切换器中的当前配置，然后点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.actions.more.svg) 并选择   编辑   选项。

![编辑运行/调试配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_edit_configurations.png)

2. 在   Playwright 选项  字段中，指定  `--headed` 命令：

![配置运行/调试配置以在有头模式下运行测试](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_pw_for_js_ts_headed_mode.png)

3. 应用更改并运行您的测试。

适用于 JVM 的 Playwright:

Procedure:

1. 打开包含您想要在 headed 模式下运行的测试的文件。

2. 请在您的代码中添加以下选项：

```
launch(new BrowserType.LaunchOptions().setHeadless(false))

```

![将代码修改为在有界面模式下运行测试](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_pw_for_jvm_run_tests_in_headed_mode.png)

3. 运行您的测试。

适用于 Python 的 Playwright:

Procedure:

1. 点击运行/调试配置切换器中的当前配置，然后点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.actions.more.svg) 并选择   编辑   选项。

![编辑运行/调试配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_edit_configurations_pw_for_python.png)

2. 在   附加实参  字段中，指定  `--headed` 命令：

![配置运行/调试配置以在有头模式下运行测试](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_pw_for_python_headed_mode.png)

3. 应用更改并运行您的测试。

结果，一个浏览器被打开以重现测试中的步骤。

## 查看测试结果

测试运行完成后，结果会显示在   运行   工具窗口的   测试运行器   选项卡上。 在此选项卡上，可以重新运行测试、导出和导入测试结果、查看每个测试的运行耗时以及执行其他操作。

![显示在运行工具窗口的测试运行程序选项卡上的测试结果](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_playwright_review_tests.png)

有关更多信息，请参见 [浏览测试结果](viewing-and-exploring-test-results.html)。

## 调试测试

一般来说，调试过程包括以下步骤：

1.  为需要暂停执行的代码行设置断点。

2.  在调试模式下运行您的代码。

3.  使用   调试   工具窗口分析代码并定位潜在问题。

4.  修复问题。

要在 IDE 中重现这些步骤，请执行以下操作：

Procedure:

1. 在装订区域，将鼠标悬停在想要暂停执行的可执行代码行上，然后点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.breakpoints.breakpoint.svg)。

![设置断点](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_playwright_set_breakpoints.png)

2. 在装订区域中点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.run.run.svg) 并选择   调试  。 这将启动调试器会话并运行您的代码。

![开始调试会话](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ps_debug_playwright_tests.png)

3. 程序命中断点后，执行将被挂起，可以在   调试   工具窗口中查看调试器会话的结果。

![调试工具窗口概述](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_debug_overview.png)

有关调试的详细信息，请参阅 [调试代码](debugging-code.html)。

## 生成 Playwright 报告

[Playwright reporters](https://playwright.dev/docs/test-reporters) 提供有关失败测试的详细信息，使您能够更彻底地分析测试执行期间发生的情况。

默认情况下，会生成一个  `html`  报告，但您可以使用运行/调试配置切换到其他格式。 为此：

Procedure:

> **Note:**
> 您只能更改 [Playwright for JS/TS](#playwright-for-js-ts) 项目的报告者。

1. 点击运行/调试配置切换器中的当前配置，然后点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.actions.more.svg) 并选择   编辑   选项。

![编辑运行/调试配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_edit_configurations.png)

2. 在   Playwright 选项  字段中，指定所需的 [报告者](https://playwright.dev/docs/test-reporters#built-in-reporters)。 例如：

```GENERIC
--reporter=line

```

3. 应用更改并运行您的测试。

因此，会生成一份详细报告。

![生成的 Playwright 报告](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_pw_report.png)

## 修改运行/调试配置

如果您想修改测试的启动属性，请编辑运行/调试配置：

Procedure:

1. 在运行/调试配置切换器中点击当前配置，并选择   编辑配置…   选项。

![选择运行/调试配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_playwright_edit_run_debug_config.png)

2. 在   运行/调试配置   对话框中，选择要编辑的配置。

3. 配置所需的启动属性。

> **Note:**
> 根据项目设置，运行/调试配置参数可能会有所不同。

Playwright for JS/TS:

![配置启动属性](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_playwright_run_debug_config.png)

适用于 JVM 的 Playwright:

![配置启动属性](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_playwright_run_debug_config_jvm.png)

适用于 Python 的 Playwright:

![配置启动属性](https://resources.jetbrains.com.cn/help/img/idea/2026.3/调试配置](run-debug-configuration.html)。

## 自定义定位器模板

如果想自定义将选定元素添加到代码的方式，可以修改模板：

Procedure:

1. 点击状态栏上的框架名称。 将打开   UI 自动化框架   菜单。

![自定义模板](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_customize_playwright_template.png)

2. 请选择   自定义模板  选项。

3. 在   文件和代码模板   对话框中，从列表中选择所需的框架。

![文件和代码模板对话框](https://resources.jetbrains.com.cn/help/img/idea/2026.3/aqua_playwright_locator_template.png)

4. 重写 Web 元素定位器的代码生成算法。

> **Tip:**
> 使用 [Apache Velocity](https://velocity.apache.org/) 模板语言。

5. 点击   OK   以保存更改。

因此，定位器将根据更新后的代码生成算法添加到代码中。

## See also

### 外部链接

[Playwright](https://playwright.dev/) [Playwright reporters](https://playwright.dev/docs/test-reporters) [List of reporters](https://playwright.dev/docs/test-reporters#built-in-reporters)

