Wiki

← Tất cả bài wiki

Playwright Inspector & PWDEBUG (Debug từng bước với trình inspector)

automationplaywright

Playwright Inspector là cửa sổ debug chạy song song trình duyệt: step qua từng action, xem locator được resolve, đọc log auto-wait và pick locator trực tiếp trên trang. Kích hoạt bằng biến môi trường PWDEBUG=1, flag --debug, hoặc page.pause() trong code.

Khái niệm & Bản chất

  • Inspector là debug UI của Playwright: hiện dòng code đang thực thi, nút Step Over / Resume / Pick Locator, chạy song song với browser headed.
  • PWDEBUG là biến môi trường bật debug mode: test tự chạy headed, mở Inspector và pause ngay đầu test chờ bạn điều khiển.
  • Khi đang debug, Playwright tắt action timeout — bạn soi bao lâu cũng được mà không sợ test chết vì timeout.
  • Khác Chrome DevTools: Inspector soi ở tầng action của Playwright (locator, auto-wait), DevTools soi tầng DOM/network/JS của trang — hai công cụ bổ sung nhau.

Cách hoạt động & API chính

  • macOS/Linux: PWDEBUG=1 npx playwright test; Windows PowerShell: $env:PWDEBUG=1; npx playwright test; cmd: set PWDEBUG=1 && npx playwright test.
  • npx playwright test --debug tương đương PWDEBUG=1 — ngắn gọn hơn, không phụ thuộc shell.
  • await page.pause() đặt 'breakpoint' tại đúng dòng cần soi — test chạy bình thường rồi dừng ở đó mở Inspector.
  • Trong Inspector: Resume chạy tiếp, Step Over qua từng action, Pick Locator click element trên trang để lấy locator gợi ý, nút record bật codegen ngay trong phiên debug.
  • PWDEBUG=console mở REPL trong terminal thay Inspector GUI — ít dùng nhưng hữu ích khi không có màn hình đồ hoạ.

Ví dụ & Cú pháp thực tế

  • Debug đúng một test bị fail: ``bash # Chạy 1 test duy nhất ở debug mode PWDEBUG=1 npx playwright test tests/checkout.spec.ts -g 'thanh toán COD' # Tương đương, gọn hơn npx playwright test tests/checkout.spec.ts -g 'thanh toán COD' --debug # Debug trên đúng browser project bị fail npx playwright test --debug --project=webkit ``
  • Đặt pause ngay trước đoạn nghi ngờ: ``ts test('debug giỏ hàng', async ({ page }) => { await page.goto('/cart'); await page.getByRole('button', { name: 'Áp mã' }).click(); await page.pause(); // Inspector dừng ở đây — pick locator, step tiếp await page.getByPlaceholder('Mã giảm giá').fill('SALE10'); await page.getByRole('button', { name: 'Áp dụng' }).click(); }); ``
  • Workflow thực tế khi locator fail: page.pause() trước dòng lỗi → Resume đến đó → dùng Pick Locator click đúng element → copy locator → dán về test.

Best practices & Khi nào dùng

  • Test fail 'không hiểu tại sao': dùng page.pause() ngay trước dòng fail — xem locator resolve ra element nào, đôi khi element đúng selector nhưng không phải cái bạn tưởng.
  • Ưu tiên Pick Locator của Inspector thay vì tự chế CSS selector bằng DevTools — Playwright sẽ ưu tiên role/text bền hơn.
  • Luôn kết hợp -g (grep theo tên) hoặc test.only để chạy đúng 1 test — debug cả suite chỉ tổ mất thời gian step qua test lành.
  • Đọc log auto-wait trong Inspector (waiting for element to be visible/enabled/stable) — nó nói chính xác Playwright đang chờ điều gì.

Gotchas, So sánh & Lưu ý

  • page.pause() trên CI/headless là no-op (không treo pipeline), nhưng vẫn phải xoá trước khi commit — code để lại vừa bẩn vừa gây hiểu nhầm.
  • Inspector chỉ dùng được khi có màn hình — trên CI không có GUI thì debug bằng trace thay vì mơ tới Inspector.
  • Step qua một action có auto-waiting sẽ thấy nó 'đứng' chờ — đó không phải treo, đó là Playwright đang chờ điều kiện; đọc log để biết chờ cái gì.
  • So với breakpoint VS Code: Inspector dừng theo action Playwright, breakpoint VS Code dừng theo dòng JS và soi được biến — debug logic phức tạp nên dùng VS Code, debug locator/action dùng Inspector.
  • PWDEBUG ép mọi test chạy headed + không timeout — đừng bật nó trong script CI hay npm test chung.