casebook 0.1.0

A local browser and editor for YAML test cases.

Casebook

Casebook 是一个面向 AI 时代测试用例工作的本地工具。

它把需求文档、AI 测试设计规范、JSON Schema 约束、YAML 用例文件和可视化编辑界面连成一条完整工作流：

docs/requirements/ 需求文档
  -> AI 按技能包理解需求并生成用例
  -> releases/ YAML 测试用例
  -> casebook serve 本地浏览、标记、编辑

Casebook 的目标不是替代测试人员，而是把测试人员从重复录入中释放出来：人负责需求理解、风险判断和评审，AI 负责按规范批量生成结构化用例，Casebook 负责可视化查看和编辑。

核心能力

• 一条命令创建标准 Casebook 用例项目。
• 将需求文档放入 docs/requirements/，让 AI 按项目技能包生成测试用例。
• 使用 schema/test-case-schema.json 约束 YAML 用例格式。
• 在本地 Web UI 中浏览、筛选、展开、标记和编辑 YAML 用例。
• 保存编辑时直接回写原始 YAML 文件。
• 使用 ruamel.yaml 尽量保留 YAML 注释、字段顺序、缩进和 inline list 风格。
• 将标记状态保存在 .casebook/marks.json，不污染用例文件本身。
• 监听 YAML 文件变化，并通知浏览器刷新。

安装

Casebook 需要 Python 3.10 或更高版本。

在本仓库中安装：

pip install -e .

安装后可以使用：

casebook --help

快速开始

创建一个新的 Casebook 项目：

casebook init my-casebook
cd my-casebook

启动本地用例工作台：

casebook serve releases

默认地址：

http://127.0.0.1:8089

也可以自动打开浏览器：

casebook serve releases --open

指定端口：

casebook serve releases --port 8090

初始化项目

casebook init <project> 会创建一个完整的用例项目脚手架：

my-casebook/
  AGENTS.md
  .agents/
    skills/
      casebook-test-cases/
        SKILL.md
  .vscode/
    settings.json
  docs/
    requirements/
      login.md
  releases/
    example/
      login.yaml
  schema/
    test-case-schema.json

这些文件分别负责：

• docs/requirements/login.md：示例需求文档。
• releases/example/login.yaml：由示例需求反向配套的 YAML 测试用例。
• schema/test-case-schema.json：测试用例结构约束。
• .agents/skills/casebook-test-cases/SKILL.md：AI 生成用例时需要遵循的技能包。
• AGENTS.md：项目根目录 AI 入口，提示 AI 读取技能包和 schema。
• .vscode/settings.json：让 VS Code YAML 插件自动关联 schema。

如果目标目录中已经存在同名文件，init 默认跳过，不会覆盖：

casebook init my-casebook

需要重置脚手架文件时，可以使用：

casebook init my-casebook --force

casebook project <project> 也可用，等价于 casebook init <project>。

AI 用例生成工作流

推荐工作方式：

1. 将产品需求、接口说明、交互规则或业务背景放入 docs/requirements/。
2. 让 AI 阅读 AGENTS.md 和 .agents/skills/casebook-test-cases/SKILL.md。
3. AI 根据需求、技能包和 schema/test-case-schema.json 生成 YAML 用例。
4. 将真实项目用例写入 releases/<版本或模块>/<功能>.yaml。
5. 使用 casebook serve releases 查看、标记和编辑用例。

示例目录中的 releases/example/ 只用于脚手架演示。真实项目用例建议放在更明确的目录中，例如：

releases/v1-auth/login.yaml
releases/v5-user-backend/package-management.yaml

用例格式

Casebook 读取符合以下结构的 YAML 文件：

metadata:
  module: "系统认证"
  feature: "用户登录"
  owner: "qa"
  last_reviewed: "2026-06-24"
  tags: [auth, login]

test_cases:
  - id: "TC_LOGIN_001"
    title: "有效用户名和密码登录成功"
    description: "验证用户使用正确的登录凭证可以成功进入系统。"
    priority: "P0"
    type: "functional"
    preconditions:
      - 用户已注册并处于正常可登录状态
    steps:
      - 输入有效用户名和对应密码
      - 点击登录按钮
    expected_results:
      - 登录成功，进入系统首页
      - 显示当前用户姓名和欢迎信息
    tags: [smoke, login]
    auto: true

字段约束以 schema/test-case-schema.json 为准。默认支持的优先级：

P0, P1, P2

默认支持的类型：

functional, ui, security, performance, accessibility, business, other, data-consistency

本地工作台

启动后，Casebook 提供一个本地 Web UI：

• 左侧按目录展示 YAML 用例文件。
• 中间展示当前文件的用例列表、统计、优先级和标签。
• 用例行可以展开，直接查看前置条件、步骤和预期结果。
• 可以用 Mark 标记需要关注或后续修改的用例。
• 点击 Edit 打开右侧编辑抽屉，并保存回 YAML 文件。

Casebook 会根据文件修改时间做编辑冲突检查。如果 YAML 文件在页面加载后被外部修改，保存时会提示冲突，避免覆盖他人的改动。

命令参考

创建项目：

casebook init my-casebook

覆盖脚手架文件：

casebook init my-casebook --force

启动默认用例目录：

casebook serve releases

同时扫描多个目录：

casebook serve releases/v1 releases/v2

指定主机和端口：

casebook serve releases --host 127.0.0.1 --port 8090

禁用文件监听：

casebook serve releases --no-watch

项目状态文件

Casebook 的标记数据保存在项目根目录：

.casebook/marks.json

示例：

{
  "releases/example/login.yaml#TC_LOGIN_001": {
    "needs_update": true,
    "updated_at": "2026-06-24T02:00:00+00:00"
  }
}

这些状态不写入 YAML 用例文件，因此不会影响用例正文和 schema 校验。

开发

本地开发安装：

pip install -e .

创建演示项目：

casebook init /tmp/casebook-demo
cd /tmp/casebook-demo
casebook serve releases

在源码模式下也可以直接运行：

python -m casebook.cli init /tmp/casebook-demo
python -m casebook.cli serve releases

设计理念

传统测试用例往往散落在表格、文档和测试管理平台里，格式难统一，版本难追踪，AI 也很难稳定复用。

Casebook 将用例工程化：

• 用 docs/requirements/ 承载需求输入。
• 用 .agents/skills/ 固化测试设计方法。
• 用 schema/ 固化结构约束。
• 用 releases/ 存放可版本化的 YAML 用例。
• 用本地 Web UI 完成审阅、标记和编辑。

这让测试用例变成可以被 AI 生成、被 schema 校验、被 Git 管理、被人高效评审的工程资产。