# 录入和管理用例

test-infra 提供了以下几种方式录入用例：

1. [通过 TCMS 录入](#一、通过-TCMS-录入)，适用于录入**单个**用例
2. [从 YAML 文件录入](#二、通过-YAML-文件录入)，适用于录入**多个**用例
3. [飞书表格](#三、通过飞书表格录入)，适用于录入**多个**用例, 同时方便用飞书表格做管理

用例各个字段的含义见 [Case 字段解释](#Case-字段解释)。

## 一、通过 TCMS 录入

访问 <https://tcms.pingcap.net/dashboard/cases/new>。![case](static/case.jpg)

### 二、通过 YAML 文件录入

录入 2 个简单的用例（用例只包含一部分必须的字段）：

```bash
echo 'apiVersion: "api/v1"
kind: Case
name: "example_001"
summary: test basic function
# 如：[">v3.0.0,<v4.0.0", "v5.0.0", "v5.1.0", "nightly"]
supportedVersions: [">=3.0"]
# 用户自定义用来进行过滤和搜索的 tag，比如 ”bigcluster" "bigdata"
tags: ["example"]
designer: gaozifeng@pingcap.com
framework:
  generic:
    command: ["sh", "-c", "echo {{parameters.words}}"]
    image: debian:buster
    imagePullPolicy: "IfNotPresent"
parameters:
  - name: words
    default: "Hello world!"' > case.yaml

# 后续更新 case，也是执行下面的命令
tcctl apply -f case.yaml
```

### 三、通过飞书表格录入

> 如果使用飞书表格作为用例管理的方式，记得一定要将修改同步回飞书表格, 否则下次重新导入表格时，TCMS 上的记录会被覆盖导致丢失。

飞书表格需要遵循格式： <https://pingcap.feishu.cn/sheets/shtcnqmVMUPHbzgKejUcWVAURhf>。 ![feishu](static/feishu.png)

当表格有更新时，我们将飞书表格导出为 csv 文件，然后用 tcctl 更新到 TCMS 上：

```bash
tcctl apply -f cases.csv
```

## Case 字段解释

> 带 \* 为必填

| 字段                 | 备注                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name\*               | 名称，能够表达特性/场景内容的疑问字母或者缩略词                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Summary              | 说明，简洁，短小，且能够尽可能表达测试意图、内容等相关信息、标题不要太长，一般控制在 20 个中文字符内                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Designer             | 用例设计者邮箱，用来跟踪测试用例的设计负责人，默认是自己                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Supported Versions\* | 用例支持的版本号，要求：填写数组，数组中每个 item 都是个版本范围或者具体某个版本。如：['>v3.0.0, <v4.0.0', 'v5.0.0', 'v5.1.0','nightly']                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Command\*            | 用例调用的命令行参数                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Image\*              | Case 镜像地址。如果用例是 endless 编写的，endless 的 CI 会自动编译出 Docker 镜像。如果是其他方式，则需要自己构建一个镜像                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Working Dir          | 工作目录，默认 `/`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Image Pull Policy    | 建议设置成 Always                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Timeout              | 用例执行超时时间，默认为 0，永不超时                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Parameters           | 两类参数，一类为 Resource 参数, 即在 [Testbed](test_cluster.md) 声明的测试资源; 另外一种为字符串参数。见：[资源类型参数](#资源类型参数) 和 [字符串类型参数](#资源类型参数)                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Category             | 用例的测试类型，暂时约定以下几种类型：1、Functionality Test：对需求功能进行一致性验证，以测试是否满足用户要求; 2、Performance Test：验证是否达到标称的性能规格、精度规格，如吞吐量和响应时间; 3、Compatibility Test：不同软件平台、硬件平台协同测试、版本前后向兼容测试; 4、Reliability Test：采用特定的方法激活系统中的各种故障，通过观察失效的发生情况来对系统容错能力进行评估，常用的构造方法有：压力测试、长时间测试、故障注入测试; 5、Security Test：测试系统防侵害及保护信息和数据的能力; 6、Maintainability Test：运维、或者定位手段可用性、正确性、规范性; 7、Scene Test：模拟真实用户场景的测试 |
| Automation           | 测试用例的自动化状态，约定以下四种状态：1、Automated：已自动化完成; 2、Unable to Automate：不能自动化或者暂时没有规划自动化; 3、Not Automated：计划要进行自动化，但是当前还未完成自动化; 4、In Progress：实现自动化过程中，但是还没有完成自动化                                                                                                                                                                                                                                                                                                                                                          |
| Precondition         | 预置条件主要对测试用例执行时需要预先进行配置的部分进行描述。内容包含：1、环境配置（运行该用例依赖的环境）; 2、运行用例时需要开启的特性开关; 3、运行用例需要预置的数据或者入口条件                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Priority             | 测试用例优先级，约定以下几种优先级状态：1、P1：所有基本功能点覆盖，用户使用频率高和重要性程度高的基本功能、异常场景等。2、P2：所有功能点全面覆盖的剩余用例。 3、P3：较生僻的预置条件和数据设置，很少见的异常场景，真实用户很难遇到。                                                                                                                                                                                                                                                                                                                                                                     |
| Steps                | 操作步骤，要求：1、操作步骤必须保证可执行性、无二义性。2、操作步骤清楚、简洁地描述每个操作的方法、对象和过程，避免使用过于含糊的用语。3、操作步骤的结果一定是可观察的、易确认的。4、操作步骤不易过多，建议不超过 10 步                                                                                                                                                                                                                                                                                                                                                                                   |
| Expected Result      | 预期结果要准确、明了、判断标准唯一，可观测。避免使用含糊或者概要性的语句表达，要求：1、预期结果必须正确、完整，要包含所有验证点。2、预期结果能定量描述的必定定量描述，不能使用含糊不清的词语，如“大概”、“也许”、“可能”等。 3、预期结果要与测试步骤对应，写法为：1、步骤 2：.... 2、步骤 3：....。 4、对于某些特性检查点较多、较复杂或对测试人员有较高技能要求的观察点，建议编写测试指导书，测试指导书详述指导如何观测结果的正确性                                                                                                                                                                        |

### 资源类型参数

测试用例中有操作测试资源（例如 tidb 集群, sysbench 负载, lightning/dumpling/br 工具等）的需求, 但是这些测试资源并不是由测试用例创建而是由 test-infra 负责创建并注入到测试用例中，因此测试用例需要通过资源的标识符来连接外部传入的资源。

测试资源类型参数即用来声明外部传入的测试资源，声明出一些字符串标识符。

```yaml
parameters:
    - type: RESOURCE
      name: tc
    - type: RESOURCE
      name: go_tpc_workload
```

和`字符串类型参数` 不同的，测试资源类型参数不支持在命令行中进行注入，需要引入 test-infra SDK。

### 字符串类型参数

字符串类型参数即通常意义上的参数，能够在测试用例的一些参数中直接使用。

例如某个测试用例的 parameters 如下所示：

```yaml
parameters:
    - name: dsn # type 默认为 STRING
    - name: host
```

则可以用如下形式在用例执行时(通过指定`command`)引用这些参数：

```yaml
[
    "/bin/example",
    "--dsn={{parameters.dsn}}",
    "--host={{parameters.host}}",
    "--port={{parameters.port}}",
    "--user={{parameters.username}}",
    "--password={{parameters.password}}",
]
```