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

name, description

name	description
cakephp-unit-test	Phân tích một class mã nguồn PHP CakePHP (Table, Entity, Controller, Service, Command, Component, Middleware, Mailer, Form, Behavior) và tự động sinh file Unit / Integration Test hoàn chỉnh đạt chuẩn AAA, cô lập cao và bao phủ biên.

Skill: CakePHP Unit & Integration Test Generator

Skill này là công cụ chính để tự động tạo ra file Test cho bất kỳ class nào trong dự án CakePHP (từ CakePHP 3.x, 4.x đến 5.x+).

Cách kích hoạt

🏆 QUY TRÌNH CHUẨN PRO CHO DỰ ÁN LỚN (KHUYÊN DÙNG NHẤT):

Để tránh bị tràn context token và đảm bảo viết sâu 100% từng nhánh SonarQube, hãy tách biệt 2 pha: PHA VIẾT (Generation) và PHA CHẠY (Execution):

1. Bước 1: Quét bản đồ dự án (--untested):

   /cakephp-unit-test --untested
   

   Liệt kê danh sách class trong src/ chưa có test trong tests/TestCase/ theo độ ưu tiên: Tables/Entities -> Services -> Controllers -> Commands -> Components/Middlewares.

2. Bước 2: Viết test tập trung theo từng tầng (CHỈ VIẾT, CHƯA CHẠY TEST):

   /cakephp-unit-test src/Model/Table/
   # Sau khi xong, viết tiếp:
   /cakephp-unit-test src/Service/
   /cakephp-unit-test src/Controller/
   /cakephp-unit-test src/Command/
   

   AI dồn 100% token tập trung sinh test sâu, đầy đủ Happy Path, Edge Cases, Exception và Branch Coverage.

3. Bước 3: Chạy test đồng loạt ngoài Terminal & Nghiệm thu:

   ./test-runner.sh --coverage
   

   Chạy 1 lần duy nhất bằng bin/cake test app hoặc phpunit trên In-memory SQLite siêu tốc, đo độ phủ và xuất file báo cáo.

---

⚡ CÁC CHẾ ĐỘ TIỆN ÍCH KHÁC:

4. Chế độ Autopilot Khép Kín: Viết & Chạy Test Ngay (--all --run hoặc --autopilot):

   /cakephp-unit-test --all --run
   

   Dành cho dự án vừa và nhỏ: AI tự lập manifest, viết đến đâu chạy ./test-runner.sh ngay đến đó, tự động sửa lỗi (Auto-Healing) nếu test fail.

5. Chế độ Viết Cho 1 File & Test Luôn (--run):

   /cakephp-unit-test src/Model/Table/UsersTable.php --run
   

6. Chế độ Theo Git Diff (Dành Cho Pull Request):

   /cakephp-unit-test --changed
   

7. Chế độ File đơn lẻ:

   /cakephp-unit-test src/Controller/ArticlesController.php
   

---

Quy trình 6 Bước Tự Động của Agent

Bước 1: Khảo sát Môi trường & Phiên bản CakePHP

1. Đọc composer.json để xác định:
   • Phiên bản CakePHP:
     • CakePHP 5.x: PHP >= 8.1, kiểu khai báo kiểu nghiêm ngặt (strict types), Attributes PHP 8 #[Test].
     • CakePHP 4.x: PHP 7.4 - 8.2, Cake\TestSuite\TestCase, dùng fetchTable().
     • CakePHP 3.x: TableRegistry::get().
   • PHPUnit: PHPUnit 9 / 10 / 11.

Bước 2: Phân tích File Nguồn & Xác Định Loại Component

1. Đọc toàn bộ nội dung file class nguồn được chỉ định.
2. Xác định cấu trúc Component CakePHP:
   • Table (src/Model/Table/*Table.php): Test validation rules, custom finder methods (findTagged(), findAuth()), buildRules, save/delete logic.
   • Entity (src/Model/Entity/*.php): Test virtual fields, mutators (_setPassword()), accessors, hidden/accessible properties.
   • Controller (src/Controller/*Controller.php): Dùng Cake\TestSuite\IntegrationTestTrait. Test endpoints HTTP (GET, POST, PUT, DELETE), flash messages, redirect, view vars, auth/session.
   • Service / Action (src/Service/*.php): Test logic nghiệp vụ thuần túy, mock các dependency ngoài hoặc Table locator.
   • Command (src/Command/*Command.php): Dùng Cake\Console\TestSuite\ConsoleIntegrationTestTrait. Test arguments, options, output text, exit code (CODE_SUCCESS, CODE_ERROR).
   • Component (src/Controller/Component/*.php): Test logic tái sử dụng của Controller với mocked Controller/Request/Response.
   • Middleware (src/Middleware/*.php): Test PSR-15 / CakePHP middleware với ServerRequest và ResponseHandler.
   • Mailer (src/Mailer/*Mailer.php): Dùng Cake\TestSuite\EmailTrait. Test subject, to, template, view vars.
   • Form (src/Form/*Form.php): Test validationDefault(), _buildSchema(), _execute().
   • Behavior (src/Model/Behavior/*.php): Test ORM hooks (beforeSave, beforeFind,...).
   • Helper (src/View/Helper/*.php): Test render HTML, tags, view outputs.

Bước 3: Xác Định Fixtures & Chiến Lược Giả Lập (Mocking)

• Database & Fixtures:
  • Đối với Table & Controller test: Xác định các bảng liên quan để khai báo fixture:

    protected array $fixtures = [
        'app.Users',
        'app.Articles',
    ];
    

• External Dependencies & APIs:
  • Dùng Mockery hoặc PHPUnit Mock ($this->createMock()) cho các HTTP Client ngoài, 3rd party SDKs, Payment Gateway.
• Session & Auth:
  • Đối với Controller: $this->session(['Auth.User.id' => 1]) hoặc Token-based Auth.
  • Kích hoạt CSRF & Security token khi test POST:

    $this->enableCsrfToken();
    $this->enableSecurityToken();
    

Bước 4: Lập Ma Trận Test Scenarios (Bao Phủ 100% Nhánh SonarQube)

• 100% Public Methods: Mọi phương thức public đều phải có test.
  • Với Table: bắt buộc test custom finders, validation failures, save thành công & thất bại.
  • Với Controller: bắt buộc test thành công (200/302), validation failure (422/render form), unauthorized (403/redirect login), not found (404).
  • Với Command: bắt buộc test execute() với input đúng, input thiếu, exit code.
• Bao phủ nhánh rẽ:
  • Kịch bản Null Coalescing ?? và Ternary ?:.
  • Kịch bản try - catch: ép mock/dữ liệu ném Exception để chạy qua khối catch.
  • Mọi if, else if, else, switch, match.

Bước 5: Sinh Mã Nguồn Test Chuẩn Mirror

1. Xác định đường dẫn file test theo chuẩn CakePHP:
   • Nguồn: src/Model/Table/ArticlesTable.php
   • Đích: tests/TestCase/Model/Table/ArticlesTableTest.php
   • Nguồn: src/Controller/ArticlesController.php
   • Đích: tests/TestCase/Controller/ArticlesControllerTest.php
   • Nguồn: src/Command/CleanCacheCommand.php
   • Đích: tests/TestCase/Command/CleanCacheCommandTest.php
2. Sử dụng đúng base class:
   • Cake\TestSuite\TestCase (kèm các Trait tương ứng: IntegrationTestTrait, ConsoleIntegrationTestTrait, EmailTrait).
3. Viết code theo mô hình AAA (// Arrange, // Act, // Assert).

Bước 6: Thẩm định & Lưu File

1. Tự kiểm tra file test qua checklist quy chuẩn.
2. Ghi file test vào thư mục tests/TestCase/....
3. In ra lệnh chạy test gợi ý:

   bin/cake test app tests/TestCase/Model/Table/ArticlesTableTest.php
   # Hoặc:
   ./test-runner.sh --filter=ArticlesTableTest