Files

T

Pham-Tan-Thien 6fc49787a9 feat: add --all --run autopilot mode for instant write-and-test execution

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

2026-09-07 16:45:45 +07:00

15 KiB

Raw Blame History

📖 CẨM NANG TOÀN TẬP: HƯỚNG DẪN CÀI ĐẶT, SỬ DỤNG & CẬP NHẬT

BỘ CÔNG CỤ TỰ ĐỘNG HÓA LARAVEL UNIT TESTING (SMARTGIFT AI)

Tài liệu chuẩn hóa dành cho toàn thể thành viên Team Smartgift: Từ bước cài đặt lần đầu, sử dụng cho dự án bất kỳ, quy trình viết test, cho đến cách cập nhật phiên bản mới nhất khi bộ công cụ có nâng cấp.

📑 MỤC LỤC

Cơ Chế Hoạt Động Của Bộ Công Cụ
Cài Đặt Lần Đầu (Dành Cho Thành Viên Mới)
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 Khi Bộ Công Cụ Có Thay Đổi Mới (Update Guide)
Giải Đáp Thắc Mắc & Lỗi Thường Gặp (FAQ & Troubleshooting)
Bảng Tra Cứu Toàn Bộ Lệnh (Full Cheat Sheet)

1. Cơ Chế Hoạt Động Của Bộ Công Cụ

Bộ công cụ này biến Claude Code thành một Chuyên Gia Tự Động Hóa Kiểm Thử (Senior QA Automation Engineer) thông qua 3 thành phần:

Bộ 4 Claude Code Skills (Cài đặt tại ~/.claude/skills/):
- Tự động quét môi trường, phát hiện thiếu thư viện (/laravel-test-setup).
- Tự động phân tích class nguồn và sinh Unit Test chuẩn AAA (/laravel-unit-test).
- Tự động thẩm định, bắt lỗi anti-patterns theo thang điểm 100 (/laravel-test-review).
- Tự động sinh mã Mockery / Laravel Fakes nhanh (/laravel-mock-helper).
Hệ Thống Tri Thức (Knowledge Base - 23 Files Docs & Rules):
- Hướng dẫn chi tiết 13 tầng kiến trúc Laravel (Services, Controllers, Jobs, Policies, Rules,...).
- Xử lý các ca khó: DB::transaction(), Upload files, Traits, PHP 8.4 Property Hooks.
Bộ Scripts Chạy Test Thông Minh (Smart Runners):
- ./test-runner.sh: Tự nhận diện Laravel Sail, Docker Compose hay PHP Local.
- ./setup-test-deps.sh: Tự động cài package test vào đúng container.

2. Cài Đặt Lần Đầu (Dành Cho Thành Viên Mới)

Mỗi thành viên trong team khi bắt đầu chỉ cần cài đặt đúng 1 lần duy nhất trên máy tính theo 1 trong 2 cách sau:

🌟 Cách A: Cài Đặt Siêu Tốc Bằng 1 Dòng Lệnh (KHUYÊN DÙNG NHẤT)

Mở Terminal lên, dán dòng lệnh sau và bấm Enter:

git clone ssh://git@ssh-git.smartgift.io.vn:2222/Smartgift-AI/agent-unit-testing.git ~/.smartgift/agent-unit-testing && ~/.smartgift/agent-unit-testing/sg-install-unit-testing.sh --global

Lệnh này sẽ tự động clone repo về thư mục chuẩn ~/.smartgift/agent-unit-testing (gọn gàng, không làm rác Desktop) và tự động kích hoạt toàn cục.

🔹 Cách B: Clone Thủ Công

Nếu muốn lưu repo ở thư mục tùy ý trên máy (ví dụ trong ~/Workspace/):

# 1. Clone repository về máy
git clone ssh://git@ssh-git.smartgift.io.vn:2222/Smartgift-AI/agent-unit-testing.git

# 2. Di chuyển vào thư mục và chạy cài đặt toàn cục
cd agent-unit-testing
./sg-install-unit-testing.sh --global

🎯 Lợi ích sau khi cài đặt thành công:

Bộ 4 Skills được cài đặt toàn cục vào tài khoản máy của bạn (~/.claude/skills/).
Các lệnh CLI sg-install-unit-testing.sh, laravel-unit-test-setup, sg-test-update được đăng ký vào $PATH của hệ thống.
Kể từ lúc này, bạn có thể đứng ở BẤT KỲ FOLDER NÀO trên máy tính để sử dụng mà không cần phải quay lại thư mục agent-unit-testing nữa!

3. Khởi Tạo Cho Một Dự Án Laravel Bất Kỳ

Giả sử bạn đang làm việc trên một dự án Laravel (ví dụ: ~/Workspace/my-project, /var/www/client-app):

Trường hợp A: Dự án đã có sẵn mã nguồn Laravel

Mở terminal tại thư mục dự án đó:

cd /duong-dan/toi/du-an-laravel-cua-ban

# Chạy lệnh khởi tạo (KHÔNG CẦN dấu ./ ở đầu):
sg-install-unit-testing.sh

(Hoặc gõ lệnh: laravel-unit-test-setup)

Lệnh sẽ tự động sinh ngay 2 file vào thư mục dự án:

test-runner.sh: Script chạy test thông minh tự động bắt Docker / Sail / Local.
setup-test-deps.sh: Script tự động cài package test vào container.

Trường hợp B: Thư mục mới/trống (Chưa có `composer.json`)

Nếu bạn muốn cài đặt sẵn công cụ vào một thư mục trống:

cd /duong-dan/toi/thu-muc-trong
sg-install-unit-testing.sh --force

4. Quy Trình 5 Bước Sinh & Chạy Unit Test

Sau khi khởi tạo, bạn mở dự án bằng Claude Code (claude) và thực hiện quy trình sau:

  [1. Setup Env]   -->   [2. Generate Test]  -->   [3. Run Test]   -->   [4. Review]
/laravel-test-setup      /laravel-unit-test       ./test-runner.sh     /laravel-test-review

Bước 1: Quét Môi Trường & Cài Thư Viện (`/laravel-test-setup`)

Trước khi viết bài test đầu tiên, hãy kiểm tra và cài đặt đầy đủ các thư viện cần thiết (mockery, faker, paratest):

Kiểm tra sức khỏe môi trường (Health-Check):
```
/laravel-test-setup
```
Tự động cài đặt các thư viện còn thiếu (Auto-Install):
```
/laravel-test-setup --install
```
AI sẽ tự động xác định bạn đang dùng Docker Compose hay Sail hay Local và chạy lệnh composer require --dev ... chính xác vào container của bạn.

Bước 2: Sinh Unit Test Tự Động (`/laravel-unit-test`)

Tùy vào nhu cầu thực tế, bạn chọn 1 trong 5 cách sau:

🌟 Cách 1: 1 LỆNH AUTOPILOT VIẾT TOÀN BỘ VÀ TỰ CHẠY TEST LUÔN (`--all --run`)

Khi bạn muốn AI tự động viết test cho toàn bộ dự án từ A-Z, viết đến đâu tự chạy test đến đó và tự sửa lỗi nếu test fail:

/laravel-unit-test --all --run
# Hoặc:
/laravel-unit-test --autopilot

🎯 Quy trình 4-trong-1 hoàn toàn tự động:

Tự động Setup: Tự kiểm tra môi trường, cấu hình SQLite :memory: và tự cài packages nếu thiếu.
Lập Manifest Kiểm Soát: Quét toàn bộ app/, lập danh sách tất cả các class cần test (tests/.test-manifest.json).
Viết & Chạy Test Ngay (Auto-Healing): Sinh xong file test nào -> Tự chạy ngay ./test-runner.sh --filter=<TênTest>. Nếu fail -> Tự đọc lỗi và sửa lại test ngay cho đến khi PASS 100%.
Nghiệm Thu Toàn Dự Án: Tự chạy ./test-runner.sh --coverage và in bảng tổng kết độ phủ code.

🔹 Cách 2: Sinh Cho 1 Class & Chạy Test Ngay (`--run`)

Khi bạn chỉ muốn viết test cho 1 file và muốn AI test luôn file đó ngay lập tức:

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

🔹 Cách 2: Sinh hàng loạt cho cả một thư mục (Batch Directory Mode)

Khi bạn chỉ muốn phủ test cho 1 module hoặc 1 layer cụ thể:

/laravel-unit-test app/Services/
# Hoặc toàn bộ Actions:
/laravel-unit-test app/Actions/
# Hoặc toàn bộ Module (DDD / Modular):
/laravel-unit-test Modules/Order/

🔹 Cách 3: Quét & Phủ test có chọn lọc (`--untested`)

Khi muốn AI quét tìm các class chưa có test và hiển thị danh sách để bạn chọn nhóm cần ưu tiên:

/laravel-unit-test --untested

🔹 Cách 4: Tự động sinh test cho Git Diff (`--changed` - Dành cho PR)

Trước khi tạo Pull Request trên Git:

/laravel-unit-test --changed

🔹 Cách 5: Sinh cho một class cụ thể (Single File Mode)

Khi bạn đang code hoặc refactor duy nhất 1 file:

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

Bước 3: Chạy Test Thông Minh (`test-runner.sh`)

Không cần nhớ cú pháp docker phức tạp, chỉ cần chạy script thông minh:

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

# Chạy riêng 1 file test vừa sinh:
./test-runner.sh --filter=PaymentServiceTest

# Chạy kèm đo độ phủ Code Coverage:
./test-runner.sh --coverage

Cơ chế tự động:

Nếu Sail đang chạy -> Tự gọi ./vendor/bin/sail test.
Nếu có Docker Compose -> Tự gọi docker compose exec -T <service> php artisan test.
Nếu chạy máy Local -> Tự gọi php artisan test và kiểm tra extension pdo_sqlite.

Bước 4: Thẩm Định & Review Chất Lượng Test (`/laravel-test-review`)

Để kiểm tra xem file test có đạt chuẩn AAA, có bị over-mocking hay thiếu kịch bản biên không:

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

AI sẽ chấm điểm theo thang 100, chỉ ra các lỗi Anti-patterns và đưa ra đoạn mã refactor chuẩn.

Bước 5: Sinh Mã Giả Lập Nhanh (`/laravel-mock-helper`)

Khi tự viết test và cần mock nhanh một Interface phức tạp:

/laravel-mock-helper App\Contracts\PaymentGatewayInterface

AI sẽ sinh sẵn khối code Mockery với 2 kịch bản (Thành công & Thất bại) để bạn copy vào test.

5. Cách Cập Nhật Khi Bộ Công Cụ Có Thay Đổi Mới (Update Guide)

Khi Trưởng nhóm (hoặc thành viên khác) cập nhật thêm tài liệu .md, thêm rules mới hoặc nâng cấp template lên Git, các thành viên khác làm thế nào để có phiên bản mới nhất?

🌟 Cách 1: Dùng Lệnh Cập Nhật 1-Click Toàn Cục (KHUYÊN DÙNG)

Bất kể bạn đang đứng ở thư mục nào trong Terminal, chỉ cần gõ:

sg-test-update

(hoặc laravel-test-update)

Lệnh này sẽ tự động:

Chạy git pull origin main trên repo agent-unit-testing của bạn để kéo toàn bộ thay đổi mới nhất về máy.
Tự động đồng bộ toàn bộ Skills, Rules, Docs vào hệ thống Claude Code (~/.claude/).
Báo cáo hoàn tất thành công!

Nếu bạn muốn cập nhật luôn các script runner trong một dự án cụ thể:

sg-test-update /duong-dan/toi/du-an-laravel-cua-ban

⚡ Cách 2: Kỹ Thuật Symlink Tự Động (Dành Cho Thành Viên Giữ Repo)

Nếu bạn đã cài đặt qua --global, toàn bộ skills đã được liên kết mềm (Symlink) trực tiếp vào repo agent-unit-testing.

Do đó, bạn chỉ cần:

cd /duong-dan/toi/agent-unit-testing
git pull origin main

Chỉ cần git pull là xong! Toàn bộ Claude Code trên máy của bạn sẽ tự động cập nhật nội dung mới nhất ngay lập tức mà không cần chạy thêm bất kỳ lệnh cài đặt nào.

6. Giải Đáp Thắc Mắc & Lỗi Thường Gặp (FAQ & Troubleshooting)

Q1: Tại sao tôi gõ `./sg-install-unit-testing.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:

sg-install-unit-testing.sh
# 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:

sg-install-unit-testing.sh --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%.

7. 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 lần đầu (Toàn cục)	`./sg-install-unit-testing.sh --global`	Chạy 1 lần duy nhất trong repo `agent-unit-testing`
Khởi tạo vào dự án bất kỳ	`sg-install-unit-testing.sh`	Chạy tại terminal của bất kỳ dự án Laravel nào
Khởi tạo vào thư mục trống	`sg-install-unit-testing.sh --force`	Dùng khi thư mục chưa có `composer.json`
Cập nhật bộ công cụ (1-Click)	`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/`	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`	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

15 KiB Raw Blame History