MrleeAdmin/.windsurf/skills/backend-tests/SKILL.md

name, description

name	description
backend-tests	通用的测试脚本管理技能，专注于测试脚本的归类、组织和管理，避免脚本散落在根目录

Tester Skill

本技能专注于测试脚本的组织、归类和管理。当需要创建、管理或执行测试脚本时，应使用此技能来确保所有测试脚本都按标准目录结构归类存放。

何时使用此技能

当遇到以下情况时使用此技能：

1. 测试脚本散落在项目根目录，需要整理归类
2. 需要创建新的测试脚本，需要遵循标准目录结构
3. 需要管理和组织测试脚本文件
4. 需要执行批量测试或验证
5. 需要统一的测试脚本管理规范

如何使用此技能

1. 测试目录结构管理规范

所有测试脚本必须归类存放，禁止在项目根目录创建临时测试文件。使用以下简化目录结构（最多一层子目录）：

backend/tests/
├── plugin/                         # 插件相关测试（直接放文件）
├── unit/                           # 单元测试（直接放文件）
├── integration/                    # 集成测试（直接放文件）
├── e2e/                           # 端到端测试（直接放文件）
├── scripts/                       # 测试脚本工具（直接放文件）
└── fixtures/                      # 测试数据文件（直接放文件）

2. 测试脚本创建和归类流程

创建测试脚本时应遵循以下流程：

1. 确定测试类型：根据测试目的选择适当的目录（unit/integration/e2e/plugin等）
2. 创建标准目录：如果目录不存在，先创建标准目录结构
3. 命名规范：使用有意义的文件名，如 user-model-test.php、api-auth-test.php
4. 归类存放：将脚本放在正确的子目录中，避免根目录
5. 清理临时文件：测试完成后，清理并删除临时测试文件
6. 更新目录文档：更新相应目录的 README 或说明文件

2. 测试脚本归类规则

所有测试脚本必须按以下规则归类存放（最多一层目录）：

2.1 按测试类型归类

• 单元测试：tests/unit/ - 测试单个类或方法（直接放文件）
• 集成测试：tests/integration/ - 测试多个组件的交互（直接放文件）
• 端到端测试：tests/e2e/ - 测试完整业务流程（直接放文件）
• 插件测试：tests/plugin/ - 专门测试插件功能（直接放文件）
• 性能测试：tests/performance/ - 测试性能和负载（直接放文件）

2.2 命名规范

• 使用有意义的文件名，如 user-model-test.php、api-auth-test.php
• 文件名应反映测试内容，避免通用名称如 test.php、check.php

2.3 禁止行为

• ❌ 禁止在项目根目录创建测试脚本
• ❌ 禁止在 public/、vendor/ 等目录创建测试脚本
• ❌ 禁止使用临时文件名（如 test1.php、temp.php）
• ❌ 禁止测试脚本残留临时文件
• ❌ 禁止创建多层子目录结构（最多一层）

4. 测试脚本质量标准

所有测试脚本应满足以下质量标准：

• ✅ 按标准目录结构归类存放
• ✅ 使用有意义的文件名，描述测试内容
• ✅ 包含清晰的注释和文档说明
• ✅ 输出标准的测试结果格式（✓/✗/⚠）
• ✅ 自动清理临时文件和资源
• ✅ 支持命令行参数和配置选项
• ✅ 可独立运行，不依赖复杂环境

5. 常用测试脚本模板

4.1 单元测试模板（简化版）

<?php
// tests/unit/UserModelTest.php
namespace Tests\Unit;

use App\Models\User;

class UserModelTest
{
    public function testUserCreation()
    {
        echo "=== 用户模型测试 ===\n";
        
        // 测试用户创建逻辑
        $user = new User(['name' => 'Test User']);
        
        if ($user->name === 'Test User') {
            echo "✓ 用户创建测试成功\n";
        } else {
            echo "✗ 用户创建测试失败\n";
        }
    }
}

4.2 API集成测试模板（简化版）

<?php
// tests/integration/AuthApiTest.php
namespace Tests\Integration;

class AuthApiTest
{
    public function testLoginApi()
    {
        echo "=== API认证测试 ===\n";
        
        // 测试登录API逻辑
        $response = $this->simulateApiCall('/api/login', [
            'username' => 'test',
            'password' => 'password'
        ]);
        
        if ($response['status'] === 200 && isset($response['token'])) {
            echo "✓ API认证测试成功\n";
        } else {
            echo "✗ API认证测试失败\n";
        }
    }
    
    private function simulateApiCall($endpoint, $data)
    {
        // 模拟API调用逻辑
        return ['status' => 200, 'token' => 'mock_token'];
    }
}

4.3 插件安装测试模板（简化版）

<?php
// tests/plugin/MigrationTest.php
namespace Tests\Plugin;

class MigrationTest
{
    public function run()
    {
        echo "=== 迁移文件测试 ===\n";
        
        // 测试迁移文件语法
        $this->testMigrationSyntax();
        
        // 测试索引名称长度
        $this->testIndexNames();
        
        // 测试引擎设置
        $this->testEngineSettings();
    }
    
    private function testMigrationSyntax()
    {
        // 迁移文件语法测试逻辑
    }
}

6. 批量测试执行和归类检查

5.1 运行所有测试（简化版）

使用 tests/scripts/run-all-tests.php 脚本执行所有归类好的测试：

<?php
// tests/scripts/run-all-tests.php
echo "=== 批量测试执行 ===\n";

// 扫描所有测试目录中的文件
$testDirectories = ['plugin', 'unit', 'integration', 'e2e'];

foreach ($testDirectories as $directory) {
    $dirPath = __DIR__ . '/../' . $directory;
    if (!is_dir($dirPath)) {
        continue;
    }
    
    echo "=== 执行 {$directory} 测试 ===\n";
    
    $files = scandir($dirPath);
    foreach ($files as $file) {
        if ($file !== '.' && $file !== '..' && pathinfo($file, PATHINFO_EXTENSION) === 'php') {
            $testPath = $dirPath . '/' . $file;
            include $testPath;
        }
    }
}

5.2 检查测试脚本归类（简化版）

使用以下脚本检查是否有未归类的测试文件：

<?php
// tests/scripts/check-classification.php
echo "=== 测试脚本归类检查 ===\n";

// 允许的目录
$allowedDirs = ['tests/', 'vendor/'];

// 查找项目根目录中的测试文件
function findTestFiles($dir)
{
    $testFiles = [];
    $patterns = ['/test.*\.php$/i', '/.*test\.php$/i', '/check.*\.php$/i'];
    
    if ($handle = opendir($dir)) {
        while (false !== ($entry = readdir($handle))) {
            if ($entry === '.' || $entry === '..') continue;
            
            $path = $dir . '/' . $entry;
            
            if (is_dir($path)) {
                // 递归查找子目录
                $testFiles = array_merge($testFiles, findTestFiles($path));
            } else {
                // 检查是否是测试文件
                foreach ($patterns as $pattern) {
                    if (preg_match($pattern, $entry)) {
                        $testFiles[] = $path;
                        break;
                    }
                }
            }
        }
        closedir($handle);
    }
    
    return $testFiles;
}

// 检查测试文件是否在允许的目录中
$projectRoot = realpath(__DIR__ . '/../../');
$allTestFiles = findTestFiles($projectRoot);
$unclassified = [];

foreach ($allTestFiles as $file) {
    $isAllowed = false;
    foreach ($allowedDirs as $allowed) {
        if (strpos($file, $allowed) !== false) {
            $isAllowed = true;
            break;
        }
    }
    
    if (!$isAllowed) {
        $unclassified[] = $file;
    }
}

// 输出结果
if (count($unclassified) > 0) {
    echo "⚠ 发现 " . count($unclassified) . " 个未正确归类的测试脚本:\n\n";
    foreach ($unclassified as $file) {
        $relativePath = str_replace($projectRoot . '/', '', $file);
        echo "  • " . $relativePath . "\n";
    }
    echo "\n请将这些文件移动到 tests/ 目录下的相应子目录中。\n";
} else {
    echo "✓ 所有测试脚本都已正确归类到 tests/ 目录中。\n";
}

6. 测试结果验证

每个测试脚本应输出明确的验证结果：

• ✓ 成功：绿色标记
• ✗ 失败：红色标记
• ⚠ 警告：黄色标记
• 详细说明：问题描述和修复建议

7. 临时文件管理

所有测试脚本应在完成后清理临时文件：

// 清理临时文件
$tempFiles = ['test_*.php', 'check_*.php', 'fix_*.php'];
foreach ($tempFiles as $pattern) {
    // 查找并删除临时文件
}

技能资源

本技能包含以下资源：

脚本资源 (scripts/)

• create-test-directory.php：创建测试目录结构的脚本
• test-template-generator.php：生成各种测试脚本模板
• validate-migration-files.php：验证迁移文件的完整脚本
• check-index-names.php：检查索引名称长度的脚本

参考资源 (references/)

• mysql-limitations.md：MySQL 限制参考（标识符长度、引擎等）
• laravel-migration-guide.md：Laravel 迁移最佳实践指南
• plugin-install-flow.md：插件安装流程和常见问题
• testing-best-practices.md：测试最佳实践和标准

资产资源 (assets/)

• test-directory-structure.txt：测试目录结构模板
• test-script-templates/：各种测试脚本模板文件
• expected-output-examples/：预期输出示例

执行流程示例

场景1：测试脚本归类检查

1. 使用 tests/scripts/check-classification.php 检查是否有未归类的测试脚本
2. 将发现的临时测试文件移动到正确的 tests/ 子目录中
3. 使用有意义的文件名重命名测试文件
4. 执行 tests/scripts/cleanup-temp.php 清理残留临时文件

场景2：创建新的插件测试

1. 在 tests/plugin/ 目录下创建新的测试文件，如 official-plugin-test.php
2. 编写测试逻辑，包含清晰的注释和输出格式
3. 执行测试验证功能是否正常
4. 确保测试完成后清理所有临时资源

场景3：批量执行测试

1. 使用 tests/scripts/run-all-tests.php 执行所有测试
2. 查看测试结果报告，识别失败的测试
3. 修复失败的测试或相关问题
4. 重新执行测试确保所有测试通过

通过本技能，可以系统化地管理和执行插件安装相关的测试工作，确保所有修复都经过充分验证，避免重复问题。