fix

Tổng quan về fix skill

fix skill làm gì

fix skill là một quy trình gỡ lỗi tập trung cho các Playwright test bị fail hoặc chập chờn. Skill này giúp AI agent đi từ tình trạng “test này đang hỏng” đến nguyên nhân gốc có khả năng nhất bằng cách tái hiện lỗi, thu thập bằng chứng từ trace, rồi phân loại vấn đề theo taxonomy dành cho flaky test thay vì chỉ đoán dựa trên assertion error.

Phù hợp nhất để gỡ lỗi Playwright test

Hãy cài skill này nếu bạn duy trì end-to-end tests và thường xuyên gặp các thông báo như “test failing,” “flaky test,” “passes locally but fails in CI,” hoặc “intermittent failure.” Skill đặc biệt hữu ích cho các team dùng Playwright trong CI, nơi lỗi có thể đến từ timing, test isolation, khác biệt môi trường hoặc áp lực hạ tầng.

Vì sao hữu ích hơn một prompt gỡ lỗi chung chung

Một prompt gỡ lỗi chung thường nhảy thẳng vào sửa code. fix skill ép quy trình đi đúng thứ tự hơn: tái hiện trước, chạy burn-in nếu lỗi biến mất, thu thập trace, rồi map triệu chứng vào từng nhóm nguyên nhân. Tệp đi kèm flaky-taxonomy.md cung cấp các nhánh chẩn đoán và mẫu sửa cụ thể, bao gồm thiếu await, shared state, khác biệt chỉ xuất hiện trên CI về viewport/font/timezone, browser crash và tình trạng mất ổn định liên quan đến worker.

Các giới hạn quan trọng trước khi cài đặt

Đây không phải công cụ sửa mọi loại bug. Skill được giới hạn cho Playwright tests và giả định agent có thể kiểm tra test file, chạy lệnh Playwright, cũng như đọc output như traces, screenshots, logs hoặc nội dung lỗi từ CI. Skill không có helper scripts, nên giá trị chính nằm ở workflow và taxonomy, không phải automation.

Cách dùng fix skill

Cài fix và các tệp cần xem trước

Cài skill trong môi trường skills tương thích bằng lệnh:

npx skills add alirezarezvani/claude-skills --skill fix

Sau khi cài, đọc SKILL.md trước để nắm workflow thực thi, rồi mở flaky-taxonomy.md để xem decision tree và các cách sửa thường gặp. Đường dẫn repository là engineering-team/playwright-pro/skills/fix, và các source file hữu ích được giữ rất gọn: không có script, rule hay metadata file ẩn nào cần cấu hình.

Input mà fix skill cần

Để có kết quả tốt nhất, hãy cung cấp ít nhất một trong các input sau:

• Đường dẫn test file, ví dụ e2e/login.spec.ts
• Tên test chính xác hoặc chuỗi --grep
• Failure message, stack trace hoặc assertion error
• Lỗi xảy ra ở local, trong CI hay cả hai
• Test chạy riêng thì pass nhưng chạy trong full suite thì fail hay không
• Trace, screenshot, video hoặc đường dẫn CI artifact nếu có
• Playwright config liên quan, đặc biệt là workers, retries, projects, viewport, timezone và base URL

Prompt yếu: “Fix my flaky checkout test.”

Prompt tốt hơn: “Use the fix skill for Debugging e2e/checkout.spec.ts, test should submit paid order. It passes locally alone, fails in CI about 30% of runs, and the failure is Timeout 5000ms exceeded waiting for getByRole('button', { name: 'Pay' }). CI uses 4 workers and retries=2. Suggest the reproduction commands, likely category, and minimal code/config changes.”

Quy trình dùng fix trong thực tế

Bắt đầu với đúng file đang fail:

npx playwright test <file> --reporter=list

Nếu test pass, hãy xem đó là lỗi có khả năng flaky và chạy burn-in:

npx playwright test <file> --repeat-each=10 --reporter=list

Nếu vấn đề chỉ xuất hiện khi chạy đồng thời, chạy với parallelism:

npx playwright test --fully-parallel --workers=4 --repeat-each=5

Sau đó thu thập bằng chứng trace:

npx playwright test <file> --trace=on --retries=0

Yêu cầu agent phân loại lỗi trước khi sửa. Các nhóm nguyên nhân kỳ vọng gồm timing/async, test isolation, environment hoặc infrastructure. Cách này giúp tránh những hướng sửa tệ thường gặp như thêm waitForTimeout tùy tiện, tăng global timeout hoặc che giấu race condition thật sự bằng retries.

Mẫu prompt để có kết quả tốt hơn

Dùng prompt tách rõ bằng chứng và yêu cầu:

“Use the fix skill. Diagnose before changing code. Test: <file> / <test name>. Reproduction result: <passes/fails command>. CI/local behavior: <details>. Trace or screenshot: <path or summary>. Current suspicion: <optional>. Please categorize using flaky-taxonomy.md, explain the evidence, propose the smallest safe fix, and list the command to verify it.”

Cấu trúc này giúp skill tạo ra một kế hoạch gỡ lỗi có thể kiểm chứng, thay vì một bản patch mang tính phỏng đoán.

FAQ về fix skill

fix chỉ dành cho flaky tests phải không?

Không. fix skill xử lý cả Playwright tests fail ổn định lẫn lỗi xảy ra thất thường. Với lỗi deterministic, skill vẫn bắt đầu bằng tái hiện và thu thập trace. Với lỗi intermittent, skill bổ sung burn-in và kiểm tra parallel-worker để làm lộ các mẫu vấn đề về timing, isolation hoặc infrastructure.

Khi nào không nên dùng skill này?

Không nên dùng skill này làm công cụ chính cho unit tests, backend integration tests, production bugs không có Playwright coverage hoặc gỡ lỗi kiến trúc ứng dụng trên diện rộng. Skill vẫn có thể gợi ý một số ý tưởng chung, nhưng lệnh, taxonomy và ví dụ của nó được viết cho Playwright end-to-end tests.

So với Playwright trace viewer thì khác gì?

Trace viewer cho thấy chuyện gì đã xảy ra; fix skill giúp quyết định trace đó có ý nghĩa gì. Ví dụ, một element bị thiếu có thể là dấu hiệu của async race, state bị rò rỉ từ test trước, khác biệt viewport trên CI hoặc phụ thuộc network. Taxonomy biến artifact thành hướng chẩn đoán và loại sửa phù hợp.

fix có thân thiện với người mới không?

Có, nếu người dùng có thể chạy lệnh Playwright và chia sẻ lỗi. Người mới sẽ hưởng lợi từ chuỗi lệnh rõ ràng và bảng phân loại nguyên nhân. Tuy vậy, skill không thay thế kiến thức thiết lập project cơ bản: Playwright phải được cài sẵn, test suite phải chạy được và artifact phải truy cập được.

Cách cải thiện fix skill

Cung cấp bằng chứng lỗi mạnh hơn cho fix

Cải thiện quan trọng nhất là nâng chất lượng input. Hãy đưa vào các lệnh chính xác đã thử và kết quả của chúng. “Fails in CI” kém hữu ích hơn “fails in CI with 4 workers, passes locally with one worker, fails locally with --fully-parallel --workers=4 --repeat-each=5.” Chỉ một chi tiết đó đã chỉ về hướng isolation hoặc parallelism thay vì timing chung chung.

Tránh các lỗi gỡ lỗi thường gặp

Đừng yêu cầu patch trước khi chẩn đoán. Các kết quả tệ thường gặp gồm thêm fixed sleeps, tăng global timeouts, bật thêm retries hoặc viết lại selectors khi chưa xác nhận nguyên nhân. Hãy yêu cầu skill nêu rõ category, evidence, minimal fix và verification command trước khi chỉnh code.

Lặp lại sau lần sửa đầu tiên

Sau khi áp dụng thay đổi được đề xuất, chạy lại lệnh kiểm chứng nhỏ nhất nhưng vẫn có ý nghĩa. Nếu bản sửa nhắm vào timing, dùng burn-in. Nếu nhắm vào isolation, so sánh hành vi khi chạy single-test với khi chạy suite. Nếu nhắm vào môi trường CI, tái hiện bằng thiết lập gần với CI hơn như Docker, workers, timezone, viewport hoặc mocked network services.

Mở rộng hướng dẫn fix cho project của bạn

Các team có thể cải thiện kết quả nội bộ bằng cách thêm ghi chú riêng của project gần workflow của skill: cấu hình CI thường dùng, dịch vụ hay flaky đã biết, yêu cầu reset test data, fixtures tiêu chuẩn, chiến lược mock và quy ước locator được ưu tiên. fix skill hoạt động tốt nhất khi taxonomy của nó được kết hợp với các mẫu lỗi thực tế trong repository của bạn.