Azure Microsoft Playwright TypeScript 测试

azure-microsoft-playwright-testing-ts
分类编程
作者Agentic Awesome Skills 社区
许可MIT
评分4.50/5
使用8.0K

Azure Playwright Workspaces SDK for TypeScript

利用云托管浏览器和集成的 Azure 门户报告大规模运行 Playwright 测试。

> 迁移通知： @azure/microsoft-playwright-testing 将于 2026 年 3 月 8 日 停用。请改用 @azure/playwright。详见 迁移指南。

安装

bash
# 推荐：自动生成配置
npm init @azure/playwright@latest

手动安装

npm install @azure/playwright --save-dev
npm install @playwright/test@^1.47 --save-dev
npm install @azure/identity --save-dev

要求：

  • Playwright 版本 1.47+（基础用法）

  • Playwright 版本 1.57+（Azure reporter 功能）

环境变量

bash
PLAYWRIGHT_SERVICE_URL=wss://eastus.api.playwright.microsoft.com/playwrightworkspaces/{workspace-id}/browsers

身份验证

Microsoft Entra ID (推荐)

bash
# 使用 Azure CLI 登录
az login
typescript
// playwright.service.config.ts
import { defineConfig } from "@playwright/test";
import { createAzurePlaywrightConfig, ServiceOS } from "@azure/playwright";
import { DefaultAzureCredential } from "@azure/identity";
import config from "./playwright.config";

export default defineConfig(
  config,
  createAzurePlaywrightConfig(config, {
    os: ServiceOS.LINUX,
    credential: new DefaultAzureCredential(),
  })
);

自定义凭据

typescript
import { ManagedIdentityCredential } from "@azure/identity";
import { createAzurePlaywrightConfig } from "@azure/playwright";

export default defineConfig(
  config,
  createAzurePlaywrightConfig(config, {
    credential: new ManagedIdentityCredential(),
  })
);

核心工作流

服务配置

typescript
// playwright.service.config.ts
import { defineConfig } from "@playwright/test";
import { createAzurePlaywrightConfig, ServiceOS } from "@azure/playwright";
import { DefaultAzureCredential } from "@azure/identity";
import config from "./playwright.config";

export default defineConfig(
  config,
  createAzurePlaywrightConfig(config, {
    os: ServiceOS.LINUX,
    connectTimeout: 30000,
    exposeNetwork: "<loopback>",
    credential: new DefaultAzureCredential(),
  })
);

运行测试

bash
npx playwright test --config=playwright.service.config.ts --workers=20

使用 Azure Reporter

typescript
import { defineConfig } from "@playwright/test";
import { createAzurePlaywrightConfig, ServiceOS } from "@azure/playwright";
import { DefaultAzureCredential } from "@azure/identity";
import config from "./playwright.config";

export default defineConfig(
  config,
  createAzurePlaywrightConfig(config, {
    os: ServiceOS.LINUX,
    credential: new DefaultAzureCredential(),
  }),
  {
    reporter: [
      ["html", { open: "never" }],
      ["@azure/playwright/reporter"],
    ],
  }
);

手动浏览器连接

typescript
import playwright, { test, expect, BrowserType } from "@playwright/test";
import { getConnectOptions } from "@azure/playwright";

test("manual connection", async ({ browserName }) => {
  const { wsEndpoint, options } = await getConnectOptions();
  const browser = await (playwright[browserName] as BrowserType).connect(wsEndpoint, options);
  const context = await br

owser.newContext();
const page = await context.newPage();

await page.goto("https://example.com");
await expect(page).toHaveTitle(/Example/);

await browser.close();
});

code
## 配置选项
typescript
type PlaywrightServiceAdditionalOptions = {
serviceAuthType?: "ENTRA_ID" | "ACCESS_TOKEN"; // 默认值: ENTRA_ID
os?: "linux" | "windows"; // 默认值: linux
runName?: string; // 用于 Portal 的自定义运行名称
connectTimeout?: number; // 默认值: 30000ms
exposeNetwork?: string; // 默认值: <loopback>
credential?: TokenCredential; // Entra ID 必需项
};
code
### ServiceOS 枚举
typescript
import { ServiceOS } from "@azure/playwright";

// 可用值
ServiceOS.LINUX // "linux" - 默认
ServiceOS.WINDOWS // "windows"

code
### ServiceAuth 枚举
typescript
import { ServiceAuth } from "@azure/playwright";

// 可用值
ServiceAuth.ENTRA_ID // 推荐 - 使用凭据 (credential)
ServiceAuth.ACCESS_TOKEN // 使用 PLAYWRIGHT_SERVICE_ACCESS_TOKEN 环境变量

code
## CI/CD 集成


GitHub Actions
yaml name: playwright-ts on: [push, pull_request]

permissions:
id-token: write
contents: read

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Azure Login
uses: azure/login@v2
with:
client-id: ${{ secrets.AZURE_CLIENT_ID }}
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

- run: npm ci

- name: Run Tests
env:
PLAYWRIGHT_SERVICE_URL: ${{ secrets.PLAYWRIGHT_SERVICE_URL }}
run: npx playwright test -c playwright.service.config.ts --workers=20

code
### Azure Pipelines
yaml
  • task: AzureCLI@2

displayName: Run Playwright Tests
env:
PLAYWRIGHT_SERVICE_URL: $(PLAYWRIGHT_SERVICE_URL)
inputs:
azureSubscription: My_Service_Connection
scriptType: pscore
inlineScript: |
npx playwright test -c playwright.service.config.ts --workers=20
addSpnToEnvironment: true
code
## 核心类型
typescript
import {
createAzurePlaywrightConfig,
getConnectOptions,
ServiceOS,
ServiceAuth,
ServiceEnvironmentVariable,
} from "@azure/playwright";

import type {
OsType,
AuthenticationType,
BrowserConnectOptions,
PlaywrightServiceAdditionalOptions,
} from "@azure/playwright";

code
## 从旧版本包迁移


| 旧版本 (@azure/microsoft-playwright-testing) | 新版本 (@azure/playwright) |
|---------------------------------------------|---------------------------|
| getServiceConfig() | createAzurePlaywrightConfig() |
| timeout 选项 | connectTimeout 选项 |
| runId 选项 | runName 选项 |
| useCloudHostedBrowsers 选项 | 已移除 (默认始终启用) |
| @azure/microsoft-playwright-testing/reporter | @azure/playwright/reporter |
| 隐式凭据 | 显式 credential 参数 |


迁移前 (旧版本)
typescript import { getServiceConfig, ServiceOS } from "@azure/microsoft-playwright-testing";

export default defineConfig(
config,
getServiceConfig(config, {
os: ServiceOS.LINUX,
timeout: 30000,
useCloudHostedBrowsers: true,
}),
{
reporter: [["@azure/microsoft-playwright-testing/reporter"]],
}
);

code
### 迁移后 (新版本)
typescript
import { createAzurePlaywrightConfig, ServiceOS } from "@azure/playwright";
import { DefaultAz_
code
ureCredential } from "@azure/identity";


export default defineConfig(
  config,
  createAzurePlaywrightConfig(config, {
    os: ServiceOS.LINUX,
    connectTimeout: 30000,
    credential: new DefaultAzureCredential(),
  }),
  {
    reporter: [
      ["html", { open: "never" }],
      ["@azure/playwright/reporter"],
    ],
  }
);

最佳实践

1. 使用 Entra ID 认证 — 比访问令牌（access tokens）更安全
2. 提供明确的凭据 — 始终传递 credential: new DefaultAzureCredential()
3. 启用 Artifacts — 在配置中设置 trace: "on-first-retry" 和 video: "retain-on-failure"
4. 扩展 Worker 数量 — 并行执行时使用 --workers=20 或更高
5. 选择区域 — 选择距离测试目标最近的区域
6. 优先配置 HTML 报告器 — 使用 Azure 报告器时，请将 HTML 报告器置于 Azure 报告器之前

适用场景

本技能适用于执行概览中所描述的工作流或操作。

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。