# 用例试运行

当我们在 staging 环境编写并调试好了用例，接下来的目标就是让用例在生产环境中润起来。需要编写[测试计划](test_plan.md)。

## 编写 OneShot Plan

1. (Optional) 如果想将 Plan 加入到 daily run，建议先 fork <https://github.com/pingcap/test-plan> 到自己的账号下：

    ```bash
    git clone git@github.com:$YOUR_NAME/test-plan.git
    cd test-plan
    ```

2. 在对应目录创建 `my-plan.yaml` 文件，这里参考 [brie-acceptance.yaml](https://github.com/pingcap/test-plan/blob/main/data-platform/brie/brie-acceptance.yaml)：

    一个 Plan 的 YAML 格式包含三部分：头部字段、testbed 和 steps/pipeline，详见 [测试计划](test_plan.md)，可以简单地这样写：

    - 添加几个固定的头部字段
    - 将之前创建集群使用的 Testbed 配置复制到 testbed 字段下
        - 在 testbed 字段中, 可以引用在 `meta.yaml` 定义的一些变量，例如 `{{meta.parameters.tidb_image}}`。也可以将一些通用的变量配置到 meta.yaml 文件中，并被其他测试计划所引用
    - steps/pipeline 字段里写我们要跑的 Case

    ```yaml
    # 头部字段
    apiVersion: api/v1
    kind: Plan
    name: brie-acceptance
    schedule: "@daily"
    tags: [ "brie", "acceptance" ]
    failFast: true
    # testbed 部分
    testbed:
      generateName: brie-acceptance-
      reclaimPolicy:
        gcStrategy:
          onFailure:
            artifact:
              monitor: true
              log: true
            reserveEnv:
              durationOnWorkingHour: 1h
            notification:
              feishu: https://open.feishu.cn/open-apis/bot/v2/hook/372b1771-5d59-40e2-8adc-6026edd05f1d
      items:
        - provider: "github.com/pingcap/test-infra/sdk/resource/impl/k8s.TiDBClusterClient"
          name: upstream
          type: TIDB_CLUSTER
          spec:
            pd:
              replicas: 1
              image: '{{meta.parameters.pd_image}}'
              requests:
                cpu: 8000m
                memory: 16Gi
              limits:
                cpu: 8000m
                memory: 16Gi
            tikv:
              replicas: 1
              image: '{{meta.parameters.tikv_image}}'
              storageClassName: fast-disks
              requests:
                cpu: 8000m
                memory: 16Gi
                storage: 500Gi
              limits:
                cpu: 8000m
                memory: 16Gi
                storage: 500Gi
            tidb:
              replicas: 1
              image: '{{meta.parameters.tidb_image}}'
              requests:
                cpu: 8000m
                memory: 16Gi
                storage: 500Gi
              limits:
                cpu: 8000m
                memory: 16Gi
                storage: 500Gi
        - name: downstream
          type: TIDB_CLUSTER
          spec:
            ...
        - name: lightning
          type: TIDB_LIGHTNING
          spec:
            ...
        - name: br
          type: WORKLOAD_NODE
          spec:
            ...
    # steps/pipeline 部分, 每个 step 跑一个 case。
    steps:
      - caseName: lightning_import_csv_from_minio_with_cli
        arguments:
          - name: target
            value: '{{testbed.upstream}}'
          - name: lightning
            value: '{{testbed.lightning}}'
      - caseName: br_backup_full_to_minio_restore
        arguments:
          - name: src_tidb
            value: '{{testbed.upstream}}'
          - name: dst_tidb
            value: '{{testbed.downstream}}'
          - name: br
            value: '{{testbed.br}}'
    # failFast 为 true 时, 当测试用例失败时，整个测试计划立即失败。
    # failFast 为 false 时, 当测试用例失败时, 后面的测试计划仍会执行。
    failFast: false
    ```

3. 然后通过 tcctl 执行：

```bash
tcctl run -m meta.yaml -f xxx/yyy/zzz.yaml
```

### 更新用例

参考[录入和管理用例](case_mng.md), 对相应字段进行变更。

### 内嵌 Case

如果想跑的 case 尚不存在于 TCMS 中，可以使用内嵌的方式引入：

```yaml
...
# 内嵌 Case myTPCC
cases:
    - name: myTPCC
      framework:
          generic:
              command: ['/bin/example', '--dsn={{parameters.dsn}}']
              image: hub.pingcap.net/qa/example_workload_node
      parameters:
          - name: tc
            type: RESOURCE
          - name: go_tpc_workload
            type: RESOURCE
          - name: dsn
steps:
    ...
    - caseName: myTPCC # 会先从 `cases` 字段中查找，再从 TCMS 上找
      arguments:
          - name: tc
            value: "{{testbed.tc}}"
          - name: go_tpc_workload
            value: "{{testbed.go_tpc_workload}}"
          - name: dsn
            value: "{{testbed.items.tc.tidb.dsn}}"
...
```

完整示例见：[examples/one-shot.yaml](../../tools/tcctl/examples/one-shot.yaml)。

### 覆盖 Case Image

如果想覆盖 Case 的镜像，可以在 pipeline-step 中添加 `caseImage` 字段，如：

```yaml
---
steps:
    - caseName: lightning_import_csv_from_minio_with_cli
      caseImage: myimage:latest
      arguments:
          - name: target
            value: "{{testbed.upstream}}"
          - name: lightning
            value: "{{testbed.lightning}}"
```