Files

T

Pham-Tan-Thien 3e1314a3e1 feat: make toolkit public and add remote 1-line installer

- Add remote web installer (install.sh) supporting curl | bash without cloning repo
- Remove team-specific wrappers and symlinks in favor of clean public install.sh
- Consolidate all usage and setup documentation directly into README.md
- Add open-source MIT License
- Streamline end-to-end testing workflow with 4-in-1 autopilot mode

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-09-08 08:57:50 +07:00

21 KiB

Raw Blame History

🚀 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

Điểm Nổi Bật & Tính Năng Cốt Lõi
Cấu Trúc Thư Mục Repository
Hướng Dẫn Cài Đặt Lần Đầu
Khởi Tạo Cho Một Dự Án Laravel Bất Kỳ
Quy Trình 5 Bước Sinh & Chạy Unit Test
Cách Cập Nhật Bộ Công Cụ Khi Có Nâng Cấp
Giải Đáp Thắc Mắc & Xử Lý Lỗi (FAQ & Troubleshooting)
Bảng Tra Cứu Toàn Bộ Lệnh (Full Cheat Sheet)
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

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.
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ỡ.
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.
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%.
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

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)

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

# Chạy lệnh cài đặt từ xa:
curl -fsSL https://raw.githubusercontent.com/<OWNER>/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):

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:

Script sẽ tải các tài nguyên cần thiết từ xa vào thư mục tạm /tmp/.
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.
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):

curl -fsSL https://raw.githubusercontent.com/<OWNER>/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ế:

┌────────────────┐     ┌────────────────┐     ┌────────────────┐     ┌────────────────┐
│  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:

cd /duong-dan/toi/source-code-laravel
curl -fsSL https://raw.githubusercontent.com/<OWNER>/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:

claude

Chạy lệnh kiểm tra và tự động cài đặt thư viện kiểm thử còn thiếu:

/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:

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

Quá trình AI thực hiện tự động hoàn toàn:

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).
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.
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=<TênTest> để 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:

./test-runner.sh --coverage

Bảng báo cáo nghiệm thu sẽ xuất hiện:

🎉 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:

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

Chỉ viết cho cả 1 thư mục & test luôn:
```
/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:
```
/laravel-unit-test --changed --run
```
Thẩm định & Chấm điểm 1 file test có sẵn (thang 100):
```
/laravel-test-review tests/Unit/Services/PaymentServiceTest.php
```

Sinh nhanh khối mã Mockery cho một Interface:

/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:

curl -fsSL https://raw.githubusercontent.com/<OWNER>/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õ:

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ý:

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:

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 <URL>/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 <URL>/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 <URL>/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. 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.

21 KiB Raw Blame History