🚀 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
2. Cấu Trúc Thư Mục Repository
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ỳ
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 2: Sinh Unit Test Tự Động (/laravel-unit-test)
   • Bước 3: Chạy Test Thông Minh (test-runner.sh)
   • 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)
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)
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

---

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

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 (dù trong hay ngoài team, trên bất kỳ máy tính nào) KHÔNG CẦN phải clone repository 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 duy nhất:

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

# 🌟 Cài đặt trực tiếp qua HTTPS công khai (không cần tài khoản, không cần SSH key):
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ó file composer.json, thêm cờ --force vào cuối: ... | bash -s -- --force).

---

🎯 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 qua HTTPS 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 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://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/install.sh | bash -s -- --global

🎯 Lợi ích:

• Tự động cài đặt 4 Skills vào ~/.claude/skills/.
• Đăng ký lệnh laravel-test-init (hoặc sg-test-init) vào Terminal để gõ ở bất kỳ thư mục nào cũng tự tạo test-runner.sh.

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

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=<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 https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/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 https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/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 https://git.smartgift.io.vn/Smartgift-AI/agent-unit-testing/raw/branch/main/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

---

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.