# @azure/playwright 中文文档

规范地址：https://npmcn.com/package/%40azure/playwright/

版本：1\.1\.6
npm 元数据更新时间：2026-06-05T15:53:28.249Z
中文译文更新时间：2026-11-07T13:25:08.830Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azure/playwright
原文对照：https://npmcn.com/package/%40azure/playwright/?lang=original
项目主页：https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/loadtesting/playwright/README.md
源码仓库：https://github.com/Azure/azure-sdk-for-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：719 kB，222 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：6 个
- peer 依赖：@playwright/test ^1\.47\.0
- 首次发布：2025-06-05T13:07:25.355Z
- 最新版本发布：2026-06-05T15:53:28.070Z
- 近 30 天下载量：280098（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：130（近 12 个月 65 个）

## 中文简介

将您的 Playwright 测试套件与 Azure Playwright 服务集成

## 安装

```sh
npm install @azure/playwright
```

也可以使用：`pnpm add @azure/playwright`、`yarn add @azure/playwright`、`bun add @azure/playwright`

## README

# Azure 剧作家

Azure Playwright是一个完全管理好的Azure服务,它使用云来使您能够同时运行Playwright测试,在不同的操作系统-浏览器组合上具有更高程度的并行性. 这意味着进行更快速的测试,涵盖范围更广,这有助于在不牺牲质量的情况下加快提供特征。 服务还包括综合报告能力,将测试结果和相关文物自动上传到Azure存储器,并在服务门户中查看,从而能够更快,更容易地排除出故障. 有了Playwright Workspaces,就可以更快更自信地发布特性.

准备好了吗? 跳入我们的行列 [快速启动指南](https://npmcn.com/package/%40azure/playwright/#readme-get-started)来啊!

## 有用链接

-   [快速启动: 在规模上运行端到端测试](https://aka.ms/pww/docs/quickstart)
-   [快速启动:在不同浏览器和操作系统中设置连续的端到端测试](https://aka.ms/pww/docs/ci)
-   [探索特征和效益](https://aka.ms/pww/docs/about)
-   [文档](https://aka.ms/pww/docs)
-   [定价](https://aka.ms/pww/docs/pricing)
-   [分享反馈](https://aka.ms/pww/docs/feedback)

## 开始

按照这些步骤运行您现有的 Playwright 测试套件与服务.

### 先决条件

-   一个Azure账户, 活动订阅 。 如果你没有Azure的订阅, [创建一个自由账户](https://aka.ms/pww/docs/create-azure-subscription) 在你开始之前.
-   您的 Azure 账户必须指定 [拥有者](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner), (中文(简体) ), [贡献者](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#contributor),或其中的一个 [经典管理员角色](https://learn.microsoft.com/azure/role-based-access-control/rbac-and-directory-admin-roles#classic-subscription-administrator-roles)。 。 。 .
-   [阿苏尔CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) 必须安装在运行 Playwright 测试的机器中.

### 创建工作空间

1.  签到 [Azure 门户网站](https://portal.azure.com/) 和你的Azure账户.
    
2.  创建工作空间 .
    
    -   选择门户左上角的菜单按钮,然后选择创建资源.
        
        ![Create a resource in Azure portal](https://aka.ms/pww/docs/createurlsnapshot)
        
    -   输入 **剧作家工作空间** 在搜索框中.
        
    -   选择 **剧作家工作空间** 牌,然后选择 **创建**。 。 。 .
        
        ![Search for Playwright Workspaces in Azure Marketplace](https://aka.ms/pww/docs/searchurlsnapshot)
        
    -   为配置新的 Playwright 工作空间提供下列信息:
        
        | 外地 | 说明 |
        | --- | --- |
        | **订阅** | 选择您要用于此 Playwright 工作空间的 Azure 订阅 . |
        | **资源组** | 选择已有资源组。 或者选择 **创建新**,然后输入新资源组的独有名称. |
        | **名称** | 输入用于识别您工作空间的独有名称.  
        名字只能由α数字字符组成,长度在3到64个字符之间. |
        | **地点** | 选择您工作空间的地理位置 .  
        此位置也决定了测试执行结果的存储位置. |
        | **报告** | 切换被设定为默认“ 启用” , 以使用户能够从 Playwright 工作空间保存和查看他们的测试运行报告 。 如果您想要关闭报告, 请将设置切换为“ 残疾 ” . |
        | **存储账户** | 新建存储账户,并默认选择存储 Playwright 工作空间报告文物. 要选择一个已有的存储账户,请从下放中选择,或点击"创造新"创建您所选择的新存储账户. |
        
        > \[注\] 您可以选择配置更多细节 **标记** 选项卡。 标记是名称/值对,通过对多个资源和资源组应用相同的标记,使您能够对资源进行分类并查看合并的帐单.
        
    -   配置完资源后,请选择 **审查 + 创建**。 。 。 .
        
    -   审查所有配置设置并选择 **创建** 开始部署 Playwright 工作空间.
        
    -   当进程完成时,会出现部署成功的信息.
        
    -   要查看新的工作空间, 请选择 **跳转到资源**。 。 。 .
        
        ![Deployment complete - Go to resource](https://aka.ms/pww/docs/deploymenturlsnapshot)
        

### 安装 Azure Playwright 包

1.  运行此命令以安装服务包
    
    ```nodejs
    npm init @azure/playwright@latest
    ```
    

安装服务包将创建一个名为服务配置的文件 `playwright.service.config.ts`

服务配置旨在:

-   直接并认证Playwright给Playwright工作空间.
-   添加 Playwright 工作空间报告到您的配置 .
-   如果需要,服务业务超时.

> 确保您的项目使用@ playwright/ test 版本1.47 或以上 .

### 获取区域终点

1.  在那个 [Azure 门户网站](https://portal.azure.com/),将命令复制到 **在您的设置中添加区域终点**。 。 。 .
    
    ![Set workspace endpoint](https://aka.ms/pww/docs/copyurlsnapshot)
    
    端点URL对应工作空间区域. 您可能在 Azure 门户网站中看到不同的端点 URL, 取决于您创建工作空间时选择的区域 .
    

### 设置环境

确保 `PLAYWRIGHT_SERVICE_URL` 您在前一步获得的,可以在您的环境中使用.

我们建议使用 `dotenv` 模块来管理您的环境。 与 `dotenv` 你会使用 `.env` 用于定义环境变量的文件.

> 别忘了说 `.env` 转到您的文件 `.gitignore` 用于不泄露您的秘密.

```sh
npm i --save-dev dotenv
```

`.env` 文件

```nodejs
PLAYWRIGHT_SERVICE_URL=wss://eastus.api.playwright.microsoft.com/playwrightworkspaces/workspace-id/browsers
```

### 设置认证

要在您的 Azure Playwright 工作空间中运行您的 Playwright 测试, 您需要认证您正在使用服务运行测试的 Playwright 客户端 。 这可能是你的本地dev机器或CI机器.

该服务提供两种认证方法:Microsoft Entra ID和Access Tokens.

微软 Entra ID 使用您的 Azure 证书,需要登录您的 Azure 账户才能安全访问. 或者,您可以从您的 Playwright 工作空间生成访问令牌并在您的设置中使用它 .

#### 使用 Microsoft Entra ID 设置认证

Microsoft Entra ID是该服务的默认和推荐认证. 从你的本地dev机器,你可以使用 [阿苏尔CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) 要登录

```CLI
az login
```

**页:1**:如果您是多个Microsoft Entra租户的一部分,请确保您登录到您工作空间所属的租户。 你可以从Azure入口处拿到房客身份证 [找到您的微软 Entra 租户](https://learn.microsoft.com/azure/azure-portal/get-subscription-tenant-id#find-your-microsoft-entra-tenant)。一旦获得身份证,使用命令登录 `az login --tenant <TenantID>`

#### 使用访问令牌设置认证

您可以从您的 Azure Playwright 工作空间生成访问符并用于您的设置 。 然而,我们强烈建议微软Entra ID进行认证,因为它加强了安全性. 访问符虽然方便,但功能类似长生密码,更容易被泄露.

1.  要使用基于访问符的认证, [启用基于访问的验证](https://aka.ms/pww/docs/authentication)
    
2.  [使用访问令牌设置认证](https://aka.ms/pww/docs/access-token)
    

> 我们强烈建议使用微软EntraID进行服务认证. 如果您正在使用访问符,请查看 [如何管理访问文件夹](https://aka.ms/pww/docs/access-token)

_注:_ 要使用 Azure Playwright 在 CI 管道中, 您需要配置认证 [在不同浏览器和操作系统中建立连续的端到端测试](https://aka.ms/pww/docs/ci)

### 运行测试

使用您在上面创建的配置对服务管理的浏览器进行 Playwright 测试 .

```nodejs
npx playwright test --config=playwright.service.config.ts --workers=20
```

## Azure Playwright 记者

Azure Playwright 包括一个自定义的记者,可以自动上传您的 Playwright HTML 测试报告到 Azure 存储器,使其直接通过 Azure 门户网站访问,以方便调试和结果共享.

### 特征

-   **自动上传报表**: 无缝上传 Playwright HTML 报告到您的 Azure 存储账户
-   **门户整合**: 在 Azure Playwright 门户网站直接查看测试结果
-   **增强调试**: 获取详细的测试文物、痕迹和截图

### 设置和配置

Azure Playwright 的记者也加入了其中 `@azure/playwright` 软件包和与 Playwright 的 HTML 内置记者一起工作.

#### 1\. 配置 Playwright 配置中的记者

将 HTML 记者和 Azure Playwright 记者添加到您的 `playwright.service.config.ts`数字 :

```typescript
import { DefaultAzureCredential } from "@azure/identity";
import { defineConfig } from "@playwright/test";
import { createAzurePlaywrightConfig } from "@azure/playwright";

const credential = new DefaultAzureCredential();
const playwrightConfig = defineConfig({});
defineConfig(playwrightConfig, createAzurePlaywrightConfig(playwrightConfig, { credential }), {
  reporter: [
    ["html", { open: "never" }], // HTML reporter must come first
    ["@azure/playwright/reporter"], // Azure reporter uploads HTML report
  ],
});
```

#### 2\. 报告的先决条件

在使用 Azure Playwright 报告器之前, 请确保您的工作空间被正确配置 :

##### 工作空间配置

**启用报告和配置存储 :**

1.  前往您的 Azure 门户网站上的 Playwright 工作空间
2.  导航到 **存储配置** 选项卡
3.  切换 **报告** 改为 **已启用**
4.  新建或选择已存在的存储账户
5.  点击 **保存**

**配置 RBAC 存储访问 :**

1.  打开链接的存储账户
2.  转到 **访问控制( IAM)** 选项卡
3.  点击 **添加角色指派**
4.  搜索和选择 **存储 Blob 数据贡献器** 角色,然后单击 **下一个**
5.  选择并添加所有正在运行测试的成员
6.  点击 **审查+指定**

**配置 Trace 查看器的 CORS :**

1.  打开链接的存储账户
2.  转到 **设置** → **资源分享**
3.  下 **Blob 服务**,添加新的记录:
    -   **允许来源**数字 : `https://trace.playwright.dev`
    -   **允许的方法**数字 : `GET, OPTIONS`
    -   **最大年龄**: 输入0至2147483647之间的值
4.  点击 **保存**

##### 客户需求

-   **认证**: 需要Microsoft Entra ID认证(报告时不支持访问令牌)
-   **剧作家版本**: 要求 Playwright 版本1.57 或更高
-   **服务配置**: 必须使用服务配置( playwright. service.config.ts)
-   **工作空间设置**: 必须在您的 Azure Playwright 工作空间上进行报告

### 如何运作

1.  **测试执行**: 测试通常使用 Azure Playwright 服务浏览器运行
2.  **HTML 报告生成**: Playwright 的 HTML 报告生成标准测试报告
3.  **自动上传**: Azure 报告人将 HTML 报告文件夹上传到您的工作空间 Azure 存储器
4.  **门户访问**: 通过提供的 URL 在 Azure 门户查看结果

## 今后的步骤

-   在 a 中进行测试 [CI/CD管道.](https://aka.ms/pww/docs/configure-pipeline)
    
-   学会如何 [管理访问](https://aka.ms/pww/docs/manage-access) 到创建的工作空间.
    
-   试验不同数目的工人 [决定测试套件的最佳配置](https://aka.ms/pww/docs/parallelism)。 。 。 .
    

## 捐款

该项目欢迎各方的贡献和建议。 大多数捐款要求您同意 撰稿人许可协议(CLA)宣布,你有权并且实际上确实给了我们 有权使用您的贡献。 详情请访问 [https://cla.opensource.microsoft.com 互联网档案馆的存檔,存档日期2014-10-02](https://cla.opensource.microsoft.com/)。 。 。 .

当您提交拉拉请求时, CLA bot 会自动确定您是否需要提供 a CLA并适当装饰PR(如状态检查、评论)。 只要听从指示 由机器人提供。 你只需要用我们的CLA 一次就能完成.

该项目通过了 [Microsoft 开源行为守则](https://opensource.microsoft.com/codeofconduct/)。 。 。 . 更多信息见 [《行为守则》](https://opensource.microsoft.com/codeofconduct/faq/) 或者说 联系人 [打开码@ microsoft.com](mailto:opencode@microsoft.com) 并附上任何其他问题或评论.

## 商标

本项目可能包含项目,产品或服务的商标或标志. 授权使用微软 商标或标志必须遵循 [微软的商标和品牌准则](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general)。 。 。 . 在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助. 任何使用第三方商标或标志的行为都必须遵守第三方的政策.

## 常见问题

### @azure/playwright 是什么？

将您的 Playwright 测试套件与 Azure Playwright 服务集成

### 如何安装 @azure/playwright？

在项目目录运行 npm install @azure/playwright，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@playwright/test（^1\.47\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @azure/playwright 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @azure/playwright 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @azure/playwright 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @azure/playwright 可以商用吗？

@azure/playwright 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @azure/playwright 的下载量有多少？

根据 npm 官方下载统计，@azure/playwright 在 2026/10/08 – 2026/11/06 这 30 天内被下载 280,098 次，日均约 9,337 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @azure/playwright 还在维护吗？

最新版本 1\.1\.6 发布于 2026/06/05（5 个月前）；至今共发布 130 个版本，其中过去 12 个月发布了 65 个；首次发布于 2025/06/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。