# testcenter

**Repository Path**: dragondjf/testcenter

## Basic Information

- **Project Name**: testcenter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TestCenter

![license](https://img.shields.io/badge/license-MIT-green) ![backend](https://img.shields.io/badge/backend-Flask%203-blue) ![frontend](https://img.shields.io/badge/frontend-React%2018%20%2B%20Antd%205-61dafb) ![db](https://img.shields.io/badge/storage-SQLite-orange)

轻量级脚本测试平台：管理脚本型测试用例，支持 **Python / JavaScript / Shell / PowerShell** 四种语言执行，提供套件编排、cron 定时调度、执行报告、在线调试，并可无侵入对接外部用例平台。

## 功能总览

| 模块 | 说明 |
|---|---|
| 项目 / 用例管理 | 用例 = 脚本内容 + 语言 + 超时，按项目分组，Monaco 在线编辑 |
| 套件（Suite） | 用例有序集合，串行执行，支持"失败即停" |
| 计划（Plan） | 套件/用例混合编排 + 5 段 cron 定时（APScheduler，重启自动恢复） |
| 执行（Execution） | 并发队列、失败重试、数据集展开、逐用例结果 + 汇总报告、趋势图 |
| 在线调试器 | 单用例即时运行，实时查看输出、步骤与断言明细、产物文件 |
| 环境变量 | 多环境管理，执行时注入，敏感值加密存储 |
| 用户与认证 | 登录会话 / 角色权限 / 可选全局 Token 认证 |
| 通知渠道 | Webhook 终态通知，可按"失败 / 停止"事件订阅 |
| 外部用例源 | 无侵入对接独立用例平台：只读代理 + 调试代理 + 收藏引用可纳入编排 |
| 解释器管理 | 页面配置各语言解释器路径，适配任意机器环境 |

## 架构

```mermaid
flowchart LR
    subgraph client["浏览器"]
        UI["React 18 + Antd 5\nMonaco Editor"]
    end
    subgraph server["Flask 后端 :5000"]
        API["REST API（/api 前缀）"]
        AUTH["认证服务"]
        SCHED["APScheduler\ncron 调度"]
        QUEUE["并发执行队列"]
        EXEC["执行器 runner.py"]
    end
    subgraph langs["语言执行器（子进程隔离）"]
        PY["Python"]
        JS["JavaScript"]
        SH["Shell"]
        PS["PowerShell"]
    end
    DB[("SQLite\ndata/")]
    EXT["外部用例平台\n（只读代理）"]
    HOOK["Webhook 通知"]

    UI -->|"axios /api"| API
    API --> AUTH
    SCHED --> QUEUE
    API --> QUEUE
    QUEUE --> EXEC
    EXEC --> PY & JS & SH & PS
    API --> DB
    EXEC --> DB
    API --> EXT
    EXEC --> HOOK
```

**关键设计：**

- **子进程隔离**：每个用例独立子进程执行，超时 kill，stdout/stderr 双阈值截断（30KB 展示截断 / 150KB 硬截断）
- **结果协议**：exit code 判基础结果，`result.json` 提供步骤/断言结构化明细
- **无侵入对接**：外部平台零改动，本平台不向外部回写任何数据，凭据加密存储

## 目录结构

```
testcenter/
├── backend/                     # Flask 后端（端口 5000）
│   ├── run.py                   # 启动入口（waitress）
│   ├── app/
│   │   ├── __init__.py          # create_app 工厂 + 可选 Token 认证
│   │   ├── config.py            # 路径/超时/截断阈值
│   │   ├── extensions.py        # db / scheduler 单例
│   │   ├── migration.py         # 轻量 schema 迁移
│   │   ├── models/              # 12 个模型（Project/TestCase/Suite/Plan/Execution/User/...）
│   │   ├── routes/              # 13 个 REST 蓝图（/api 前缀）
│   │   ├── services/            # 认证 / 加密 / 调度 / 通知 / 解释器 / 并发守卫
│   │   ├── executor/            # 4 语言执行器 + 注册表 + runner.py 执行编排
│   │   └── external/            # 外部用例源客户端
│   ├── tests/                   # pytest（单元 + API 集成）
│   └── data/                    # 运行数据（SQLite + 执行产物，已 gitignore）
├── frontend-react/              # React 18 + Antd 5 + Zustand（vite，端口 5273）
│   └── src/
│       ├── api/                 # 后端 API 封装
│       ├── views/               # 11 个页面（用例/套件/计划/报告/调试器/外部用例/...）
│       ├── components/          # 通用组件
│       ├── stores/              # Zustand 状态
│       └── themes/              # 主题
├── tools/
│   ├── devtools.py              # clean / package 跨平台实现
│   └── simple_external_platform.py  # 模拟外部用例平台（联调用）
├── Makefile                     # 一键开发 / 测试 / 打包
└── dist_release/                # 发布产物（已 gitignore）
```

## 核心工作流

```mermaid
flowchart TD
    A[触发执行\n手动调试 / 套件运行 / 计划 cron] --> B[创建 Execution 记录\n入并发队列]
    B --> C{逐用例执行}
    C --> D[子进程启动\n注入 TC_* 环境变量]
    D --> E{exit code = 0?}
    E -->|否| F[failed]
    E -->|是| G{result.json?\n存在失败明细?}
    G -->|是| F
    G -->|否| H[success]
    F --> I{订阅通知?}
    H --> I
    I -->|失败/停止| J[Webhook]
    I --> K[报告页轮询展示\n步骤/断言/产物/趋势]
```

**数据模型关系：**

```mermaid
erDiagram
    Project ||--o{ TestCase : contains
    Project ||--o{ Suite : contains
    Suite ||--o{ SuiteCase : orders
    TestCase ||--o{ SuiteCase : "in suite"
    Plan ||--o{ PlanItem : mixes
    PlanItem }o--|| Suite : "or TestCase"
    Plan ||--o{ Execution : schedules
    Execution ||--o{ ExecutionCase : results
    Environment }o--o{ Execution : injects
    ExternalSource ||--o{ ExternalCaseRef : favorites
```

## 快速开始

### 方式一：Makefile（推荐，跨 Windows / Linux / macOS）

```bash
make help          # 查看全部目标
make install       # 安装全部依赖（后端 venv + React 前端）
make -j4 dev       # 并行启动全部开发服务
make test          # 后端 pytest 全量测试
make test-react    # 前端 vitest 测试
make build         # 前端生产构建
make package       # 构建 + 生成发布 zip 到 dist_release/
make clean         # 清理缓存日志（保留 venv / node_modules / data）
```

### 方式二：手动启动

**后端**

```powershell
cd backend
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\python.exe run.py     # 默认 http://127.0.0.1:5000
```

**前端**

```powershell
cd frontend-react
npm install
npm run dev                          # http://localhost:5273（/api 代理到 5000）
```

## 服务端口一览

| 服务 | 地址 | 说明 |
|---|---|---|
| Flask API | http://localhost:5000 | 后端 REST API |
| React UI | http://localhost:5273 | 前端开发服务器 |
| 外部平台模拟器 | http://localhost:5100 | `make dev-external`，外部用例源联调 |

## 配置（环境变量）

| 变量 | 默认 | 说明 |
|---|---|---|
| `TC_HOST` | `127.0.0.1` | 后端监听地址；局域网访问设为 `0.0.0.0` |
| `TC_PORT` | `5000` | 后端端口 |
| `TC_AUTH_TOKEN` | 空（关闭） | 设置后所有 API 要求 `X-Auth-Token` 请求头（`/api/health` 与 CORS 预检豁免） |

> 安全提示：平台会执行用户提交的任意脚本。仅监听 `127.0.0.1` 供本机使用；如需局域网开放，务必设置 `TC_AUTH_TOKEN` 并使用登录认证。

## 脚本结果协议

脚本通过 **exit code**（0 = 通过）报告基础结果，另可选在同目录写入 `result.json` 提供结构化明细：

```json
{
  "status": "failed",
  "steps": [
    {"name": "登录", "status": "success", "message": "200 OK"}
  ],
  "assertions": [
    {"name": "状态码为 200", "passed": true}
  ]
}
```

判定规则（`_derive_status`）：exit code 非 0 直接 failed；`result.json` 中 `status` 为 `failed`/`error`，或任一 step/assertion 失败，也判 failed。

脚本上下文（环境变量注入）：

| 变量 | 说明 |
|---|---|
| `TC_CASE_ID` | 当前用例 ID |
| `TC_PROJECT_ID` | 所属项目 ID |
| `TC_EXECUTION_ID` | 本次执行 ID |
| `TC_RESULT_DIR` | 产物目录：截图 / 日志写入此处，即可在调试器与报告中查看 |

输出保护：stdout/stderr 超 30KB 展示截断、超 150KB 硬截断；结构化明细最多 1000 条且整体不超 150KB，超限自动降级丢弃。

## 测试与打包

```bash
# 后端（pytest 单元 + API 集成）
cd backend && .venv\Scripts\python.exe -m pytest tests -v

# 前端（vitest 单测 + Playwright E2E）
cd frontend-react && npm run test && npm run test:e2e

# 一键发布包（后端源码 + 前端构建产物 + tools + 文档）
make package        # 产物位于 dist_release/
```

## 技术栈

| 层 | 技术 |
|---|---|
| 后端 | Python / Flask 3 / SQLAlchemy / APScheduler / waitress |
| 前端 | React 18 / Ant Design 5 / Zustand / React Router / Monaco Editor / Vite |
| 测试 | pytest（后端）/ Vitest + Testing Library + Playwright（前端） |
| 存储 | SQLite（零部署依赖） |