README

此包被视为内部和实验性的，可能会在没有通知的情况下更改。

Ibexa REST 测试包

此包是 Ibexa DXP 的一部分。

要使用此包，请安装 Ibexa DXP。

入门指南

该包的目的是提供 Ibexa REST 测试框架，以减少样板代码。

安装

要开始使用，请与 ibexa/test-core 一起安装。

composer req --dev ibexa/test-rest:^0.1.x-dev ibexa/test-core:^0.1.x-dev

先决条件

假设您已经创建了一个 \Ibexa\Contracts\Core\Test\IbexaTestKernel 实例，并通过 phpunit.integration.xml.dist 或类似的 PHPUnit 配置文件以及您的 ./tests/integration/bootstrap.php 进行了配置。

配置

注册包

您的自定义 IbexaTestKernel::registerBundles 方法需要生成您的包实例，并且至少

yield from parent::registerBundles();
yield new \Hautelook\TemplatedUriBundle\HautelookTemplatedUriBundle();
yield new \Ibexa\Bundle\Rest\IbexaRestBundle();
yield new \Ibexa\Bundle\Test\Rest\IbexaTestRestBundle();

配置容器

接下来，创建 REST 路由配置文件，类似于项目配置文件通过配方准备，例如：./tests/integration/Resources/REST/routing/rest.yaml

ibexa.acme.rest:
  resource: '@IbexaAcmeBundle/Resources/routing/rest.yaml'
  prefix: '%ibexa.rest.path_prefix%'

然后，在您的自定义 IbexaTestKernel::registerContainerConfiguration 方法中配置以下内容

$loader->load(static function (ContainerBuilder $container): void {
    $container->loadFromExtension('framework', [
        'router' => [
            'resource' => __DIR__ . '/Resources/routing.yaml', // path to the file you've just created
        ],
    ]);
  
    $container->setParameter('form.type_extension.csrf.enabled', false);

    self::addSyntheticService($container, \Lexik\Bundle\JWTAuthenticationBundle\Services\JWTTokenManagerInterface::class);
});

编写第一个测试用例

此时，您应该能够编写第一个测试用例

use Ibexa\Contracts\Test\Rest\BaseRestWebTestCase;
use Ibexa\Contracts\Test\Rest\Request\Value\EndpointRequestDefinition;

final class GetAcmeTest extends BaseRestWebTestCase
{
    protected static function getEndpointsToTest(): iterable
    {
        $endpointRequestDefinition = new EndpointRequestDefinition(
            'GET',
            '/api/ibexa/v2/acme',
            'AcmeValue', // expected resource type
            self::generateMediaTypeString('AcmeValue', 'xml'), // accept header
            [], // custom HTTP headers to include in the request
            null, // InputPayload instance for POST/PATCH requests
            null, // custom request name for the data provider
            'acme/acme01' // snapshot name
        );

        yield $endpointRequestDefinition;

        yield $endpointRequestDefinition
            ->withAcceptHeader(self::generateMediaTypeString('AcmeValue', 'json'));
    }

    protected function getSchemaFileBasePath(string $resourceType, string $format): string
    {
        return dirname(__DIR__) . '/Resources/REST/Schemas/' . $resourceType;
    }

    protected static function getSnapshotDirectory(): ?string
    {
        return dirname(__DIR__) . '/Resources/REST/Snapshots';
    }
}

基类

您需要重写 \Ibexa\Contracts\Test\Rest\BaseRestWebTestCase 类。

定义要测试的内容

测试用例类需要重写 getEndpointsToTest 静态方法，该方法应该生成 EndpointRequestDefinition，描述要测试的端点和测试方式。

每个 EndpointRequestDefinition 测试一个端点，期望一个特定的响应格式（XML 或 JSON）。

EndpointRequestDefinition 以下构造函数参数，顺序如下

HTTP 方法类型（例如：'GET'、'POST' 等）
端点 URI，包括 REST 前缀。
端点应返回的预期资源类型（例如：'Content'、'Product' 或 'null' 对应于 'NoContent'）。
预期的 HTTP 头，例如：`application/vnd.ibexa.api.Content+xml`（使用 `self::generateMediaTypeString(resourceType, format)` 语法糖）。
如有必要，额外的 HTTP 头。
输入负载（对于 'GET' 请求为 `null`）。有关详细信息，请参阅测试需要输入负载的端点。
用于生成 PHPUnit 数据集名称的端点请求名称（使用默认名称为 `null`）
快照名称，有关详细信息，请参阅测试快照。

要测试另一个格式的端点，可以使用 `withAcceptHeader` 方法，这将克隆定义并更改 Accept 头。

响应内容与模式文件验证

REST 集成测试框架，对于每个资源响应，都会将其与其模式（XSD 或 JSON）进行验证。

通常，您会希望将模式文件保存在您想要的位置，并为它们创建一个目录，例如：./tests/integration/Resources/REST/Schemas。要配置它，您的测试用例类需要定义 getSchemaFileBasePath 方法，该方法返回模式文件的基础路径（包括不带扩展名的文件名），例如：./tests/integration/Resources/REST/Schemas/AcmeValue，在 Schemas 目录中，有两个模式文件：AcmeValue.xsd 和 AcmeValue.json。您可以使用 IDE 和/或一些在线工具生成这些模式文件。

通常，您会希望创建自己的抽象基类来定义此内容，并使每个测试用例类扩展它，例如。

abstract class BaseAcmeRestWebTestCase extends BaseRestWebTestCase
{
    protected function getSchemaFileBasePath(string $resourceType, string $format): string
    {
        return dirname(__DIR__) . '/Resources/REST/Schemas/' . $resourceType;
    }
}

文件扩展名不包括在内，因为它取决于验证器（例如XML文件的XSD）。

测试快照

如果您有要测试的响应快照，您的测试用例类需要重写getSnapshotDirectory方法，并在实例化EndpointRequestDefinition时定义快照基本文件路径（不带扩展名）。

REST测试框架查找快照文件连接

<snapshot_directory>/<snapshot_name>.<response_format:json|xml>

如果您想在运行时生成快照，请设置以下环境变量

TEST_REST_GENERATE_SNAPSHOTS=1

测试需要输入负载的端点

要测试突变端点（如POST、PATCH、PUT等），您需要在创建EndpointRequestDefinition时创建输入负载文件并使用\Ibexa\Contracts\Test\Rest\Input\PayloadLoader加载它们。

示例

    public static function getEndpointsToTest(): iterable
    {
        $payloadLoader = new PayloadLoader(dirname(__DIR__) . '/Resources/REST/InputPayloads');

        yield new EndpointRequestDefinition(
            'POST',
            '/api/ibexa/v2/acme',
            'AcmeValue',
            self::generateMediaTypeString('AcmeValue', 'xml'),
            [],
            $payloadLoader->loadPayload('AcmeValueCreate', 'xml', 'Acme/CustomPayloadFileName')
        );

        yield new EndpointRequestDefinition(
            'POST',
            '/api/ibexa/v2/acme',
            'AcmeValue',
            self::generateMediaTypeString('AcmeValue', 'json'),
            [],
            $payloadLoader->loadPayload('AcmeValueCreate', 'json', 'Acme/CustomPayloadFileName')
        );
    }

PayloadLoader::loadPayload期望2个参数：输入媒体类型，格式。您可以选择将自定义文件基本路径（不带扩展名）作为第3个参数传递。如果没有提供，文件基本路径将默认为指定的媒体类型。

版权

许可证

此源代码可在以下许可证下单独获取

A - Ibexa商业使用许可协议（Ibexa BUL），版本2.4或更高版本（因为许可条款可能会不时更新）Ibexa BUL通过拥有有效的Ibexa DXP（原名eZ Platform Enterprise）订阅而授予，如以下所述：https://www.ibexa.co/product有关完整的Ibexa BUL许可文本，请参阅

此源代码根目录中的LICENSE-bul文件，或
https://www.ibexa.co/software-information/licenses-and-agreements（适用最新版本）

AND

B - Ibexa试用和测试许可协议（Ibexa TTL），版本2.2或更高版本（因为许可条款可能会不时更新）试用可以通过Ibexa授予，请联系Ibexa AS以获取评估访问权限：https://www.ibexa.co/about-ibexa/contact-us有关完整的Ibexa TTL许可文本，请参阅

此源代码根目录中的LICENSE文件，或
https://www.ibexa.co/software-information/licenses-and-agreements（适用最新版本）

ibexa / test-rest

维护者

详情