README

这个库是为了允许轻松测试OpenAPI文档而编写的。它还允许验证您的代码实现与该文档的兼容性。

为什么创建这样的工具？

我们在API相关项目中投入了大量工作。有时我们创建API，有时我们使用它们。OpenAPI描述格式现在广为人知，并被用于许多不同的场景。

我们的担忧是，很难确保编写的文档反映了当前API的行为。我们想追踪文档和代码之间的实现差异。

我们在生态系统中搜索，发现存在不同的工具来模拟API或对其执行请求。然而，我们找不到一个工具允许执行使用固定值和能够对响应执行特定验证的HTTP请求。

因此，我们开始开发Raven！

它依赖于PSR以便于集成到任何项目中，并由两个不同的部分组成

一个HTTP请求工厂来定义输入
一个执行器，负责实际验证请求和响应

Raven，它不是一只鸟吗？

不，在这里我们使用X战警角色 Mystique 的人名。她能够变形和适应任何情况，这是该工具的目标。我们需要适应任何API来触发有效的请求并分析响应。

安装它

使用Composer

composer require chstudio/raven

使用Raven可能需要安装

当然，您也可以自己编写。唯一的约束是必须与PSR接口兼容。

使用方法

执行请求/响应验证

此库定义了自己的请求验证接口。它附带了一个适配器到league/openapi-psr7-validator包，该包定义了完整的验证逻辑。

<?php

use CHStudio\Raven\Bridge\LeagueOpenAPIValidation\Factory;
use CHStudio\Raven\Validator\Expectation\ExpectationCollection;

// Load OpenAPI description file
$factory = Factory::fromYamlFile('specific/path/to/openapi.yaml');

$executor = new Executor(
    /** Your own HTTP client implementation */,
    $factory->getRequestValidator(),
    $factory->getResponseValidator()
);

$executor->execute($request);

基于配置轻松生成请求

手动编写RequestInterface对象可能不是定义测试用例的最简单方式。我们创建了一个RequestFactory来帮助构建这些对象。它依赖于PSR17 HTTP工厂。

以下是一个使用nyholm/psr7的示例。

<?php

use CHStudio\Raven\Http\Factory\RequestFactory;
use Nyholm\Psr7\Factory\Psr17Factory;

$psrFactory = new Psr17Factory();
$requestFactory = new RequestFactory($psrFactory, $psrFactory);

$request = $requestFactory->fromArray([
    'uri' => 'http://myhost.com/api/users/me',
    'method' => 'POST',
    'headers' => [
        'Content-Type' => 'application/json',
        'Authorization' => 'Bearer token'
    ],
    'body' => '{"aSimple": "objectDefinition", "yep": true}'
]);

如果主体给定为一个数组，它将根据Content-Type头部进行编码

application/json，没有头部或不支持的头部将转换为JSON
multipart/form-data，将使用http_build_query。

使用解析器丰富请求体

大多数时候，静态请求体将不足以强大。我们需要从我们的固定值中提取标识符和其他细节。可以在RequestFactory周围添加一个特定层来动态解析主体。

您可以将不同的Resolver组合在一起，让配置的体通过所有方法并通过，并进行丰富。此库附带了一个特定的Faker解析器，可以通过提供程序轻松生成数据（请参阅Faker 文档）。

您可以使用ValueResolverInterface构建自己的解析器。

<?php

use CHStudio\Raven\Http\Factory\Resolver\ArrayValueResolver;
use CHStudio\Raven\Http\Factory\Resolver\FakerValueResolver;
use CHStudio\Raven\Http\Factory\Resolver\PassThroughValueResolver;

//Configure your own faker generator, maybe with some `addProvider` calls.
$generator = \Faker\Factory::create();

//Configure specific resolver logic.
$valueResolver = new ArrayValueResolver(
    new FakerValueResolver(
        $generator,
        new PassThroughValueResolver()
    )
);

//Apply it on the request factory built in the previous section.
$requestFactory = new RequestUriParametersResolver(
    $valueResolver,
    new RequestBodyResolver(
        $valueResolver,
        $requestFactory
    )
);

$request = $requestFactory->fromArray([
    'uri' => [
        'base' => 'http://myhost.com/api/users/{id}',
        'parameters' => [
            //This value will be resolved by `RequestUriParametersResolver`
            '{id}' => '<userId()>'
        ]
    ],
    'method' => 'POST',
    'body' => [
        'scalar' => [
            'bool' => true,
            'int' => 23456,
            'float' => 18.06
        ],
        //Built in Faker provider resolved by `RequestBodyResolver`
        'faker' => [
            'name' => '<name()>',
            'creationDate' => '<date("Y-m-d")>',
        ]
        //Specific provider to query database
        'institution' => '<institutionId("Massachusetts General Hospital")>'
    ]
]);

/**
 * This will generate an URL like this: http://myhost.com/api/users/a5098711-b6b2-4acb-96ea-f8baf496c700
 *
 * This will generate the following body:
 *
 * {
 *     "scalar": {
 *         "bool": true,
 *         "int": 23456,
 *         "float": 18.06
 *     },
 *     "faker": {
 *         "name": "John Doe",
 *         "creationDate": "2022-10-03"
 *     },
 *     "institution": "bf91c434-dcf3-3a4c-b49a-12e0944ef1e2"
 * }
 */

自定义期望

验证请求和响应是否遵守文档是件好事，但我们可能需要添加一些用户定义的期望。这个请求是否会触发401响应？正文是否包含正确的值？

期望可以使用请求定义数据构建。基于一些属性，它们将动态添加。期望集合可以传递给Executor::execute方法。

如果其中一个期望失败，响应验证将失败，您将通过ExpectationFailedException错误获取详细信息。

<?php

use CHStudio\Raven\Validator\Expectation\ExpectationFactory;

$requestData = [
    'uri' => 'http://myhost.com/api/users/me',
    'method' => 'GET',
    'statusCode' => 403
];

$expectations = (new ExpectationFactory())->fromArray($requestData);
$request = $requestFactory->fromArray($requestData);

$executor->execute($request, $expectations);

这个库内置了期望：StatusCode。您可以使用ResponseExpectationInterface轻松构建自己的期望。

许可证

此软件包根据Apache-2许可证发布。

贡献

如果您想为项目做出贡献，请阅读贡献指南。

chstudio / raven

维护者

详细信息