agent-unit-testing/README.md

# 🚀 Laravel Agent Unit Testing Toolkit

Bộ công cụ, cẩm nang quy chuẩn và Claude Code Skills chuyên biệt dành cho việc **tự động phân tích, thiết lập môi trường và sinh Unit Test chuẩn xác cho bất kỳ mã nguồn PHP Laravel nào** (hỗ trợ Laravel 9, 10, 11; PHPUnit 9/10/11 & Pest PHP v2/v3).

---

## 🌟 Tính Năng Nổi Bật

1. **Chuẩn Hóa Môi Trường (Step 0)**:
   - Tự động phát hiện cấu hình Docker (Sail, Docker Compose) hoặc PHP CLI cục bộ.
   - Thiết lập SQLite In-Memory (`:memory:`) siêu tốc, bảo vệ tuyệt đối database dev.
   - Script chạy test thông minh `test-runner.sh` tự nhận diện môi trường container.
2. **Triết Lý Kiểm Thử Đỉnh Cao (AAA & Isolation)**:
   - Cô lập hoàn toàn logic đơn vị, mock đúng nơi, fake đúng chỗ.
   - Tuyệt đối không over-mock DTO, Value Object hay Mock chuỗi Eloquent Builder.
3. **Cẩm Nang Chi Tiết Cho 13 Tầng Kiến Trúc Laravel**:
   - Services, Actions, Controllers, FormRequests, Custom Rules, Repositories, Query Builders, Models, Jobs, Events, Listeners, Middlewares, Policies, Notifications, Mails, Commands, View Components, Observers, Exceptions.
4. **Hệ Thống 4 Skills Tự Động Hóa Cho Claude Code**:
   - `/laravel-test-setup`: Quét môi trường, cấu hình và chạy Smoke Test.
   - `/laravel-unit-test`: Đọc class nguồn -> Sinh file test hoàn chỉnh.
   - `/laravel-test-review`: Thẩm định, chấm điểm và chỉ ra lỗi anti-patterns của file test.
   - `/laravel-mock-helper`: Sinh code Mockery / Fakes nhanh cho Interface/Class.

---

## 📁 Cấu Trúc Dự Án

```text
agent-unit-testing/
├── .claude/
│   └── skills/                              # Bộ 4 Skills cho Claude Code
│       ├── laravel-test-setup/              # Khởi tạo & kiểm tra môi trường test
│       ├── laravel-unit-test/               # Sinh mã Unit Test tự động
│       ├── laravel-test-review/             # Review & chấm điểm file test
│       └── laravel-mock-helper/             # Hỗ trợ sinh mã Mocking
│
├── docs/                                    # Cẩm nang kiến thức & quy chuẩn cốt lõi
│   ├── 00-environment-and-setup.md          # Hướng dẫn setup dependencies, DB in-memory & Docker
│   ├── 01-overview-and-principles.md        # Triết lý Unit Test: AAA, Isolation, Boundary
│   ├── 02-test-frameworks.md                # So sánh & Cú pháp PHPUnit 10/11 vs Pest PHP
│   ├── 03-mocking-strategies.md             # Toàn tập Mockery vs Laravel Fakes vs Static Facades
│   ├── 04-naming-and-structure.md           # Quy chuẩn đặt tên file, namespace, test method
│   ├── 05-anti-patterns.md                  # 12 lỗi cấm kỵ khi viết Unit Test Laravel
│   ├── 06-future-php84-laravel-latest.md    # Hướng dẫn chuyên sâu PHP 8.4+ & Laravel 12/13
│   ├── 07-troubleshooting-and-debugging.md  # Cẩm nang sửa 10 lỗi thường gặp nhất khi test
│   ├── 08-test-data-factories-and-builders.md# Quản lý fixture: Model::make(), States & DTO Builders
│   ├── 09-advanced-edge-cases.md            # DB::transaction, Traits, File uploads, Serialization
│   │
│   └── components/                          # Hướng dẫn test cho 13 loại Laravel Component
│       ├── 01-services-and-actions.md       # Service Layer, Action classes, DTOs
│       ├── 02-controllers.md                # API & Web Controllers
│       ├── 03-form-requests-and-rules.md    # FormRequest rules, Custom Validation Rules
│       ├── 04-repositories-and-queries.md   # Repositories & Custom Query Builders
│       ├── 05-models.md                     # Accessors, Mutators, Custom Casts
│       ├── 06-jobs-and-queues.md            # Queueable Jobs, handle(), retry logic
│       ├── 07-events-and-listeners.md       # Event payloads, Listeners handling
│       ├── 08-middlewares.md                # Request interception, Auth, Role, Tenant
│       ├── 09-policies-and-gates.md         # Phân quyền Policy methods (can/cannot)
│       ├── 10-notifications-and-mail.md     # Mailables & Notification channels
│       ├── 11-artisan-commands.md           # Console input/options, exit code, prompts
│       ├── 12-view-components-and-blade.md  # Blade View Components & directives
│       └── 13-observers-and-exceptions.md   # Model Observers & Custom Exceptions
│
├── templates/                               # Boilerplate mẫu sẵn dùng
│   ├── configs/                             # File config: phpunit.xml, .env.testing, Pest.php
│   ├── docker/                              # Script test-runner.sh & docker-compose.test.yml
│   ├── phpunit/                             # Templates chuẩn PHPUnit 10/11 (Attributes)
│   └── pest/                                # Templates chuẩn Pest PHP v2/v3
│
└── rules/                                   # Bộ quy tắc & Checklists
    ├── system-prompt-unit-test.md           # System prompt tối cao cho AI
    ├── edge-cases-matrix.md                 # Ma trận kịch bản biên (Null, Empty, Boundary, Error)
    └── verification-checklist.md            # Checklist 10 bước tự kiểm tra trước khi xuất code
```

---

## ⚡ Cài Đặt Cho Team (1 Dòng Lệnh Duy Nhất)

Mỗi thành viên trong team chỉ cần mở Terminal, dán lệnh sau và bấm Enter:
```bash
git clone ssh://git@ssh-git.smartgift.io.vn:2222/Smartgift-AI/agent-unit-testing.git ~/.smartgift/agent-unit-testing && ~/.smartgift/agent-unit-testing/sg-install-unit-testing.sh --global
```
*Lệnh trên tự động clone vào `~/.smartgift/` và kích hoạt toàn cục trên máy tính.*

---

## 🛠️ Hướng Dẫn Sử Dụng Nhanh

### Bước 1: Khởi Tạo Vào Dự Án Laravel Bất Kỳ
Mở terminal tại thư mục dự án Laravel của bạn:
```bash
cd /duong-dan/toi/du-an-laravel
sg-install-unit-testing.sh
```

### Bước 2: Chuẩn Bị Môi Trường
Mở Claude Code (`claude`) tại thư mục dự án và chạy skill:
```bash
/laravel-test-setup --install
```
Agent sẽ tự động kiểm tra `composer.json`, kiểm tra database test SQLite và tự cài đặt các package còn thiếu.

### Bước 3: Sinh Unit Test Tự Động
Chỉ định class, thư mục, hoặc phủ toàn bộ dự án:
```bash
# 🌟 1 lệnh duy nhất phủ test toàn bộ dự án (cam kết không sót file):
/laravel-unit-test --all

# Cho cả thư mục / module:
/laravel-unit-test app/Services/

# Cho các file vừa sửa trên Git (trước khi tạo PR):
/laravel-unit-test --changed

# Cho 1 class đơn lẻ:
/laravel-unit-test app/Services/PaymentService.php
```

### Bước 4: Chạy Kiểm Thử
Sử dụng script thông minh tự động nhận diện Docker / Sail / Local:
```bash
./test-runner.sh --filter=PaymentServiceTest
```

### Bước 5: Cập Nhật Bộ Công Cụ Khi Có Phiên Bản Mới
Thành viên đứng ở bất kỳ đâu chỉ cần gõ:
```bash
sg-test-update
```

---

## 🎯 Ma Trận Tương Thích (Compatibility Matrix)

| Thành phần | Phiên bản hỗ trợ & Tương thích tương lai |
| :--- | :--- |
| **PHP** | 8.0, 8.1, 8.2, 8.3, **8.4+** (Hỗ trợ Property Hooks, Asymmetric Visibility) |
| **Laravel** | 9.x, 10.x, 11.x, **12.x & 13.x (Latest & Future-ready)** |
| **PHPUnit** | 9.x (DocBlock), 10.x, **11.x & 12.x** (PHP 8 Attributes `#[Test]`, `#[DataProvider]`) |
| **Pest PHP** | v2.x & **v3.x** (Hỗ trợ Architectural Testing `arch()`, Mutation testing) |
| **Mocking** | Mockery, PHPUnit Test Doubles, Laravel Built-in Fakes, `Concurrency::fake()`, `Context::fake()` |
| **Database** | SQLite In-Memory (`:memory:`), MySQL Test DB |
| **Môi trường** | Docker Compose, Laravel Sail, Native PHP CLI |

---

## 📜 Giấy Phép & Bản Quyền
Phát triển bởi Smartgift AI Team. Phục vụ tự động hóa quy trình kiểm thử phần mềm đạt chuẩn chất lượng cao.