Echolot
教程

测试 API 并在 CI 中运行

为请求添加检查，在运行器中运行它们，然后在 GitHub Actions 中用命令行工具运行同一个工作区并生成 JUnit 报告。

检查能把请求变成测试：每次发送都会说明哪些通过、哪些没有。在本教程中，你会为 Alpenglow 的请求添加检查，在运行器中运行文件夹，然后在 GitHub Actions 中每次推送时用 echolot run 运行同一个工作区。

  • 用时： 20 分钟。
  • 你需要： Alpenglow 工作区，以及最后一部分用到的、你可以推送的 GitHub 仓库。
  • 你将学到： 检查、运行器及其报告、echolot run，以及 CI 中的机密。

1. 查看请求已有的检查

  1. 打开 Catalog › List products，选取它的测试标签页。
  2. 它有四项检查：状态等于 200，JSON 值 $.items.length 大于 0，标头 Content-Type 包含 json，响应时间（毫秒）小于 1000。
  3. 发送。标签页显示 4 项通过，响应的测试标签页显示 4/4，每项检查都列在检查下。

2. 添加你自己的检查

  1. 在测试标签页中，打开添加测试并选取 JSON 值。
  2. 把路径设为 $.items[0].price.currency，比较方式设为等于，期望值设为 CHF。
  3. 再次打开添加测试，选取大小（字节）、小于、65536。
  4. 发送。六项检查全部通过。

还有两种更快的添加检查的方法：

  • 在响应的 JSON 树中，右键点按某个值并选取添加断言。检查会采用它的路径和值。
  • 从响应生成… 会根据最新的响应提出检查建议，包括正文的 JSON Schema。

现在来看看失败的情形：把响应时间检查改为小于 1 并发送。标签页显示 1 个失败，共 6 个，响应的测试标签页会在失败的检查下显示返回的内容。再把它改回 1000。

对于需要代码的检查，可以在脚本标签页中用 pm.test() 编写测试脚本；参见脚本与测试。

List products 的“测试”标签页，其中列出各项检查，发送后全部通过

3. 在运行器中运行文件夹

  1. 右键点按 Catalog 文件夹并选取运行文件夹。运行器页面会打开，并按顺序运行其中的每个请求。
  2. 统计数据显示请求、通过、失败、失败的检查和时长，结果卡片则列出每个请求的状态、耗时和失败的检查。
  3. 要自己设置一次运行，请选取视图 › 运行器（⌥⌘R）。在运行卡片中：
    • 运行对象：整个工作区、某个文件夹，或一个请求。先选 Auth 并运行，再选 Orders：Orders 中的请求会发送 Sign in 存储的令牌。
    • 环境、迭代（试试 3）、请求之间的延迟（毫秒）、失败请求的重试次数，以及首次失败时停止。
    • 数据：选取 CSV 或 JSON… 会按每一行运行一次，并把行中的列作为变量。
  4. 选取运行（⌘R）。
  5. 打开存储报告，选取 JUnit XML…、JSON…、HTML… 或 HAR（所有交换）…。

运行整个工作区时也会运行 Realtime 和 Inventory。除非本地服务器正在运行，否则其中的 Socket.IO、MQTT 和 gRPC 请求会失败。详见运行器。

运行 Catalog 文件夹之后的运行器页面，全部通过

4. 在“终端”中运行

  1. 安装命令行工具：选取 Echolot › 安装命令行工具…，或者在设置 › 通用中开启它。它会把 echolot 放到你的 PATH 上。

    Mac App Store 版

    App Store 版本不包含命令行工具。请从发行版页面下载 echolot-<version>-macos.zip，解压后把 echolot 放入 PATH 中的某个文件夹。参见命令行工具。

    比较两个版本

  2. 检查每个文件是否可读、每个变量是否可解析：

    echolot validate Alpenglow.echolot

    它会输出 29 requests, 3 environments: no problems。

  3. 运行那三个只需要演示 API 的文件夹：

    echolot run Alpenglow.echolot --folder auth --folder catalog --folder orders
    ✓ POST   auth/sign-in  200 142 ms
    ✓ Status equals 200
    ✓ JSON value $.access_token exists
✓ GET    auth/who-am-i  200 87 ms
    ✓ Status equals 200
…
All 13 requests passed  18/18 checks passed · 1.35 s

    --folder 接受文件夹或请求的文件名（auth、catalog/list-products）。当请求没有收到响应或检查失败时，退出码为 1，脚本和 CI 可据此停止。

  4. 除了控制台输出，再写出一份 JUnit 报告：

    echolot run Alpenglow.echolot --folder auth --folder catalog --folder orders \
  --reporter junit --out results.xml --reporter console

    每个请求成为一个 testsuite，每项检查成为一个 testcase。所有选项都在 echolot run 中。

5. 在 GitHub Actions 中运行

  1. 把 Alpenglow.echolot 提交到你的仓库。

  2. 添加 .github/workflows/api.yml：

    name: API checks
on: [push, pull_request]

jobs:
  api:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4

      - name: Install the Echolot CLI
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh release download --repo staticdreams/echolot-public --pattern 'echolot-*-macos.zip' --dir "$RUNNER_TEMP"
          unzip -q "$RUNNER_TEMP"/echolot-*-macos.zip -d "$RUNNER_TEMP/echolot"
          echo "$RUNNER_TEMP/echolot" >> "$GITHUB_PATH"

      - name: Validate
        run: echolot validate Alpenglow.echolot

      - name: Run
        run: >
          echolot run Alpenglow.echolot
          --folder auth --folder catalog --folder orders
          --reporter console --reporter junit --out results.xml

      - name: Keep the report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: echolot-results
          path: results.xml

  3. 推送。Run 步骤会打印与你的 Mac 上相同的行，检查失败时作业会失败。JUnit 文件会作为 echolot-results 附加到这次运行上；任何 JUnit 测试报告 action 都可以把它显示为表格。

命令行工具运行在搭载 Apple 芯片的 macOS 上，所以作业使用 macOS runner。

6. 为 CI 提供机密

你 Mac 上的钥匙串不会随工作区一起转移。在 CI 中，命令行工具会从环境变量 ECHOLOT_SECRET_NAME 读取机密变量 name，或者从用 --secrets 指定的、由 NAME=value 行组成的文件读取。

Alpenglow 的演示密码是公开的，所以它是普通变量。对于真实的密码：

  1. 在工作区中把它设为机密变量，比如 password，然后提交。

  2. 在 GitHub 中添加仓库机密 API_PASSWORD（Settings › Secrets and variables › Actions）。

  3. 把它传给该步骤：

          - name: Run
        env:
          ECHOLOT_SECRET_PASSWORD: ${{ secrets.API_PASSWORD }}
        run: echolot run Alpenglow.echolot --env staging --reporter console --reporter junit --out results.xml

--env 接受环境的文件名（不含 .toml）或名称。关于 CI 的更多内容见 CI。

后续步骤

串联请求

只登录一次，存储令牌，让每个需要它的请求都能发送它，并使用动态值和 Idempotency-Key。

规范优先的设计与模拟

导入或设计 OpenAPI 规范，对其进行 lint，提供它的模拟服务，向模拟服务器发送请求，并对照规范检查真实响应。

本页内容

1. 查看请求已有的检查2. 添加你自己的检查3. 在运行器中运行文件夹4. 在“终端”中运行5. 在 GitHub Actions 中运行6. 为 CI 提供机密后续步骤