独立协议验证器

本项目提供命令行界面，用于验证运行中的提供者与协议文件。它是一个单独的可执行二进制文件。实现了所有至 V4 的 Pact 规范。

在线 Rust 文档

Pact 验证器通过从多个协议文件中获取所有交互（请求和响应）来工作。对于每个交互，它将对协议中定义的运行服务提供者发起请求，并将收到的响应与协议文件中定义的响应进行比较。所有不匹配都会被报告。

命令行界面

Pact 验证器被打包为单个二进制可执行文件 pact_verifier_cli。不带任何选项运行它将显示标准帮助信息。

$ pact_verifier_cli,ignore
Standalone pact verifier for provider pact verification

Usage: pact_verifier_cli [OPTIONS]

Options:
      --help     Print help and exit
  -v, --version  Print version information and exit

Logging options:
  -l, --loglevel <loglevel>  Log level to emit log events at (defaults to warn) [possible values: error, warn, info, debug, trace, none]
      --pretty-log           Emits excessively pretty, multi-line logs, optimized for human readability.
      --full-log             This emits human-readable, single-line logs for each event that occurs, with the current span context displayed before the formatted representation of the event.
      --compact-log          Emit logs optimized for short line lengths.
  -j, --json <json-file>     Generate a JSON report of the verification [env: PACT_VERIFIER_JSON_REPORT=]
  -x, --junit <junit-file>   Generate a JUnit XML report of the verification (requires the junit feature) [env: PACT_VERIFIER_JUNIT_REPORT=]
      --no-colour            Disables ANSI escape codes in the output [aliases: no-color]

Loading pacts options:
  -f, --file <file>
          Pact file to verify (can be repeated)
  -d, --dir <dir>
          Directory of pact files to verify (can be repeated)
  -u, --url <url>
          URL of pact file to verify (can be repeated)
  -b, --broker-url <broker-url>
          URL of the pact broker to fetch pacts from to verify (requires the provider name parameter) [env: PACT_BROKER_BASE_URL=]
      --webhook-callback-url <webhook-callback-url>
          URL of a Pact to verify via a webhook callback. Requires the broker-url to be set. [env: PACT_WEBHOOK_CALLBACK_URL=]
      --ignore-no-pacts-error
          Do not fail if no pacts are found to verify

Authentication options:
      --user <user>          Username to use when fetching pacts from URLS [env: PACT_BROKER_USERNAME=]
      --password <password>  Password to use when fetching pacts from URLS [env: PACT_BROKER_PASSWORD=]
  -t, --token <token>        Bearer token to use when fetching pacts from URLS [env: PACT_BROKER_TOKEN=]

Provider options:
  -h, --hostname <hostname>
          Provider hostname (defaults to localhost) [env: PACT_PROVIDER_HOSTNAME=]
  -p, --port <port>
          Provider port (defaults to protocol default 80/443) [env: PACT_PROVIDER_PORT=]
      --transport <transport>
          Provider protocol transport to use (http, https, grpc, etc.) [env: PACT_PROVIDER_TRANSPORT=] [default: http]
      --transports <transports>
          Allows multiple protocol transports to be configured (http, https, grpc, etc.) with their associated port numbers separated by a colon. For example, use --transports http:8080 grpc:5555 to configure both.
  -n, --provider-name <provider-name>
          Provider name (defaults to provider) [env: PACT_PROVIDER_NAME=]
      --base-path <base-path>
          Base path to add to all requests [env: PACT_PROVIDER_BASE_PATH=]
      --request-timeout <request-timeout>
          Sets the HTTP request timeout in milliseconds for requests to the target API and for state change requests. [env: PACT_PROVIDER_REQUEST_TIMEOUT=]
  -H, --header <custom-header>
          Add a custom header to be included in the calls to the provider. Values must be in the form KEY=VALUE, where KEY and VALUE contain ASCII characters (32-127) only. Can be repeated.
      --disable-ssl-verification
          Disables validation of SSL certificates

Provider state options:
  -s, --state-change-url <state-change-url>
          URL to post state change requests to [env: PACT_PROVIDER_STATE_CHANGE_URL=]
      --state-change-as-query
          State change request data will be sent as query parameters instead of in the request body [env: PACT_PROVIDER_STATE_CHANGE_AS_QUERY=]
      --state-change-teardown
          State change teardown requests are to be made after each interaction [env: PACT_PROVIDER_STATE_CHANGE_TEARDOWN=]

Filtering interactions:
      --filter-description <filter-description>
          Only validate interactions whose descriptions match this filter (regex format) [env: PACT_DESCRIPTION=]
      --filter-state <filter-state>
          Only validate interactions whose provider states match this filter (regex format) [env: PACT_PROVIDER_STATE=]
      --filter-no-state
          Only validate interactions that have no defined provider state [env: PACT_PROVIDER_NO_STATE=]
  -c, --filter-consumer <filter-consumer>
          Consumer name to filter the pacts to be verified (can be repeated)

Publishing options:
      --publish
          Enables publishing of verification results back to the Pact Broker. Requires the broker-url and provider-version parameters.
      --provider-version <provider-version>
          Provider version that is being verified. This is required when publishing results.
      --build-url <build-url>
          URL of the build to associate with the published verification results.
      --provider-tags <provider-tags>
          Provider tags to use when publishing results. Accepts comma-separated values.
      --provider-branch <provider-branch>
          Provider branch to use when publishing results

Pact Broker options:
      --consumer-version-tags <consumer-version-tags>
          Consumer tags to use when fetching pacts from the Broker. Accepts comma-separated values.
      --consumer-version-selectors <consumer-version-selectors>
          Consumer version selectors to use when fetching pacts from the Broker. Accepts a JSON string as per https://docs.pact.io/pact_broker/advanced_topics/consumer_version_selectors/. Can be repeated.
      --enable-pending
          Enables Pending Pacts
      --include-wip-pacts-since <include-wip-pacts-since>
          Allow pacts that don't match given consumer selectors (or tags) to  be verified, without causing the overall task to fail. For more information, see https://pact.io/wip

选项

日志级别

您可以使用 -l, --loglevel <loglevel> 选项来控制日志级别。默认为 warn，您可以指定的选项有：error、warn、info、debug、trace、none。

协议文件来源

您可以使用以下选项指定要验证的协议。它们可以被重复使用来设置多个来源。

通过 webhook 回调验证契约

契约代理允许通过提供验证契约的 URL 的回调来验证契约。要仅验证 webhook 调用中的契约，请使用 --webhook-callback-url 并将其设置为与 --broker-url 选项一起提供的 URL。

提供者选项

可以使用以下选项指定正在运行的提供者

过滤交互

以下选项可以过滤要验证的交互

-c, --filter-consumer<filter-consumer>

这将仅验证匹配消费者的交互。您可以通过以逗号分隔名称或重复选项来指定多个消费者。

--filter-description<filter-description>

此选项将过滤与描述匹配的交互。您可以使用正则表达式进行匹配。

--filter-state<filter-state>

此选项将根据提供者状态过滤要验证的交互。您可以使用正则表达式进行匹配。不能与 --filter-no-state 选项一起使用。

--filter-no-state

此选项将过滤未定义提供者状态的交互。不能与 --filter-state 选项一起使用。

状态更改请求

提供者状态 是一种定义提供者需要处于何种状态才能验证特定请求的机制。这是通过设置一个将接收在实际请求之前发送的 POST 请求的状态更改 URL 来实现的。

注意：对于通过 HTTP 获取的消息，提供者状态也通过获取消息的请求传递，因此不需要状态更改 URL。

例如，如果正在验证的契约文件具有提供者状态 "数据库中存在用户"，并且提供者状态 URL 设置为 https://127.0.0.1:8080/provider-state，则以下请求将在交互验证之前发出

POST /provider-state HTTP/1.1
Host: localhost:8080
content-type: application/json

{
    "state": "a user exists in the database",
    "params": {},
    "action": "setup"
}

如果为提供者状态配置了任何参数，它们将通过 "params" 属性传递。

提供者状态回调可以返回一个值映射（JSON 对象），然后可以由提供者状态生成器等使用。返回的值映射将回退到提供者状态参数。

-s, --state-change-url<state-change-url>

这将设置在每次实际请求之前发出的 POST 请求的绝对 URL。如果未设置此值，则不会发出状态更改请求。

--state-change-as-query

默认情况下，状态更改请求的状态将作为请求体中的 JSON 文档发送。此选项强制将其作为查询参数发送。

--state-change-teardown

此选项会导致验证器在发出主要请求后也发出拆解请求。它将在主体或查询参数中接收到一个名为 action 的字段，其值为 teardown。

--consumer-version-selectors

接受一组以 JSON 编码的 消费者版本选择器。

一个良好的参数值示例可能是

--consumer-version-selectors '{"branch": "master"}'

示例运行

这将验证在 pact broker（在本地主机上运行）中找到的所有 happy_provider 的 pacts，与在本地主机 5050 端口上运行的提供者进行验证。只有 Consumer 和 Consumer2 的 pacts 将被验证。

$ pact_verifier_cli -b https://127.0.0.1 -n 'happy_provider' -p 5050 --filter-consumer Consumer --filter-consumer Consumer2
21:59:28 [WARN] pact_matching::models: No metadata found in pact file "https://127.0.0.1/pacts/provider/happy_provider/consumer/Consumer/version/1.0.0", assuming V1.1 specification
21:59:28 [WARN] pact_matching::models: No metadata found in pact file "https://127.0.0.1/pacts/provider/happy_provider/consumer/Consumer2/version/1.0.0", assuming V1.1 specification

Verifying a pact between Consumer and happy_provider
  Given I am friends with Fred
    WARNING: State Change ignored as there is no state change URL
  Given I have no friends
    WARNING: State Change ignored as there is no state change URL
  a request to unfriend but no friends
    returns a response which
      has status code 200 (OK)
      includes headers
      has a matching body (OK)
  a request friends
    returns a response which
      has status code 200 (FAILED)
      includes headers
        "Content-Type" with value "application/json" (FAILED)
      has a matching body (FAILED)
  a request to unfriend
    returns a response which
      has status code 200 (OK)
      includes headers
        "Content-Type" with value "application/json" (OK)
      has a matching body (FAILED)


Verifying a pact between Consumer2 and happy_provider
  Given I am friends with Fred
    WARNING: State Change ignored as there is no state change URL
  Given I have no friends
    WARNING: State Change ignored as there is no state change URL
  a request to unfriend but no friends
    returns a response which
      has status code 200 (OK)
      includes headers
      has a matching body (OK)
  a request friends
    returns a response which
      has status code 200 (FAILED)
      includes headers
        "Content-Type" with value "application/json" (FAILED)
      has a matching body (FAILED)
  a request to unfriend
    returns a response which
      has status code 200 (OK)
      includes headers
        "Content-Type" with value "application/json" (OK)
      has a matching body (FAILED)


Failures:

0) Verifying a pact between Consumer and happy_provider - a request friends returns a response which has a matching body
    expected 'application/json' body but was 'text/plain'

1) Verifying a pact between Consumer and happy_provider - a request friends returns a response which has status code 200
    expected 200 but was 404

2) Verifying a pact between Consumer and happy_provider - a request friends returns a response which includes header 'Content-Type' with value 'application/json'
    Expected header 'Content-Type' to have value 'application/json' but was 'text/plain'

3) Verifying a pact between Consumer and happy_provider Given I am friends with Fred - a request to unfriend returns a response which has a matching body
    $.body -> Type mismatch: Expected Map {"reply":"Bye"} but received  "Ok"


4) Verifying a pact between Consumer2 and happy_provider - a request friends returns a response which has a matching body
    expected 'application/json' body but was 'text/plain'

5) Verifying a pact between Consumer2 and happy_provider - a request friends returns a response which has status code 200
    expected 200 but was 404

6) Verifying a pact between Consumer2 and happy_provider - a request friends returns a response which includes header 'Content-Type' with value 'application/json'
    Expected header 'Content-Type' to have value 'application/json' but was 'text/plain'

7) Verifying a pact between Consumer2 and happy_provider Given I am friends with Fred - a request to unfriend returns a response which has a matching body
    $.body -> Type mismatch: Expected Map {"reply":"Bye"} but received  "Ok"



There were 8 pact failures

验证消息 pacts

可以验证消息 pacts，只需从 HTTP 端点获取消息即可。验证器将向配置的提供者发送 POST 请求，并期望在响应中接收消息有效负载。POST 请求将包括 Pact 文件中为消息配置的描述和任何提供者状态，格式为 JSON。

示例 POST 请求

{
    "description": "Test Message",
    "providerStates":[ {"name": "message exists"} ]
}

验证元数据

消息元数据可以以 base64 编码的键/值对的形式包含在响应中，打包到 Pact-Message-Metadata HTTP 头中，并将与 pact 文件中任何预期的元数据进行比较。

值可以包含任何有效的 JSON。

例如，给定此元数据

{
  "Content-Type": "application/json",
  "topic": "baz",
  "number": 27,
  "complex": {
    "foo": "bar"
  }
}

我们将将其编码为 base64 字符串，得到 ewogICJDb250ZW50LVR5cGUiOiAiYXBwbGljYXRpb24vanNvbiIsCiAgInRvcGljIjogImJheiIsCiAgIm51bWJlciI6IDI3LAogICJjb21wbGV4IjogewogICAgImZvbyI6ICJiYXIiCiAgfQp9Cg==。

TLS 和证书管理

Pact 使用 rustls-native-certs 包，作为 TLS 客户端操作时将尊重平台的本地证书存储

此功能支持 Windows、macOS 和 Linux

• 在 Windows 上，证书从系统证书存储加载。使用 schannel 包来访问 Windows 证书存储 API。
• 在 macOS 上，证书从密钥链加载。用户、管理员和系统信任设置合并在一起，如 Apple 文档所述。使用 security-framework 包来访问密钥存储 API。
• 在 Linux 和其他类 UNIX 操作系统上，使用 openssl-probe 包来发现系统 CA 包的文件名。

在 Linux 上，还将尊重标准 OpenSSL 环境变量 SSL_CERT_FILE 和 SSL_CERT_DIR。

验证 V4 Pact 文件

需要插件的 Pact 文件

需要插件的 Pact 文件可以使用版本 0.9.0-beta.0+ 进行验证。有关插件如何工作的详细信息，请参阅 Pact 插件项目。

每个必需的插件都在 plugins 部分的 Pact 元数据中定义。插件将从插件目录加载。默认情况下，这是 ~/.pact/plugins 或 PACT_PLUGIN_DIR 环境变量的值。每个所需的插件都必须安装在那里。您需要按照每个插件的安装说明进行操作，但默认情况下是将插件解压缩到子目录中 <plugin->-<plugin-version>（例如，对于 Protobuf 插件 0.0.0，它将是 protobuf-0.0.0）。必须存在插件清单文件才能加载插件。

验证 HTTP 和消息交互

V4 协议文件可以支持同一文件中的 HTTP 和基于消息的交互。在这种情况下，如果您需要处理这两种交互的验证，您需要使用 --transports <transports> 选项。这将允许配置不同的端口来发送不同的请求。

例如，--transports http:8080 message:8081 将会将 HTTP 请求发送到端口 8080，将消息请求发送到端口 8081。