8.3 KiB
8.3 KiB
🚀 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
- 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.shtự nhận diện môi trường container.
- 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.
- 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.
- 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
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:
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:
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:
/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ạy Test Ngay
Chỉ định class, thư mục, hoặc phủ toàn bộ dự án:
# 🌟 1 lệnh duy nhất Autopilot: Tự động viết test cả dự án & TỰ CHẠY TEST LUÔN:
/laravel-unit-test --all --run
# Sinh test cho 1 file & tự động chạy test kiểm tra ngay:
/laravel-unit-test app/Services/PaymentService.php --run
# Cho cả thư mục / module & test luôn:
/laravel-unit-test app/Services/ --run
# Cho các file vừa sửa trên Git & test luôn (trước khi tạo PR):
/laravel-unit-test --changed --run
Bước 4: Chạy Kiểm Thử
Sử dụng script thông minh tự động nhận diện Docker / Sail / Local:
./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õ:
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.