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.
- Playwright Test est unframework de test intégré, sans dépendances supplémentaires.
- Le fichier de configuration peut définirle timeout, les tentatives, les rapports, les projets de navigateur, etc.
- Les cas de test prennent en chargele regroupement, les hooks, le pilotage par les données。
- 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 charge
expectassertions. - Isolation des tests: chacun
tests'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
- Utiliser
describepour organiser les tests - Utiliser
beforeEach/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.
- Playwright Test est unframework de test intégré, aucune dépendance supplémentaire n'est nécessaire.
- Le fichier de configuration peut définirle timeout, les tentatives, les rapports, les projets de navigateur, etc.
- Les cas de test prennent en chargele regroupement, les hooks, le pilotage par les données。
- 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
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
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
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
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
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
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 |
Autres extensionsConsultez la documentation officielle pour connaître toutes les options CLI et Reporter.(Playwright)