agent-unit-testing/USAGE-GUIDE.md

📖 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

1. Cơ Chế Hoạt Động Của Bộ Công Cụ
2. Cài Đặt Lần Đầu (Dành Cho Thành Viên Mới)
3. Khởi Tạo Cho Một Dự Án Laravel Bất Kỳ
4. Quy Trình 5 Bước Sinh & Chạy Unit Test
5. Cách Cập Nhật Khi Bộ Công Cụ Có Thay Đổi Mới (Update Guide)
6. Giải Đáp Thắc Mắc & Lỗi Thường Gặp (FAQ & Troubleshooting)
7. 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:

1. 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).
2. 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.
3. 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):

1. Kiểm tra sức khỏe môi trường (Health-Check):

   /laravel-test-setup
   

2. 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 DUY NHẤT PHỦ TOÀN BỘ FILE TRONG DỰ ÁN (--all)

Khi bạn muốn AI tự động viết test cho toàn bộ dự án từ A-Z mà đảm bảo không bỏ sót bất kỳ file nào:

/laravel-unit-test --all

🎯 Cơ chế cam kết không sót file (Full Coverage Engine):

1. Lập Manifest Kiểm Soát: AI tự động quét toàn bộ app/ (và Modules/), lọc ra tất cả các class có logic (Services, Actions, FormRequests, Rules, Jobs, Policies, Middlewares, Listeners, Observers, Repositories). Lập file danh sách kiểm soát tests/.test-manifest.json (ví dụ: Tổng cộng 42 files).
2. Thực Thi Tuần Tự & Lưu Tiến Độ: Duyệt tuần tự từng class ([1/42], [2/42],...), sinh test tương ứng và đánh dấu [COMPLETED]. Tránh hoàn toàn việc tràn token/context và có thể chạy tiếp nếu bị gián đoạn.
3. Tự Động Chạy Thử & Tự Sửa Lỗi (Auto-Healing): Mỗi khi sinh xong 1 file test, AI lập tức chạy ./test-runner.sh --filter=<TênTest>. Nếu fail -> Tự sửa lại code test ngay cho đến khi pass 100%.
4. Nghiệm Thu Toàn Dự Án: Chạy ./test-runner.sh --coverage và in bảng tổng kết: 42/42 files covered, 100% Passed, Code Coverage: > 80%.

---

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

1. 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.
2. Tự động đồng bộ toàn bộ Skills, Rules, Docs vào hệ thống Claude Code (~/.claude/).
3. 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
Sinh test TOÀN BỘ dự án (1 lệnh)	/laravel-unit-test --all	Tự động lập manifest, sinh tuần tự, cam kết không sót file
Sinh test cho 1 file	/laravel-unit-test app/.../Service.php	Khi đang code 1 class đơn lẻ
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