README

HTr是一个基于PHP的实用库，允许应用程序（尤其是HTTP REST服务）开发人员通过单个配置文件（用YAML或JSON编写）轻松测试他们的RESTful服务。

为什么使用YAML或JSON在现代网络标准中，JSON和YAML实体定义语言已成为配置建模的默认标准，这些配置可以在编程工具和语言之间轻松移植。因此，我们利用现有已知于开发人员社区的语言，而不是创建新的语言。

安装

该库是一个基于PHP的库，因此需要一个PHP二进制文件以及强大的PHP库包管理器composer。

要安装库，只需运行以下命令

> composer require drewlabs/htr

用法

配置

HTr客户端应用程序与JSON (JavaScript对象表示法)格式或YAML格式的配置文件一起工作。下面是一个示例配置文件

version: 0.1.0
# $schema: https://json-schema.fullstack.org.cn/id/<SCHEMA_ID>
name: My Test API

# Environment definitions
# Note: Environemnts are used by the runner to customize requests
env:
  _host: http://127.0.0.1:12300
  _apiVersion: "api"
  _postId: 2
  _commentId: 2

components:
  # The part below defines a request group or directory
  - name: "posts"
    description: Defines post management REST interfaces"
    items:
      - url: "[_host]/[_apiVersion]/posts"
        method: "GET"
        authorization:
          name: "bearer"
          value: "[_bearerToken]"
        body:
        params:
          page: 1
          per_page: 50
        tests:
          - "[status] eq 200" # Asser that request response status code == 200
      - url: "[_host]/[_apiVersion]/post"
        method: "POST"
        authorization:
          name: "bearer"
          value: "[_bearerToken]"
        body:
          title: "Environments"
          content: "This is an environment post"
        tests:
          - "[body].title eq Environment" #  Assert that request response body is has title field == Environments
          - "[status] eq 200" # Assert that request must be completed with status code 200
      - url: "[_host]/[_apiVersion]/post/:[_postId]"
        method: "PUT"
        authorization:
          name: "bearer"
          value: "[_bearerToken]"
        body:
        # Pass request body
        tests:
          - "[status] eq 422" # Assert that request response status code is 422

  # Comments requests directory
  - name: "comments"
    description: "Defines comments management REST interfaces"
    items:
      # Here we difines a request configuration that sends a POST request to http://127.0.0.1:12300/api/comments
      - url: "[_host]/[_apiVersion]/posts"
        method: "GET"
        authorization:
          name: "bearer"
          value: "[_bearerToken]"
        # body:
        params:
          page: 1
          per_page: 50
        tests:
          - "[status] eq 200" # Assert that request response status code == 200
      - url: "[_host]/[_apiVersion]/comments"
        method: "POST"
        authorization:
          name: "bearer"
          value: "[_bearerToken]"
        body:
          post_id: "[_postId]"
          content: "My Comment"
        tests:
          - "[status] eq 200" # Assert that request must be completed with status code 200
      - url: "[_host]/[_apiVersion]/post/:[_commentId]"
        method: "PUT"
        authorization:
          name: "bearer"
          value: "[_bearerToken]"
        body:
        # Pass request body
        tests:
          - "[status] eq 422" # Assert that request response status code is 422

注意根据上述配置，可以使用环境变量来定制请求。环境变量必须用[variable]括起来。

测试

测试断言使用自然语言，使其易于编写测试。下面是编写测试的语法

left op right -> 用于简单断言
left op right and condition_2_left and condition_2_right -> 用于复合断言

支持的测试操作符

逻辑运算符
- and : 用于连接2个或多个条件，只有当所有条件都返回true时才返回true
- or : 用于连接2个或更多条件，如果其中一个条件为true则返回true
比较运算符
- lt或> : 表示“小于”
- lte或<= : 用于“小于等于”比较
- gt或> : 用于“大于”比较
- gte或>= : 用于“大于等于”比较
- eq或ne : 分别表示“等于”或“不等于”
- has : 检查数组是否具有给定的键或属性
- in : 检查一个值是否存在于一系列值中。例如：mango in banana,orange,pinneaple

我们使用[]来表示响应对象的属性

[status]表示响应状态码
[body]表示响应体
[headers]表示响应头。

要访问响应体的属性，我们使用[body]与属性名连接，使用.符号，如下所示；

[body].title -> 用于访问响应体的标题属性
[body].address.email -> 可以用于访问响应体对象的内部属性

命令行

该库提供基于配置文件测试HTTP REST服务的命令行界面。以下是在项目根目录中运行的命令的基本测试命令

> ./vendor/bin/htr test --input=$(pwd)/htr.yml

上述命令假定您在项目根目录中有一个名为htr.yml的文件，其中包含有效的HTr测试配置。

默认情况下，cli 脚本将以静默模式运行测试并将输出写入您项目根目录下唯一生成的文件。要运行 HTr cli 的调试模式，请执行以下命令：
```
> ./vendor/bin/htr test --input=$(pwd)/htr.yml --verbose
```
在调试模式下运行客户端应用程序允许开发者看到每次请求的实时运行，并且将每个请求的参数输出到终端。
命令输出要覆盖命令日志写入的输出文件名路径，简单使用以下 --output 标志：
```
> ./vendor/bin/htr test --input=$(pwd)/htr.yml --output="$(pwd)/htr.log"
```
请求过滤

有时开发者可能只想执行特定的请求或特定的请求目录组件。在这种情况下，HTr 为开发者提供了 --request 或 --req，以便通过请求名称或 ID 进行过滤。
```
> ./vendor/bin/htr test --input=$(pwd)/htr.yml -req="request-name"
// For running single request
// or
> ../vendor/bin/htr test --input=$(pwd)/htr.yml -req="request1" --req="request2"
// For running multiple request matching the provided name
```
同样，要执行特定的请求目录，可以使用 -d 或 -directory 标志。HTr 客户端将仅执行指定目录中的请求测试。

>./vendor/bin/htr test --input=$(pwd)/htr.yml -d="directory name"
// For running tests in a single directory
// or
> ./vendor/bin/htr test --input=$(pwd)/htr.yml -d="directory1" -d="directory2"

For running tests in multiple directories

覆盖环境变量

当使用 HTr 客户端运行测试时，--input 参数通常包含一个 env 字段，该字段是在运行测试时应用的。要使用命令行变量覆盖环境变量，简单使用以下 --env 开关：

./vendor/bin/htr test --env=MyVar:MyVarValue --input=$(pwd)/htr.yml
JSON 默认情况下，HTr 客户端支持基于 YAML 的配置文件。为了使用 JSON 配置文件，简单使用以下 --json 标志：

  > ./vendor/bin/htr test --input=$(pwd)/htr.json --json

drewlabs / htr

维护者

详细信息

README

安装

用法

配置

测试

命令行