agent-unit-testing/.claude/skills/laravel-test-setup/skill.md

name, description

name	description
laravel-test-setup	Tự động quét kiểm tra môi trường, dependencies, database config và docker để chuẩn bị viết Unit Test cho bất kỳ dự án Laravel nào.

Skill: Laravel Test Environment Setup & Health Check

Skill này chịu trách nhiệm chuẩn bị "Bước 0" cho dự án Laravel trước khi bắt đầu viết bất kỳ Unit Test nào.

Cách kích hoạt

• Chế độ kiểm tra (Dry-run / Health-Check):

  /laravel-test-setup
  

• Chế độ tự động cài đặt gói thiếu (Auto-Install Mode):

  /laravel-test-setup --install
  

Quy trình thực hiện (Execution Workflow)

Khi người dùng kích hoạt lệnh /laravel-test-setup, Agent sẽ tuần tự thực hiện các bước sau:

Bước 1: Quét composer.json & Nhận Diện Thư Viện Cần Thiết

1. Đọc file composer.json tại thư mục gốc của dự án.
2. Xác định:
   • Phiên bản PHP & Laravel: PHP 8.0 - 8.4+, Laravel 9.x - 13.x
   • Test Framework: phpunit/phpunit hay pestphp/pest
   • Mocking & Fake: mockery/mockery, fakerphp/faker
   • Performance & Coverage: brianium/paratest, nunomaduro/collision
3. Nếu phát hiện thiếu thư viện:
   • Nếu có cờ --install hoặc người dùng đồng ý: Agent tự động kích hoạt lệnh cài đặt qua môi trường tương ứng (Sail / Docker Compose / Local Composer):

     # Nếu dùng Sail:
     ./vendor/bin/sail composer require --dev mockery/mockery fakerphp/faker --with-all-dependencies
     # Nếu dùng Docker Compose (service app):
     docker compose exec -T app composer require --dev mockery/mockery fakerphp/faker --with-all-dependencies
     # Nếu chạy Local:
     composer require --dev mockery/mockery fakerphp/faker --with-all-dependencies
     

   • Hoặc chạy script ./setup-test-deps.sh có sẵn.

Bước 2: Kiểm tra cấu hình Testing Database & Drivers

1. Kiểm tra sự tồn tại của phpunit.xml (hoặc phpunit.xml.dist) hoặc .env.testing.
2. Xác thực cấu hình thẻ <php> trong phpunit.xml:
   • DB_CONNECTION phải là sqlite và DB_DATABASE là :memory: (hoặc kết nối DB test riêng an toàn).
   • CACHE_STORE hoặc CACHE_DRIVER phải là array.
   • QUEUE_CONNECTION phải là sync.
   • MAIL_MAILER phải là array.
   • BCRYPT_ROUNDS nên là 4.
3. Nếu chưa có hoặc cấu hình đang trỏ vào database dev thật:
   • Cảnh báo người dùng về nguy cơ mất dữ liệu dev.
   • Đề xuất tạo .env.testing hoặc cập nhật phpunit.xml dựa trên template có sẵn tại templates/configs/.

Bước 3: Phát hiện Môi trường Docker / Runtime

1. Kiểm tra ./vendor/bin/sail -> Nếu có Sail, ưu tiên lệnh ./vendor/bin/sail test.
2. Kiểm tra docker-compose.yml -> Dò tìm service PHP (app, php, backend,...) -> Đề xuất lệnh docker compose exec -T <service> php artisan test.
3. Nếu chạy Local: Kiểm tra xem extension pdo_sqlite đã được bật chưa bằng php -m | grep sqlite.

Bước 4: Chạy Smoke Test (Kiểm tra thử nghiệm)

1. Chạy thử nghiệm lệnh test hiện có của project (ví dụ: php artisan test --filter=ExampleTest).
2. Nếu test PASS: Báo cáo môi trường đã sẵn sàng 100% để sinh Unit Test.
3. Nếu test FAIL hoặc văng lỗi (ví dụ: thiếu APP_KEY, thiếu SQLite driver, lỗi database): Đưa ra chẩn đoán chính xác nguyên nhân và lệnh khắc phục.

---

Mẫu báo cáo đầu ra cho người dùng:

### 📋 BÁO CÁO MÔI TRƯỜNG TEST (HEALTH CHECK)

1. **Framework & Dependencies**:
   - Laravel: 11.2.0 | PHP: 8.3
   - Test Runner: Pest PHP v2.34
   - Mocking: Mockery 1.6 (Đã cài)
   - Faker: FakerPHP 1.23 (Đã cài)

2. **Cấu hình Môi trường**:
   - DB Test: SQLite (:memory:) [OK - An toàn]
   - Cache / Queue / Mail: Array / Sync [OK - Tối ưu]
   - BCRYPT_ROUNDS: 4 [OK - Tốc độ cao]

3. **Môi trường thực thi**:
   - Docker Service: `app` container đang hoạt động
   - Lệnh chạy test chuẩn: `docker compose exec -T app php artisan test`

4. **Kết quả Smoke Test**:
   - Trạng thái: ✅ PASSED (2 tests, 4 assertions)

🎉 **Môi trường đã hoàn toàn sẵn sàng cho việc sinh Unit Test!**