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

name, description

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

Skill: CakePHP Test Environment Setup & Health Check

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

Cách kích hoạt

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

  /cakephp-test-setup
  

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

  /cakephp-test-setup --install
  

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

Khi người dùng kích hoạt lệnh /cakephp-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 CakePHP Version

1. Đọc file composer.json tại thư mục gốc của dự án.
2. Xác định:
   • Phiên bản CakePHP:
     • cakephp/cakephp: ^5.0: Yêu cầu PHP >= 8.1
     • cakephp/cakephp: ^4.0: Yêu cầu PHP >= 7.4
     • cakephp/cakephp: ^3.0: Legacy CakePHP 3.x
   • Test Runner & Dependencies:
     • phpunit/phpunit
     • cakephp/cakephp-codesniffer (nếu có)
     • mockery/mockery (hỗ trợ nâng cao)
     • fakerphp/faker
3. Nếu phát hiện thiếu thư viện hoặc cờ --install:
   • Kích hoạt lệnh cài đặt qua môi trường tương ứng:

     # Nếu dùng Docker Compose (service app / web / php):
     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
     

Bước 2: Kiểm tra Cấu hình Testing Database (Datasources.test)

1. Kiểm tra file config/app_local.php hoặc config/app.php.
2. Xác thực cấu hình Datasources.test:
   • Đảm bảo kết nối test được tách biệt với default (production/dev).
   • Khuyên dùng SQLite In-Memory hoặc SQLite file test để đảm bảo tốc độ cao và an toàn tuyệt đối 100% cho dữ liệu dev:

     'test' => [
         'className' => 'Cake\Database\Connection',
         'driver' => 'Cake\Database\Driver\Sqlite',
         'database' => ':memory:', // hoặc TMP . 'test.sqlite'
         'encoding' => 'utf8',
         'timezone' => 'UTC',
         'cacheMetadata' => true,
         'quoteIdentifiers' => false,
     ],
     

3. Kiểm tra file cấu hình PHPUnit (phpunit.xml hoặc phpunit.xml.dist):
   • Đảm bảo có suite <testsuite name="app"> trỏ vào tests/TestCase.
   • Có extension / listener fixture (Cake\TestSuite\Fixture\FixtureExtension cho CakePHP 4.3+ / 5.x).

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

1. Kiểm tra bin/cake -> Đảm bảo có quyền thực thi (chmod +x bin/cake).
2. Kiểm tra docker-compose.yml -> Dò tìm service chạy CakePHP (app, web, php, backend) -> Lệnh chuẩn:

   docker compose exec -T app bin/cake test app
   # Hoặc:
   docker compose exec -T app vendor/bin/phpunit
   

3. Nếu chạy Local: Kiểm tra PHP CLI có đủ extension intl (php -m | grep intl) và pdo_sqlite (php -m | grep sqlite).

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

1. Chạy thử nghiệm một test case mẫu sẵn có hoặc test mặc định:

   ./test-runner.sh
   # hoặc bin/cake test app
   

2. Nếu test PASS: Báo cáo môi trường đã sẵn sàng 100%.
3. Nếu test FAIL: Đưa ra chẩn đoán chính xác nguyên nhân (thiếu driver SQLite, sai database credentials, thiếu fixture strategy,...).

---

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

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

1. **Framework & Dependencies**:
   - CakePHP: 4.5.3 (hoặc 5.0.x) | PHP: 8.2
   - Test Runner: PHPUnit 10.5
   - Mocking: Mockery 1.6 (Đã cài)
   - Fixture Strategy: TransactionStrategy / FixtureExtension [OK]

2. **Cấu hình Môi trường Test**:
   - Datasource Test: SQLite (:memory:) [OK - An toàn, không đụng dữ liệu dev]
   - phpunit.xml: Đã cấu hình suite `app` trỏ tới `tests/TestCase`

3. **Môi trường thực thi**:
   - Docker Service: `app` (hoặc `web`) đang hoạt động
   - Lệnh chạy test chuẩn: `docker compose exec -T app bin/cake test app`

4. **Kết quả Smoke Test**:
   - Trạng thái: ✅ PASSED

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