内容
# Suitest — 原生MCP测试平台
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/brand/logo-dark.svg">
<img src="assets/brand/logo-light.svg" alt="Suitest" width="380">
</picture>
</p>
<p align="center">
<strong>手动测试管理。 确定性运行。 可选的自主AI。<br>您的技术栈，您的LLM，您的數據。</strong>
</p>
<p align="center">
<a href="https://github.com/suiflex/suitest/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/suiflex/suitest/ci.yml?branch=main&style=for-the-badge" alt="CI状态"></a>
<a href="https://github.com/suiflex/suitest/releases"><img src="https://img.shields.io/github/v/tag/suiflex/suitest?include_prereleases&style=for-the-badge&label=release" alt="发布"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-4ade80.svg?style=for-the-badge" alt="Apache-2.0 License"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-native-4ade80?style=for-the-badge" alt="MCP原生"></a>
</p>
<p align="center">
<img src="assets/demo.gif" alt="Suitest 30-second demo: PRD-generated test suite executing green against the bundled Brewly demo app" width="960">
</p>
<p align="center">
<em>AI生成的测试套件（来自 <a href="./examples/demo-app/PRD.md">PRD.md</a> ）在实时应用中运行绿色 — API + 浏览器步骤，包含截图。<br>
在一个命令中重现： <code>make demo</code> → <a href="http://localhost:3000">localhost:3000</a> （ <code>demo@suitest.dev</code> / <code>demo1234</code> ）。无需LLM密钥。</em>
</p>
**Suitest** 是一个可自我托管的、开源的QA平台，完全 **无需LLM** （ZERO层级）：手动测试用例管理加上确定性运行引擎，通过 [MCP](https://modelcontextprotocol.io) 驱动任何目标（Playwright、HTTP API、Postgres等）。如果您想在上面添加AI，请插入您自己的LLM密钥（云或本地Ollama）以解锁测试生成、故障诊断和对话式测试。无需供应商锁定，无需强制API密钥。
它还附带一个 **用于IDE代理的MCP服务器** （Claude Code、Cursor、Codex）：分析存储库、生成可运行的测试、执行它们并带有视频和截图证据，并发布结果。它的 **黑盒DOM引擎** 可以仅通过URL和测试凭证测试任何Web应用程序，无需存储库访问。
后端：Python 3.12 + FastAPI · 前端：Vite + React 19 · 数据库：Postgres 16 + pgvector · 队列：ARQ/Redis · 插件层：MCP。
[文档](./docs) · [快速入门](#安装) · [MCP服务器](./docs/MCP_PLUGINS.md) · [黑盒测试](./docs/BLACKBOX_UI_TESTING.md) · [部署](./docs/DEPLOYMENT.md) · [架构](./docs/ARCHITECTURE.md) · [故障排除](./docs/TROUBLESHOOTING.md) · [贡献](./CONTRIBUTING.md)
新安装？从 [安装](#安装) 开始。 `npx @suiflex/suitest onboard` 在一个命令中启动完整的平台；MCP服务器仅需一个 `npx` 命令即可运行；团队服务器只需一个 `make docker-up` 命令。
---
## 项目状态
**预发布1.0，正在积极开发中。** 今天 **有效** 的功能：
- ✅ 手动测试管理 — 创建/编辑测试用例、步骤、套件、项目（读写）
- ✅ 通过MCP的确定性运行器 — `playwright` 、 `api-http` 、 `postgres` 提供程序
- ✅ 实时运行日志（WebSocket）、截图 + 每测试视频、MinIO工件、取消/重新运行
- ✅ 基于规则的缺陷、可追溯性矩阵、分析、集成 + CI webhook（GitHub/GitLab/Jira/Slack）
- ✅ 确定性生成器 — OpenAPI、浏览器记录器、爬虫
- ✅ **用于IDE代理的MCP服务器** （ `npx -y @suiflex/suitest-mcp` ）— 分析 → 生成 → 运行 → 发布来自Claude Code / Cursor / Codex，包括 **黑盒DOM引擎** ，可仅通过URL +凭证测试任何Web应用程序（无需存储库，无需LLM密钥）
- ✅ 每个工作区可自带LLM（设置 → LLM：Anthropic/OpenAI/Gemini/…，本地Ollama/vLLM，或任何OpenAI兼容的URL）— 解锁代理聊天、PRD驱动的测试生成、LLM代码生成
- ✅ 本地身份验证：超级管理员引导 + 仅限邀请的注册（无需OAuth）
参见 [docs/ROADMAP.md](./docs/ROADMAP.md) — 构建状态的单一来源。
---
## 安装
支持五种安装路径。
### 1. 本地捆绑包 — 一个命令（推荐的快速入门）
要求： **Node ≥ 18** 和 [uv](https://docs.astral.sh/uv/) 。
```bash
npx @suiflex/suitest onboard
```
在本地启动完整的平台 — 带有SQLite的Web仪表板 + API + 运行监督器（端口4000，备用端口4001–4009，绑定 `127.0.0.1` ）— 并在同一步骤中连接您的IDE的MCP配置。无需Docker，无需Postgres，无需LLM密钥（生成使用通过IDE代理的MCP采样）。数据存储在 `./.suitest/` 中；仪表板和Suitest轮子包含在npm包中（约3 MB）。 `suitest up` / `suitest down` 管理堆栈； `--port` 、 `--ide` 、 `--base-url` 覆盖默认值。详情： [packages/suitest-npx](./packages/suitest-npx/README.md) 。
### 2. 仅MCP服务器（无需安装）
要求： **Node ≥ 18** 和 **Python ≥ 3.11** 在PATH上。
```bash
npx -y @suiflex/suitest-mcp
```
Python原生路由（使用 [uv](https://docs.astral.sh/uv/) 的相同服务器）：
```bash
uvx --from suiflex-suitest-lifecycle suitest-mcp
```
将其连接到Claude Code / Cursor（ `.mcp.json` ）：
```json
{
"mcpServers": {
"suitest": {
"command": "npx",
"args": ["-y", "@suiflex/suitest-mcp"],
"env": { "SUITEST_API_URL": "http://localhost:4000", "SUITEST_API_KEY": "sk_suitest_…" }
}
}
}
```
代理获得22种工具：基于存储库的生命周期（分析 → 生成 → 运行 → 报告）， **黑盒引擎** 用于您没有存储库的应用程序（浏览器设置向导、登录检测、安全爬取、确定性Playwright生成、证据），以及PRD驱动的规划。 `SUITEST_API_URL` / `KEY` 是可选的 — 有了它们，案例/运行/证据发布到Web TCM中；没有它们，结果保留在 `suitest-output/` 下。
### 3. 完整平台 — Docker Compose
要求： **Docker + Docker Compose** 。
```bash
git clone https://github.com/suiflex/suitest && cd suitest
cp .env.example .env
```
在 `.env` 中设置超级管理员，以便您可以登录（ZERO层级不需要LLM）：
```bash
SUITEST_AUTH_SECRET=<32-char-random-hex> # openssl rand -hex 32
SUITEST_SUPERADMIN_EMAIL=admin@example.com
SUITEST_SUPERADMIN_PASSWORD=<strong-password>
```
```bash
make docker-up # 拉取预构建的 ghcr.io/suiflex/suitest-* 镜像并启动堆栈
open http://localhost:3000
```
应用镜像（ `api` 、 `web` 、 `runner` ）根据 `images-v*` 版本在GHCR上预构建 — 无需本地构建。 使用 `SUITEST_IMAGE_TAG=<version>` 固定一个版本；使用 `make docker-up-prod` 从源代码构建。
使用超级管理员电子邮件/密码登录。 从 **设置 → 邀请** 其他用户 — 默认情况下注册仅限邀请。 默认层级为 **ZERO** — 永远不会调用LLM。 可选配置文件： `--profile local` 添加了一个用于空气隔离LOCAL层级推理的Ollama服务。
演示数据： `make seed` （或 `docker compose -f infra/docker/docker-compose.yml exec api python -m suitest_db.seed` ）。
### 4. Kubernetes — Helm
要求：集群 + [Helm](https://helm.sh) ；Postgres/Redis/对象存储作为外部服务（ `values.yaml` 中的URL）。
```bash
helm install suitest infra/helm/suitest -f infra/helm/suitest/values.yaml
# 空气隔离（LOCAL层级，通过集群内Ollama）：
helm install suitest infra/helm/suitest -f infra/helm/suitest/values-airgapped.yaml
```
图表分别部署 `api` 、 `web` 和 `runner` ，带有PodDisruptionBudget。 完整指南（环境变量、TLS、备份、空气隔离检查清单）： [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md) · 图表注释： [infra/README.md](./infra/README.md) 。
### 5. 本地开发（应用程序无需Docker）
要求： **Python 3.12 + [uv](https://docs.astral.sh/uv/)** ， **Node 20 + [pnpm](https://pnpm.io/)** ，以及Postgres/Redis/MinIO（最简单： `docker compose -f infra/docker/docker-compose.yml up -d postgres redis minio` ）。
```bash
make setup # cp .env → 安装依赖 → 运行迁移 → 种子数据库
make dev # 同时启动API（:4000）+ web（:3000）+ runner
```
其他有用目标（完整列表参见 `make help` ）：
| 命令 | 执行操作 |
|---------|------|
| `make dev-api` / `dev-web` / `dev-runner` | 启动一个服务 |
| `make migrate` / `migrate-new m="..."` | 应用/创建Alembic迁移 |
| `make seed` | 种子演示数据 |
| `make ci` | CI运行的所有操作：lint + 类型检查 + 测试（Python + Web） |
| `make check-all` | 仅lint + 类型检查（无测试） |
| `make docker-up-local` / `docker-up-cloud` | 启动Ollama / 云LLM配置文件 |
---
## 您的第一个测试（仅UI，无LLM）
从空安装中，您可以在不接触API的情况下引导并运行真正的浏览器测试：
1. **登录** （超级管理员电子邮件/密码）。 安装时会创建一个 **工作区** ；侧边栏选择器（ `＋ 新建工作区` ）会创建更多。
2. **创建项目，然后创建测试套件** — 测试用例屏幕在每个为空时都会提示您。
3. **编写测试用例** — “新建用例”，然后添加步骤。 一个步骤针对MCP提供程序（例如捆绑的 **`playwright-mcp` `， `target_kind = FE_WEB` ）带有JSON工具调用，例如 `{"tool":"browser_navigate","arguments":{"url":"https://www.saucedemo.com"}}` 。
4. **立即运行** — 确定性运行器通过MCP调度每个步骤（Playwright驱动真实浏览器），运行详情页面 **流式传输实时状态到PASS/FAIL** 。
5. **分类** — 失败的步骤 **自动归档缺陷** （基于规则，ZERO）；将测试套件标记为 ** gating** 以阻止部署； 在 **仪表板** 上查看通过率/就绪度。
整个旅程由一个无模拟、真实后端Playwright套件锁定 — `make e2e-real` （启动ZERO api + web + runner，种子一个空工作区，并驱动UI针对实时堆栈）。
---
## 启用AI（可选）
LLM提供商 **每个工作区从Web UI配置** — `设置 → LLM` — 而不是通过环境变量。 密钥在存储时使用AES-GCM加密，并且永远不会再次显示。 设置提供商会将工作区层级升级（ZERO → CLOUD/LOCAL），并解锁代理聊天、PRD驱动的生成和LLM代码生成。
- **CLOUD** — 自带密钥：Anthropic、OpenAI、Gemini、Groq、OpenRouter、DeepSeek、…（通过 [LiteLLM](https://docs.litellm.ai) 100+提供商）或 **`custom`** — 任何OpenAI兼容的基准URL（网关、路由器、代理）。
- **LOCAL** — 优先考虑隐私/空气隔离：Ollama、llama.cpp、vLLM、LM Studio（ `make docker-up-local` 提供了Ollama服务）。
默认始终为 **ZERO** ：在显式配置工作区之前，永远不会调用LLM。
---
## 功能层级
| 层级 | 触发器 | 您获得的功能 |
|------|---------|--------------|
| **ZERO** | 未配置工作区LLM（默认） | 完整的手动测试管理，通过MCP进行确定性运行，确定性生成器，黑盒引擎，基于规则的缺陷，可追溯性，分析，集成 + CI网络钩子。 永远不会调用LLM。 |
| **LOCAL** | 工作区LLM = `ollama` / `llamacpp` / `vllm` / `lmstudio` | ZERO拥有的所有功能 + AI功能，所有推理都在您的硬件上进行。 |
| **CLOUD** | 工作区LLM = `anthropic` / `openai` / `gemini` / `custom` / … | 与LOCAL相同，使用云LLM，具有成本跟踪 + 预算防护。 |
详情： [docs/CAPABILITY_TIERS.md](./docs/CAPABILITY_TIERS.md) 。
---
## 仓库结构
```
suitest/
├── README.md ← 你在这里
├── CLAUDE.md ← AI代理的编码规则（Cursor / Claude Code）
├── Makefile ← 所有开发命令（make help）
│
├── apps/
│ ├── web/ ← Vite 6 + React 19（Suitest UI）
│ ├── api/ ← FastAPI后端
│ └── runner/ ← ARQ工作器（每步MCP调度）
│
├── packages/
│ ├── agent/ ← LiteLLM路由器 + 代理图
│ ├── db/ ← SQLAlchemy 2 异步 + Alembic + 种子
│ ├── mcp/ ← MCP客户端 + 注册表 + 池 + 捆绑提供程序
│ ├── lifecycle/ ← MCP服务器：分析→生成→运行→发布 + 黑盒引擎
│ ├── mcp-npx/ ← @suiflex/suitest-mcp — MCP服务器的npx启动器
│ ├── suitest-npx/ ← @suiflex/suitest — 一键本地平台启动器
│ ├── shared/ ← 跨包Pydantic模式
│ └── core/ ← 能力解析器，自主性，AES-GCM加密
│
├── sdk/
│ ├── python/ ← suiflex-suitest-sdk（生命周期使用的REST客户端）
│ └── typescript/ ← @suiflex/suitest-sdk
│
├── assets/brand/ ← logo.svg + 浅色/深色徽标 + 标记
│
├── infra/
│ ├── docker/ ← 每个服务的Dockerfile
│ └── helm/suitest/ ← Helm图表
│
└── docs/ ← 参见下面的文档索引
```
---
## 文档
**从 [docs/ROADMAP.md](./docs/ROADMAP.md) 开始** — 它是选择任何功能的单一入口。 仅在您正在处理的功能需要时打开下面的规范文档。
| 文档 | 主题 |
|-----|-------|
| [ROADMAP.md](./docs/ROADMAP.md) | 里程碑M0 → M15 + 构建状态（从这里开始） |
| [PRODUCT.md](./docs/PRODUCT.md) | 愿景、角色、用户旅程 |
| [ARCHITECTURE.md](./docs/ARCHITECTURE.md) | 堆栈、服务、拓扑 |
| [DATA_MODEL.md](./docs/DATA_MODEL.md) | SQLAlchemy模式 + 实体图 |
| [API.md](./docs/API.md) | REST + WebSocket合约 |
| [UI_SPEC.md](./docs/UI_SPEC.md) | 屏幕组件规范 |
| [CAPABILITY_TIERS.md](./docs/CAPABILITY_TIERS.md) | ZERO/LOCAL/CLOUD 分级 |
| [MCP_PLUGINS.md](./docs/MCP_PLUGINS.md) | MCP注册表 + 路由 + 沙盒安全 |
| [GENERATORS.md](./docs/GENERATORS.md) | 生成器设计（确定性和LLM） |
| [AUTONOMY.md](./docs/AUTONOMY.md) | 工作区自主权调节器 |
| [AI_AGENT.md](./docs/AI_AGENT.md) | 提示 + LangGraph + 工具注册表（规范，M3） |
| [BLACKBOX_UI_TESTING.md](./docs/BLACKBOX_UI_TESTING.md) | 黑盒DOM引擎 — 仅需URL即可测试任何Web应用程序（Zero + MCP） |
| [DEPLOYMENT.md](./docs/DEPLOYMENT.md) | 组合 / Helm / 空气隔离 |
---
## 对比
| 功能 | TestRail | Playwright | TestSprite | **Suitest ZERO** | **Suitest CLOUD** |
|------------|:--:|:--:|:--:|:--:|:--:|
| 一流的手动测试管理 | ✓ | ✗ | 部分 | ✓ | ✓ |
| 确定性运行器 | ✗ | ✓ | ✓ | ✓ | ✓ |
| 通用MCP插件层 | ✗ | ✗ | 部分 | ✓ | ✓ |
| AI生成/诊断 | ✗ | ✗ | ✓ | ✗ | ✓ |
| 自我托管 | ✓ | ✓ | ✗ | ✓ | ✓ |
| 自带LLM（100+提供商） | n/a | n/a | ✗ 锁定 | n/a | ✓ |
| 空气隔离 | ✓ | ✓ | ✗ | ✓ | ✓（Ollama） |
| 开源 | ✗ | 仅运行器 | ✗ | ✓ | ✓ |
---
## 贡献
1. **阅读 [CLAUDE.md](./CLAUDE.md)** — 本仓库的绑定约定（也适用于AI编码代理）。
2. **选择 [docs/ROADMAP.md](./docs/ROADMAP.md) 中的下一个未勾选项目** — 一个PR = 一个验收标准。 路线图会告诉你哪个规格文档需要打开。
3. **分支：** `feat/<范围>-<简短描述>`。 **提交：** 传统提交（`feat(api): ...`）。
4. **推送前：** `make ci` 必须通过（ruff + mypy 严格，tsc 严格 + ESLint，pytest 异步 + vitest）。
参见 [CONTRIBUTING.md](./CONTRIBUTING.md)， [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)，和 [SECURITY.md](./SECURITY.md)。
---
## 许可证
Apache License 2.0。 参见 [LICENSE](./LICENSE)。
## 致谢
基于 [Model Context Protocol](https://modelcontextprotocol.io) （Anthropic）， [LiteLLM](https://github.com/BerriAI/litellm) （BerriAI）， [LangGraph](https://langchain-ai.github.io/langgraph/) （LangChain）， [`@ai-sdk/react`](https://sdk.vercel.ai/docs) + assistant-ui（Vercel），shadcn/ui，TanStack，以及FastAPI / SQLAlchemy / Pydantic生态系统。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器