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 để đảm bảo TÍNH ĐẦY ĐỦ VÀ TOÀN DIỆN 100%:

---

[ ] 1. Tính Đầy Đủ Của Phương Thức (Are ALL public methods tested?)

• 100% public methods của class nguồn đã có ít nhất một bộ test chưa?
• Có bất kỳ helper method public, getter/setter có logic, formatters hoặc hook nào bị bỏ sót không?
• Tuyệt đối không chỉ test hàm chính mà bỏ quên các hàm phụ còn lại trong class.

[ ] 2. Độ Phủ Toàn Diện: Kịch Bản Biên, Ngoại Lệ & 100% Nhánh Rẽ (Edge Cases, Exceptions & All Branches)

• Happy Path: Đã có test case với dữ liệu chuẩn xác chưa?
• Ngoại lệ (Exception): Đã có test case giả lập lỗi để ép mock ném Exception chưa?
• Khối try/catch: Đã có test case kích hoạt và chạy qua toàn bộ thân khối catch chưa?
• Kịch bản biên: Đã kiểm tra null, mảng rỗng [], chuỗi rỗng "", chuỗi khoảng trắng " ", số 0, số âm, giá trị cực đại chưa?
• Nhánh rẽ điều kiện:
  • Mọi toán tử ?? và ?: đã có test case cho cả 2 vế chưa?
  • Mọi toán tử logic && và || đã kiểm thử đủ các tổ hợp điều kiện chưa?
  • Mọi nhánh if, else if, else, switch, match (kể cả nhánh default) đã được kích hoạt chưa?
  • Mọi Guard Clause và Early Return đã có test case kích hoạt chưa?

[ ] 3. Kiểm Tra Trạng Thái & Tác Động Thực Tế (Are state mutations & side effects verified?)

• Với Database: Đã kiểm tra bản ghi thật sự được tạo/sửa/xóa qua assertDatabaseHas, assertDatabaseMissing hoặc Fixture Table chưa?
• Với Event/Queue/Mail: Đã assert Event được dispatch với đúng payload, Job được dispatch, Mail được gửi chưa?
• Với Transaction: Đã test commit khi thành công và rollback khi thất bại chưa?

[ ] 4. 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?

[ ] 5. 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?

[ ] 6. Mock Expectations Chặt Chẽ (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?
• Không over-mocking: DTO, Value Object, Collection, CakePHP Entity phải dùng instance thật.

[ ] 7. Quy Chuẩn Thành Phần Riêng Biệt (Are component-specific conventions followed?)

• 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?
• CakePHP Table: Đã test validationDefault() cho từng rule, buildRules(), custom finders và save/delete chưa?
• Laravel Job: Đã test cả phương thức handle() và failed(Throwable $e) chưa?
• Laravel Repository: Đã test query thật trên SQLite in-memory chưa (cấm chỉ assert Builder::class)?
• Laravel FormRequest: Đã test authorize() (true & false) và test từng rule vi phạm riêng biệt chưa?
• Laravel Policy: Đã test mọi action cho cả user có quyền (true) và không có quyền (false) chưa?

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

• Có sử dụng Strict Assertion (assertSame, toBe) thay vì loose assertion không?
• Tuyệt đối KHÔNG có assertion rỗng kiểu $this->assertTrue(true) hay // TODO.

[ ] 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).