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ừ 1 lệnh duy nhất cho toàn bộ dự án đến từng file đơn lẻ):

1. 🌟 Chế độ Autopilot Khép Kín: Viết Xong Chạy Test Luôn (--all --run hoặc --autopilot):

   /laravel-unit-test --all --run
   # Hoặc:
   /laravel-unit-test --autopilot
   

   Chỉ với 1 lệnh duy nhất, Agent sẽ thực thi trọn vẹn quy trình 4-trong-1:

   • Tự động Setup: Kiểm tra dependencies & SQLite in-memory, tự cài đặt gói thiếu.
   • Tự động Quét: Lập manifest toàn bộ class trong dự án app/.
   • Tự động Viết & Test Ngay: Sinh test đến đâu -> Chạy test ./test-runner.sh ngay đến đó.
   • Tự động Sửa Lỗi (Auto-Healing): Nếu test đỏ (Fail) -> Tự đọc log lỗi và sửa lại test cho đến khi XANH (Pass 100%).
   • Nghiệm thu: Đo Code Coverage và in bảng tổng kết cuối cùng.

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

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

   Sinh test cho class và lập tức chạy thử để xác nhận Pass 100% trước khi hoàn thành.

3. Chế độ Hàng loạt theo Thư mục (Batch Directory Mode):

   /laravel-unit-test app/Services/ --run
   # Hoặc toàn bộ Actions:
   /laravel-unit-test app/Actions/ --run
   

4. Chế độ Theo Module / DDD (Module Mode):

   /laravel-unit-test Modules/Order/ --run
   # Hoặc:
   /laravel-unit-test app/Domains/Payment/ --run
   

5. Chế độ Theo Git Diff (Changed Files Mode - Dành Cho Pull Request):

   /laravel-unit-test --changed --run
   

6. Chế độ File đơn lẻ (Single File Mode):

   /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 (Tối thiểu cho mỗi public method)

• 1 Happy Path: Đầu vào hợp lệ -> Thực thi thành công -> Trả về đúng kết quả.
• N Edge Cases: Input biên (0, số âm, rỗng "", [], null, unicode).
• N Exception Cases: Tham số sai ném InvalidArgumentException, service ngoài lỗi ném PaymentFailedException,...

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 rõ ràng: ->once(), ->never().
   • Dùng Strict assertion: $this->assertSame() hoặc expect(...)->toBe().

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