azure-microsoft-playwright-testing-ts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure Playwright Workspaces SDK for TypeScript

Azure Playwright Workspaces TypeScript SDK

Run Playwright tests at scale with cloud-hosted browsers and integrated Azure portal reporting.

Migration Notice:
@azure/microsoft-playwright-testing
is retired on March 8, 2026. Use
@azure/playwright
instead. See migration guide.

借助云托管浏览器和集成的Azure门户报告功能，大规模运行Playwright测试。

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

Installation

安装

bash

undefined

bash

undefined

Recommended: Auto-generates config

推荐：自动生成配置

npm init @azure/playwright@latest

Manual installation

手动安装

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


**Requirements:**
- Playwright version 1.47+ (basic usage)
- Playwright version 1.57+ (Azure reporter features)

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报告功能）

Environment Variables

环境变量

bash

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

bash

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

Authentication

身份验证

Microsoft Entra ID (Recommended)

Microsoft Entra ID（推荐）

bash

undefined

bash

undefined

Sign in with Azure CLI

使用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(),
  })
);

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(),
  })
);

Custom Credential

自定义凭据

typescript

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

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

typescript

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

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

Core Workflow

核心工作流

Service Configuration

服务配置

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(),
  })
);

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(),
  })
);

Run Tests

运行测试

bash

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

bash

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

With Azure Reporter

搭配Azure报告器

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 { 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"],
    ],
  }
);

Manual Browser Connection

手动浏览器连接

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 browser.newContext();
  const page = await context.newPage();

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

  await browser.close();
});

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 browser.newContext();
  const page = await context.newPage();

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

  await browser.close();
});

Configuration Options

配置选项

typescript

type PlaywrightServiceAdditionalOptions = {
  serviceAuthType?: "ENTRA_ID" | "ACCESS_TOKEN";  // Default: ENTRA_ID
  os?: "linux" | "windows";                        // Default: linux
  runName?: string;                                // Custom run name for portal
  connectTimeout?: number;                         // Default: 30000ms
  exposeNetwork?: string;                          // Default: <loopback>
  credential?: TokenCredential;                    // REQUIRED for Entra ID
};

typescript

type PlaywrightServiceAdditionalOptions = {
  serviceAuthType?: "ENTRA_ID" | "ACCESS_TOKEN";  // 默认值: ENTRA_ID
  os?: "linux" | "windows";                        // 默认值: linux
  runName?: string;                                // 门户中的自定义运行名称
  connectTimeout?: number;                         // 默认值: 30000ms
  exposeNetwork?: string;                          // 默认值: <loopback>
  credential?: TokenCredential;                    // Entra ID 必需
};

ServiceOS Enum

ServiceOS 枚举

typescript

import { ServiceOS } from "@azure/playwright";

// Available values
ServiceOS.LINUX   // "linux" - default
ServiceOS.WINDOWS // "windows"

typescript

import { ServiceOS } from "@azure/playwright";

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

ServiceAuth Enum

ServiceAuth 枚举

typescript

import { ServiceAuth } from "@azure/playwright";

// Available values
ServiceAuth.ENTRA_ID      // Recommended - uses credential
ServiceAuth.ACCESS_TOKEN  // Use PLAYWRIGHT_SERVICE_ACCESS_TOKEN env var

typescript

import { ServiceAuth } from "@azure/playwright";

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

CI/CD Integration

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

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 登录
        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: 运行测试
        env:
          PLAYWRIGHT_SERVICE_URL: ${{ secrets.PLAYWRIGHT_SERVICE_URL }}
        run: npx playwright test -c playwright.service.config.ts --workers=20

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

yaml

- task: AzureCLI@2
  displayName: 运行 Playwright 测试
  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

Key Types

关键类型

typescript

import {
  createAzurePlaywrightConfig,
  getConnectOptions,
  ServiceOS,
  ServiceAuth,
  ServiceEnvironmentVariable,
} from "@azure/playwright";

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

typescript

import {
  createAzurePlaywrightConfig,
  getConnectOptions,
  ServiceOS,
  ServiceAuth,
  ServiceEnvironmentVariable,
} from "@azure/playwright";

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

Migration from Old Package

从旧包迁移

Old ( `@azure/microsoft-playwright-testing` )	New ( `@azure/playwright` )
`getServiceConfig()`	`createAzurePlaywrightConfig()`
`timeout` option	`connectTimeout` option
`runId` option	`runName` option
`useCloudHostedBrowsers` option	Removed (always enabled)
`@azure/microsoft-playwright-testing/reporter`	`@azure/playwright/reporter`
Implicit credential	Explicit `credential` parameter

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

Before (Old)

迁移前（旧包）

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"]],
  }
);

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"]],
  }
);

After (New)

迁移后（新包）

typescript

import { createAzurePlaywrightConfig, ServiceOS } from "@azure/playwright";
import { DefaultAzureCredential } from "@azure/identity";

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

typescript

import { createAzurePlaywrightConfig, ServiceOS } from "@azure/playwright";
import { DefaultAzureCredential } from "@azure/identity";

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

Best Practices

最佳实践

Use Entra ID auth — More secure than access tokens
Provide explicit credential — Always pass
```
credential: new DefaultAzureCredential()
```

Enable artifacts — Set

trace: "on-first-retry"

video: "retain-on-failure"

in config

Scale workers — Use
```
--workers=20
```
or higher for parallel execution
Region selection — Choose region closest to your test targets
HTML reporter first — When using Azure reporter, list HTML reporter before Azure reporter

使用Entra ID身份验证 — 比访问令牌更安全

提供显式凭据 — 始终传入

credential: new DefaultAzureCredential()

启用工件 — 在配置中设置

trace: "on-first-retry"

、

video: "retain-on-failure"

扩展工作进程 — 使用
```
--workers=20
```
或更高值实现并行执行
选择区域 — 选择离测试目标最近的区域
优先使用HTML报告器 — 使用Azure报告器时，将HTML报告器列在Azure报告器之前

When to Use

使用场景

This skill is applicable to execute the workflow or actions described in the overview.

本工具适用于执行概述中描述的工作流或操作。