Pham-Tan-Thien
da1bd48444
- Decouple framework installation: add install-laravel.sh and install-cakephp.sh, isolate skills and docs per framework, and auto-clean leftover artifacts - Remove all SonarQube configs, templates, and references - Enforce comprehensive test completeness: 100% public methods, edge cases, full branch coverage, exception paths, and state assertions - Replace all placeholder assertions in PHPUnit and Pest templates with full realistic implementations - Rename and update 10-comprehensive-test-coverage-guide.md
492 lines
25 KiB
Markdown
492 lines
25 KiB
Markdown
# 🚀 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](#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. [Cài Đặt Nhanh (1 Dòng Lệnh Duy Nhất)](#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-phần-1-hướng-dẫn-dành-riêng-cho-laravel)
|
|
- [4.1. Kiến Trúc & 13 Tầng Hỗ Trợ](#41-kiến-trúc--13-tầng-hỗ-trợ-laravel)
|
|
- [4.2. Quy Trình Thực Chiến 5 Bước Cho Laravel](#42-quy-trình-thực-chiến-5-bước-cho-laravel)
|
|
- [4.3. Bảng Tra Cứu Lệnh Laravel (Cheat Sheet)](#43-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-phần-2-hướng-dẫn-dành-riêng-cho-cakephp)
|
|
- [5.1. Kiến Trúc & 10 Tầng Hỗ Trợ](#51-kiến-trúc--10-tầng-hỗ-trợ-cakephp)
|
|
- [5.2. Quy Trình Thực Chiến 5 Bước Cho CakePHP](#52-quy-trình-thực-chiến-5-bước-cho-cakephp)
|
|
- [5.3. Bảng Tra Cứu Lệnh CakePHP (Cheat Sheet)](#53-bảng-tra-cứu-lệnh-cakephp-cheat-sheet)
|
|
6. [Cập Nhật Bộ Công Cụ](#6-cập-nhật-bộ-công-cụ)
|
|
7. [Giải Đáp Thắc Mắc & Xử Lý Lỗi (FAQ)](#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](#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. **Viết File Test Đầy Đủ & Toàn Diện Tuyệt Đối (Completeness First)**:
|
|
- Viết trọn vẹn 100% public methods của class, không bỏ sót helper, hook hay method phụ.
|
|
- Bao phủ toàn diện 4 nhóm kịch bản: Happy Path, Edge Cases (null, empty, số âm, số 0, boundary), 100% nhánh điều kiện (`??`, `?:`, `if/else`, `match`, `try/catch`), và Exception handling.
|
|
- Kiểm tra chặt chẽ tác động thực tế: xác minh thay đổi DB (`assertDatabaseHas`), Event dispatch, Queue job, Mail.
|
|
- Tập trung thuần túy vào chất lượng file test đầy đủ, không sinh các file cấu hình rác hay phụ thuộc ngoài lề.
|
|
4. **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%.
|
|
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 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
|
|
|
|
```text
|
|
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-comprehensive-test-coverage-guide.md # Chiến lược viết test đầy đủ & đạt độ phủ toàn diện
|
|
│
|
|
├── 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 (Tách Biệt Riêng Biệt Cho Từng Framework)
|
|
|
|
Bộ công cụ được thiết kế **hoàn toàn độc lập và tách biệt**: Khi cài đặt cho Laravel, toàn bộ skills và tài liệu của CakePHP sẽ không bao giờ xuất hiện (và ngược lại), giúp source code của bạn luôn gọn gàng và chuẩn xác 100%.
|
|
|
|
### 🔴 Cách 1: Cài đặt chuyên biệt cho LARAVEL
|
|
Mở Terminal, `cd` vào thư mục dự án **Laravel** của bạn và chạy một trong hai lệnh sau:
|
|
|
|
```bash
|
|
cd /duong-dan/toi/du-an-laravel
|
|
|
|
# Lệnh cài trực tiếp cho Laravel:
|
|
curl -fsSL https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install-laravel.sh | bash
|
|
|
|
# Hoặc qua install.sh kèm cờ --laravel:
|
|
curl -fsSL https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install.sh | bash -s -- --laravel
|
|
```
|
|
|
|
🎯 **Kết quả sau khi cài đặt Laravel:**
|
|
- `.claude/skills/` chỉ chứa 4 skills Laravel (`laravel-unit-test`, `laravel-test-setup`, `laravel-test-review`, `laravel-mock-helper`).
|
|
- `.claude/testing-docs/` chỉ chứa cẩm nang 13 component Laravel và template PHPUnit/Pest của Laravel.
|
|
- Tự động dọn dẹp sạch sẽ bất kỳ file CakePHP nào nếu đã từng cài nhầm trước đó.
|
|
- Cấu hình SQLite in-memory `:memory:` an toàn trong `phpunit.xml`.
|
|
|
|
---
|
|
|
|
### 🔵 Cách 2: Cài đặt chuyên biệt cho CAKEPHP
|
|
Mở Terminal, `cd` vào thư mục dự án **CakePHP** của bạn và chạy một trong hai lệnh sau:
|
|
|
|
```bash
|
|
cd /duong-dan/toi/du-an-cakephp
|
|
|
|
# Lệnh cài trực tiếp cho CakePHP:
|
|
curl -fsSL https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install-cakephp.sh | bash
|
|
|
|
# Hoặc qua install.sh kèm cờ --cakephp:
|
|
curl -fsSL https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install.sh | bash -s -- --cakephp
|
|
```
|
|
|
|
🎯 **Kết quả sau khi cài đặt CakePHP:**
|
|
- `.claude/skills/` chỉ chứa 4 skills CakePHP (`cakephp-unit-test`, `cakephp-test-setup`, `cakephp-test-review`, `cakephp-mock-helper`).
|
|
- `.claude/testing-docs/` chỉ chứa cẩm nang Table/Controller/Command CakePHP và templates của CakePHP.
|
|
- Tự động dọn dẹp sạch sẽ bất kỳ file Laravel nào nếu đã từng cài nhầm trước đó.
|
|
|
|
---
|
|
|
|
### ⚡ Cách 3: Tự Động Nhận Diện Framework (Auto-Detect)
|
|
Nếu bạn đứng trong source code và không truyền cờ, bộ cài sẽ tự động dò tìm:
|
|
```bash
|
|
curl -fsSL https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install.sh | bash
|
|
```
|
|
- Nếu thấy `artisan` hoặc `laravel/framework` -> Tự động kích hoạt chế độ **Laravel riêng biệt**.
|
|
- Nếu thấy `bin/cake` hoặc `cakephp/cakephp` -> Tự động kích hoạt chế độ **CakePHP riêng biệt**.
|
|
|
|
---
|
|
|
|
### 🌐 Cách 4: Cài Đặt Toàn Cục Cho Máy Tính (Global Mode)
|
|
```bash
|
|
# Cho máy chuyên code Laravel:
|
|
curl -fsSL https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install.sh | bash -s -- --global --laravel
|
|
|
|
# Cho máy chuyên code CakePHP:
|
|
curl -fsSL https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install.sh | bash -s -- --global --cakephp
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```text
|
|
┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
|
|
│ 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õ:
|
|
```bash
|
|
claude
|
|
```
|
|
Chạy lệnh kiểm tra môi trường:
|
|
```text
|
|
/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à đảm bảo viết sâu, đầy đủ 100% từng logic và nhánh rẽ, hãy để AI viết sâu từng tầng:
|
|
```text
|
|
# 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
|
|
```text
|
|
/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**:
|
|
```text
|
|
/laravel-unit-test app/Services/PaymentService.php --run
|
|
```
|
|
- **Viết test cho các file vừa sửa đổi trên Git**:
|
|
```text
|
|
/laravel-unit-test --changed
|
|
```
|
|
- **Quét danh sách class thiếu test**:
|
|
```text
|
|
/laravel-unit-test --untested
|
|
```
|
|
|
|
---
|
|
|
|
#### 🔹 Bước 3: Chạy Test Ngoài Terminal & Đo Độ Phủ (Coverage)
|
|
Quay ra terminal và chạy:
|
|
```bash
|
|
# Chạy toàn bộ test:
|
|
./test-runner.sh
|
|
|
|
# Chạy 1 test cụ thể:
|
|
./test-runner.sh --filter=PaymentServiceTest
|
|
|
|
# Đo độ phủ code toàn diện (Coverage report trên Terminal):
|
|
./test-runner.sh --coverage
|
|
|
|
# Xuất báo cáo HTML trực quan:
|
|
./test-runner.sh --coverage-html html-coverage
|
|
```
|
|
|
|
---
|
|
|
|
#### 🔹 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:
|
|
```text
|
|
/laravel-test-review tests/Unit/Services/PaymentServiceTest.php
|
|
```
|
|
|
|
---
|
|
|
|
#### 🔹 Bước 5: Sinh Nhanh Mã Mock Cho Interface / Service
|
|
```text
|
|
/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
|
|
|
|
```text
|
|
┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
|
|
│ 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õ:
|
|
```bash
|
|
claude
|
|
```
|
|
Chạy lệnh kiểm tra môi trường:
|
|
```text
|
|
/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)
|
|
```text
|
|
# 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
|
|
```text
|
|
/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**:
|
|
```text
|
|
/cakephp-unit-test src/Model/Table/ArticlesTable.php --run
|
|
```
|
|
- **Viết test cho các file vừa sửa đổi trên Git**:
|
|
```text
|
|
/cakephp-unit-test --changed
|
|
```
|
|
- **Quét danh sách class CakePHP thiếu test**:
|
|
```text
|
|
/cakephp-unit-test --untested
|
|
```
|
|
|
|
---
|
|
|
|
#### 🔹 Bước 3: Chạy Test Ngoài Terminal & Đo Độ Phủ
|
|
Quay ra terminal và chạy:
|
|
```bash
|
|
# 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 toàn diện:
|
|
./test-runner.sh --coverage
|
|
```
|
|
|
|
---
|
|
|
|
#### 🔹 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):
|
|
```text
|
|
/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:
|
|
```text
|
|
/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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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`:
|
|
```bash
|
|
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](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.
|