Azure Playwright Workspaces SDK pour TypeScript

Exécutez des tests Playwright à l'échelle avec des navigateurs hébergés dans le cloud et des rapports intégrés au portail Azure.

Avis de migration : @azure/microsoft-playwright-testing est retiré le 8 mars 2026. Utilisez @azure/playwright à la place. Consultez le guide de migration.

Installation

# Recommandé : Génère automatiquement la config
npm init @azure/playwright@latest

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

Prérequis :

• Playwright version 1.47+ (utilisation basique)
• Playwright version 1.57+ (fonctionnalités du rapporteur Azure)

Variables d'environnement

PLAYWRIGHT_SERVICE_URL=wss://eastus.api.playwright.microsoft.com/playwrightworkspaces/{workspace-id}/browsers
AZURE_TOKEN_CREDENTIALS=prod # Requis uniquement si DefaultAzureCredential est utilisé en production

Authentification

Credential Token Microsoft Entra (Recommandé)

# Se connecter avec Azure CLI
az login

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

// Dev local : DefaultAzureCredential. Production : définissez AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<specific_credential>
const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]});
// Ou utilisez une credential spécifique directement en production :
// Voir https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
// const credential = new ManagedIdentityCredential();

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

Credential personnalisée

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

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

Flux de travail principal

Configuration du service

// 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({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]}),
  })
);

Exécuter les tests

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

Avec le rapporteur Azure

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({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]}),
  }),
  {
    reporter: [
      ["html", { open: "never" }],
      ["@azure/playwright/reporter"],
    ],
  }
);

Connexion manuelle au navigateur

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

Options de configuration

type PlaywrightServiceAdditionalOptions = {
  serviceAuthType?: "ENTRA_ID" | "ACCESS_TOKEN";  // Par défaut : ENTRA_ID
  os?: "linux" | "windows";                        // Par défaut : linux
  runName?: string;                                // Nom de run personnalisé pour le portail
  connectTimeout?: number;                         // Par défaut : 30000ms
  exposeNetwork?: string;                          // Par défaut : <loopback>
  credential?: TokenCredential;                    // REQUIS pour Entra ID
};

Énumération ServiceOS

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

// Valeurs disponibles
ServiceOS.LINUX   // "linux" - par défaut
ServiceOS.WINDOWS // "windows"

Énumération ServiceAuth

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

// Valeurs disponibles
ServiceAuth.ENTRA_ID      // Recommandé - utilise credential
ServiceAuth.ACCESS_TOKEN  // Utilise la variable d'environnement PLAYWRIGHT_SERVICE_ACCESS_TOKEN

Intégration CI/CD

GitHub Actions

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

Azure Pipelines

- 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

Types clés

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

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

Migration depuis l'ancien package

Avant (Ancien)

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

Après (Nouveau)

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({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]}),
  }),
  {
    reporter: [
      ["html", { open: "never" }],
      ["@azure/playwright/reporter"],
    ],
  }
);

Bonnes pratiques

1. Utilisez Microsoft Entra Token Credential — Plus sécurisé que les tokens d'accès
2. Utilisez DefaultAzureCredential pour le développement local ; utilisez ManagedIdentityCredential ou WorkloadIdentityCredential pour la production
3. Activez les artefacts — Définissez trace: "on-first-retry", video: "retain-on-failure" dans la config
4. Augmentez les workers — Utilisez --workers=20 ou plus pour l'exécution parallèle
5. Sélection de région — Choisissez la région la plus proche de vos cibles de test
6. Rapporteur HTML en premier — Lors de l'utilisation du rapporteur Azure, listez le rapporteur HTML avant le rapporteur Azure