Testany Guide

Testany 平台参考

本 skill 提供 Testany 平台的核心概念参考。详细内容见 references/ 目录。若上游来自 testany-eng，优先配合 approved Test Spec 中的 Testany Automation Handoff 一起使用。

核心实体关系

Traditional Test Scenario
  │
  └──► Testany Platform Case
             │
             └──► Pipeline (执行与编排单元) ──► Execution
                           │
                           ├──► Plan
                           ├──► Manual Trigger
                           └──► Gatekeeper

快速参考

• 对象边界与职责链 → automation-model.md
• 实体定义和可见性规则 → concepts.md
• Executor 配置详解 → executors.md
• Pipeline YAML 语法 → pipeline-yaml.md

宿主能力适配

testany-bot 通用版按能力而不是按宿主品牌分支：

• 如果宿主支持结构化提问工具（如 AskUserQuestion），优先一次性收集缺失信息。
• 如果宿主不支持该工具，则用普通文本在当前对话中提问；低风险字段可给出默认值建议，但必须明确告知用户。
• 如果宿主支持 slash command / router，可推荐相关 workflow 的命令入口。
• 如果宿主不支持 slash command，不要阻塞任务；直接在当前线程继续对应 workflow。

标识符格式

MCP Schema Resources

在组装 API payload 前，应先读取对应的 schema resource：

Testany 自动化对象模型

这份说明用于统一 testany-bot 各 skill 的心智模型，避免把传统测试概念直接投射到 Testany 平台对象上。

4 个核心对象

一句话边界

• test-spec 产出的是场景级测试设计，不是 Testany 平台资产。
• 当 testany-eng 的 Test Spec 已包含 Testany Automation Handoff 时，它就是进入 testany-bot 的首选上游输入。
• Testany case 是可复用的原子自动化步骤包，不是传统语义下的完整测试场景。
• pipeline 才是 Testany 的执行与编排单元。即使只有一个 platform case，要真正执行也仍然需要一条 pipeline。
• trigger 是执行入口，不是编排层。它只决定“如何触发 pipeline”，不决定 pipeline 内部逻辑。
• execution 发起之后的观测、查询、刷新、取消与失败交接，属于 testany-execution。

为什么不能直接把传统 Test Case 映射成 Testany Case

传统测试设计里的一个“测试用例/测试场景”，经常包含：

• 前置步骤
• 主操作
• 多个验证点
• 失败分支或清理动作
• 与其他步骤之间的数据传递

在 Testany 平台里，这些内容更适合拆成：

• 一个或多个 platform cases
• 再由一条或多条 pipelines 进行编排

因此：

• 一个 traditional test scenario 可能对应 多个 Testany platform cases
• 一个 traditional test scenario 也可能对应 一条或多条 pipelines

推荐职责链

approved test-spec (+ Testany Automation Handoff) / 用户需求
  -> testany-case-writing
     - 拆解 scenario
     - 生成 platform cases
     - 产出 automation design / decomposition
  -> testany-case                     (手工路径：注册现成 ZIP)
     - 将 platform cases 注册到 Testany 平台
     - 返回 case keys
  -> testany-import-git               (Git 路径：从仓库导入)
     - 连 Git → 建 import history → sync
     - 由 backend 生成 platform cases 并维护 file bindings
  -> testany-pipeline
     - 根据 decomposition 和 case keys 组装 pipeline
  -> testany-trigger
     - 为 pipeline 配置 Plan / Manual Trigger / Gatekeeper
     - 或立即执行一次
  -> testany-execution
     - 查看进度、查历史、刷新状态、取消未开始执行
     - 失败时交给 testany-debug

场景拆解经验法则

优先拆成多个 platform cases 的情况：

• 某一步会产出可供下游复用的 relay 数据
• 某一步本身就是可复用前置条件，例如登录、创建资源、清理资源
• 不同步骤需要不同 executor / runtime / 环境约束
• 存在条件分支、失败分支或 expect: fail
• 需要把主流程、校验流程、清理流程分开维护

可以保持为单个 platform case 的情况：

• 整个动作天然原子
• 不需要 relay 给下游
• 不需要条件分支或跨 case 依赖
• 单一 executor 即可稳定表达

与 4 个核心 skill 的直接关系

• testany-case-writing 必须先决定“场景要拆成几个 platform cases”，再写脚本和 ZIP。
• 若上游提供 Testany Automation Handoff，testany-case-writing 应优先消费它，而不是从整篇 Test Spec 重新猜测拆分方式。
• testany-pipeline 的主路径应消费上游的 decomposition 结果，而不是主要依赖猜测 case 描述。
• testany-trigger 必须同时覆盖 persistent trigger（Plan、Manual Trigger、Gatekeeper）和 ad-hoc run now。
• testany-execution 应负责 execution 发起之后的观测与管理，而不是再次承担 trigger 职责。
• testany-import-git 是 testany-case-writing + testany-case 的"从 Git 导入"分支：当 platform cases 的真源在 Git 仓库（非手工构造 ZIP）时，由它负责连接、选仓、建 import history、同步、演化 bindings 与 webhook。产出的依旧是 platform cases，下游继续走 testany-pipeline / testany-trigger。

Case Visibility Policy

Testany case 可见性的权威文档。凡是涉及 case 创建 / 更新 / 批量更新 / Git 导入的 skill 都链回本文档，不要在各自 skill 内复述规则。

---

1. Visibility 模型

TCase 上两个字段共同决定可见性：

合法组合

---

2. deployment_type 约束

deployment_type 是 tenant 级属性，一个租户内所有 workspace 共享。Agent 通过 testany_get_tenant_config() 获取。

两种部署形态

Visibility 规则矩阵

错误码

---

3. Agent 执行流程

决定可见性的标准步骤

1. 调 `testany_get_tenant_config()` 拿到 deployment_type

• Session 级缓存：tenant 属性在一个 session 内不会变

2. 根据 deployment_type + 用户意图决定：

3. 不要自作主张推断 deployment_type（例如"看到多个 workspace 就猜是 type=2"）。始终以 testany_get_tenant_config 为准。

撞 E400001 的恢复

如果代码路径意外撞上 E400001（例如用户在会话中途切换了 tenant，或 session 缓存过期）： 1. 重新调 testany_get_tenant_config() 刷新 2. 向用户解释 visibility 约束 3. 改为 is_private=true + 问 workspace_keys，重试

---

4. Skill 作者 checklist

引用本文档的 skill 应当：

• [ ] 在涉及 is_private / workspace_keys 的字段表里链回本文档，而不是复制规则
• [ ] 不要出现"Global: 共享工具类测试"之类的建议语 — 这在 type=2 环境下是反向诱导
• [ ] Create / update / bulk update 路径都提 deployment_type preflight
• [ ] 默认策略：deployment_type=1 走 global（不打扰用户）；deployment_type=2 走 restricted + `workspace_keys`（因为该部署不允许 global）

---

5. Skill 引用点

Testany 核心概念

实体定义

Case（测试用例）

定义：Testany 平台上的可复用原子自动化步骤包

属性：

• case_key: 8 位大写十六进制标识符（如 A1B2C3D4）
• name: 用例名称
• runtime_uuid: 执行环境 UUID（推荐 cloudprime）
• case_meta: 执行配置（trigger_method, environment_variables）
• is_private: 可见性控制
• workspace_keys: 私有 case 可见的工作空间列表

说明：

• Case 是平台资产，不等同于传统测试设计里的完整测试场景。
• Case 应尽量保持原子、自包含、可重复执行。
• Case 可以输出 relay 变量，供 pipeline 中的下游 case 使用。

Pipeline（流水线）

定义：编排多个 case 的执行与编排单元

属性：

• pipeline_key: 格式为 {WS_KEY}-{4-5位大写十六进制}（如 Y2K-0601、Y2K-0001A）
• name: 流水线名称
• definition: YAML 格式的执行规则定义（Pipeline YAML）
• case_keys: Case keys 列表（可替代 definition）
• 支持依赖关系（whenPassed/whenFailed）和变量传递（relay）

说明：

• Testany 平台执行的是 Pipeline，而不是单条 Case。
• 即使只有一个 Case，要真正执行也仍然需要一条 Pipeline。

Execution（执行）

定义：一次测试运行的实例

属性：

• execution_id: 格式为 {pipeline_key}-{5位大写十六进制}（如 Y2K-0601-0000A）
• status: NOT_STARTED(-1), RUNNING(0), SUCCESS(1), FAILURE(2), SKIPPED(3), FAIL_AS_EXPECTED(4), CANCELLED(5), ERROR(99)

说明：

• execution 是 trigger 发起之后生成的运行实例
• execution 的观测、刷新、取消、历史查询属于 testany-execution

Plan（定时计划）

定义：自动化调度的执行计划

属性：

• plan_key: 格式为 P-{workspace_key}-{5位大写十六进制}（如 P-Y2K-0001A）
• 关联多个 pipeline（按配置顺序触发）
• schedule_expr: 标准 5 段 Cron（UNIX）分 时 日 月 周
• timezone: 时区（为空时后端默认 Asia/Shanghai）
• watchers / notify_ignore_success：通知相关配置（可选）

Manual Trigger（手动触发）

定义：按需执行一个或多个 pipeline 的触发模板

属性：

• manual_trigger_key: 格式为 M-{workspace_key}-{4~5位大写十六进制}
• 关联一个或多个 pipeline
• 支持按需发起执行，不依赖定时调度或外部 webhook
• Owner 与实际执行人是两个不同概念

说明：

• Manual Trigger 是持久化 trigger 资源
• 它不等于“现在立刻执行一次”的 ad-hoc run

Gatekeeper（Webhook 触发器）

定义：通过 Webhook 触发一个“Pipeline Group”（一组 pipelines）执行的触发器

属性：

• gatekeeper_key: 格式为 G-{workspace_key}-{5位大写十六进制}（如 G-Y2K-0001A）
• 绑定 pipelines（通过 Pipeline Group 绑定；未绑定时 webhook 会报错 “no pipelines in gatekeeper”）
• hook_url: Webhook URL（用于外部系统触发）
• trigger_method / trigger_name / trigger_condition：触发条件的描述信息（便于团队理解与维护）
• watchers / notify_ignore_success / owned_by：通知与归属配置

Workspace（工作空间）

定义：资源隔离和权限控制单元

属性：

• workspace_key: 3 位大写字母数字（如 Y2K）
• 角色：Owner > Admin > Member > Viewer

---

可见性规则

Case / Pipeline 可见性

使用建议

• Global：共享工具类测试、组织级标准用例
• Private：团队专属测试、开发中的用例、含敏感数据的测试

---

工作空间角色权限

---

执行状态码

Executor 配置详解

Executor 选择规则

根据脚本语言/框架自动选择 executor：

注意：python 和 pyres 的区别是 pyres 提供更丰富的测试报告能力，推荐使用 pyres。

---

Postman

Executor: postman

{
  "case_meta": {
    "trigger_method": {
      "executor": "postman",
      "trigger_path": "my-collection.postman_collection.json"
    }
  }
}

ZIP 结构：

my-case.zip
└── my-collection.postman_collection.json

---

Python / PyRes

Executor: pyres（推荐）或 python

{
  "case_meta": {
    "trigger_method": {
      "executor": "pyres",
      "trigger_command": ["python", "test_api.py", "--env", "staging"]
    }
  }
}

执行命令：python test_api.py --env staging

ZIP 结构：

my-case.zip
├── test_api.py
└── utils/
    └── helpers.py

高级用法 - 嵌套目录执行：

{
  "trigger_command": ["cd", "tests", ";", "python", "run_all.py"]
}

---

Maven

Executor: maven

{
  "case_meta": {
    "trigger_method": {
      "executor": "maven",
      "trigger_path": "./"
    }
  }
}

指定测试文件：

{
  "trigger_path": "src/test/java/com/testany/LoginTest.java"
}

ZIP 结构：

my-case.zip
├── pom.xml
└── src/
    └── test/
        └── java/
            └── com/testany/LoginTest.java

---

Gradle

Executor: gradle

配置与 Maven 类似，区别在于项目根目录有 build.gradle 而非 pom.xml。

{
  "case_meta": {
    "trigger_method": {
      "executor": "gradle",
      "trigger_path": "./"
    }
  }
}

---

Playwright

Executor: playwright

{
  "case_meta": {
    "trigger_method": {
      "executor": "playwright",
      "trigger_path": "tests/e2e/login.spec.js",
      "playwright_config_path": "playwright.config.js"
    }
  }
}

必需文件：

• package.json
• playwright.config.js（或在 playwright_config_path 指定）

ZIP 结构：

my-case.zip
├── package.json
├── playwright.config.js
└── tests/
    └── e2e/
        └── login.spec.js

---

环境变量类型

`secret_ref` 结构：{ workspace_key, credential_safe_key, credential_key }，三个字段都必填。

`secrets` 行的只读字段：读回时每条 secrets 行附带 status（valid / blocked / invalid）和 status_reasons[]；非 valid 要向用户说明原因。写入时不要传这两个字段。

配置示例：

{
  "case_meta": {
    "environment_variables": [
      { "name": "API_URL", "type": "env", "value": "https://api.example.com" },
      {
        "name": "API_KEY",
        "type": "secrets",
        "secret_ref": {
          "workspace_key": "WKS",
          "credential_safe_key": "WKS-CS-0001",
          "credential_key": "prod-api-key"
        }
      },
      { "name": "TOKEN", "type": "output", "value": "-" }
    ]
  }
}

Pipeline YAML 语法

基本结构

kind: rule/v1.3
spec:
  rules:
    - run: 'A1B2C3D4'           # 第一个 case（无依赖）
    - run: 'E5F6A7B8'
      whenPassed: 'A1B2C3D4'    # 仅当 A1B2C3D4 通过时执行
      relay:
        - key: AUTH_TOKEN       # 本 case 中接收变量名
          refKey: A1B2C3D4/TOKEN  # 来源：case_key/变量名
          nonSecret: true

---

Rule 字段说明

---

依赖规则

1. 互斥约束：whenPassed 和 whenFailed 不能同时出现 2. DAG 约束：被引用的 case 必须在 rules 数组中之前定义 3. 单依赖约束：每个 rule 只能依赖一个 case

---

Relay（变量传递）

Relay 字段

Relay 约束（重要）

配置 relay 时，必须先查询 case 定义来验证环境变量：

验证流程:
1. testany_get_case 获取 run 对应的 case
   → 检查 case_meta.environment_variables
   → relay.key 必须存在且 type='env'

2. testany_get_case 获取 refKey 中的源 case
   → 检查 case_meta.environment_variables
   → refKey 中的变量必须存在且 type='output'

---

常见编排模式

顺序执行（无依赖）

kind: rule/v1.3
spec:
  rules:
    - run: 'A1B2C3D4'
    - run: 'E5F6A7B8'
    - run: 'C9D0E1F2'

链式依赖

kind: rule/v1.3
spec:
  rules:
    - run: 'A1B2C3D4'  # Login
    - run: 'E5F6A7B8'
      whenPassed: 'A1B2C3D4'  # Get Profile（需要登录成功）
    - run: 'C9D0E1F2'
      whenPassed: 'E5F6A7B8'  # Update Profile（需要获取成功）

带 Relay 的链式

Case A (04E41DDE) 的 environment_variables:

[{ "name": "TOKEN", "type": "output", "value": "-" }]

Case B (FAFC249A) 的 environment_variables:

[{ "name": "AUTH_TOKEN", "type": "env", "value": "-" }]

Pipeline YAML:

kind: rule/v1.3
spec:
  rules:
    - run: '04E41DDE'  # Login → 输出 TOKEN
    - run: 'FAFC249A'
      whenPassed: '04E41DDE'
      relay:
        - key: AUTH_TOKEN        # ✓ FAFC249A 中 type='env'
          refKey: 04E41DDE/TOKEN # ✓ 04E41DDE 中 type='output'
          nonSecret: true

失败后执行（清理场景）

kind: rule/v1.3
spec:
  rules:
    - run: 'A1B2C3D4'  # Main test
    - run: 'C1EA2E01'  # Cleanup case
      whenFailed: 'A1B2C3D4'  # 仅当主测试失败时执行清理

---

Schema Reference

在创建或更新 pipeline 前，读取 MCP Resource 获取完整 schema：

URI: testany://schema/pipeline
Method: resources/read