你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：使用 Microsoft Playwright Testing 预览版对测试进行故障排除

项目
12/04/2024

在本快速入门中，你将了解如何使用 Microsoft Playwright Testing 预览版上发布的报告和工件轻松排查 Playwright 测试问题。此外，本指南还演示了如何利用报告功能，无论你是否在服务提供的云托管浏览器上运行测试。

完成本快速入门后，你将拥有一个 Microsoft Playwright Testing 工作区，可在服务门户中查看测试结果和工件。

重要

Microsoft Playwright Testing 目前以预览版提供。有关 beta 版、预览版或尚未正式发布的 Azure 功能所适用的法律条款，请参阅 Microsoft Azure 预览版的补充使用条款。

背景

Microsoft Playwright Testing 服务使你能够：

使用云托管浏览器并行运行测试来加速生成管道。
将测试结果和工件发布到服务，使它们可通过服务门户访问，从而简化故障排除。

服务的这两个功能可以独立使用，也可以一起使用，每个功能都有其自己的定价计划。你可以灵活地：

通过使用以下两项功能来加快测试运行并简化故障排除操作：在云托管浏览器中运行测试以及将结果发布到服务。
仅在云托管的浏览器中运行测试，以便更快地完成测试运行。
将测试结果发布到服务，同时继续在本地运行测试，以便进行高效的故障排除。

注意

本文重点介绍如何在不使用云托管浏览器的情况下将测试结果发布到服务。如果还想了解如何加速测试性运行，请参阅快速入门：大规模运行 Playwright 测试

先决条件

具有活动订阅的 Azure 帐户。如果没有 Azure 订阅，请在开始之前创建一个免费帐户。
Azure 帐户需要所有者、参与者或经典管理员角色之一。
Playwright 项目。如果没有项目，请使用 Playwright 入门文档创建一个，或使用 Microsoft Playwright Testing 示例项目。
Azure CLI。如果你没有 Azure CLI，请参阅安装 Azure CLI。

创建工作区

若要开始在 Playwright Testing 服务上发布测试结果，请先在 Playwright 门户中创建 Microsoft Playwright Testing 工作区。

使用 Azure 帐户登录到 Playwright 门户。
如果已有工作区，请选择现有工作区，然后转到下一步。

提示

如果有多个工作区，可以通过选择页面顶部的工作区名称切换到另一个工作区，然后选择“管理所有工作区”。

如果还没有工作区，请选择“+ 新建工作区”，然后提供以下信息：

字段	说明
工作区名称	输入唯一名称以标识工作区。该名称只能包含字母数字字符，长度介于 3 到 64 个字符之间。
Azure 订阅	选择要用于此 Microsoft Playwright Testing 工作区的 Azure 订阅。
区域	选择要托管工作区的地理位置。这是为工作区存储测试运行数据的位置。

选择“创建工作区”以在订阅中创建工作区。

在工作区创建期间，Azure 订阅中会创建新的资源组和 Microsoft Playwright Testing Azure 资源。

工作区创建完成后，会重定向到设置指南。

安装 Microsoft Playwright Testing 包

若要使用该服务，请安装 Microsoft Playwright Testing 包。

npm init @azure/microsoft-playwright-testing@latest

注意

确保项目使用 @playwright/test 版本 1.47 或更高版本。

此命令会生成 playwright.service.config.ts 文件，用于：

将 Playwright 客户端定向到 Microsoft Playwright Testing 服务并对其进行身份验证。
添加一个报告程序来发布测试结果和项目。

如果你已有此文件，提示会询问你是否替代它。

若要仅对测试运行使用报告功能，请通过将 useCloudHostedBrowsers 设置为 false 来禁用云托管的浏览器。

export default defineConfig(
  config,
  getServiceConfig(config, {
    timeout: 30000,
    os: ServiceOS.LINUX,
	useCloudHostedBrowsers: false // Do not use cloud hosted browsers
  }),
  {
    reporter: [['list'], ['@azure/microsoft-playwright-testing/reporter']], // Reporter for Microsoft Playwright Testing service
  }
);

将值设置为 false 可确保云托管的浏览器不用于运行测试。测试在本地计算机上运行，但结果和工件在服务上发布。

若要使用该服务，请安装 Microsoft Playwright Testing 包。

dotnet add package Azure.Developer.MicrosoftPlaywrightTesting.NUnit --prerelease

注意

确保项目使用 Microsoft.Playwright.NUnit 版本 1.47 或更高版本。

要仅使用报告功能，请在项目的 .runsettings 文件中更新以下内容：

通过将 useCloudHostedBrowsers 设置为 false 来禁用云托管浏览器。
在“记录器”部分添加 Microsoft Playwright Testing 记录器。

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
    <TestRunParameters>        
        <!--Select if you want to use cloud-hosted browsers to run your Playwright tests.-->
        <Parameter name="UseCloudHostedBrowsers" value="true" />
        <!--Select the authentication method you want to use with Entra-->
    </TestRunParameters> 
 .
 .
 .
    <LoggerRunSettings>
        <Loggers>
            <!--Microsoft Playwright Testing service logger for reporting -->
            <Logger friendlyName="microsoft-playwright-testing" enabled="True" />
            <!--could enable any logger additionally -->
            <Logger friendlyName="trx" enabled="false" />
        </Loggers>
    </LoggerRunSettings>
</RunSettings>

提示

如果要使用云托管浏览器加速测试运行，可以将 useCloudHostedBrowsers 设置为 true。这将在服务托管浏览器上运行测试。

配置服务区域终结点

在设置中，必须提供区域特定的服务终结点。终结点取决于在创建工作区时选择的 Azure 区域。

要获取服务终结点 URL，请执行以下步骤：

在“在设置中添加区域终结点”中，复制工作区的区域终结点。

终结点 URL 与创建工作区时选择的 Azure 区域匹配。请确保此 URL 在 PLAYWRIGHT_SERVICE_URL 环境变量中可用。

设置你的环境

若要设置环境，必须使用在前面步骤中获取的值配置 PLAYWRIGHT_SERVICE_URL 环境变量。

建议使用dotenv模块管理环境。使用dotenv，可以在.env文件中定义环境变量。

将dotenv模块添加到项目：
```
npm i --save-dev dotenv
```
在 Playwright 项目中的 playwright.config.ts 文件旁边创建 .env 文件：
```
PLAYWRIGHT_SERVICE_URL={MY-REGION-ENDPOINT}
```
请务必将 {MY-REGION-ENDPOINT} 文本占位符替换为之前复制的值。

设置服务配置

在根目录中创建一个名为 PlaywrightServiceSetup.cs 的文件，并添加以下内容。

using Azure.Developer.MicrosoftPlaywrightTesting.NUnit;

namespace PlaywrightTests; // Remember to change this as per your project namespace

[SetUpFixture]
public class PlaywrightServiceSetup : PlaywrightServiceNUnit {};

注意

确保项目使用 Microsoft.Playwright.NUnit 版本 1.47 或更高版本。

设置身份验证

若要向你的 Microsoft Playwright Testing 工作区发布测试结果和工件，需要对使用该服务运行测试的 Playwright 客户端进行身份验证。该客户端可能是你的本地开发计算机，也可能是 CI 计算机。

该服务提供两种身份验证方法：Microsoft Entra ID 和访问令牌。

Microsoft Entra ID 使用 Azure 凭据，这需要登录到 Azure 帐户进行安全访问。或者，可以从 Playwright 工作区生成访问令牌并在设置中使用它。

使用 Microsoft Entra ID 设置身份验证

Microsoft Entra ID 是该服务的默认身份验证方法，也是建议的方法。在本地开发计算机中，可以使用 Azure CLI 登录

az login

注意

如果你属于多个 Microsoft Entra 租户，请确保登录到你的工作区所属的租户。可以从 Azure 门户获取租户 ID。有关详细信息，请参阅查找 Microsoft Entra 租户。获取 ID 后，使用命令 az login --tenant <TenantID> 登录

使用访问令牌设置身份验证

可以从 Playwright Testing 工作区生成访问令牌并在设置中使用它。但是，我们强烈建议使用 Microsoft Entra ID 进行身份验证，因为它具有增强的安全性。访问令牌虽然很方便使用，但其功能类似于长期密码，因此更容易泄露。

默认情况下，已禁用使用访问令牌的身份验证。若要使用，请启用基于访问令牌的身份验证
使用访问令牌设置身份验证

注意

我们强烈建议使用 Microsoft Entra ID 对该服务进行身份验证。如果使用访问令牌，请参阅如何管理访问令牌

在 Playwright 设置中启用工件

在项目的 playwright.config.ts 文件中，请确保收集所有必需的工件。

  use: {
    trace: 'on-first-retry',
    video:'retain-on-failure',
    screenshot:'on'
  }

启用 Playwright 捕获的项目，例如屏幕截图、视频和跟踪。

有关屏幕截图，请参阅捕获屏幕截图
有关视频，请参阅录制测试的视频
有关跟踪，请参阅录制跟踪

收集这些项目后，将它们附加到 TestContext，以确保它们在测试报告中可用。有关详细信息，请参阅我们的 NUnit 示例项目

在 Microsoft Playwright Testing 上运行测试并发布结果

现在，你已准备好通过 Microsoft Playwright Testing 发布测试结果和工件的配置。使用新建的 playwright.service.config.ts 文件运行测试，并将测试结果和工件发布到服务。

   npx playwright test --config=playwright.service.config.ts

注意

对于 Microsoft Playwright Testing 的报告功能，将根据发布的测试结果数收费。如果你是第一次使用或通过免费试用版入门，则可以先发布单个测试结果而不是完整的测试套件，以避免耗尽免费试用限制。

测试完成后，可以在终端中查看测试状态。

Running 6 test using 2 worker
    5 passed, 1 failed (20.2s)

Test report: https://playwright.microsoft.com/workspaces/<workspace-id>/runs/<run-id>

现在，你已准备好通过 Microsoft Playwright Testing 发布测试结果和工件的配置。使用 .runsettings 文件运行测试，并将测试结果和工件发布到服务。

dotnet test --settings:.runsettings

在 .runsettings 文件中定义测试运行的设置。有关详细信息，请参阅如何使用服务包选项

注意

测试运行完成后，可以在终端中查看测试状态。

Starting test execution, please wait...

Initializing reporting for this test run. You can view the results at: https://playwright.microsoft.com/workspaces/<workspace-id>/runs/<run-id>

A total of 100 test files matched the specified pattern.

Test Report: https://playwright.microsoft.com/workspaces/<workspace-id>/runs/<run-id>

Passed!  - Failed:     0, Passed:     100, Skipped:     0, Total:     100, Duration: 10 m - PlaywrightTestsNUnit.dll (net7.0)

Workload updates are available. Run `dotnet workload list` for more information.

注意

根据测试套件的大小，对于超出分配的免费测试结果的测试结果，可能会产生额外费用。

在 Playwright 门户中查看测试运行和结果

现在，你可以在 Playwright 门户中排查失败的测试案例所存在的问题。

测试运行完成后，将生成一个指向 Playwright 门户的链接。打开此链接即可查看详细的测试结果和关联的工件。该门户会显示基本信息，包括：
- CI 生成详细信息
- 总体测试运行状态
- 链接到测试运行的提交 ID
Playwright 门户会提供故障排除所需的所有信息。您可以：
- 在重试之间切换。
- 查看详细的错误日志、测试步骤和附加工件（例如屏幕截图或视频）。
- 直接导航到“跟踪查看器”，进行更深入的分析。
跟踪查看器让你可以直观地逐步查看测试执行情况。您可以：
- 使用时间线将鼠标悬停在各个步骤上，显示每个操作前后的页面状态。
- 检查每个步骤的详细日志、DOM 快照、网络活动、错误和控制台输出。

测试性运行完成后，会在终端中获得 Playwright 门户的链接。打开此链接即可查看详细的测试结果和关联的工件。该门户会显示基本信息，包括：
- CI 生成详细信息
- 总体测试运行状态
- 链接到测试运行的提交 ID
Playwright 门户会提供故障排除所需的所有信息。您可以：
- 查看详细的错误日志和附加项目（例如屏幕截图或视频）。
- 直接导航到“跟踪查看器”，进行更深入的分析。

注意

某些元数据（例如所有者、说明和类别）当前未显示在服务仪表板上。如果希望添加其他信息，请在我们的存储库中提交 GitHub 问题。

跟踪查看器让你可以直观地逐步查看测试执行情况。您可以：
- 使用时间线将鼠标悬停在各个步骤上，显示每个操作前后的页面状态。
- 检查每个步骤的详细日志、DOM 快照、网络活动、错误和控制台输出。

提示

你还可以使用 Microsoft Playwright Testing 服务通过云托管的浏览器并行运行测试。报告和云托管浏览器都是独立的功能，单独计费。你可以使用其中任意一个或两者。有关详细信息，请参阅如何使用服务功能

注意

发布的测试结果和项目会在服务上保留 90 天。之后，它们会自动删除。

下一步

已成功在 Playwright 门户中创建 Microsoft Playwright Testing 工作区，并在云浏览器中运行 Playwright 测试。

转到下一个快速入门，在 CI/CD 工作流中运行 Playwright 测试以设置连续端到端测试。

在 CI/CD 中设置连续端到端测试

通过