agent-unit-testing/rules/verification-checklist.md

Checklist Tự Thẩm Định Chất Lượng Unit Test (Verification Checklist)

Trước khi xuất bất kỳ file test nào cho người dùng, Agent BẮT BUỘC phải tự đối chiếu mã nguồn của mình qua các câu hỏi kiểm định nghiêm ngặt dưới đây:

---

[ ] 1. Tính Đơn Vị & An Toàn Cơ Sở Dữ Liệu (Isolation & DB Safety)

• Test có đang vô tình gọi Database dev thật hoặc gọi router HTTP ngoài đời thực không?
• Với CakePHP: Đã cấu hình dùng Datasources.test (SQLite :memory:) và khai báo Fixtures đầy đủ chưa?
• Với Laravel: Đã cấu hình SQLite :memory: và mock các dịch vụ ngoài bằng Fake/Mockery chưa?

[ ] 2. Cấu Trúc AAA Rõ Ràng (Is AAA clearly structured?)

• Các khối // Arrange, // Act, // Assert có được phân định rõ ràng bằng comment không?
• Khối // Act có đúng là chỉ thực hiện 1 hành động duy nhất không?

[ ] 3. Mock Expectations Đầy Đủ (Are mock calls strictly verified?)

• Mọi mock method có được khai báo số lần gọi cụ thể (->once(), ->never(), ->times(N)) thay vì bỏ trống không?
• Các tham số truyền vào hàm mock có được kiểm tra qua ->with(...) hoặc ->withArgs(...) không?

[ ] 4. Không Over-Mock DTO/Value Object/Entity (Are value objects kept real?)

• Các đối tượng DTO, Value Object, Collection, CakePHP Entity có được tạo bằng instance thật thay vì mock không?

[ ] 5. Độ Phủ Ngoại Lệ, Kịch Bản Biên & SonarQube Branches (Are edge cases & branches covered?)

• Đã có test case cho trường hợp ném ngoại lệ (Exception) chưa?
• Đã kiểm tra các trường hợp biên: null, mảng rỗng [], số 0, số âm chưa?
• Mọi toán tử ?? và ?: đã có test case cho cả 2 vế chưa?
• Mọi khối try/catch đã có test case ép mock ném Exception để chạy qua khối catch chưa?

[ ] 6. Không Bỏ Sót Phương Thức & Trait Cốt Lõi (Are all core methods & traits tested?)

• CakePHP Controller: Đã sử dụng Cake\TestSuite\IntegrationTestTrait và gọi $this->enableCsrfToken(), $this->enableSecurityToken() khi test POST/PUT chưa?
• CakePHP Command: Đã sử dụng Cake\Console\TestSuite\ConsoleIntegrationTestTrait và assert exit code (assertExitSuccess()) chưa?
• CakePHP Mailer: Đã sử dụng Cake\TestSuite\EmailTrait chưa?
• Laravel Job hoặc Command: Đã test phương thức handle() và failed() chưa? Tuyệt đối không chỉ test helper phụ!
• Tất cả các public methods của class đã có ít nhất một bài test tương ứng chưa?

[ ] 7. Assertions Chặt Chẽ & Có Nghĩa (Are assertions meaningful?)

• Có sử dụng Strict Assertion (assertSame, toBe) thay vì loose assertion không?
• Với CakePHP: Có dùng assertion chuyên dụng (assertResponseOk(), assertRedirect(), assertFlashMessage()) không?
• Có bị dính assertion rỗng kiểu $this->assertTrue(true) không?

[ ] 8. Đặt Tên Chuẩn & Dễ Đọc (Are method names expressive?)

• Tên test method có thể hiện rõ "Hành động + Kết quả + Ngữ cảnh" không? (Ví dụ: testValidationFailsWhenTitleIsEmpty hoặc testAddPostSuccessWithAuth)

[ ] 9. Cú Pháp Đúng Phiên Bản Framework (Is syntax version-accurate?)

• Nếu là PHPUnit 10+: Đã dùng Attribute #[Test] và #[DataProvider] thay cho DocBlock cũ chưa?
• Nếu là Pest: Đã dùng đúng cú pháp describe(), it(), expect() chưa?

[ ] 10. Import Đầy Đủ & Namespace Chính Xác (Are imports complete?)

• Tất cả các class, exception, interface, attribute, trait sử dụng trong file test đã có lệnh use ... ở đầu file chưa? (Tránh lỗi Class not found).