目录

• 为什么需要一个测试 DSL？
• 安装
• 与其他测试库的比较
• 测试定义语法
• 什么是 JSONPath？
• 引用值和动态输入用于后续 API 请求
• 日期断言
• 使用环境变量
• 贡献和帮助
• 许可协议

为什么需要一个测试 DSL？

• 团队不应该因为想测试一个 Web 系统的 API 就被迫编写 JavaScript (Postman)、Groovy (Katalon) 或 Java (Rest-Assured)。
• 我们应该能够创建交互式构建器，生成这个底层的 DSL（领域特定语言）。因此，你甚至不需要在未来手动编写这个 DSL。
• 我们应该能够使用相同的脚本来进行单个测试和负载测试。
• 我们仍然能够在版本控制中持久化这些测试，并与同事协作。
• 受到 本地优先软件 原则的启发。

安装

要安装 testkit，请按照以下选项之一操作（点击切换）

[注意]

成功安装 testkit 后，运行 testkit --help 命令以获取所有 CLI 命令和选项。

与其他测试库的比较

在深入了解 testkit 及其功能之前，让我们将其与其他测试库进行比较，以突出其优雅、简洁和简单。通过展示差异，您将看到 testkit 如何提供更流畅、更用户友好的 API 测试方法。为了说明这一点，我们将重写以下 Cypress 测试

Cypress ⤵️

describe('TODO API testing', () => {
  let todoItem;
  it('fetches Todo items - GET', () => {
    cy.request('/todos/').as('todoRequest');
    cy.get('@todoRequest').then((todos) => {
      todoItem = todos.body[0]['_id'];
      expect(todos.status).to.eq(200);
      assert.isArray(todos.body, 'Todos Response is an array');
    });
  });

  it('Deletes Todo items - DELETE', () => {
    cy.request('DELETE', `/todos/${todoItem}`).as('todoRequest');
    cy.get('@todoRequest').then((todos) => {
      expect(todos.status).to.eq(200);
      assert.isString(todos.body, 'todo deleted!');
    });
  });

  it('Adds Todo item - POST', () => {
    cy.request('POST', '/todos/', { task: 'run tests' }).as('todoRequest');
    // Adds new Todo item by defining Todo name
    cy.get('@todoRequest').then((todos) => {
      expect(todos.status).to.eq(200);
      cy.wrap(todos.body).should('deep.include', {
        task: 'run tests',
        completed: false,
      });
    });
  });
});

Testkit ⤵️

---
    - title: fetches TODO items - GET
      GET: /todos/
      asserts: # Asserts accepts a list of expressions, usually via JSONPaths to identify the items being referred to.
        - ok: $.resp.status == 200  # Rely on an expressions library for parsing expressions
        - array: $.resp.json
      exports: # Values which should be accessible to future steps.
        todoItem: $.resp.json[0]._id

    - title: deletes TODO items - DELETE
      DELETE: /todos/$.stages[0].todoItem # Relative syntax exists: $.stages[-1].todoItem, -1 means one stage before me
      asserts:
        - empty: $.resp.json.todos
        - string: $.resp.json

    - title: Adds Todo item - POST
      POST: /todos/
      json:
        task: "run tests"
      asserts:
        - ok: $.resp.status == 200
        - ok: $.resp.json.task == "run tests"
        - ok: $.resp.json.completed == false

Testkit 提供了一种干净直观的语法，简化了定义和执行 API 测试场景的过程。

测试定义语法

Testkit 使用基于 YAML 的语法来定义测试场景。每个场景由多个阶段组成，其中每个阶段代表一个特定的 API 请求及其关联的断言。以下是定义 API 测试的 YAML 语法的示例

---
    - title: fetches TODO items - GET
      GET: /todos/
      asserts:
        - ok: $.resp.status == 200
        - array: $.resp.json
      exports:
        todoItem: $.resp.json[0]._id

    - title: deletes TODO items - DELETE
      DELETE: /todos/$.stages[0].todoItem
      asserts:
        - empty: $.resp.json.todos
        - string: $.resp.json

    - title: Adds Todo item - POST
      POST: /todos/
      json:
          task: "run tests"
      asserts:
        - ok: $.resp.status == 200
        - ok: $.resp.json.task == "run tests"
        - ok: $.resp.json.completed

在上面的示例中，YAML 测试文件定义了三个测试项：使用 GET 请求获取 TODO 项、使用 DELETE 请求删除特定的 TODO 项以及使用 POST 请求添加新的 TODO 项。YAML 文件由一系列测试场景组成。每个场景代表一个 API 请求，并包含以下字段

请点击以下每个切换按钮，以了解更多关于每个字段的信息。

# POST request
- title: Adds Todo item - POST
  POST: /todos/

# GET request
- title: Fetches Todo items - GET
  GET: /todos/

- title: Fetches Todo items - GET with headers
  GET: /todos/
  headers:
    Authorization: Bearer <token>
    Content-Type: application/json
    Allowed-Methods:
      - GET
      - POST

- title: Create User - POST
  POST: /users/
  json:
    name: John Doe
    age: 25
    email: [email protected]

- title: Fetches Todo items - GET
  GET: /todos/
  asserts:
    - ok: $.resp.status == 200
    - array: $.resp.json
    - ok: $.resp.json[0].task == "run tests"

- title: Fetches Todo items - GET
  GET: /todos/
  exports:
    todoItem: $.resp.json[0]._id

什么是 JSONPath？

JSONPath 是一种强大的查询语言，旨在导航和从JSON文档中提取数据。它提供了一种简洁的语法，允许您指定到JSON结构中特定元素的路径，便于数据访问和操作。在 testkit 中，广泛使用JSONPath表达式来提取数据用于断言和导出。以下是一些示例来说明JSONPath的工作原理

• $.user.name：此表达式从JSON文档的顶层对象中检索用户名称。
• $.todos[0].task：此表达式访问todos数组中第一个元素的task属性。
• $.todos[*].task.description：此表达式检索todos数组中所有任务的description属性。

JSONPath表达式的语法包括几个关键组件

通过使用JSONPath表达式，您可以在JSON结构中精确地定位所需数据。这些表达式在testkit中扮演着至关重要的角色，它有助于在测试过程中提取数据以进行断言和捕获导出。

[注意]

要了解更多关于JSONPaths的信息，请参阅官方文档。

引用值和动态输入用于后续 API 请求

testkit中的exports字段不仅允许您从API响应中捕获值，而且还提供了一个强大的机制来引用这些值，并在后续的API请求中动态生成输入。

通过使用exports字段捕获相关数据，您可以将其存储为导出，并在测试场景的后续阶段轻松引用它。这种功能在您需要访问从响应中提取的特定值并在后续API请求中使用它们时尤其有用。

例如，假设您在第一阶段使用exports字段从一个API响应中检索一个ID

- title: Fetch User - GET
  GET: /users/1
  exports:
    userId: $.resp.body.id

为了在后续API请求中引用此userId导出，您可以使用$.stages[n].<VAL>语法

- title: Update User - PUT
  PUT: /users/$.stages[0].userId
  json:
    name: 'John Doe'

在上面的示例中，使用语法$.stages[0].userId访问了在第一阶段捕获的userId。 testkit理解它应该在执行期间用相应的值替换引用。

您还可以使用相对引用，如$.stages[-n]，它引用当前阶段之前的第n个阶段的exports。示例

- title: deletes TODO items - DELETE
  DELETE: /todos/$.stages[-1].todoItem #-1 means one stage before me
  asserts:
    - string: $.resp.json.task
    - ok: $.resp.json.id == $.stages[-1].todoItem

通过引用之前阶段捕获的特定值，您可以在不同的API请求之间建立依赖关系，并确保在整个测试场景中无缝地流动数据。这种灵活性允许您构建更全面、更现实的测试，模拟复杂的用户交互或工作流程。

日期断言

要在testkit中进行日期断言，您需要提供日期字符串和日期格式，如下所示

- title: Get User Profile - GET
  GET: /user/jon_doe
  asserts:
    - date: $.resp.json.createdAt %Y-%m-%d %H:%M:%S %Z

在上面的示例中，我们首先提供一个JSONPath到日期，然后是日期的格式。

使用环境变量

Testkit支持两种方式的环境变量（.env文件和CLI配置）。这些方法允许用户配置和自定义他们的测试脚本，同时不暴露敏感数据，使无缝切换不同环境和场景变得更容易。

配置环境变量

使用.env文件涉及到在测试脚本目录中创建一个名为.env的文本文件，并为每个环境变量定义KEY=VALUE对。在测试执行期间，testkit自动从.env文件中加载这些变量，如下所示

APIURL=https://api.example.com
EMAIL=[email protected]
PASSWORD=mysecretpassword
USERNAME=myusername
APIKEY=mysecretapikey

直接设置环境变量是通过命令行或测试环境完成的，如下所示

APIKEY=SECRETAPIKEY testkit test --file test.tk.yaml

利用环境变量

要在testkit中利用环境变量，可以使用以下语法：$.env.<VAL>，其中<VAL>表示您想要使用的特定环境变量的名称。这允许您轻松引用和结合使用这些环境变量的值，在测试脚本中，从而提供更大的灵活性和适应性，而不需要将敏感信息或配置细节硬编码。以下是一个示例

- title: Register
  POST: '$.env.APIURL/users'
  headers:
    Content-Type: application/json
    X-Requested-With: XMLHttpRequest
  json: '{"user":{"email":"$.env.EMAIL", "password":"$.env.PASSWORD", "username":"$.env.USERNAME"}}'
  asserts:
    - exists: $.resp.json.user
    - exists: $.resp.json.user.email
    - exists: $.resp.json.user.username
    - exists: $.resp.json.user.bio
    - exists: $.resp.json.user.image
    - exists: $.resp.json.user.token