# 🚀 Laravel Unit Testing Toolkit for Claude Code > **Bộ công cụ tự động hóa toàn diện cho việc thiết lập môi trường, sinh Unit Test chuẩn AAA và kiểm thử tự động cho bất kỳ dự án PHP & Laravel nào (từ Laravel 8 đến 13+, PHP 8.0 đến 8.4+).** Được phát triển dưới dạng mã nguồn mở (Open Source) dành cho mọi lập trình viên, đội ngũ kỹ thuật và cộng đồng phát triển phần mềm. --- ## 📑 MỤC LỤC 1. [Điểm Nổi Bật & Tính Năng Cốt Lõi](#1-điểm-nổi-bật--tính-năng-cốt-lõi) 2. [Cấu Trúc Thư Mục Repository](#2-cấu-trúc-thư-mục-repository) 3. [Hướng Dẫn Cài Đặt Lần Đầu](#3-hướng-dẫn-cài-đặt-lần-đầu) 4. [Khởi Tạo Cho Một Dự Án Laravel Bất Kỳ](#4-khởi-tạo-cho-một-dự-án-laravel-bất-kỳ) 5. [Quy Trình 5 Bước Sinh & Chạy Unit Test](#5-quy-trình-5-bước-sinh--chạy-unit-test) - [Bước 1: Quét Môi Trường & Cài Packages (`/laravel-test-setup`)](#bước-1-quét-môi-trường--cài-packages-laravel-test-setup) - [Bước 2: Sinh Unit Test Tự Động (`/laravel-unit-test`)](#bước-2-sinh-unit-test-tự-động-laravel-unit-test) - [Bước 3: Chạy Test Thông Minh (`test-runner.sh`)](#bước-3-chạy-test-thông-minh-test-runnersh) - [Bước 4: Thẩm Định & Chấm Điểm Test (`/laravel-test-review`)](#bước-4-thẩm-định--chấm-điểm-test-laravel-test-review) - [Bước 5: Sinh Mã Giả Lập Nhanh (`/laravel-mock-helper`)](#bước-5-sinh-mã-giả-lập-nhanh-laravel-mock-helper) 6. [Cách Cập Nhật Bộ Công Cụ Khi Có Nâng Cấp](#6-cách-cập-nhật-bộ-công-cụ-khi-có-nâng-cấp) 7. [Giải Đáp Thắc Mắc & Xử Lý Lỗi (FAQ & Troubleshooting)](#7-giải-đáp-thắc-mắc--xử-lý-lỗi-faq--troubleshooting) 8. [Bảng Tra Cứu Toàn Bộ Lệnh (Full Cheat Sheet)](#8-bảng-tra-cứu-toàn-bộ-lệnh-full-cheat-sheet) 9. [Ma Trận Tương Thích & Bản Quyền](#9-ma-trận-tương-thích--bản-quyền) --- ## 1. Điểm Nổi Bật & Tính Năng Cốt Lõi 1. **Chuẩn Hóa Môi Trường Tự Động (Bước 0)**: - Tự động nhận diện runtime: **Laravel Sail**, **Docker Compose** (service `app`/`php`), hoặc **PHP CLI cục bộ**. - Bảo vệ an toàn database: thiết lập SQLite In-Memory (`:memory:`), tuyệt đối không chạm hay làm mất dữ liệu dev/local. - Tự động cài đặt các package còn thiếu (`mockery`, `faker`, `paratest`) thẳng vào đúng container đang chạy. 2. **Triết Lý Kiểm Thử Đỉnh Cao (AAA & Isolation)**: - Đảm bảo tính cô lập tuyệt đối (Zero Leakage): mock toàn bộ external services, APIs, queues, mails. - Không over-mocking: giữ nguyên thực thể DTO, Value Object, Collection thật. - Chặn đứng lỗi anti-pattern mock chuỗi Eloquent Query Builder dễ vỡ. 3. **Bao Phủ Trọn Vẹn 13 Tầng Kiến Trúc Laravel**: - Services, Actions, Controllers, FormRequests, Custom Rules, Repositories, Query Builders, Models, Jobs, Events, Listeners, Middlewares, Policies, Notifications, Mailables, Artisan Commands, View Components, Observers, Exceptions. 4. **Chế Độ Autopilot Khép Kín (`/laravel-unit-test --all --run`)**: - Chỉ với 1 lệnh duy nhất: tự động lập manifest quét toàn bộ dự án, viết test tuần tự không sót file, **viết đến đâu tự chạy test đến đó**, và **tự động sửa lỗi (Auto-Healing)** cho đến khi PASS 100%. 5. **Sẵn Sàng Cho Tương Lai & Architecture Testing**: - Hỗ trợ đầy đủ tính năng mới nhất của **PHP 8.4+** (Property Hooks, Asymmetric Visibility). - Tích hợp bộ kiểm thử kiến trúc toàn dự án **Architecture Test** bằng Pest v3 / PHPUnit (`arch()`). - Cung cấp sẵn file cấu hình CI/CD Quality Gate (GitHub Actions, GitLab CI) chặn merge PR nếu code coverage < 80%. --- ## 2. Cấu Trúc Thư Mục Repository ```text agent-unit-testing/ ├── install.sh # Script cài đặt chính (hỗ trợ Toàn cục & Theo dự án) ├── .claude/ │ └── skills/ # Bộ 4 Skills tích hợp cho Claude Code │ ├── laravel-test-setup/ # Kiểm tra môi trường & tự cài đặt dependencies │ ├── laravel-unit-test/ # Sinh Unit Test tự động (hỗ trợ Autopilot --all --run) │ ├── laravel-test-review/ # Chấm điểm chất lượng test theo thang 100 & bắt lỗi anti-patterns │ └── laravel-mock-helper/ # Sinh mã Mockery & Laravel Fakes nhanh │ ├── docs/ # 10 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, SQLite in-memory & Docker │ ├── 01-overview-and-principles.md # Triết lý Unit Test: AAA, cách ly, ranh giới Feature test │ ├── 02-test-frameworks.md # So sánh & cú pháp PHPUnit 10/11 vs Pest PHP v2/v3 │ ├── 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 chạy 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/ # 13 Cẩm Nang Chi Tiết Cho Từng Component Laravel │ ├── 01-services-and-actions.md # Service Layer, Action classes, DTOs │ ├── 02-controllers.md # API & Web Controllers │ ├── 03-form-requests-and-rules.md # FormRequests & 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, retry logic, failed() │ ├── 07-events-and-listeners.md # Event payloads & Listener handlers │ ├── 08-middlewares.md # Request interception, Auth, Role, Tenant │ ├── 09-policies-and-gates.md # Policies authorization logic (can/cannot) │ ├── 10-notifications-and-mail.md # Mailables & Notification channels │ ├── 11-artisan-commands.md # Console arguments, options, exit codes │ ├── 12-view-components-and-blade.md # Blade View Components & directives │ └── 13-observers-and-exceptions.md # Model Observers & Custom Exceptions │ ├── templates/ # Templates Mẫu Chuẩn │ ├── configs/ # phpunit.xml.dist, .env.testing, Pest.php │ ├── docker/ # Smart test-runner.sh & docker-compose.test.yml │ ├── ci/ # GitHub Actions & GitLab CI quality gates │ ├── phpunit/ # 8 Component templates + ArchitectureTest │ └── pest/ # 8 Component templates + ArchitectureTest │ ├── rules/ # Bộ Quy Tắc & Tiêu Chí Đánh Giá │ ├── system-prompt-unit-test.md # System prompt cốt lõi cho AI │ ├── edge-cases-matrix.md # Ma trận kịch bản biên (Null, Boundary, Errors) │ └── verification-checklist.md # Checklist 10 bước tự kiểm tra trước khi xuất code │ ├── LICENSE # Giấy phép mã nguồn mở MIT └── README.md # Tài liệu hướng dẫn chính ``` --- ## 3. Cài Đặt Trực Tiếp Vào Source Code (Không Cần Clone Repo) Bất kỳ ai muốn sử dụng bộ công cụ này **KHÔNG CẦN phải clone source code công cụ về máy**. Chỉ cần mở Terminal, `cd` vào thư mục dự án Laravel của bạn và chạy **đúng 1 dòng lệnh**: ### 🌟 1 Dòng Lệnh Cài Đặt Từ Xa (Remote 1-Line Installer) ```bash cd /duong-dan/toi/source-code-laravel-cua-ban # Chạy lệnh cài đặt từ xa: curl -fsSL https://raw.githubusercontent.com//agent-unit-testing/main/install.sh | bash ``` *(Đối với thành viên trong nội bộ team Smartgift hoặc khi dùng Git SSH server):* ```bash cd /duong-dan/toi/source-code-laravel-cua-ban # Cài đặt trực tiếp qua Git mà không cần lưu repo công cụ: bash <(git archive --remote=ssh://git@ssh-git.smartgift.io.vn:2222/Smartgift-AI/agent-unit-testing.git main install.sh | tar -xO) ``` --- ### 🎯 Quy Trình Tự Động Diễn Ra Ngầm: 1. Script sẽ tải các tài nguyên cần thiết từ xa vào thư mục tạm `/tmp/`. 2. Tự động cấy trực tiếp vào source code của bạn: - Thư mục `.claude/skills/` (với trọn bộ 4 Skills viết test tự động). - Thư mục `.claude/testing-docs/` (cẩm nang quy chuẩn 13 tầng Laravel). - Script chạy test thông minh `./test-runner.sh` (tự bắt Docker/Sail/Local). - Script cài package test `./setup-test-deps.sh`. - Tự động cấu hình SQLite In-Memory `:memory:` an toàn vào `phpunit.xml`. - Tự động tạo GitHub Actions CI `.github/workflows/unit-tests.yml`. 3. Tự động xóa sạch thư mục tạm, **hoàn toàn không lưu lại rác hay repository công cụ trên máy của bạn**! --- ## 4. Tùy Chọn: Cài Đặt Toàn Cục Cho Toàn Máy Tính (Global Mode) Nếu bạn là lập trình viên muốn cài 1 lần duy nhất cho toàn bộ máy tính (để mọi source code mở Claude Code lên đều tự có sẵn các lệnh): ```bash curl -fsSL https://raw.githubusercontent.com//agent-unit-testing/main/install.sh | bash -s -- --global ``` 🎯 **Lợi ích:** - Tự động cài đặt 4 Skills vào `~/.claude/skills/`. - Đăng ký lệnh `sg-test-init` (hoặc `laravel-test-init`) vào Terminal để gõ ở bất kỳ thư mục nào cũng tự tạo `test-runner.sh`. --- ## 5. Quy Trình Trọn Vẹn: Từ Bắt Đầu Đến Hoàn Thành Viết Unit Test Dưới đây là **kịch bản thực chiến trọn vẹn từ A đến Z** khi bạn áp dụng vào một source code Laravel thực tế: ```text ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ 1. CÀI ĐẶT │ ──> │ 2. SETUP ENV │ ──> │ 3. AUTOPILOT │ ──> │ 4. NGHIỆM THU │ │ curl | bash │ │ test-setup │ │ unit-test --all│ │ Coverage > 80% │ └────────────────┘ └────────────────┘ └────────────────┘ └────────────────┘ ``` --- ### 🔹 Giai đoạn 1: Cài đặt công cụ vào Source Code (Chỉ mất 5 giây) Mở terminal, `cd` vào thư mục source code Laravel của bạn và chạy 1 dòng lệnh: ```bash cd /duong-dan/toi/source-code-laravel curl -fsSL https://raw.githubusercontent.com//agent-unit-testing/main/install.sh | bash ``` ✅ **Kết quả**: Source code đã được tích hợp bộ Skills, cẩm nang rules, script `./test-runner.sh` và cấu hình SQLite `:memory:` an toàn. --- ### 🔹 Giai đoạn 2: Khởi động Claude Code & Chuẩn hóa môi trường Mở Claude Code ngay tại thư mục source code: ```bash claude ``` Chạy lệnh kiểm tra và tự động cài đặt thư viện kiểm thử còn thiếu: ```text /laravel-test-setup --install ``` ✅ **Kết quả**: AI tự động kiểm tra `composer.json`, nếu thiếu `mockery`, `faker`, `paratest` -> AI tự động kích hoạt lệnh cài đặt vào container Docker hoặc môi trường Local của bạn và xác nhận môi trường chuyển sang trạng thái "Xanh" (100% Sẵn sàng). --- ### 🔹 Giai đoạn 3: Ra lệnh viết toàn bộ Unit Test & Tự động chạy test luôn Chỉ cần gõ **đúng 1 lệnh Autopilot**: ```text /laravel-unit-test --all --run ``` **Quá trình AI thực hiện tự động hoàn toàn:** 1. **Quét & Lập Manifest**: AI quét toàn bộ `app/Services/`, `app/Actions/`, `app/Http/Requests/`, `app/Jobs/`, `app/Policies/`, `app/Rules/`,... và tạo file kiểm soát `tests/.test-manifest.json` (ví dụ: Tổng cộng 36 files). 2. **Viết test tuần tự**: AI duyệt từng file `[1/36]`, `[2/36]`... sinh mã test chuẩn AAA, đầy đủ kịch bản Happy Path, Edge Cases (0, âm, null, rỗng) và Exception. 3. **Chạy test & Tự động sửa lỗi (Auto-Healing)**: - Viết xong file nào, AI tự động gọi `./test-runner.sh --filter=` để chạy test file đó ngay. - Nếu test bị ĐỎ (Fail) do thiếu mock hoặc sai tham số -> AI tự động đọc log lỗi, tự sửa code test ngay tại chỗ cho đến khi XANH (Pass 100%). --- ### 🔹 Giai đoạn 4: Nghiệm thu kết quả & Kiểm tra Code Coverage Sau khi hoàn tất toàn bộ danh sách trong manifest, AI sẽ tự động chạy: ```bash ./test-runner.sh --coverage ``` Bảng báo cáo nghiệm thu sẽ xuất hiện: ```markdown 🎉 HOÀN TẤT VIẾT VÀ TEST TOÀN BỘ DỰ ÁN: ✓ Tổng số class đã phủ test: 36/36 files (100%) ✓ Tổng số test cases được sinh: 142 test cases ✓ Kết quả thực thi: 142 PASSED (0 FAILED) ✓ Code Coverage: 86.4% (Đạt tiêu chuẩn Quality Gate > 80%) ``` --- ### 🔹 Giai đoạn 5 (Tùy chọn): Các chế độ chạy linh hoạt khác Nếu không muốn chạy cả dự án, bạn có thể chọn các chế độ linh hoạt sau: - **Chỉ viết cho 1 class & test luôn**: ```text /laravel-unit-test app/Services/PaymentService.php --run ``` - **Chỉ viết cho cả 1 thư mục & test luôn**: ```text /laravel-unit-test app/Services/ --run ``` - **Chỉ viết cho các file vừa sửa đổi trên Git trước khi tạo PR**: ```text /laravel-unit-test --changed --run ``` - **Thẩm định & Chấm điểm 1 file test có sẵn (thang 100)**: ```text /laravel-test-review tests/Unit/Services/PaymentServiceTest.php ``` - **Sinh nhanh khối mã Mockery cho một Interface**: ```text /laravel-mock-helper App\Contracts\PaymentGatewayInterface ``` --- ## 6. Cách Cập Nhật Bộ Công Cụ Khi Có Nâng Cấp Khi repository công cụ trên Git có tài liệu mới hoặc nâng cấp rules: ### 🌟 Cách 1: Cập nhật trực tiếp vào source code hiện tại Đứng tại thư mục source code Laravel của bạn và chạy lại dòng lệnh cài đặt: ```bash curl -fsSL https://raw.githubusercontent.com//agent-unit-testing/main/install.sh | bash ``` *(Script sẽ tự động kéo bản mới nhất và ghi đè cập nhật vào `.claude/skills/` và runner của source code).* --- ### ⚡ Cách 2: Nếu bạn đã cài đặt chế độ Toàn Cục (Global) Bất kể bạn đang đứng ở thư mục nào trong Terminal, chỉ cần gõ: ```bash laravel-test-update ``` *(hoặc alias: `sg-test-update`)* Lệnh sẽ tự động kéo bản cập nhật mới nhất từ Git về máy bạn trong 3 giây. --- ## 7. Giải Đáp Thắc Mắc & Xử Lý Lỗi (FAQ & Troubleshooting) ### Q1: Tại sao tôi gõ `./install.sh` thì bị báo `zsh: no such file or directory`? 👉 **Trả lời**: Ký hiệu `./` nghĩa là tìm file ngay trong thư mục hiện tại. Khi bạn đã `cd` sang một dự án khác, thư mục đó không có file này. **Cách sửa**: Bỏ dấu `./` đi, chỉ cần gõ thẳng tên lệnh toàn cục đã được đăng ký: ```bash laravel-test-init # Hoặc: laravel-unit-test-setup ``` ### Q2: Tôi cài đặt vào một thư mục trống nhưng bị báo chưa có `artisan` hoặc `composer.json`? 👉 **Trả lời**: Mặc định script sẽ kiểm tra để tránh cài nhầm vào thư mục không phải Laravel. Nếu bạn muốn cài đặt trước vào thư mục trống, hãy thêm cờ `--force`: ```bash install.sh --force # Hoặc: laravel-test-init --force ``` ### Q3: Chạy test trên SQLite `:memory:` bị lỗi hàm MySQL (`JSON_CONTAINS`, `DATE_FORMAT`)? 👉 **Trả lời**: Mở tài liệu `docs/07-troubleshooting-and-debugging.md` (mục 5) để xem cách đăng ký hàm giả lập trong `setUp()`, hoặc chuyển kết nối test sang một container MySQL test riêng. ### Q4: Làm sao chặn merge Pull Request nếu Code Coverage dưới 80%? 👉 **Trả lời**: Bộ công cụ đã tạo sẵn file `.github/workflows/unit-tests.yml` (hoặc `.gitlab-ci.yml`). Pipeline CI sẽ tự động chạy song song trên PHP 8.2, 8.3, 8.4 và tự động từ chối merge nếu độ phủ < 80%. --- ## 8. Bảng Tra Cứu Toàn Bộ Lệnh (Full Cheat Sheet) | Nhiệm Vụ | Lệnh Terminal / Claude Code | Ngữ Cảnh Sử Dụng | | :--- | :--- | :--- | | **Cài đặt từ xa (Không cần clone)** | `curl -fsSL /install.sh \| bash` | Đứng tại source code Laravel và chạy 1 dòng duy nhất | | **Cài đặt toàn cục (Global Mode)** | `curl -fsSL /install.sh \| bash -s -- --global` | Cài vào máy dùng cho mọi folder | | **Cài đặt vào thư mục trống** | `curl -fsSL /install.sh \| bash -s -- . --force` | Dùng khi thư mục chưa có `composer.json` | | **Khởi tạo test runner nhanh** | `laravel-test-init` (hoặc `sg-test-init`) | Gõ tại terminal của bất kỳ dự án nào | | **Cập nhật bộ công cụ (1-Click)** | `laravel-test-update` (hoặc `sg-test-update`) | Kéo bản mới nhất từ Git về máy mọi lúc | | **Quét & Setup môi trường test** | `/laravel-test-setup` | Chạy trong Claude Code để kiểm tra cấu hình | | **Tự động cài gói composer thiếu**| `/laravel-test-setup --install` | Cài `mockery`, `faker`, `paratest` vào container | | **Autopilot: Viết xong test luôn**| `/laravel-unit-test --all --run` | 1 lệnh tự setup, viết test cả dự án, chạy test & tự fix | | **Sinh test cho 1 file & test luôn**| `/laravel-unit-test app/.../Service.php --run`| Sinh test cho 1 class và chạy test kiểm tra ngay | | **Sinh test cả thư mục** | `/laravel-unit-test app/Services/ --run` | Khi cần phủ test cho cả 1 folder / module | | **Quét dự án lớn chưa có test** | `/laravel-unit-test --untested` | Tìm các class thiếu test để sinh hàng loạt | | **Sinh test cho Git Diff** | `/laravel-unit-test --changed --run` | Trước khi tạo Pull Request trên Git | | **Review chất lượng file test** | `/laravel-test-review tests/.../Test.php`| Chấm điểm thang 100 & bắt lỗi anti-patterns | | **Sinh code Mockery nhanh** | `/laravel-mock-helper MyInterface` | Sinh code mock sẵn dùng | | **Chạy test tự nhận diện** | `./test-runner.sh --filter=MyTest` | Tự bắt Docker / Sail / Local | | **Tra cứu sửa lỗi** | Đọc `docs/07-troubleshooting-and-debugging.md` | Sửa 10 lỗi thường gặp nhất | | **Tra cứu 7 ca khó** | Đọc `docs/09-advanced-edge-cases.md` | `DB::transaction()`, Trait, Upload file, Queue | | **Tra cứu sửa lỗi** | Đọc `docs/07-troubleshooting-and-debugging.md` | Sửa 10 lỗi thường gặp nhất | | **Tra cứu 7 ca khó** | Đọc `docs/09-advanced-edge-cases.md` | `DB::transaction()`, Trait, Upload file, Queue | --- ## 9. Ma Trận Tương Thích & Bản Quyền | Thành Phần | Phiên Bản Hỗ Trợ | | :--- | :--- | | **PHP** | 8.0, 8.1, 8.2, 8.3, **8.4+** (Property Hooks, Asymmetric Visibility) | | **Laravel** | 8.x, 9.x, 10.x, 11.x, **12.x & 13.x (Kiến trúc hiện đại)** | | **PHPUnit** | 9.x (DocBlock fallback), 10.x, **11.x & 12.x** (PHP 8 Attributes `#[Test]`) | | **Pest PHP** | v2.x & **v3.x** (Architecture 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 | | **Hệ Điều Hành** | macOS, Linux, WSL2 (Windows), Docker, CI/CD Environments | ### Giấy Phép (License) Phát hành theo giấy phép mã nguồn mở [MIT License](LICENSE). Bất kỳ ai cũng có quyền tự do sử dụng, chỉnh sửa và đóng góp cho dự án.