agent-unit-testing/.claude/skills/laravel-unit-test/skill.md

name, description

name	description
laravel-unit-test	Phân tích một class mã nguồn PHP Laravel bất kỳ và tự động sinh file Unit Test hoàn chỉnh đạt chuẩn AAA, cô lập cao và bao phủ biên.

Skill: Laravel Unit Test Generator

Skill này là công cụ chính để tự động tạo ra file Unit Test cho bất kỳ class nào trong dự án Laravel (Service, Action, Controller, Job, FormRequest, Policy, Rule,...).

Cách kích hoạt

Người dùng có thể kích hoạt linh hoạt theo các chế độ (từ quy trình chuẩn Pro 3 bước cho dự án lớn đến file đơn lẻ):

🏆 QUY TRÌNH CHUẨN PRO CHO DỰ ÁN LỚN (KHUYÊN DÙNG NHẤT):

Để tránh bị tràn context token và đảm bảo viết sâu 100% từng nhánh SonarQube, hãy tách biệt 2 pha: PHA VIẾT (Generation) và PHA CHẠY (Execution):

1. Bước 1: Quét bản đồ dự án (--untested):

   /laravel-unit-test --untested
   

   Liệt kê danh sách class chưa có test theo độ ưu tiên: Services/Actions -> Requests/Rules -> Jobs/Policies.

2. Bước 2: Viết test tập trung theo từng tầng (CHỈ VIẾT, CHƯA CHẠY TEST):

   /laravel-unit-test app/Services/
   # Sau khi xong, viết tiếp:
   /laravel-unit-test app/Actions/
   /laravel-unit-test app/Http/Requests/
   

   AI dồn 100% token tập trung sinh test sâu, đầy đủ Happy Path, Edge Cases, Exception và Branch Coverage.

3. Bước 3: Chạy test đồng loạt ngoài Terminal & Nghiệm thu:

   ./test-runner.sh --coverage
   

   Chạy 1 lần duy nhất trên In-memory SQLite siêu tốc, đo độ phủ và xuất file báo cáo.

---

⚡ CÁC CHẾ ĐỘ TIỆN ÍCH KHÁC:

4. Chế độ Autopilot Khép Kín: Viết & Chạy Test Ngay (--all --run hoặc --autopilot):

   /laravel-unit-test --all --run
   

   Dành cho dự án vừa và nhỏ: AI tự lập manifest, viết đến đâu chạy ./test-runner.sh ngay đến đó, tự động sửa lỗi (Auto-Healing) nếu test fail.

5. Chế độ Viết Cho 1 File & Test Luôn (--run):

   /laravel-unit-test app/Services/PaymentService.php --run
   

6. Chế độ Theo Git Diff (Dành Cho Pull Request):

   /laravel-unit-test --changed
   

7. Chế độ File đơn lẻ:

   /laravel-unit-test app/Services/PaymentService.php
   

---

Quy trình 6 Bước Tự Động của Agent

Bước 1: Khảo sát Môi trường & Framework

1. Đọc composer.json để xác định Framework test của dự án:
   • Nếu có pestphp/pest: Tạo test theo định dạng Pest PHP.
   • Nếu có phpunit/phpunit:
     • PHP >= 8.1 & PHPUnit 10+: Dùng PHP 8 Attributes (#[Test], #[DataProvider]).
     • PHP < 8.1 hoặc PHPUnit 9: Dùng DocBlock (/** @test */).

Bước 2: Phân tích File Nguồn

1. Đọc toàn bộ nội dung file class nguồn được chỉ định.
2. Xác định:
   • Loại Component: Service, Action, Controller, FormRequest, Model, Job, Policy, Middleware,...
   • Constructor Dependencies: Các class/interface được inject vào qua __construct().
   • Public Methods: Danh sách các hàm cần test.
   • Kiểu dữ liệu & Logic phân nhánh: Các lệnh if/else, try/catch, throw, type hints của params và return types.

Bước 3: Phân Loại Mock vs Real Object

• Mock bằng Mockery: Các Interface, Repository, 3rd Party Client, Mailer, Logger.
• Dùng Laravel Fakes: Http::fake(), Queue::fake(), Event::fake(), Storage::fake().
• Dùng Object thật (Không Mock): DTOs, Value Objects, Collections, Request payload dạng mảng.

Bước 4: Lập Ma Trận Test Scenarios (Đảm Bảo Coverage > 90% Trên SonarQube)

Mục tiêu cốt lõi: SonarQube tính cả Line Coverage và Branch Coverage. Để đạt Coverage > 90%, Agent phải tuân thủ nghiêm ngặt ma trận sau:

1. 100% Public Methods: Mọi phương thức public của class đều phải có bài test.
2. Quét 100% Nhánh Rẽ (Branch / Condition Coverage):
   • Toán tử ?? (Null Coalescing): Bắt buộc 2 test case (có giá trị & null/fallback).
   • Toán tử ?: (Ternary): Bắt buộc 2 test case (true & false).
   • Biểu thức logic && và ||: Phải test các kịch bản kết hợp để thỏa mãn điều kiện rẽ nhánh SonarQube.
   • Khối try - catch - finally: BẮT BUỘC có test case ép mock ném Exception để chạy qua khối catch.
   • Mọi if, else if, else, switch, match (kể cả nhánh default).
3. Chiến Lược Riêng Cho Từng Tầng Laravel Để Đạt > 90%:
   • FormRequest (app/Http/Requests/):
     • Test authorize() trả về cả true (cho phép) và false (từ chối).
     • Test rules(): Bắt buộc test dữ liệu hợp lệ VÀ test vi phạm cho từng rule (required, email, max, numeric, unique) để phủ 100% các nhánh validator.
   • Custom Rules (app/Rules/): Test cả 2 trường hợp passes() === true và passes() === false (kèm thông báo message()).
   • Controllers (app/Http/Controllers/):
     • Endpoint Success: 200 OK hoặc 201 Created.
     • Validation Error: 422 Unprocessable Entity khi payload thiếu/sai.
     • Unauthorized: 401 Unauthenticated hoặc 403 Forbidden.
     • Not Found: 404 khi Model ID không tồn tại.
   • Services & Actions (app/Services/, app/Actions/):
     • Happy Path: Đầu vào chuẩn -> kết quả đúng.
     • Exception Path: Bắt buộc test mock ném ngoại lệ (PaymentFailedException,...).
     • Nếu có DB::transaction(): Test cả commit thành công và rollback khi gặp lỗi.
   • Jobs (app/Jobs/):
     • BẮT BUỘC test phương thức handle() (với đầy đủ mock S3, Queue, DB, Mail).
     • BẮT BUỘC test phương thức failed(Throwable $e). Tuyệt đối cấm chỉ test helper phụ.
   • Policies (app/Policies/):
     • Mọi action (view, create, update, delete,...) bắt buộc test cả 2 kịch bản: true (User có quyền) và false (User không có quyền).
   • Artisan Commands (app/Console/Commands/):
     • Test exit code 0 (assertExitCode(0)) khi arguments hợp lệ.
     • Test exit code 1 khi thiếu arguments hoặc command gặp Exception.
   • Repositories (app/Repositories/):
     • Test kết quả truy vấn / cập nhật dữ liệu thật trên SQLite in-memory (cấm chỉ assert Builder::class).

Bước 5: Sinh Mã Nguồn Test

1. Xác định đường dẫn file test theo quy tắc Mirror:
   • Nguồn: app/Services/OrderService.php
   • Đích: tests/Unit/Services/OrderServiceTest.php
2. Tham chiếu hướng dẫn tương ứng trong docs/components/ và template trong templates/.
3. Viết đầy đủ code:
   • Tuân thủ mô hình AAA (// Arrange, // Act, // Assert).
   • Mock expectation có số lần gọi nghiêm ngặt: ->once(), ->never().
   • Dùng Strict assertion: $this->assertSame() hoặc expect(...)->toBe().
   • Đảm bảo quét sạch tất cả các nhánh điều kiện để SonarQube Line & Branch Coverage đạt > 85% - 95%.

Bước 6: Thẩm định & Lưu File

1. Tự kiểm tra file test qua rules/verification-checklist.md.
2. Ghi file test vào thư mục tests/Unit/....
3. In ra lệnh chạy test gợi ý:

   php artisan test --filter=OrderServiceTest
   # Hoặc qua docker runner:
   ./templates/docker/test-runner.sh --filter=OrderServiceTest