Bài 58: teardown: 'cleanup' — Project Chạy Cuối

Sau khi hoàn thành bài này, bạn sẽ:

• Khai báo teardown project trong playwright.config.ts đúng cú pháp.
• Viết teardown file với import test as teardown và nhiều cleanup action.
• Nắm rõ khi nào teardown chạy, khi nào bị skip.
• Phân biệt teardown project với afterAll hook và globalTeardown legacy.
• Áp dụng idempotent cleanup để teardown fail không làm hỏng CI exit code.

Field teardown trong object project nhận tên của một project khác. Project được chỉ định đó sẽ chạy sau khi project khai báo nó kết thúc — bất kể kết quả pass hay fail.

Teardown project là một project Playwright bình thường — nó có testMatch để scope file, có thể có use options, và được hiển thị trong HTML reporter với kết quả riêng. Sự khác biệt duy nhất là cách Playwright lên lịch chạy nó: không phải do user gọi trực tiếp, mà do lifecycle của project khác trigger.

Ví dụ thực tế: project main chạy toàn bộ test E2E, tạo ra test data trong DB và file upload trên server. Sau khi main xong, Playwright tự động chạy project cleanup để xoá toàn bộ dữ liệu đó — không cần script wrapper bên ngoài.

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

export default defineConfig({
  projects: [
    // Project teardown — khai báo trước để dễ đọc config
    {
      name: 'cleanup',
      testMatch: /cleanup\.teardown\.ts/,
    },

    // Project chính — chỉ định teardown bằng tên project cleanup
    {
      name: 'main',
      teardown: 'cleanup',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

Một số điểm cần lưu ý về cú pháp:

• Thứ tự khai báo trong array không quan trọng: Playwright resolve lifecycle theo teardown field, không phải thứ tự array. Khai báo cleanup trước hay sau main đều hoạt động như nhau.
• Giá trị của teardown phải khớp chính xác tên project: là exact match, không phải glob. Viết sai tên sẽ bị Playwright báo lỗi khi validate config.
• Teardown project nên có testMatch: để tách biệt file teardown khỏi các test thông thường. Convention phổ biến là dùng đuôi .teardown.ts.

File teardown dùng cú pháp test Playwright bình thường, nhưng import alias test as teardown để phân biệt với test spec thông thường trong cùng codebase:

// cleanup.teardown.ts
import { test as teardown } from '@playwright/test';
import { rm } from 'fs/promises';

// Xoá thư mục upload sau test
teardown('delete uploaded files', async () => {
  await rm('uploads/', { recursive: true, force: true });
});

// Gọi API cleanup để xoá test data trong DB
teardown('truncate test data', async ({ request }) => {
  await request.post('/api/test/cleanup');
});

// Nhiều teardown action trong 1 file — chạy tuần tự theo thứ tự khai báo
teardown('clear redis cache', async ({ request }) => {
  await request.post('/api/test/cache/flush');
});

Alias teardown không bắt buộc về mặt kỹ thuật — dùng tên test thông thường cũng chạy được. Nhưng alias giúp đồng nghiệp đọc code nhận ra ngay đây là teardown logic, không phải test case thật.

Teardown file có đầy đủ fixture access — bao gồm request (APIRequestContext), page, và custom fixture. Không cần viết logic network thủ công.

Flow cơ bản khi config có 1 main project và 1 teardown project:

1. Playwright chạy toàn bộ test trong project main.
2. Khi main kết thúc (dù pass hay fail), Playwright tự động lên lịch chạy project cleanup.
3. Project cleanup chạy trong separate process — không chia sẻ state hay worker với main.
4. Kết quả của cleanup được ghi nhận độc lập trong reporter.

Quan trọng — teardown và trường hợp setup fail: Behavior này phụ thuộc vào kết hợp dependencies + teardown. Khi không có setup dependency:

• Main pass → teardown chạy.
• Main fail (một số test fail) → teardown vẫn chạy.
• Main bị interrupt (thoát giữa chừng) → teardown vẫn được trigger nếu Playwright còn control flow.

Khi kết hợp với setup dependency (xem mục 9): nếu setup fail → main bị skip → teardown cũng bị skip theo (không có gì để cleanup vì main chưa chạy). Đây là behavior có chủ ý — tránh cleanup state chưa từng được tạo ra.

Trường hợp SIGKILL (process bị kill cứng, ví dụ CI timeout giết process): teardown không được trigger. Chỉ SIGTERM (graceful shutdown) mới đảm bảo teardown chạy.

afterAll và teardown project không loại trừ nhau — có thể dùng cả hai cùng lúc. afterAll cleanup local state trong từng file, còn teardown project cleanup global state sau toàn run.

Playwright khuyến nghị ưu tiên teardown project hơn globalTeardown cho các use case mới. globalTeardown vẫn được support nhưng ít flexible hơn — không thể dùng fixture và không hiển thị trong report.

Mỗi project chỉ có thể trỏ đến 1 teardown project. Khi có nhiều main project cần cleanup riêng, khai báo teardown project riêng cho từng cái:

// playwright.config.ts
export default defineConfig({
  projects: [
    // Teardown projects
    {
      name: 'cleanup-A',
      testMatch: /cleanup-a\.teardown\.ts/,
    },
    {
      name: 'cleanup-B',
      testMatch: /cleanup-b\.teardown\.ts/,
    },

    // Main projects
    {
      name: 'project-A',
      teardown: 'cleanup-A',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'project-B',
      teardown: 'cleanup-B',
      use: { ...devices['Desktop Firefox'] },
    },
  ],
});

Trong ví dụ này:

• project-A và project-B chạy song song (không có dependency).
• Khi project-A xong → cleanup-A được trigger.
• Khi project-B xong → cleanup-B được trigger.
• cleanup-A và cleanup-B có thể chạy đồng thời nếu worker pool còn slot.

Nếu nhiều main project cần cùng cleanup logic, cách đơn giản nhất là trỏ cả hai về cùng một teardown project:

projects: [
  { name: 'cleanup', testMatch: /global\.teardown\.ts/ },

  { name: 'project-A', teardown: 'cleanup', use: { ...devices['Desktop Chrome'] } },
  { name: 'project-B', teardown: 'cleanup', use: { ...devices['Desktop Firefox'] } },
],

Khi cả project-A và project-B đều cần cleanup, Playwright chạy cleanup một lần sau khi cả hai kết thúc — không chạy hai lần riêng biệt. Đây là behavior quan trọng cần nhớ để tránh tình huống cleanup chạy nhiều lần không mong muốn.

Kết hợp dependencies và teardown để có vòng đời đầy đủ: setup → test → cleanup. Đây là pattern chuẩn cho test suite cần chuẩn bị và dọn dẹp state:

// playwright.config.ts
export default defineConfig({
  projects: [
    // Phase 0 — setup
    {
      name: 'setup',
      testMatch: /.*\.setup\.ts/,
    },

    // Phase 2 — cleanup (khai báo để main có thể tham chiếu)
    {
      name: 'cleanup',
      testMatch: /.*\.teardown\.ts/,
    },

    // Phase 1 — main test
    {
      name: 'main',
      dependencies: ['setup'], // chờ setup xong mới chạy
      teardown: 'cleanup',     // sau khi xong thì chạy cleanup
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

Thứ tự thực thi đảm bảo: setup → main → cleanup.

Behavior chi tiết theo từng kịch bản:

Behavior "setup fail → cleanup skip" là có chủ ý: nếu setup chưa tạo ra bất kỳ state nào (vì fail sớm), chạy cleanup là vô nghĩa và có thể gây lỗi (cleanup thứ không tồn tại).

Delete test data

Test E2E thường tạo user, order, product trong DB. Sau khi chạy xong, cleanup xoá tất cả bản ghi có prefix test:

teardown('delete test users', async ({ request }) => {
  await request.delete('/api/test/users?prefix=test_');
});

teardown('delete test orders', async ({ request }) => {
  await request.delete('/api/test/orders?created_by=test_runner');
});

Reset DB schema

Với test database riêng, có thể truncate hoặc drop-recreate toàn bộ schema:

teardown('truncate test db', async ({ request }) => {
  // Endpoint này chỉ tồn tại ở test environment
  await request.post('/api/test/db/truncate', {
    data: { tables: ['users', 'orders', 'uploads'] },
  });
});

Delete uploaded files

Test upload file tạo file rác trên disk hoặc S3:

import { test as teardown } from '@playwright/test';
import { rm } from 'fs/promises';

teardown('delete local uploads', async () => {
  // Xoá thư mục upload local của test server
  await rm('test-server/uploads/', { recursive: true, force: true });
});

teardown('clear S3 test bucket', async ({ request }) => {
  await request.post('/api/test/s3/clear', {
    data: { bucket: 'my-app-test-uploads' },
  });
});

Send notification

Gửi kết quả test lên Slack hoặc Telegram sau khi run xong:

teardown('notify slack', async ({ request }) => {
  const status = process.env.TEST_STATUS ?? 'unknown';
  await request.post(process.env.SLACK_WEBHOOK!, {
    data: {
      text: `E2E run completed: ${status}`,
    },
  });
});

Generate aggregated report

Gọi script tổng hợp metrics từ nhiều nguồn sau khi test xong:

import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

teardown('aggregate metrics', async () => {
  await execAsync('node scripts/aggregate-test-metrics.js');
});

Cleanup logic nên idempotent — chạy nhiều lần không gây hại, và nếu fail thì không ảnh hưởng CI exit code. Vấn đề xảy ra khi cleanup bị lỗi mà main test đã pass: CI sẽ báo fail vì teardown project fail, dù business logic đã OK.

Pattern phổ biến: wrap cleanup trong try/catch và log warning thay vì rethrow:

import { test as teardown } from '@playwright/test';

teardown('cleanup test data', async ({ request }) => {
  try {
    await request.delete('/api/test/data');
  } catch (err) {
    // Log nhưng không throw — cleanup fail không block CI
    console.warn('Cleanup failed (non-fatal):', err);
  }
});

teardown('clear uploads', async () => {
  try {
    const { rm } = await import('fs/promises');
    await rm('uploads/', { recursive: true, force: true });
  } catch (err) {
    console.warn('Upload cleanup failed:', err);
  }
});

Hai trường hợp cần cân nhắc:

• Cleanup không quan trọng (ví dụ: xoá file log tạm): luôn dùng try/catch, không throw.
• Cleanup quan trọng (ví dụ: xoá test user để tránh ảnh hưởng production): để throw, nhưng cần có monitoring riêng để alert khi cleanup fail.

Dùng force: true trong Node.js rm() để không throw khi path không tồn tại — tránh lỗi "file not found" trên các run lần đầu:

// Không throw kể cả khi thư mục chưa tồn tại
await rm('uploads/', { recursive: true, force: true });

• 1 teardown per project: mỗi project chỉ có thể khai báo 1 teardown. Nếu cần nhiều nhóm cleanup logic riêng biệt, gộp tất cả vào 1 teardown file với nhiều teardown() call — không thể point đến nhiều teardown project cùng lúc.
• Teardown không nhận kết quả của main: teardown chạy trong separate process và không có access thông tin pass/fail count của main project. Cleanup là "blind" — không biết bao nhiêu test đã fail hay fail ở đâu. Nếu cần conditional cleanup dựa trên kết quả, phải dùng custom reporter để ghi kết quả ra file rồi teardown đọc lại.
• SIGKILL bỏ qua teardown: CI timeout dùng SIGKILL (không phải SIGTERM) sẽ kill process ngay lập tức mà không trigger teardown. Nếu cleanup quan trọng, cần đảm bảo CI dùng SIGTERM với grace period đủ dài.
• Teardown bị skip khi dùng --no-deps: flag --no-deps (bỏ qua dependencies) cũng bỏ qua teardown. Cần lưu ý khi debug local.

Pitfall 1 — Teardown fail làm CI fail dù main pass

Teardown là project thật — nếu teardown throw uncaught error, CI exit code sẽ là non-zero dù toàn bộ main test đã pass. Kết quả CI fail dù business logic đúng. Cách tránh: wrap cleanup logic trong try/catch và log warning thay vì throw (xem mục 11).

Pitfall 2 — Teardown phụ thuộc vào state mà main đã clear

Ví dụ: teardown cần đọc list ID của các bản ghi đã tạo trong test để xoá đúng bản ghi đó. Nhưng bản ghi đó đã bị test trong afterEach xoá rồi. Teardown chạy sau toàn bộ afterEach — nếu state cần thiết đã bị clear trước, teardown sẽ không cleanup được gì. Giải pháp: dùng endpoint cleanup tập trung (truncate theo prefix, không cần biết ID cụ thể).

Pitfall 3 — Quên gitignore artifact của teardown

Teardown tạo ra file log, report tổng hợp, hoặc temp files. Nếu không thêm vào .gitignore, chúng sẽ bị commit vào repo qua lần commit vô tình sau khi chạy test local:

# .gitignore
test-results/
playwright-report/
uploads/           # thư mục upload test
*.teardown-report.json

Pitfall 4 — Teardown chạy chậm làm tăng CI duration đáng kể

Nếu teardown gọi nhiều API cleanup tuần tự (nhiều teardown() call chạy một sau một), thời gian tích lũy có thể lớn. Ví dụ: 10 API call × 500ms mỗi call = 5 giây thêm vào mỗi run. Với CI chạy nhiều lần mỗi ngày, con số này đáng kể. Cách tối ưu: song song hóa cleanup với Promise.all trong 1 teardown step, hoặc dùng bulk delete endpoint thay vì nhiều request lẻ.

// Chậm — tuần tự
teardown('cleanup users', async ({ request }) => {
  for (const id of userIds) {
    await request.delete(`/api/users/${id}`);
  }
});

// Nhanh hơn — song song hoặc bulk
teardown('cleanup users', async ({ request }) => {
  await request.delete('/api/test/users/bulk', {
    data: { ids: userIds },
  });
});

Câu 1. Config có project main với teardown: 'cleanup'. Nếu 3 trong 20 test của main fail, teardown có chạy không?

Câu 2. Project main có cả dependencies: ['setup'] và teardown: 'cleanup'. Nếu project setup fail, điều gì xảy ra với cleanup?

Câu 3. Sự khác biệt cốt lõi giữa teardown project và afterAll hook về visibility trong report?

Câu 4. Tại sao nên dùng try/catch trong cleanup logic thay vì để throw?

Câu 5. Có 2 main project (project-A và project-B) cùng trỏ teardown: 'cleanup'. Playwright chạy cleanup bao nhiêu lần?

Bài 59: testMatch & testIgnore Per Project — Scope File Theo Project