🚀 PHP 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 & Integration Test chuẩn AAA và kiểm thử tự động cho bất kỳ dự án PHP nào. Hỗ trợ chuyên sâu và tách biệt cho cả hai framework phổ biến: Laravel (8 đến 13+) và CakePHP (3.x đến 5.x+), tương thích PHP 7.4 đế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
2. Cấu Trúc Thư Mục Repository
3. Cài Đặt Nhanh (1 Dòng Lệnh Duy Nhất)
4. 🔴 PHẦN 1: HƯỚNG DẪN DÀNH RIÊNG CHO LARAVEL
   • 4.1. Kiến Trúc & 13 Tầng Hỗ Trợ
   • 4.2. Quy Trình Thực Chiến 5 Bước Cho Laravel
   • 4.3. Bảng Tra Cứu Lệnh Laravel (Cheat Sheet)
5. 🔵 PHẦN 2: HƯỚNG DẪN DÀNH RIÊNG CHO CAKEPHP
   • 5.1. Kiến Trúc & 10 Tầng Hỗ Trợ
   • 5.2. Quy Trình Thực Chiến 5 Bước Cho CakePHP
   • 5.3. Bảng Tra Cứu Lệnh CakePHP (Cheat Sheet)
6. Cập Nhật Bộ Công Cụ
7. Giải Đáp Thắc Mắc & Xử Lý Lỗi (FAQ)
8. 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 Framework (Laravel hay CakePHP) và runtime: Docker Compose, Laravel Sail, 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 bẩn/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, 3rd party APIs, queues, mails.
   • Không over-mocking: giữ nguyên thực thể DTO, Value Object, Collection, Entity thật.
3. Chế Độ Autopilot Khép Kín (--all --run):
   • 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%.
4. 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 kiểm thử kiến trúc toàn dự án 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

agent-unit-testing/
├── install.sh                               # Script cài đặt chính (hỗ trợ Toàn cục & Theo dự án)
├── .claude/
│   └── skills/                              # Bộ Skills tích hợp cho Claude Code
│       │── # Skills Dành Cho CakePHP:
│       ├── cakephp-unit-test/               # Sinh Test tự động cho CakePHP (Table, Controller, Service...)
│       ├── cakephp-test-setup/              # Quét môi trường & cấu hình Datasources.test cho CakePHP
│       ├── cakephp-test-review/             # Chấm điểm chất lượng test CakePHP theo thang 100
│       ├── cakephp-mock-helper/             # Sinh nhanh mã Mock PHPUnit/Mockery cho CakePHP
│       │── # Skills Dành Cho Laravel:
│       ├── laravel-test-setup/              # Kiểm tra môi trường & tự cài đặt dependencies cho Laravel
│       ├── laravel-unit-test/               # Sinh Unit Test tự động cho Laravel
│       ├── laravel-test-review/             # Chấm điểm chất lượng test Laravel
│       └── laravel-mock-helper/             # Sinh mã Mockery & Laravel Fakes nhanh
│
├── docs/                                    # Cẩm Nang Kiến Thức & Quy Chuẩn Cốt Lõi
│   ├── cakephp/                             # Cẩm nang chuyên sâu CakePHP (Testing Guide & 10 Components)
│   ├── components/                          # Cẩm nang 13 tầng component Laravel
│   ├── 00-environment-and-setup.md          # Setup dependencies, SQLite in-memory & Docker
│   ├── 01-overview-and-principles.md        # Triết lý Unit Test: AAA, cách ly
│   ├── 02-test-frameworks.md                # So sánh PHPUnit vs Pest PHP
│   ├── 03-mocking-strategies.md             # Toàn tập Mockery vs Fakes
│   ├── 05-anti-patterns.md                  # 12 lỗi cấm kỵ khi viết Unit Test
│   └── 10-sonarqube-100-percent-coverage.md # Chiến lược đạt 100% Coverage trên SonarQube
│
├── templates/                               # Templates Mẫu Chuẩn
│   ├── cakephp/                             # Templates PHPUnit & Config cho CakePHP
│   │   ├── phpunit/                         # 10 Component templates (Table, Entity, Controller, Command...)
│   │   └── configs/                         # phpunit.xml.dist & app_local.test.php (:memory:)
│   ├── phpunit/                             # Templates PHPUnit cho Laravel (8 component templates)
│   ├── pest/                                # Templates Pest PHP cho Laravel
│   └── docker/                              # Smart test-runner.sh (tự nhận diện Laravel & CakePHP)
│
├── rules/                                   # Bộ Quy Tắc & Tiêu Chí Đánh Giá
├── 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 Nhanh (1 Dòng Lệnh Duy Nhất)

Bất kỳ ai muốn sử dụng bộ công cụ này (trên máy cá nhân, server hay container) KHÔNG CẦN phải clone repository về máy.

🌟 Cách 1: Cài trực tiếp vào Source Code của bạn (Khuyên dùng)

Mở Terminal, cd vào thư mục dự án của bạn (dù là Laravel hay CakePHP) và chạy:

cd /duong-dan/toi/source-code-cua-ban

# Cài đặt trực tiếp qua HTTPS công khai (không cần SSH key, không cần tài khoản):
curl -fsSL https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install.sh | bash

(Nếu thư mục đang trống hoặc chưa có composer.json, thêm cờ --force vào cuối: ... | bash -s -- --force).

🎯 Cơ chế tự động:

• Script tự động phát hiện dự án là Laravel hay CakePHP.
• Tự động cấy bộ Skills tương ứng vào .claude/skills/.
• Tự động đồng bộ tài liệu vào .claude/testing-docs/.
• Tự động tạo Smart Runner ./test-runner.sh (tự nhận diện runner và Docker).
• Tự động thiết lập kết nối SQLite In-Memory an toàn (không làm mất dữ liệu dev).

---

⚡ Cách 2: Cài Đặt Toàn Cục Cho Máy Tính (Global Mode)

Nếu muốn cài 1 lần duy nhất để dùng cho mọi dự án trên máy:

curl -fsSL https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install.sh | bash -s -- --global

🎯 Lợi ích:

• Đăng ký sẵn các lệnh tiện ích trong Terminal: laravel-test-init, cakephp-test-init, sg-test-init.
• Mọi thư mục khi mở Claude Code đều nhận diện sẵn trọn bộ skills của cả 2 framework.

---

4. 🔴 PHẦN 1: HƯỚNG DẪN DÀNH RIÊNG CHO LARAVEL

4.1. Kiến Trúc & 13 Tầng Hỗ Trợ Laravel

Bộ công cụ sinh test chuẩn xác cho 13 tầng kiến trúc Laravel:

1. Services & Actions (app/Services/, app/Actions/)
2. Controllers (app/Http/Controllers/)
3. Form Requests & Rules (app/Http/Requests/, app/Rules/)
4. Repositories & Query Builders (app/Repositories/)
5. Models (app/Models/ - Accessors, Mutators, Custom Casts)
6. Jobs & Queues (app/Jobs/ - kiểm thử bắt buộc handle() và failed())
7. Events & Listeners (app/Events/, app/Listeners/)
8. Middlewares (app/Http/Middleware/)
9. Policies & Gates (app/Policies/)
10. Notifications & Mail (app/Notifications/, app/Mail/)
11. Artisan Commands (app/Console/Commands/)
12. View Components (app/View/Components/)
13. Observers & Exceptions (app/Observers/, app/Exceptions/)

---

4.2. Quy Trình Thực Chiến 5 Bước Cho Laravel

┌────────────────┐     ┌────────────────┐     ┌────────────────┐     ┌────────────────┐
│  1. CÀI ĐẶT    │ ──> │ 2. SETUP ENV   │ ──> │ 3. SINH TEST   │ ──> │ 4. CHẠY & REVIEW│
│  curl | bash   │     │ laravel-setup  │     │ laravel-test   │     │ ./test-runner  │
└────────────────┘     └────────────────┘     └────────────────┘     └────────────────┘

🔹 Bước 1: Khởi động Claude Code & Setup môi trường

Đứng tại thư mục Laravel và gõ:

claude

Chạy lệnh kiểm tra môi trường:

/laravel-test-setup --install

AI sẽ tự động kiểm tra composer.json, thiết lập SQLite :memory: trong phpunit.xml, kiểm tra Sail / Docker và tự động cài mockery, faker, paratest nếu thiếu.

---

🔹 Bước 2: Sinh Unit Test Tự Động

🏆 Cách Khuyên Dùng Cho Dự Án Lớn: Viết Tập Trung Theo Từng Tầng (Batch Mode)

Để tiết kiệm token và đạt độ phủ 100% từng nhánh SonarQube, hãy để AI viết sâu từng tầng:

# 1. Viết toàn bộ tầng Services:
/laravel-unit-test app/Services/

# 2. Viết tiếp tầng Actions:
/laravel-unit-test app/Actions/

# 3. Viết tiếp FormRequests & Custom Rules:
/laravel-unit-test app/Http/Requests/
/laravel-unit-test app/Rules/

# 4. Viết tiếp Jobs, Listeners, Policies:
/laravel-unit-test app/Jobs/
/laravel-unit-test app/Policies/

🌟 Cách Dành Cho Dự Án Vừa & Nhỏ: Autopilot Khép Kín

/laravel-unit-test --all --run

AI tự động quét toàn bộ app/, viết test tuần tự, viết đến đâu tự gọi ./test-runner.sh đến đó và tự sửa lỗi nếu test fail.

⚡ Các chế độ sinh test khác:

• Viết cho 1 file & test luôn:

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

• Viết test cho các file vừa sửa đổi trên Git:

  /laravel-unit-test --changed
  

• Quét danh sách class thiếu test:

  /laravel-unit-test --untested
  

---

🔹 Bước 3: Chạy Test Ngoài Terminal & Đo Độ Phủ SonarQube

Quay ra terminal và chạy:

# Chạy toàn bộ test:
./test-runner.sh

# Chạy 1 test cụ thể:
./test-runner.sh --filter=PaymentServiceTest

# Đo độ phủ code và xuất file cho SonarQube:
./test-runner.sh --coverage-clover coverage.xml

---

🔹 Bước 4: Thẩm Định & Chấm Điểm Test (Reviewer)

Nếu muốn kiểm tra xem 1 file test có đạt chuẩn AAA và không bị anti-pattern:

/laravel-test-review tests/Unit/Services/PaymentServiceTest.php

---

🔹 Bước 5: Sinh Nhanh Mã Mock Cho Interface / Service

/laravel-mock-helper App\Contracts\PaymentGatewayInterface

---

4.3. Bảng Tra Cứu Lệnh Laravel (Cheat Sheet)

Nhiệm Vụ	Lệnh / Cú Pháp	Mô Tả
Setup môi trường	/laravel-test-setup	Kiểm tra cấu hình testing & database
Cài packages thiếu	/laravel-test-setup --install	Tự động cài mockery, faker, paratest
Autopilot toàn dự án	/laravel-unit-test --all --run	Quét toàn bộ app/, viết test & tự sửa lỗi
Sinh test cả thư mục	/laravel-unit-test app/Services/	Viết hàng loạt cho 1 folder
Sinh test 1 file & chạy test	/laravel-unit-test app/.../File.php --run	Viết cho 1 class và kiểm tra ngay
Quét class thiếu test	/laravel-unit-test --untested	Liệt kê các class chưa có file test
Sinh test cho Git Diff	/laravel-unit-test --changed --run	Viết test cho code vừa sửa trước khi tạo PR
Chấm điểm file test	/laravel-test-review tests/.../Test.php	Chấm điểm thang 100, bắt lỗi anti-patterns
Sinh nhanh mã Mockery	/laravel-mock-helper MyInterface	Tạo code mock sẵn dùng
Chạy test terminal	./test-runner.sh	Tự bắt Sail / Docker / Local PHP

---

5. 🔵 PHẦN 2: HƯỚNG DẪN DÀNH RIÊNG CHO CAKEPHP

5.1. Kiến Trúc & 10 Tầng Hỗ Trợ CakePHP

Bộ công cụ hỗ trợ toàn diện các phiên bản CakePHP 3.x, 4.x và 5.x+ (PHP 7.4 - 8.4+):

1. Table Classes (ORM) (src/Model/Table/*Table.php): Test validationDefault, buildRules, custom finders, save/delete với Fixtures.
2. Entity Classes (src/Model/Entity/*.php): Test password hashing, accessible fields, virtual fields (_getFullName()).
3. Controller Classes (src/Controller/*Controller.php): Dùng Cake\TestSuite\IntegrationTestTrait, test HTTP status (200/302/403/404/422), session, auth, CSRF & Security tokens.
4. Domain Services (src/Service/*.php): Test logic nghiệp vụ thuần túy với mocked dependencies.
5. Console Commands (src/Command/*Command.php): Dùng Cake\Console\TestSuite\ConsoleIntegrationTestTrait, test exit codes (CODE_SUCCESS), arguments, options, output.
6. Controller Components (src/Controller/Component/*.php): Test logic dùng chung của Controllers qua ComponentRegistry.
7. Middlewares (PSR-15) (src/Middleware/*.php): Test ServerRequest & Response flow.
8. Mailers (src/Mailer/*Mailer.php): Dùng Cake\TestSuite\EmailTrait, assert recipient, subject, template body.
9. Forms (src/Form/*Form.php): Test standalone forms (validationDefault(), _execute()).
10. ORM Behaviors (src/Model/Behavior/*.php): Test lifecycle hooks (beforeSave, beforeFind).

---

5.2. Quy Trình Thực Chiến 5 Bước Cho CakePHP

┌────────────────┐     ┌────────────────┐     ┌────────────────┐     ┌────────────────┐
│  1. CÀI ĐẶT    │ ──> │ 2. SETUP ENV   │ ──> │ 3. SINH TEST   │ ──> │ 4. CHẠY & REVIEW│
│  curl | bash   │     │ cakephp-setup  │     │ cakephp-test   │     │ ./test-runner  │
└────────────────┘     └────────────────┘     └────────────────┘     └────────────────┘

🔹 Bước 1: Khởi động Claude Code & Setup môi trường CakePHP

Đứng tại thư mục CakePHP và gõ:

claude

Chạy lệnh kiểm tra môi trường:

/cakephp-test-setup --install

AI sẽ tự động:

• Kiểm tra phiên bản CakePHP (3.x / 4.x / 5.x) & PHP.
• Đảm bảo kết nối Datasources.test trong config/app_local.php hoặc config/app.php trỏ vào SQLite :memory: an toàn (tuyệt đối không đụng database dev thật).
• Kiểm tra testsuite app trong phpunit.xml và cài đặt packages cần thiết.

---

🔹 Bước 2: Sinh Unit & Integration Test Cho CakePHP

🏆 Cách Khuyên Dùng Cho Dự Án Lớn: Viết Tập Trung Theo Từng Tầng (Batch Mode)

# 1. Viết tầng ORM Table (dùng Fixtures & fetchTable):
/cakephp-unit-test src/Model/Table/

# 2. Viết tầng Entities:
/cakephp-unit-test src/Model/Entity/

# 3. Viết tầng Domain Services:
/cakephp-unit-test src/Service/

# 4. Viết tầng Controllers (IntegrationTestTrait với CSRF/Auth):
/cakephp-unit-test src/Controller/

# 5. Viết tầng Console Commands (ConsoleIntegrationTestTrait):
/cakephp-unit-test src/Command/

# 6. Viết tiếp Components, Middlewares, Mailers:
/cakephp-unit-test src/Controller/Component/
/cakephp-unit-test src/Middleware/
/cakephp-unit-test src/Mailer/

🌟 Cách Dành Cho Dự Án Vừa & Nhỏ: Autopilot Khép Kín

/cakephp-unit-test --all --run

AI tự động quét toàn bộ src/, sinh test vào tests/TestCase/ tương ứng, gọi bin/cake test app và tự fix lỗi cho đến khi toàn bộ test pass.

⚡ Các chế độ sinh test CakePHP khác:

• Viết cho 1 file & test luôn:

  /cakephp-unit-test src/Model/Table/ArticlesTable.php --run
  

• Viết test cho các file vừa sửa đổi trên Git:

  /cakephp-unit-test --changed
  

• Quét danh sách class CakePHP thiếu test:

  /cakephp-unit-test --untested
  

---

🔹 Bước 3: Chạy Test Ngoài Terminal & Đo Độ Phủ

Quay ra terminal và chạy:

# Chạy toàn bộ test CakePHP (tự nhận diện Docker hoặc Local):
./test-runner.sh

# Hoặc chạy trực tiếp qua CakePHP CLI:
bin/cake test app

# Chạy 1 test cụ thể:
./test-runner.sh --filter=ArticlesTableTest

# Đo độ phủ code SonarQube:
./test-runner.sh --coverage-clover coverage.xml

---

🔹 Bước 4: Thẩm Định & Chấm Điểm Test CakePHP

Kiểm tra chất lượng và bắt các lỗi anti-patterns (quên CSRF token, tạo new Controller thủ công, truy vấn DB thật thay vì fixture):

/cakephp-test-review tests/TestCase/Controller/ArticlesControllerTest.php

---

🔹 Bước 5: Sinh Nhanh Mã Mock Cho CakePHP

Sinh nhanh mã PHPUnit Native Mock hoặc Mockery cho CakePHP Service hoặc Component:

/cakephp-mock-helper App\Service\PaymentProcessingService

---

5.3. Bảng Tra Cứu Lệnh CakePHP (Cheat Sheet)

Nhiệm Vụ	Lệnh / Cú Pháp	Mô Tả
Setup môi trường	/cakephp-test-setup	Kiểm tra Datasources.test & dependencies
Cài packages thiếu	/cakephp-test-setup --install	Cài đặt phpunit, mockery, faker
Autopilot toàn dự án	/cakephp-unit-test --all --run	Quét toàn bộ src/, sinh test & tự sửa lỗi
Sinh test cả thư mục	/cakephp-unit-test src/Model/Table/	Viết hàng loạt cho Table / Service / Controller
Sinh test 1 file & chạy test	/cakephp-unit-test src/.../File.php --run	Viết cho 1 class và chạy kiểm tra ngay
Quét class thiếu test	/cakephp-unit-test --untested	Liệt kê các class trong src/ chưa có test
Sinh test cho Git Diff	/cakephp-unit-test --changed --run	Viết test cho code vừa thay đổi trên Git
Chấm điểm file test	/cakephp-test-review tests/TestCase/...	Chấm điểm thang 100, kiểm tra chuẩn CakePHP
Sinh nhanh mã Mock	/cakephp-mock-helper MyService	Tạo code mock PHPUnit / Mockery sẵn dùng
Chạy test terminal	./test-runner.sh	Tự bắt Docker (bin/cake test app) hoặc Local

---

6. Cập Nhật Bộ Công Cụ

Khi repository công cụ trên Git có nâng cấp tài liệu hoặc bổ sung tính năng mới:

🌟 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 của bạn và chạy lại dòng lệnh cài đặt:

curl -fsSL https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install.sh | bash

⚡ Cách 2: Nếu đã cài đặt chế độ Toàn Cục (Global)

Gõ lệnh cập nhật ở bất kỳ đâu trong Terminal:

cakephp-test-update   # Dành cho CakePHP
laravel-test-update   # Dành cho Laravel
sg-test-update        # Lệnh chung

---

7. Giải Đáp Thắc Mắc & Xử Lý Lỗi (FAQ)

Q1: Tại sao gõ ./install.sh bị báo zsh: no such file or directory?

👉 Trả lời: Ký hiệu ./ tìm file trong thư mục hiện tại. Hãy dùng lệnh toàn cục: laravel-test-init hoặc cakephp-test-init.

Q2: Cài vào thư mục mới/trống có được không?

👉 Trả lời: Được! Thêm cờ --force:

install.sh --force
# Hoặc:
cakephp-test-init --force
laravel-test-init --force

Q3: Chạy test có làm mất hoặc thay đổi dữ liệu database dev không?

👉 Trả lời: Tuyệt đối không!

• Với Laravel: Cấu hình DB_CONNECTION=sqlite và DB_DATABASE=:memory:.
• Với CakePHP: Cấu hình Datasources.test dùng SQLite :memory: hoặc Fixture Transaction Strategy tự động rollback dữ liệu sau mỗi test.

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. CI sẽ tự động chạy song song trên các phiên bản PHP và từ chối merge nếu độ phủ < 80%.

---

8. Ma Trận Tương Thích & Bản Quyền

Thành Phần	Phiên Bản Hỗ Trợ
PHP	7.4, 8.0, 8.1, 8.2, 8.3, 8.4+ (Property Hooks, Asymmetric Visibility)
CakePHP	3.x, 4.x, 5.x+ (Toàn bộ kiến trúc Table, Entity, Controller, Command, Mailer...)
Laravel	8.x, 9.x, 10.x, 11.x, 12.x & 13.x (Kiến trúc hiện đại)
PHPUnit	9.x (DocBlock), 10.x, 11.x & 12.x (PHP 8 Attributes #[Test])
Pest PHP	v2.x & v3.x (Architecture Testing arch(), Mutation testing)
Mocking	CakePHP Fixtures, PHPUnit Test Doubles, Mockery, Laravel Built-in Fakes
Database	SQLite In-Memory (:memory:), MySQL Test DB, PostgreSQL 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. 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.