Playwright Test

En plus d'être un outil d'automatisation de navigateur, Playwright est également fourni avec unframework de test complet —— Playwright Test。

Playwright Test nous aide à organiser les cas de test, générer des rapports, exécuter en parallèle, réessayer en cas d'échec, et offre toutes les fonctionnalités dès l'installation.

  1. Playwright Test est unframework de test intégré, sans dépendances supplémentaires.
  2. Le fichier de configuration peut définirle timeout, les tentatives, les rapports, les projets de navigateur, etc.
  3. Les cas de test prennent en chargele regroupement, les hooks, le pilotage par les données。
  4. et offrentl'exécution parallèle, les rapports HTML, les réessais en cas d'échecet d'autres capacités avancées.

Aperçu du framework de test

  • Framework de test intégré: fourni avec un exécuteur de tests intégré, pas besoin d'installer Jest ou Mocha séparément.
  • Bibliothèque d'assertions intégrée: prend en chargeexpectassertions.
  • Isolation des tests: chacuntests'exécute dans un nouveau contexte de navigateur par défaut, indépendamment les uns des autres.
  • Fonctionnalités riches: exécution parallèle, réessais, captures d'écran, enregistrement, rapports HTML, etc.

Méthode d'installation :

npm init playwright@latest

Générer automatiquement la structure du projet, y compris le fichier de configurationplaywright.config.js。

1. Détails du fichier de configuration

Playwright Test utiliseplaywright.config.js(ou.ts) comme point d'entrée de configuration.

// playwright.config.js
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',         // 测试目录
  timeout: 30 * 1000,         // 单个测试超时时间
  retries: 2,                 // 失败重试次数
  reporter: [['html'], ['list']], // 测试报告类型
  use: {
    headless: true,           // 是否无头模式
    screenshot: 'only-on-failure', // 失败时截图
    video: 'retain-on-failure',    // 失败时保留视频
    baseURL: 'https://example.com', // 基础 URL
  },
  projects: [
    { name: 'Chromium', use: { browserName: 'chromium' } },
    { name: 'Firefox',  use: { browserName: 'firefox' } },
    { name: 'WebKit',   use: { browserName: 'webkit' } },
  ],
});

2. Structure du script de test

Les scripts Playwright Test incluent généralement :

1. Importer la bibliothèque de test

  import { test, expect } from '@playwright/test';

2. Écrire des cas de test

test('示例测试', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle('Example Domain');
});

3. Regroupement et hooks

  • Utiliserdescribepour organiser les tests
  • UtiliserbeforeEach / afterEachpour la mise en place et le démontage

Écriture de cas de test

1. test()Utilisation des fonctions

test('页面标题验证', async ({ page }) => {
  await page.goto('https://playwright.dev');
  await expect(page).toHaveTitle(/Playwright/);
});

2. describe()Regroupement

test.describe('用户登录模块', () => {
  test('输入正确账号密码', async ({ page }) => {
    // 登录逻辑...
  });

  test('输入错误密码', async ({ page }) => {
    // 验证错误提示...
  });
});

3. Hooks de test

test.describe('购物车模块', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('https://example.com/cart');
  });

  test.afterEach(async ({ page }) => {
    await page.screenshot({ path: 'cart.png' });
  });

  test('添加商品', async ({ page }) => {
    await page.click('#add-item');
    await expect(page.locator('#cart-count')).toHaveText('1');
  });
});

4. Préparation des données de test

Prend en charge les tests paramétrés :

const users = [
  { name: 'admin', password: '123456' },
  { name: 'guest', password: 'guest' },
];

for (const user of users) {
  test(`用户 ${user.name} 登录`, async ({ page }) => {
    await page.goto('https://example.com/login');
    await page.fill('#username', user.name);
    await page.fill('#password', user.password);
    await page.click('#submit');
    await expect(page.locator('.welcome')).toBeVisible();
  });
}

Exécution et rapports

1. Commandes d'exécution des tests

npx playwright test          # 运行全部测试
npx playwright test login.spec.js   # 运行单个文件
npx playwright test -g "登录"       # 运行指定用例

2. Tests en parallèle

Playwright par défautexécute les fichiers en parallèle, ou vous pouvez spécifier le nombre de workers dans le fichier de configuration :

npx playwright test --workers=4

3. Génération de rapports de test

Après l'exécution, générezun rapport HTML:

npx playwright show-report

4. Mécanisme de nouvelle tentative en cas d'échec

Dans le fichier de configurationplaywright.config.jsdéfinir :

retries: 2

Lorsqu'un test échoue, il est automatiquement réessayé, ce qui convient pour gérer les erreurs intermittentes.

  1. Playwright Test est unframework de test intégré, aucune dépendance supplémentaire n'est nécessaire.
  2. Le fichier de configuration peut définirle timeout, les tentatives, les rapports, les projets de navigateur, etc.
  3. Les cas de test prennent en chargele regroupement, les hooks, le pilotage par les données。
  4. et offrentl'exécution parallèle, les rapports HTML, les réessais en cas d'échecet d'autres capacités avancées.

Exemple complet de suite de tests

1. Structure du projet

playwright-demo/
├─ playwright.config.ts           # 全局配置(多项目、多浏览器、报告、重试…)
├─ package.json
├─ tests/
│  ├─ auth.setup.ts               # 一次性登录,生成 storageState
│  ├─ smoke/
│  │  └─ home.spec.ts             # 冒烟用例:标题/URL/截图对比
│  └─ e2e/
│     └─ cart.spec.ts             # 端到端:添加购物车、断言、附件、步骤
├─ fixtures/
│  ├─ pages.ts                    # 页面对象(PO)
│  └─ test.extend.ts              # 自定义 fixtures
└─ snapshots/                     # 视觉基线(自动生成)

2. Fichier de configuration (playwright.config.ts)

Exemple

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  timeout: 30_000,
  retries: 2,
  workers: 4,
  reporter: [['html', { outputFolder: 'report' }], ['list']],
  forbidOnly: !!process.env.CI,

  // Utilisation par défaut unifiée (peut être surchargée au niveau du projet ou du test)
  use: {
    baseURL: 'https://demo.playwright.dev',
    headless: true,
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    trace: 'retain-on-failure',
    viewport: { width: 1366, height: 900 },
    locale: 'zh-CN',
  },

  // Plusieurs projets : différents navigateurs/appareils/états de connexion
  projects: [
    { name: 'Chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'Firefox',  use: { ...devices['Desktop Firefox'] } },
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 7'], headless: vrai },
    },
    // Projet avec état de connexion (réutiliser storageState)
    {
      name: 'Chromium Logged-in',
      use: { storageState: 'storageState.json' },
      dependencies: ['setup'], // Dépend d'un projet de configuration pour générer l'état de connexion
    },
    // Projet de configuration : s'exécute une fois pour générer storageState
    {
      name: 'setup',
      testMatch: /auth\.setup\.ts/,
    },
  ],
});

Points clés :les projets permettent à la même suite de tests de s'exécuter dans différents navigateurs/configurations ; use peut être surchargé au niveau global/projet/test ; les rapports et les tentatives sont gérés de manière centralisée dans la configuration.

3. Fixtures et Page Objects

fixtures/test.extend.ts (fixtures personnalisées + encapsulation des étapes communes)

Exemple

// fixtures/test.extend.ts
import { test as base } from '@playwright/test';
import { HomePage, CartPage } from './pages';

type MyFixtures = {
  home: HomePage;
  cart: CartPage;
};

export const test = base.extend<MyFixtures>({
  home: async ({ page }, use) => {
    const home = new HomePage(page);
    await use(home);
  },
  cart: async ({ page }, use) => {
    const cart = new CartPage(page);
    await use(cart);
  },
});

export { expect } from '@playwright/test';

Ajoutez des fixtures personnalisées basées sur test.extend(), ce qui facilite l'injection directe des instances home et cart dans n'importe quel cas de test.

fixtures/pages.ts (objets de page)

Exemple

// fixtures/pages.ts
import { Page, expect } from '@playwright/test';

export class HomePage {
  constructor(private page: Page) {}
  async goto() { await this.page.goto('/'); }
  get tryTodoLink() { return this.page.getByRole('link', { name: /ToDo MVC/i }); }
}

export class CartPage {
  constructor(private page: Page) {}
  async goto() { await this.page.goto('/e2e'); } // En supposant qu'une page d'exemple e2e existe
  get addFirstItem() { return this.page.getByRole('button', { name: /Add .* #1/i }); }
  get cartCount() { return this.page.locator('[data-test=cart-count]'); }
  async addOne() { await this.addFirstItem.click(); }
  async expectCount(n: number) { await expect(this.cartCount).toHaveText(String(n)); }
}

4. Pré-connexion (Générer storageState une fois)

tests/auth.setup.ts (s'exécute uniquement dans le projet "setup")

Exemple

// tests/auth.setup.ts
import { test, expect } from '@playwright/test';

test('créer storageState', async ({ page }) => {
  await page.goto('https://demo.playwright.dev/todomvc');
  // ...Remplacez par votre flux de connexion...
  // On suppose que la connexion réussit
  await expect(page).toHaveURL(/todomvc/);
  await page.context().storageState({ path: 'storageState.json' });
});

5. Tests de fumée (Titre/URL/Comparaison visuelle)

tests/smoke/home.spec.ts

Exemple

import { test, expect } from '@playwright/test';

test.describe('Fumée - Accueil', () => {
  test('titre & URL & capture visuelle', async ({ page }) => {
    await page.goto('https://playwright.dev');
    await expect(page).toHaveTitle(/Playwright/);
    await expect(page).toHaveURL(/playwright\.dev/);

    // Régression visuelle (génération automatique/comparaison de la référence)
    await expect(page).toHaveScreenshot(); // La première exécution génère une référence
  });
});

Pour la comparaison visuelle, il est recommandé d'utiliser toHaveScreenshot (préféré à l'approche manuelle utilisant page.screenshot() + toMatchSnapshot).

6. Tests de bout en bout (Étapes, Pièces jointes, Assertions)

tests/e2e/cart.spec.ts

Exemple

import { test, expect } from '../../fixtures/test.extend';

test.describe.configure({ mode: 'parallel' });

test.describe('E2E - Panier', () => {
  test.beforeEach(async ({ home }) => {
    await test.step('Aller à la page d'accueil', async () => {
      await home.goto();
    });
  });

  test('Ajouter un produit au panier (avec pièce jointe et assertion)', async ({ page, cart }) => {
    await test.step('Aller à la page du panier et ajouter le produit', async () => {
      await cart.goto();
      await cart.addOne();
      await cart.expectCount(1);
    });

    await test.step('Joindre les informations de débogage au rapport', async () => {
      await test.info().attach('state.json', {
        contentType: 'application/json',
        body: Buffer.from(JSON.stringify({ ts: Date.now(), note: 'après ajout' })),
      });
    });

    // Capture d'écran au niveau de l'élément
    await test.step('Capture d'écran de l'élément', async () => {
      const badge = page.locator('[data-test=cart-count]');
      await expect(badge).toBeVisible();
      await expect(badge).toHaveScreenshot(); // Instantané de l'élément
    });
  });
});

Utilisez test.step pour enregistrer les étapes de manière hiérarchique, et utilisez test.info().attach() pour joindre des données de débogage/captures d'écran au rapport afin de faciliter le dépannage ; le mode parallèle peut utiliser describe.configure({ mode: 'parallel' }).

7. Exécution et rapports

Commandes courantes :

npx playwright test                # 运行全部
npx playwright test tests/e2e      # 运行目录
npx playwright test -g "Cart"      # 按标题过滤
npx playwright test --project="Chromium"   # 指定项目
npx playwright show-report         # 打开HTML报告
npx playwright test --update-snapshots     # 更新视觉基线
npx playwright test --debug        # 调试模式(Inspector)

Pour le filtrage CLI, la sélection de projet, la consultation des rapports, la mise à jour des instantanés, etc., consultez la documentation officielle CLI/Reporting/Snapshot.


Référence rapide des API associées courantes (Playwright Test)

1. Tests et regroupement

API Objectif
test(name, fn) Définir des tests
test.describe(title, fn) Regroupement
test.describe.configure({ mode }) parallel / serial
test.beforeAll/afterAll Hooks before/after au niveau du groupe
test.beforeEach/afterEach Hooks before/after de cas de test
test.skip/only/fixme/slow/fail Marquer/contrôler les cas de test

2. Fixtures et configuration

API Objectif
test.extend<Fixtures>(defs) Étendre les fixtures personnalisées
test.use(options) Remplacement au niveau du testuseOptions (telles questorageState、viewport、localeetc.)
defineConfig({...}) Entrée du fichier de configuration (testDir、retries、workers、reporter…)
projects exécution multi-projet/multi-navigateur/configurations différentes
use: { baseURL, trace, video, screenshot, viewport, locale, timezoneId, storageState } Environnement d'exécution et stratégie de capture

Pour plus de détails sur les fixtures / l'utilisation / les options de configuration et les projets, consultez la documentation officielle « Fixtures / Options d'utilisation / Configuration / Projets ». (Playwright)

3. Assertions (expect)

API Objectif
expect(value).toBe / toEqual / toContain ... Assertions générales
expect(locator).toHaveText/Value/Attribute Assertions spécifiques au Web (avec attente intelligente)
expect(locator).toBeVisible/Hidden/Enabled/Disabled/Checked Assertions d'état
expect(page).toHaveTitle/URL Assertions de page
`expect(page/locator).toHaveScreenshot([name options])` Comparaison visuelle d'instantanés (recommandé)

Pour les pratiques recommandées sur les assertions et les captures visuelles, consultez la documentation Assertions and Snapshots.(Playwright)

4. Étapes et pièces jointes

API Objectif
test.step(name, fn) Décomposer les tests en étapes (visualisation du rapport)
`test.info().attach(name, { path body, contentType })` Joindre des fichiers/données aux tests ou aux étapes (affichés dans le rapport)

Les pièces jointes peuvent également être appliquées au niveau de l'étape (voir TestStep / TestStepInfo).(Playwright)

5. Rapports et CLI

Commande/Configuration Objectif
reporter: [['html', { outputFolder }], ['list']] Configuration du rapport
npx playwright test --project="Chromium" Sélectionner le projet à exécuter
-g "keyword" / --grep / --grep-invert Filtrer les cas de test
--update-snapshots Mettre à jour les références visuelles
npx playwright show-report Ouvrir le rapport

Consultez la documentation officielle pour connaître toutes les options CLI et Reporter.(Playwright)

Autres extensions