Azure Microsoft Playwright Testing Ts

1---
2name: azure-microsoft-playwright-testing-ts
3description: Run Playwright tests at scale using Azure Playwright Workspaces (formerly Microsoft Playwright Testing). Use when scaling browser tests across cloud-hosted browsers, integrating with CI/CD pipelines, or publishing test results to the Azure portal.
4package: "@azure/playwright"
5---
6 
7# Azure Playwright Workspaces SDK for TypeScript
8 
9Run Playwright tests at scale with cloud-hosted browsers and integrated Azure portal reporting.
10 
11> **Migration Notice:** `@azure/microsoft-playwright-testing` is retired on **March 8, 2026**. Use `@azure/playwright` instead. See [migration guide](https://aka.ms/mpt/migration-guidance).
12 
13## Installation
14 
15```bash
16# Recommended: Auto-generates config
17npm init @azure/playwright@latest
18 
19# Manual installation
20npm install @azure/playwright --save-dev
21npm install @playwright/test@^1.47 --save-dev
22npm install @azure/identity --save-dev
23```
24 
25**Requirements:**
26- Playwright version 1.47+ (basic usage)
27- Playwright version 1.57+ (Azure reporter features)
28 
29## Environment Variables
30 
31```bash
32PLAYWRIGHT_SERVICE_URL=wss://eastus.api.playwright.microsoft.com/playwrightworkspaces/{workspace-id}/browsers
33```
34 
35## Authentication
36 
37### Microsoft Entra ID (Recommended)
38 
39```bash
40# Sign in with Azure CLI
41az login
42```
43 
44```typescript
45// playwright.service.config.ts
46import { defineConfig } from "@playwright/test";
47import { createAzurePlaywrightConfig, ServiceOS } from "@azure/playwright";
48import { DefaultAzureCredential } from "@azure/identity";
49import config from "./playwright.config";
50 
51export default defineConfig(
52  config,
53  createAzurePlaywrightConfig(config, {
54    os: ServiceOS.LINUX,
55    credential: new DefaultAzureCredential(),
56  })
57);
58```
59 
60### Custom Credential
61 
62```typescript
63import { ManagedIdentityCredential } from "@azure/identity";
64import { createAzurePlaywrightConfig } from "@azure/playwright";
65 
66export default defineConfig(
67  config,
68  createAzurePlaywrightConfig(config, {
69    credential: new ManagedIdentityCredential(),
70  })
71);
72```
73 
74## Core Workflow
75 
76### Service Configuration
77 
78```typescript
79// playwright.service.config.ts
80import { defineConfig } from "@playwright/test";
81import { createAzurePlaywrightConfig, ServiceOS } from "@azure/playwright";
82import { DefaultAzureCredential } from "@azure/identity";
83import config from "./playwright.config";
84 
85export default defineConfig(
86  config,
87  createAzurePlaywrightConfig(config, {
88    os: ServiceOS.LINUX,
89    connectTimeout: 30000,
90    exposeNetwork: "<loopback>",
91    credential: new DefaultAzureCredential(),
92  })
93);
94```
95 
96### Run Tests
97 
98```bash
99npx playwright test --config=playwright.service.config.ts --workers=20
100```
101 
102### With Azure Reporter
103 
104```typescript
105import { defineConfig } from "@playwright/test";
106import { createAzurePlaywrightConfig, ServiceOS } from "@azure/playwright";
107import { DefaultAzureCredential } from "@azure/identity";
108import config from "./playwright.config";
109 
110export default defineConfig(
111  config,
112  createAzurePlaywrightConfig(config, {
113    os: ServiceOS.LINUX,
114    credential: new DefaultAzureCredential(),
115  }),
116  {
117    reporter: [
118      ["html", { open: "never" }],
119      ["@azure/playwright/reporter"],
120    ],
121  }
122);
123```
124 
125### Manual Browser Connection
126 
127```typescript
128import playwright, { test, expect, BrowserType } from "@playwright/test";
129import { getConnectOptions } from "@azure/playwright";
130 
131test("manual connection", async ({ browserName }) => {
132  const { wsEndpoint, options } = await getConnectOptions();
133  const browser = await (playwright[browserName] as BrowserType).connect(wsEndpoint, options);
134  const context = await browser.newContext();
135  const page = await context.newPage();
136 
137  await page.goto("https://example.com");
138  await expect(page).toHaveTitle(/Example/);
139 
140  await browser.close();
141});
142```
143 
144## Configuration Options
145 
146```typescript
147type PlaywrightServiceAdditionalOptions = {
148  serviceAuthType?: "ENTRA_ID" | "ACCESS_TOKEN";  // Default: ENTRA_ID
149  os?: "linux" | "windows";                        // Default: linux
150  runName?: string;                                // Custom run name for portal
151  connectTimeout?: number;                         // Default: 30000ms
152  exposeNetwork?: string;                          // Default: <loopback>
153  credential?: TokenCredential;                    // REQUIRED for Entra ID
154};
155```
156 
157### ServiceOS Enum
158 
159```typescript
160import { ServiceOS } from "@azure/playwright";
161 
162// Available values
163ServiceOS.LINUX   // "linux" - default
164ServiceOS.WINDOWS // "windows"
165```
166 
167### ServiceAuth Enum
168 
169```typescript
170import { ServiceAuth } from "@azure/playwright";
171 
172// Available values
173ServiceAuth.ENTRA_ID      // Recommended - uses credential
174ServiceAuth.ACCESS_TOKEN  // Use PLAYWRIGHT_SERVICE_ACCESS_TOKEN env var
175```
176 
177## CI/CD Integration
178 
179### GitHub Actions
180 
181```yaml
182name: playwright-ts
183on: [push, pull_request]
184 
185permissions:
186  id-token: write
187  contents: read
188 
189jobs:
190  test:
191    runs-on: ubuntu-latest
192    steps:
193      - uses: actions/checkout@v4
194 
195      - name: Azure Login
196        uses: azure/login@v2
197        with:
198          client-id: ${{ secrets.AZURE_CLIENT_ID }}
199          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
200          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
201 
202      - run: npm ci
203      
204      - name: Run Tests
205        env:
206          PLAYWRIGHT_SERVICE_URL: ${{ secrets.PLAYWRIGHT_SERVICE_URL }}
207        run: npx playwright test -c playwright.service.config.ts --workers=20
208```
209 
210### Azure Pipelines
211 
212```yaml
213- task: AzureCLI@2
214  displayName: Run Playwright Tests
215  env:
216    PLAYWRIGHT_SERVICE_URL: $(PLAYWRIGHT_SERVICE_URL)
217  inputs:
218    azureSubscription: My_Service_Connection
219    scriptType: pscore
220    inlineScript: |
221      npx playwright test -c playwright.service.config.ts --workers=20
222    addSpnToEnvironment: true
223```
224 
225## Key Types
226 
227```typescript
228import {
229  createAzurePlaywrightConfig,
230  getConnectOptions,
231  ServiceOS,
232  ServiceAuth,
233  ServiceEnvironmentVariable,
234} from "@azure/playwright";
235 
236import type {
237  OsType,
238  AuthenticationType,
239  BrowserConnectOptions,
240  PlaywrightServiceAdditionalOptions,
241} from "@azure/playwright";
242```
243 
244## Migration from Old Package
245 
246| Old (`@azure/microsoft-playwright-testing`) | New (`@azure/playwright`) |
247|---------------------------------------------|---------------------------|
248| `getServiceConfig()` | `createAzurePlaywrightConfig()` |
249| `timeout` option | `connectTimeout` option |
250| `runId` option | `runName` option |
251| `useCloudHostedBrowsers` option | Removed (always enabled) |
252| `@azure/microsoft-playwright-testing/reporter` | `@azure/playwright/reporter` |
253| Implicit credential | Explicit `credential` parameter |
254 
255### Before (Old)
256 
257```typescript
258import { getServiceConfig, ServiceOS } from "@azure/microsoft-playwright-testing";
259 
260export default defineConfig(
261  config,
262  getServiceConfig(config, {
263    os: ServiceOS.LINUX,
264    timeout: 30000,
265    useCloudHostedBrowsers: true,
266  }),
267  {
268    reporter: [["@azure/microsoft-playwright-testing/reporter"]],
269  }
270);
271```
272 
273### After (New)
274 
275```typescript
276import { createAzurePlaywrightConfig, ServiceOS } from "@azure/playwright";
277import { DefaultAzureCredential } from "@azure/identity";
278 
279export default defineConfig(
280  config,
281  createAzurePlaywrightConfig(config, {
282    os: ServiceOS.LINUX,
283    connectTimeout: 30000,
284    credential: new DefaultAzureCredential(),
285  }),
286  {
287    reporter: [
288      ["html", { open: "never" }],
289      ["@azure/playwright/reporter"],
290    ],
291  }
292);
293```
294 
295## Best Practices
296 
2971. **Use Entra ID auth** — More secure than access tokens
2982. **Provide explicit credential** — Always pass `credential: new DefaultAzureCredential()`
2993. **Enable artifacts** — Set `trace: "on-first-retry"`, `video: "retain-on-failure"` in config
3004. **Scale workers** — Use `--workers=20` or higher for parallel execution
3015. **Region selection** — Choose region closest to your test targets
3026. **HTML reporter first** — When using Azure reporter, list HTML reporter before Azure reporter
303