---
name: laravel-unit-test
description: 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ế độ 1 Lệnh Duy Nhất Cho Toàn Bộ Dự Án (All-in-One Full Coverage Mode - Khuyên dùng cho dự án lớn)**:
   ```text
   /laravel-unit-test --all
   ```
   **Cơ chế cam kết không bỏ sót bất kỳ file nào:**
   - **Giai đoạn 1 (Lập Manifest Kiểm Soát)**: Tự động quét toàn bộ `app/` (và `Modules/`), lọc ra tất cả các class có logic (Services, Actions, FormRequests, Rules, Jobs, Policies, Middlewares, Listeners, Observers, Repositories, Custom Casts). Lập file danh sách kiểm soát `tests/.test-manifest.json` (ví dụ: Tổng cộng 42 files).
   - **Giai đoạn 2 (Thực Thi Tuần Tự & Theo Dõi Tiến Độ)**: Duyệt tuần tự từng class trong manifest (`[1/42]`, `[2/42]`,...), sinh test tương ứng và đánh dấu `[COMPLETED]`. Không bao giờ bị tràn context và có thể tiếp tục nếu bị gián đoạn.
   - **Giai đoạn 3 (Tự Động Chạy Thử & Sửa Lỗi Ngay - Auto-Healing)**: Sinh xong file nào lập tức chạy `./test-runner.sh --filter=<Test>` cho file đó. Nếu FAIL -> Tự động đọc log lỗi và sửa lại test cho đến khi PASS 100%.
   - **Giai đoạn 4 (Báo Cáo Nghiệm Thu Độ Phủ)**: Chạy `./test-runner.sh --coverage` và in bảng tổng kết: `42/42 files covered, 100% Passed, Code Coverage: > 80%`.

2. **Chế độ Hàng loạt theo Thư mục (Batch Directory Mode)**:
   ```text
   /laravel-unit-test app/Services/
   # Hoặc:
   /laravel-unit-test app/Actions/
   ```

3. **Chế độ Theo Module / DDD (Module Mode)**:
   ```text
   /laravel-unit-test Modules/Order/
   # Hoặc:
   /laravel-unit-test app/Domains/Payment/
   ```

4. **Chế độ Quét & Phủ Test Toàn Dự Án (Untested Audit Mode)**:
   ```text
   /laravel-unit-test --untested
   ```

5. **Chế độ Theo Git Diff (Changed Files Mode - Dành Cho Pull Request)**:
   ```text
   /laravel-unit-test --changed
   ```

6. **Chế độ File đơn lẻ (Single File Mode)**:
   ```text
   /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 ý:
   ```bash
   php artisan test --filter=OrderServiceTest
   # Hoặc qua docker runner:
   ./templates/docker/test-runner.sh --filter=OrderServiceTest
   ```