opencroc

v1.8.1

Published

3 hours ago

AI-native project intelligence platform — universal scanner, knowledge graph, risk analysis, multi-perspective reports, and E2E testing

0High
0Medium
0Low

wangchunji

project-intelligence knowledge-graph code-analysis risk-detection e2e testing ai playwright test-generation self-healing source-aware multi-language scanner

OpenCroc 是什么？

OpenCroc 是一个构建在 Playwright 之上的 AI 原生端到端测试框架。你不需要手写大量脚本，OpenCroc 会读取后端源码（模型、控制器、DTO），并自动生成完整 E2E 测试套件，包括 API 调用链、种子数据、请求体与断言。

当测试失败时，OpenCroc 不只是报错，而是会沿完整请求链路定位根因、生成修复补丁，并自动回归验证修复结果。

核心能力

| 能力 | 说明 | |---|---| | 源码感知测试生成 | 通过 ts-morph 解析 Sequelize/TypeORM 模型、Express/NestJS 控制器、DTO 装饰器，识别 API 面 | | AI 配置生成 | 使用 LLM 生成请求模板、种子数据、参数映射，并通过三层校验（schema -> semantic -> dry-run） | | 智能调用链规划 | 构建 API 依赖 DAG，做拓扑排序并以贪心策略提升覆盖率 | | 日志驱动完成判定 | 超越 networkidle，通过后端日志（api_exec end）确认请求真正完成 | | 失败链路归因 | 从网络异常 -> 慢接口 -> 后端日志逐层追踪，定位根因 | | 可控自愈机制 | backup -> AI patch -> dry-run -> apply -> re-run -> verify -> rollback，每步有安全闸门 | | 影响面分析 | 基于外键关系做 BFS 传播分析，自动输出 Mermaid 图 |

快速开始

前置要求

Node.js >= 18
使用 Express/NestJS + Sequelize/TypeORM 的后端项目

安装

npm install opencroc --save-dev

初始化

npx opencroc init

该命令会：

扫描项目结构
识别 ORM 与后端框架
生成默认 opencroc.config.ts
生成一套示例测试

生成测试

# 为单个模块生成测试
npx opencroc generate --module=knowledge-base

# 为所有模块生成测试
npx opencroc generate --all

# 仅预览，不落盘
npx opencroc generate --all --dry-run

运行测试

# 运行全部生成的测试
npx opencroc test

# 运行指定模块
npx opencroc test --module=knowledge-base

# 启用自愈运行
npx opencroc test --self-heal

校验 AI 配置

# 校验所有生成配置
npx opencroc validate --all

# 比较两份报告差异
npx opencroc compare --baseline=report-a.json --current=report-b.json

启动 OpenCroc Studio

OpenCroc Studio 是一个像素风鳄鱼办公室 + 实时知识图谱 UI。它在本地启动一个 Web 服务器，可视化展示项目结构、Agent 状态和测试结果。

# 启动 Studio（自动打开浏览器 http://localhost:8765）
npx opencroc serve

# 自定义端口
npx opencroc serve --port 3000

# 不自动打开浏览器
npx opencroc serve --no-open

# 指定 host（如远程访问）
npx opencroc serve --host 0.0.0.0 --port 8765

Studio 功能：

知识图谱画布 — 项目模型、控制器、API 关系的可交互图谱（拖拽、缩放、悬停提示）
像素鳄鱼办公室 — 6 只 AI 鳄鱼 Agent（解析鳄 🐊、分析鳄 🐊、测试鳄 🐊、修复鳄 🐊、规划鳄 🐊、汇报鳄 🐊），带实时状态动画
实时 WebSocket — Agent 状态和图谱变化即时推送到浏览器
模块侧边栏 — 一目了然浏览已发现的模块和 Agent 状态
REST API — GET /api/project（图谱数据）、GET /api/agents（Agent 状态）、POST /api/project/refresh（重新扫描）

完整流水线（一条命令）

# 一键运行：generate → execute → analyze → heal → report
npx opencroc run

# 带选项
npx opencroc run --module=users --self-heal --report html,json

CI/CD 集成

# 生成 GitHub Actions 工作流
npx opencroc ci --platform github

# 生成 GitLab CI 管道
npx opencroc ci --platform gitlab --self-heal

Dashboard 与报告

# 生成可视化 Dashboard
npx opencroc dashboard

# 生成多格式报告
npx opencroc report --format html,json,markdown

架构

┌─────────────────────────────────────────────────────────────┐
│              OpenCroc Studio (localhost:8765)                │
│    像素鳄鱼办公室  +  知识图谱  +  WebSocket                 │
├─────────────────────────────────────────────────────────────┤
│                     CLI / Orchestrator                       │
├──────────┬──────────┬──────────┬──────────┬─────────────────┤
│  Source   │  Chain   │  Test    │ Execution│   Self-Healing  │
│  Parser   │ Planner  │Generator │  Engine  │     Engine      │
│           │          │          │          │                 │
│ ts-morph  │ DAG +    │ Template │Playwright│ AI Attribution  │
│ Model     │ Topo     │ + AI     │ + Log    │ + Controlled    │
│ Controller│ Sort +   │ Config   │ Driven   │ Fix + Verify    │
│ DTO       │ Greedy   │ Merge    │ Assert   │ + Rollback      │
├──────────┴──────────┴──────────┴──────────┴─────────────────┤
│              Observation Bus (Network + Backend Logs)         │
├──────────────────────────────────────────────────────────────┤
│              Report Engine (HTML / JSON / Markdown)           │
└──────────────────────────────────────────────────────────────┘

6 阶段流水线

Source Scan -> ER Diagram -> API Analysis -> Chain Planning -> Test Generation -> Failure Analysis
     │            │             │              │                │                  │
  ts-morph    Mermaid      Dependency       Topological     Playwright +      Root Cause +
  parsing     erDiagram    DAG builder      + greedy        AI body/seed      Impact map

工作原理

1. 源码解析

OpenCroc 基于 ts-morph 做静态分析：

Models：从 Sequelize Model.init() / TypeORM @Entity() 提取表名、字段类型、索引、外键
Controllers：从 Express router.get/post/put/delete 提取路由、HTTP 方法、路径参数
DTOs：从 @IsString()、@IsNumber()、@IsOptional() 装饰器提取校验规则

2. AI 配置生成

每个模块都会调用 LLM（OpenAI / 智谱 / 任意 OpenAI 兼容 API）生成：

请求体模板：字段级精确的 POST/PUT payload
种子数据：beforeAll 的初始化步骤与正确调用顺序
参数映射：路径参数别名（/:id -> categoryId）
ID 别名：避免多资源链路中的 ID 冲突

每份配置都要通过 3 层校验：

Schema 校验：JSON 结构完整性
语义校验：字段值是否与源码元数据一致
Dry-run 校验：TypeScript 编译检查

若校验失败，会在落盘前自动修复（最多 3 轮）。

3. 日志驱动完成判定

不依赖脆弱的 networkidle：

Frontend Request -> Backend api_exec start log -> Backend processing -> api_exec end log
                                                                          ↓
                                              OpenCroc polls end logs to confirm completion

这能覆盖“前端看起来空闲、后端仍在处理”的场景。

4. 自愈闭环

Test Failure
  -> AI Attribution (LLM + heuristic fallback)
  -> Generate Fix Patch
  -> Dry-Run Validation
  -> Apply Patch (with backup)
  -> Re-run Failed Tests
  -> Verify Fix
  -> Commit or Rollback

真实项目验证

OpenCroc 已在一套生产级 RBAC 系统（多租户企业权限管理）上完成验证，涵盖 100+ Sequelize 模型、75+ Express 控制器、以及模型文件内嵌的关联声明：

$ npx tsx examples/rbac-system/smoke-test.ts

Modules        : 5 (default, aigc, data-platform, integration, workflow)
ER Diagrams    : 5
  [default] 102 tables, 65 relations
  [aigc] 6 tables, 0 relations
  [data-platform] 4 tables, 0 relations
  [integration] 14 tables, 0 relations
  [workflow] 2 tables, 0 relations
Chain Plans    : 5
  [aigc] 78 chains, 150 steps
Generated Files: 78
Duration       : 1153ms

关键发现：

从扁平模型布局中正确提取了 102 张表 和 65 条外键关系
无需独立 association 文件，直接检测模型文件中的嵌入式关联（.belongsTo() / .hasMany()）
5 个模块共生成 78 个测试文件，耗时仅 1 秒出头
同时兼容扁平（models/*.ts）和嵌套（models/module/*.ts）目录结构

配置示例

// opencroc.config.ts
import { defineConfig } from 'opencroc';

export default defineConfig({
  // 后端源码路径
  backend: {
    modelsDir: 'src/models',
    controllersDir: 'src/controllers',
    servicesDir: 'src/services',
  },

  // 目标应用
  baseUrl: 'http://localhost:3000',
  apiBaseUrl: 'http://localhost:3000/api',

  // AI 配置
  ai: {
    provider: 'openai',        // 'openai' | 'zhipu' | 'custom'
    apiKey: process.env.AI_API_KEY,
    model: 'gpt-4o-mini',
  },

  // 测试执行
  execution: {
    workers: 4,
    timeout: 30_000,
    retries: 1,
  },

  // 日志驱动完成判定（需后端埋点）
  logCompletion: {
    enabled: true,
    endpoint: '/internal/test-logs',
    pollIntervalMs: 500,
    timeoutMs: 10_000,
  },

  // 自愈
  selfHealing: {
    enabled: false,
    fixScope: 'config-only',   // 'config-only' | 'config-and-source'
    maxFixRounds: 3,
    dryRunFirst: true,
  },
});

支持的技术栈

| 层级 | 已支持 | 规划中 | |---|---|---| | ORM | Sequelize, TypeORM, Prisma, Drizzle | — | | Framework | Express | NestJS, Fastify, Koa | | Test Runner | Playwright | — | | LLM | OpenAI, ZhiPu (GLM), Ollama (local) | Anthropic | | Database | MySQL, PostgreSQL | SQLite, MongoDB |

对比

| 功能 | OpenCroc | Playwright | Metersphere | auto-playwright | |---|---|---|---|---| | 源码感知生成 | ✅ | ❌ | ❌ | ❌ | | AI 配置生成 + 校验 | ✅ | ❌ | ❌ | ❌ | | 日志驱动完成判定 | ✅ | ❌ | ❌ | ❌ | | 失败链路归因 | ✅ | ❌ | 部分 | ❌ | | 自愈 + 回滚 | ✅ | ❌ | ❌ | ❌ | | API 依赖 DAG | ✅ | ❌ | ❌ | ❌ | | 零配置测试生成 | ✅ | 仅 codegen | 手工 | NL->action | | 影响面分析 | ✅ | ❌ | ❌ | ❌ |

Roadmap

[x] 6-stage source-to-test pipeline
[x] AI configuration generation with 3-layer validation
[x] Controlled self-healing loop
[x] Log-driven completion detection
[x] Failure chain attribution + impact analysis
[x] TypeORM / Prisma adapter
[x] Ollama local LLM support
[x] Real-world validation (102 tables, 65 relations, 78 generated tests)
[x] GitHub Actions / GitLab CI integration
[x] VS Code extension scaffold
[x] Plugin system
[x] HTML / JSON / Markdown report generation
[x] NestJS controller parser
[x] Visual dashboard (opencroc.com)
[x] Drizzle ORM adapter
[x] AI Config Suggester + Enhanced DTO-aware Suggester
[x] Auto-Fixer（4 策略：接口路径匹配、DTO 字段填充、种子依赖排序、参数映射修复）
[x] 三层配置验证（schema → semantic → dry-run）
[x] DTO Parser（ts-morph 接口解析 + express-validator 规则提取）
[x] Baseline Comparator（Playwright 报告 diff + 回归检测）
[x] 模块配置预设加载器
[x] LLM 增强链路规划器
[x] Runtime 基础设施（Playwright 配置生成、认证 Setup、Teardown、网络监控）
[x] 全流程编排管道
[x] 高级报告系统（检查清单、工单生成、Token 追踪）
[x] OpenCroc Studio — 像素鳄鱼办公室 + 知识图谱 UI（opencroc serve）

发布快照

当前稳定版本：1.3.0
npm latest 标签：1.3.0
Roadmap 状态：M1 Studio 已交付
全量质量门禁：34 个测试文件 / 373 个测试通过（Node.js 20.x & 22.x）

版本节奏

0.3.x：插件系统、CI 模板、报告系统、VS Code 脚手架、CI 稳定化
0.4.x：NestJS 控制器解析
0.5.x：Drizzle ORM 适配器
0.6.x：可视化 dashboard 与 Windows 下 Vitest 稳定性收口
0.7.x – 0.9.x：Runtime 基础设施（Playwright 生成器、认证、日志驱动检测、规则引擎）
1.0.0：全流程编排管道
1.1.0：高级自愈（对话循环、可控修复器、自动修复 PR 生成）
1.2.0：高级报告系统 + Sprint 0-3 迁移完成
1.3.0：OpenCroc Studio M1 — Fastify 服务器、知识图谱 API、像素鳄鱼办公室前端

发布验证

npm run lint
npm run typecheck
npm test
npm view opencroc version dist-tags --json