feat: complete Smartgift AI Laravel unit testing toolkit

- Add 10 core testing guides (setup, AAA principles, PHPUnit/Pest, mocking, anti-patterns, PHP 8.4+, debugging, data factories, advanced edge cases) - Add 13 component testing guides covering all Laravel layers - Add standard templates for PHPUnit 10/11 and Pest v2/v3 including ArchitectureTest - Add Docker smart test runner, dependency installer, and CI/CD templates (GitHub Actions, GitLab CI) - Add 4 Claude Code skills (laravel-test-setup, laravel-unit-test with --all mode, laravel-test-review, laravel-mock-helper) - Add single unified installer script (sg-install-unit-testing.sh) with global support, CLI runners, and 1-click updater (sg-test-update) - Add comprehensive documentation (README.md, USAGE-GUIDE.md) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-07 16:41:37 +07:00
commit 2045c856e9
60 changed files with 5248 additions and 0 deletions
@@ -0,0 +1,258 @@
+#!/usr/bin/env bash
+
+# ==============================================================================
+# SMARTGIFT AI - LARAVEL UNIT TESTING TOOLKIT INSTALLER
+# Bộ cài đặt công cụ chuẩn hóa và tự động sinh Unit Test cho dự án Laravel
+#
+# Cách dùng:
+#   1. Cài đặt TOÀN CỤC (Khuyên dùng cho cả Team - chạy được ở MỌI thư mục):
+#      ./sg-install-unit-testing.sh --global
+#
+#   2. Cài đặt riêng vào một dự án cụ thể:
+#      ./sg-install-unit-testing.sh /duong-dan/toi/du-an-laravel
+#
+#   3. Cài đặt ngay tại thư mục hiện tại:
+#      ./sg-install-unit-testing.sh .
+# ==============================================================================
+
+set -e
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+# Tự động tìm đường dẫn gốc của repository (kể cả khi gọi qua symlink ở bất kỳ đâu)
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+CURRENT_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+
+if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+    echo -e "${BLUE}===================================================================${NC}"
+    echo -e "${CYAN}  SMARTGIFT AI: LARAVEL UNIT TESTING TOOLKIT INSTALLER${NC}"
+    echo -e "${BLUE}===================================================================${NC}"
+    echo -e "Cách dùng:"
+    echo -e "  1. Cài đặt toàn cục (dùng ở mọi nơi trên máy):"
+    echo -e "     ${YELLOW}sg-install-unit-testing.sh --global${NC}"
+    echo -e "  2. Khởi tạo vào dự án tại thư mục hiện tại:"
+    echo -e "     ${YELLOW}sg-install-unit-testing.sh${NC} (hoặc ${YELLOW}sg-install-unit-testing.sh .${NC})"
+    echo -e "  3. Khởi tạo vào một thư mục dự án cụ thể:"
+    echo -e "     ${YELLOW}sg-install-unit-testing.sh /duong-dan/toi/du-an${NC}"
+    exit 0
+fi
+
+# ==============================================================================
+# 1. XỬ LÝ CÀI ĐẶT TOÀN CỤC (GLOBAL MODE: DÙNG CHO MỌI THƯ MỤC TRÊN MÁY TÍNH)
+# ==============================================================================
+if [ "$1" = "--global" ] || [ "$1" = "-g" ]; then
+    echo -e "${BLUE}===================================================================${NC}"
+    echo -e "${CYAN}  SMARTGIFT AI: CÀI ĐẶT BỘ LARAVEL UNIT TESTING TOOLKIT TOÀN CỤC${NC}"
+    echo -e "${YELLOW}  Thư mục đích: $HOME/.claude/skills/${NC}"
+    echo -e "${BLUE}===================================================================${NC}"
+
+    # 1. Cài đặt Skills cho Claude Code (Liên kết động để khi git pull tự động cập nhật ngay)
+    mkdir -p "$HOME/.claude/skills"
+    echo -e "📦 Đang liên kết bộ 4 Claude Code Skills vào $HOME/.claude/skills/..."
+    for skill_dir in "$CURRENT_DIR/.claude/skills/"*; do
+        skill_name="$(basename "$skill_dir")"
+        ln -sfn "$skill_dir" "$HOME/.claude/skills/$skill_name"
+    done
+
+    # 2. Lưu trữ Docs và Templates tham khảo toàn cục
+    mkdir -p "$HOME/.claude/laravel-testing-docs/templates"
+    cp -R "$CURRENT_DIR/docs/"* "$HOME/.claude/laravel-testing-docs/"
+    cp -R "$CURRENT_DIR/rules/"* "$HOME/.claude/laravel-testing-docs/"
+    cp -R "$CURRENT_DIR/templates/"* "$HOME/.claude/laravel-testing-docs/templates/"
+
+    # 3. Tạo lệnh CLI toàn cục: laravel-unit-test-setup & sg-test-init
+    mkdir -p "$HOME/.local/bin"
+    cat << 'EOF' > "$HOME/.local/bin/laravel-unit-test-setup"
+#!/usr/bin/env bash
+# Smartgift AI - Laravel Unit Test Project Initializer
+
+if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+    echo "=================================================================="
+    echo "  SMARTGIFT AI: LARAVEL UNIT TEST PROJECT INITIALIZER"
+    echo "=================================================================="
+    echo "Cách dùng: laravel-unit-test-setup [đường-dẫn-dự-án]"
+    echo "Mặc định khởi tạo vào thư mục hiện tại nếu không truyền tham số."
+    exit 0
+fi
+
+TARGET_DIR="${1:-.}"
+SOURCE_DIR="$HOME/.claude/laravel-testing-docs"
+
+if [ ! -d "$TARGET_DIR" ]; then
+    echo "Lỗi: Thư mục '$TARGET_DIR' không tồn tại!"
+    exit 1
+fi
+
+echo "🚀 Đang khởi tạo công cụ test cho dự án tại: $TARGET_DIR"
+
+if [ -f "$SOURCE_DIR/templates/docker/test-runner.sh" ]; then
+    cp "$SOURCE_DIR/templates/docker/test-runner.sh" "$TARGET_DIR/test-runner.sh"
+    chmod +x "$TARGET_DIR/test-runner.sh"
+    echo "  ✓ Đã tạo $TARGET_DIR/test-runner.sh"
+fi
+
+if [ -f "$SOURCE_DIR/templates/setup-dependencies.sh" ]; then
+    cp "$SOURCE_DIR/templates/setup-dependencies.sh" "$TARGET_DIR/setup-test-deps.sh"
+    chmod +x "$TARGET_DIR/setup-test-deps.sh"
+    echo "  ✓ Đã tạo $TARGET_DIR/setup-test-deps.sh"
+fi
+
+echo "🎉 Khởi tạo hoàn tất! Bạn có thể mở Claude Code tại thư mục này và gõ /laravel-test-setup"
+EOF
+    chmod +x "$HOME/.local/bin/laravel-unit-test-setup"
+
+    # Tạo thêm các bí danh ngắn gọn
+    rm -f "$HOME/.local/bin/laravel-test-init" "$HOME/.local/bin/sg-test-init"
+    cp "$HOME/.local/bin/laravel-unit-test-setup" "$HOME/.local/bin/laravel-test-init"
+    cp "$HOME/.local/bin/laravel-unit-test-setup" "$HOME/.local/bin/sg-test-init"
+    chmod +x "$HOME/.local/bin/laravel-test-init" "$HOME/.local/bin/sg-test-init"
+
+    # 4. Tạo lệnh CLI toàn cục: sg-test-update (Cập nhật 1-Click cho Team)
+    cat << EOF > "$HOME/.local/bin/sg-test-update"
+#!/usr/bin/env bash
+# Smartgift AI - One-Click Toolkit Updater
+
+TOOLKIT_REPO="$CURRENT_DIR"
+TARGET_DIR="\${1:-}"
+
+# Tự động nhận diện nếu đang đứng trong một dự án Laravel
+if [ -z "\$TARGET_DIR" ] && [ -f "./composer.json" ]; then
+    TARGET_DIR="."
+fi
+
+echo "🔄 Đang cập nhật bộ công cụ Smartgift AI Unit Testing từ Git..."
+
+if [ -d "\$TOOLKIT_REPO/.git" ]; then
+    git -C "\$TOOLKIT_REPO" pull origin main
+    echo "✓ Đã kéo mã nguồn mới nhất từ remote Git."
+else
+    echo "⚠️ Không tìm thấy git repo tại \$TOOLKIT_REPO"
+fi
+
+# Tự động đồng bộ lại docs và skills
+mkdir -p "$HOME/.claude/laravel-testing-docs/templates"
+cp -R "\$TOOLKIT_REPO/docs/"* "$HOME/.claude/laravel-testing-docs/"
+cp -R "\$TOOLKIT_REPO/rules/"* "$HOME/.claude/laravel-testing-docs/"
+cp -R "\$TOOLKIT_REPO/templates/"* "$HOME/.claude/laravel-testing-docs/templates/"
+
+# Nếu có truyền đường dẫn dự án cụ thể, update luôn cho dự án đó
+if [ -n "\$TARGET_DIR" ] && [ -d "\$TARGET_DIR" ]; then
+    echo "📦 Cập nhật cho dự án: \$TARGET_DIR"
+    cp "\$TOOLKIT_REPO/templates/docker/test-runner.sh" "\$TARGET_DIR/test-runner.sh" 2>/dev/null || true
+    cp "\$TOOLKIT_REPO/templates/setup-dependencies.sh" "\$TARGET_DIR/setup-test-deps.sh" 2>/dev/null || true
+    chmod +x "\$TARGET_DIR/test-runner.sh" "\$TARGET_DIR/setup-test-deps.sh" 2>/dev/null || true
+    if [ -d "\$TARGET_DIR/.claude/testing-docs" ]; then
+        cp -R "\$TOOLKIT_REPO/docs/"* "\$TARGET_DIR/.claude/testing-docs/"
+        cp -R "\$TOOLKIT_REPO/rules/"* "\$TARGET_DIR/.claude/testing-docs/"
+    fi
+fi
+
+echo "🎉 CẬP NHẬT HOÀN TẤT! Tất cả các Skills & Docs đã ở phiên bản mới nhất."
+EOF
+    chmod +x "$HOME/.local/bin/sg-test-update"
+    cp "$HOME/.local/bin/sg-test-update" "$HOME/.local/bin/laravel-test-update"
+    chmod +x "$HOME/.local/bin/laravel-test-update"
+
+    echo -e "${GREEN}✓ CÀI ĐẶT TOÀN CỤC CHO TEAM THÀNH CÔNG RỰC RỠ!${NC}"
+    echo -e ""
+    echo -e "${YELLOW}Kể từ bây giờ, ở BẤT KỲ THƯ MỤC NÀO trên máy tính của bạn:${NC}"
+    echo -e "  1. Khi mở Claude Code (gõ 'claude'), các lệnh sau luôn sẵn sàng 100%:"
+    echo -e "     - ${CYAN}/laravel-test-setup${NC}          -> Tự động kiểm tra môi trường & cài package"
+    echo -e "     - ${CYAN}/laravel-unit-test <target>${NC}   -> Sinh test cho file, folder, hoặc --changed"
+    echo -e "     - ${CYAN}/laravel-test-review <test>${NC}   -> Chấm điểm và bắt lỗi anti-patterns"
+    echo -e "     - ${CYAN}/laravel-mock-helper <class>${NC}   -> Sinh mã Mockery nhanh"
+    echo -e "  2. Lệnh khởi tạo runner cho bất kỳ dự án nào:"
+    echo -e "     ${CYAN}laravel-unit-test-setup${NC} (hoặc ${CYAN}sg-test-init${NC})"
+    echo -e "  3. Lệnh cập nhật 1-Click khi team có thay đổi mới:"
+    echo -e "     ${CYAN}sg-test-update${NC} (hoặc ${CYAN}laravel-test-update${NC})"
+    exit 0
+fi
+
+# ==============================================================================
+# 2. XỬ LÝ CÀI ĐẶT VÀO MỘT DỰ ÁN CỤ THỂ (PROJECT-SPECIFIC MODE)
+# ==============================================================================
+TARGET_DIR="${1:-.}"
+FORCE_INSTALL=false
+
+if [ "$2" = "--force" ] || [ "$1" = "--force" ]; then
+    FORCE_INSTALL=true
+    if [ "$1" = "--force" ]; then
+        TARGET_DIR="${2:-.}"
+    fi
+fi
+
+# Chuẩn hóa đường dẫn tương đối thành tuyệt đối
+TARGET_DIR="$(cd "$TARGET_DIR" 2>/dev/null && pwd || echo "$TARGET_DIR")"
+
+if [ ! -d "$TARGET_DIR" ]; then
+    echo -e "${RED}Lỗi: Thư mục '$TARGET_DIR' không tồn tại!${NC}"
+    exit 1
+fi
+
+if [ ! -f "$TARGET_DIR/artisan" ] && [ ! -f "$TARGET_DIR/composer.json" ]; then
+    if [ "$FORCE_INSTALL" = false ]; then
+        echo -e "${YELLOW}⚠️ Cảnh báo: Thư mục '$TARGET_DIR' chưa có file artisan hoặc composer.json.${NC}"
+        echo -e "Nếu bạn vẫn muốn cài đặt trước bộ skills vào thư mục này, hãy thêm cờ: ${GREEN}--force${NC}"
+        echo -e "Ví dụ: ${BLUE}$0 $TARGET_DIR --force${NC}"
+        exit 1
+    else
+        echo -e "${YELLOW}ℹ Chế độ --force: Tiến hành cài đặt skills dù chưa có artisan/composer.json.${NC}"
+    fi
+fi
+
+echo -e "${BLUE}===================================================================${NC}"
+echo -e "${CYAN}  SMARTGIFT AI: CÀI ĐẶT LARAVEL UNIT TESTING TOOLKIT VÀO DỰ ÁN${NC}"
+echo -e "${YELLOW}  Thư mục đích: $TARGET_DIR${NC}"
+echo -e "${BLUE}===================================================================${NC}"
+
+# Tạo thư mục .claude/skills trong dự án đích
+mkdir -p "$TARGET_DIR/.claude/skills"
+echo -e "📦 Đang copy bộ skills..."
+cp -R "$CURRENT_DIR/.claude/skills/"* "$TARGET_DIR/.claude/skills/"
+
+# Tạo thư mục chứa docs tham khảo
+mkdir -p "$TARGET_DIR/.claude/testing-docs"
+cp -R "$CURRENT_DIR/docs/"* "$TARGET_DIR/.claude/testing-docs/"
+cp -R "$CURRENT_DIR/rules/"* "$TARGET_DIR/.claude/testing-docs/"
+
+# Cài đặt test runner script & dependency setup script
+if [ ! -f "$TARGET_DIR/test-runner.sh" ]; then
+    echo -e "🚀 Cài đặt smart test-runner.sh vào root của dự án..."
+    cp "$CURRENT_DIR/templates/docker/test-runner.sh" "$TARGET_DIR/test-runner.sh"
+    chmod +x "$TARGET_DIR/test-runner.sh"
+fi
+
+if [ ! -f "$TARGET_DIR/setup-test-deps.sh" ]; then
+    echo -e "📦 Cài đặt smart setup-test-deps.sh vào root của dự án..."
+    cp "$CURRENT_DIR/templates/setup-dependencies.sh" "$TARGET_DIR/setup-test-deps.sh"
+    chmod +x "$TARGET_DIR/setup-test-deps.sh"
+fi
+
+# Cài đặt GitHub Actions CI/CD Pipeline (nếu dự án dùng git)
+if [ -d "$TARGET_DIR/.github" ] || [ -d "$TARGET_DIR/.git" ]; then
+    mkdir -p "$TARGET_DIR/.github/workflows"
+    if [ ! -f "$TARGET_DIR/.github/workflows/unit-tests.yml" ]; then
+        echo -e "⚙️  Cài đặt GitHub Actions CI Workflow vào .github/workflows/unit-tests.yml..."
+        cp "$CURRENT_DIR/templates/ci/github-actions.yml.template" "$TARGET_DIR/.github/workflows/unit-tests.yml"
+    fi
+fi
+
+echo -e "${GREEN}✓ Cài đặt hoàn tất thành công!${NC}"
+echo -e ""
+echo -e "${YELLOW}Các lệnh bạn có thể sử dụng ngay trong dự án đích với Claude Code:${NC}"
+echo -e "  1. ${CYAN}/laravel-test-setup${NC}          -> Quét và kiểm tra môi trường test"
+echo -e "  2. ${CYAN}/laravel-unit-test <file|dir>${NC} -> Tự động sinh Unit Test (hỗ trợ cả file, folder, và --changed)"
+echo -e "  3. ${CYAN}/laravel-test-review <test>${NC}    -> Review chất lượng file test"
+echo -e "  4. ${CYAN}/laravel-mock-helper <class>${NC}    -> Sinh mã Mockery nhanh"
+echo -e "  5. ${CYAN}./test-runner.sh${NC}               -> Chạy test tự nhận diện Docker / Sail / Local"
+echo -e "  6. ${CYAN}./setup-test-deps.sh${NC}           -> Tự động cài thư viện test còn thiếu"