Test và cải thiện suite với ak:test

Dùng ak:test để biến một thay đổi hoặc câu hỏi về chất lượng thành bằng chứng validation mới. Skill có thể chạy unit, integration, end-to-end, build, coverage và UI check dựa trên browser. Skill cũng có thể tạo test suite bao phủ, optimize suite cùng chi phí CI, hoặc audit suite để tìm test yếu. Các rule test-principles của Skill chi phối scope, layer, environment và cách thực thi cho mọi operation; hãy tải chúng trước khi thiết kế hoặc thay đổi test.

Chọn ak:test khi kết quả cần có là validation

Dùng ak:test khi

• Bạn cần bằng chứng test tập trung hoặc rộng sau khi triển khai hay sửa bug.
• Project cần validation type, lint, build hoặc coverage trước khi bàn giao.
• Landing page, form hoặc website khác cần check visual, responsive, accessibility, form hay console.
• Bạn cần QA report có cấu trúc, test suite mới, CI optimization an toàn hơn hoặc test audit có bằng chứng.

Chọn workflow khác khi

• Một test fail cần chẩn đoán root cause và sửa. Dùng ak:debug, rồi ak:fix.
• Bạn muốn triển khai kèm giai đoạn test. Dùng ak:cook.
• Bạn cần thiết kế delivery plan thay vì thực thi validation. Dùng ak:plan.
• Bạn không kiểm soát target site hoặc thiếu quyền cho automated browsing, protected route, submit form hay tạo load.

Chuẩn bị test surface

Trước khi bắt đầu:

• Hoàn tất Onboarding và xác nhận Marketing Kit đã được cài cho runtime cùng scope bạn đang dùng.
• Mở project và cung cấp thay đổi, requirement, vùng đang fail hoặc test scope dùng để quyết định command.
• Giữ sẵn test runner, dependency, fixture, biến môi trường và build tooling của project.
• Với UI testing, cung cấp URL được cấp quyền, ưu tiên staging hoặc dữ liệu fixture, và nêu form nào được phép submit hay account state nào được phép thay đổi.
• Với protected UI route, chọn test authentication project-native hoặc tự đăng nhập thủ công. Giữ credential ngoài prompt, screenshot và report.

Chọn operation

Skill nhận [context], ui [url] hoặc create|optimize|audit [scope]. Nếu bạn cung cấp scope, Skill tiến hành validation code liên quan. Khi không có argument, Skill hỏi bạn muốn chạy operation nào. Dùng ui <url> để chọn trực tiếp browser workflow, hoặc bắt đầu bằng create, optimize hay audit để làm việc với chính test suite.

/ak:test "Validate the signup form change: run the focused form tests and the production build."

/ak:test ui https://staging.example.com/pricing --mobile — inspect only; do not submit forms or change account state

/ak:test "Validate the signup form change: run the focused form tests and the production build."

/ak:test ui https://staging.example.com/pricing --mobile — inspect only; do not submit forms or change account state

$ak:test "Validate the signup form change: run the focused form tests and the production build."

$ak:test ui https://staging.example.com/pricing --mobile — inspect only; do not submit forms or change account state

Với create, optimize và audit, thêm --advice để dùng checkpoint tư vấn của kongming hoặc --interview để duyệt từng proposed change group trước khi edit. --ultra chạy năm analysis candidate read-only độc lập trong một parallel wave với một verifier: create và optimize chọn nguyên vẹn một design thắng cuộc, còn audit trả về union finding đã được xác minh bằng bằng chứng và deduplicate. Slot thất bại được retry một lần; nếu không có dispatch song song read-only hoặc sau retry vẫn dưới năm kết quả usable, lần chạy fail closed. Các flag có thể kết hợp. Khi không có --interview, create và optimize áp dụng trực tiếp thay đổi trong scope và báo cáo đầy đủ change list. Audit chỉ báo cáo trừ khi được cấp quyền sửa suite riêng; bỏ flag không cấp quyền sửa hay retirement.

/ak:test create "Cover the newsletter signup workflow" --interview
/ak:test optimize "Reduce pull-request CI time" --advice
/ak:test audit "Check skipped and ineffective form tests" --ultra

Command và coverage threshold do project định nghĩa được ưu tiên. Khi project không định nghĩa threshold, Skill báo cáo coverage thực tế cùng behavior quan trọng còn thiếu thay vì tự đặt một ngưỡng phần trăm. Tái dùng test hiện có đủ bảo vệ; refactor đã được bao phủ có thể không thêm test mới.

Trước khi thêm test hoặc chạy check rộng, nêu contract được chấp nhận cùng nguồn thẩm quyền, risk bị ảnh hưởng, check hiện có phù hợp và gap bằng chứng còn lại. Expectation suy ra chỉ là giả thuyết cho tới khi được đối chiếu với nguồn đó. Chỉ thêm test cho gap bảo vệ cụ thể; chứng minh failure dự kiến khi an toàn và khả thi, hoặc báo rõ chưa có bằng chứng đó.

Kết hợp, hạ layer hoặc retirement test cần lifecycle review về contract được bảo vệ, lịch sử regression, chi phí đã đo và bảo vệ còn lại. Riêng overlap của mutation kill được lấy mẫu hay line coverage không đổi không đủ để retirement. Review toàn bộ suite còn lại, giữ test bắt buộc cùng mandatory gate và có quyền sửa suite cho retirement. Sau thay đổi được cấp quyền, chạy lại contract bị ảnh hưởng và cùng các fault lấy mẫu hợp lệ trên suite còn lại, rồi chạy gate bắt buộc.

Dùng impact selection và các mode semantic tùy chọn

Với repository có test-impact manifest đáng tin cậy, optimize dùng ak test optimize --base <ref> --json để lập kế hoạch chọn các nhóm check theo thứ hạng một cách tất định, kèm lý do chọn hoặc bỏ qua. Việc lập kế hoạch là read-only. --run thực thi các lệnh thuộc repository đã được chọn, và đây không phải sandbox; --output <new-file> lưu kết quả cục bộ. Khi không chắc chắn, phạm vi chọn được mở rộng về phía full suite đã khai báo, các nhóm bắt buộc và policy check vẫn phải chạy, và policy mapping chưa được giải quyết sẽ chặn việc thực thi. Đường này không liên hệ provider semantic nào.

Các mode semantic chỉ chạy khi opt in, và Skill không bao giờ suy ra consent từ một key có sẵn trong môi trường. Với grant tường minh cho consumer test-impact, --semantic shadow giữ nguyên baseline có hiệu lực, còn --semantic advisory chỉ có thể thêm check hoặc mở rộng phạm vi chọn. Mode semantic đã được cấp quyền có thể gửi dữ kiện ngắn gọn tới provider bên ngoài và phát sinh chi phí. ak test classify-e2e cần grant riêng và không bao giờ thay đổi lịch chạy E2E hay class manifest. Với UI testing, một thử nghiệm shadow ak eval ui được yêu cầu, có grant tường minh ui-regression, có thể thêm tín hiệu regression từ bằng chứng đã quan sát; nó không bao giờ biến một lỗi thành đạt hay thay đổi kết quả UI test.

Agentic E2E tùy chọn qua tester-army/e2e chỉ dành cho project đã dùng engine đó hoặc khi bạn yêu cầu setup rõ ràng. Điều này không cấp quyền cài đặt, truy cập provider, gọi model hay telemetry; UI check native thông thường không cần model. Kiểm tra capability của engine đã cài trước khi chạy. Cache replay action, không phải pass: chạy lại assertion outcome chính xác trên app hiện tại. Riêng --strict-cache không bảo đảm không gọi model. Nếu cấm model call, dùng cơ chế cưỡng chế được xác minh độc lập cho version đã chọn hoặc giữ native route. Báo replay/live execution thực tế và exploration chưa hoàn tất; không có finding hay cache hit không xác minh release claim chưa được thực thi.

Hiểu điều gì xảy ra trong một lần chạy

1. Skill xác định scope. Skill nối contract được chấp nhận, nguồn thẩm quyền và risk với check nhỏ nhất hữu ích ở layer thấp nhất đáng tin, rồi nêu gap bằng chứng trước khi thêm việc.
2. Skill chạy check liên quan hẹp nhất trước. Type hoặc build check chạy khi bao phủ contract bị ảnh hưởng; gate repository bắt buộc vẫn được giữ.
3. Skill thực thi các suite đã chọn và phân tích kết quả, tập trung vào test fail, flaky, chậm và bị skip.
4. Skill đo coverage khi phù hợp và chỉ ra critical path, error handler cùng nhánh edge case chưa được bao phủ.
5. Skill kiểm tra UI khi được chọn. Skill đặt charter hẹp với route, behavior mong đợi, quyền account/data và check bắt buộc. Skill dùng ak:agent-browser hoặc browser test project-native, mặc định tuần tự; chỉ target độc lập, cô lập với capacity phù hợp mới đáng delegate cho tester. Browser check chỉ chứng minh scope quan sát được từ browser, không phải coverage backend. Assert chính xác identity, permission, count, side effect và control/path được claim; route khác không cứu được control hỏng. Lưu visual evidence liên quan trong report directory thay vì chụp screenshot mọi page.
6. Skill tạo report. Skill trả kết quả ngắn gọn cho lần chạy nhỏ hoặc ghi report có cấu trúc vào vị trí report của repository.

Giữ tác động của test trong tầm kiểm soát

• Test command có thể tạo file coverage, screenshot, build output, dữ liệu tạm hoặc browser state. Hãy nêu vị trí artifact, giới hạn execution/retry và yêu cầu cleanup được phép; chỉ dọn resource do lần chạy này sở hữu.
• Mutation proof có chọn lọc, không phải yêu cầu cho execution thường lệ hay CI. Chỉ fault injection có giới hạn trong disposable copy do lần chạy sở hữu, không trên active worktree. Ghi source identity, restore copy chính xác cả khi fail, xác minh restoration và chạy lại behavior đã restore. Chỉ target assertion failure là semantic kill; compilation, setup, infrastructure hay provider failure là bằng chứng invalid hoặc inconclusive, không phải kill.
• UI flow và end-to-end test có thể submit form hoặc thay đổi dữ liệu nếu ứng dụng hoạt động như vậy. Hãy chạy chúng trên test environment an toàn.
• Truy cập Chrome profile thật cần quyền rõ ràng và login state cần thiết; bind đúng tab nhận biết profile. URL bên ngoài, hosted browser cùng chi phí provider hay vận hành cần quyền riêng.
• Operation UI không triển khai fix. Việc tìm root cause của sản phẩm thuộc về ak:debug và ak:fix.

Xác minh report

Một kết quả hoàn chỉnh nên cung cấp:

• Scope chính xác và mọi command đã chạy.
• Contract được chấp nhận và nguồn thẩm quyền, source/input fingerprint trước và sau execution, runner/configuration, environment cùng receipt hoặc artifact.
• Tổng số test pass, fail và skip cùng duration đã đo; giữ mọi attempt thất bại cùng raw status ngay cả khi retry pass.
• Mọi test fail kèm error message và stack trace liên quan.
• Giá trị coverage cùng file hoặc function cụ thể chưa được bao phủ khi có yêu cầu coverage.
• Build status, warning và vấn đề dependency khi có build verification.
• Page UI đã test, đường dẫn screenshot, console error và viewport đã check hoặc bị bỏ qua.
• Critical issue, recommendation đã xếp ưu tiên và câu hỏi chưa giải quyết.
• Giới hạn environment, authentication và bằng chứng.
• Thay đổi suite đã áp dụng so với đề xuất, quyền thực hiện và bảo vệ còn lại. Chỉ so chi phí khi source task, environment, toolchain và cache condition tương ứng: gồm setup, generation/review, runner/model call, token, CI minute và device resource đã quan sát khi có. Metric chưa biết vẫn là unknown; elapsed time không phải CI minute bị tính phí, và ít test hay token hơn riêng lẻ không chứng minh tiết kiệm.

Chỉ coi lần chạy là đạt khi các check được yêu cầu báo không có lỗi, build thoát thành công nếu có build, và threshold của project được đáp ứng. Một check chạy một phần hoặc bị skip chỉ chứng minh surface thực sự đã chạy.

Mandatory gate bị skip hoặc không khả dụng nghĩa là chưa đủ bằng chứng. Chỉ tái dùng receipt khi scope, source mới, dirty/untracked input liên quan, configuration và environment khớp; riêng commit SHA không đủ. Receipt invalid, stale hoặc thuộc scope khác cần chạy lại check cần thiết, không lặp mù quáng toàn suite. Input cuối đã đổi hoặc chưa xác minh ngăn claim pass cho source cuối; báo state đã test và gap còn lại.

Xử lý sự cố hoặc tiếp tục

Chuyển lỗi cho ak:debug và ak:fix, hoặc tiếp tục với ak:git sau khi validation được yêu cầu đã đạt.

Biết giới hạn hiện tại

• Skill bị giới hạn trong test runner, browser, credential, URL và environment khả dụng ở session hiện tại.
• Hướng dẫn của Skill cũng nhắc tới ak:chrome-profile và ak:web-testing. Package Marketing Kit cho Claude Code không bao gồm các Skill đó, vì vậy hãy dùng ak:agent-browser hoặc browser test project-native trừ khi chúng được cài từ nguồn khác.
• Tỷ lệ coverage không chứng minh behavior nằm ngoài assertion hoặc điều kiện runtime đã được chạy.
• Cách gọi Cursor bằng slash là bằng chứng do người dùng xác minh, không phải bằng chứng về runtime parity đầy đủ.