README

Spectator

Spectator提供轻量级的OpenAPI测试工具，您可以在现有的Laravel测试套件中使用。

编写测试以验证您的API规范不会偏离实现。

要求

• PHP 8.1+
• Laravel 10+

安装

您可以通过Composer安装此包。

composer require hotmeteor/spectator --dev

然后，使用以下命令发布此包的配置文件

php artisan vendor:publish --provider="Spectator\SpectatorServiceProvider"

该配置文件将发布到config/spectator.php。

从v1升级到v2

重要： Spectator v2需要PHP 8.1和Laravel 10。如果您正在使用较旧的PHP或Laravel版本，则不应升级到v2。

虽然这应该是一个简单的升级，但您应该注意已经做出的某些更改。

请阅读UPGRADE.md文件以获取更多信息。

配置

来源

来源是指您的API规范所在的位置。根据您或您的团队的工作方式或规范所在的位置，您可能需要为不同的环境配置不同的来源。

如您从配置中看到的，有三种来源类型可用：local、remote和github。每个来源都需要定义您的规范所在的文件夹，而不是规范文件本身。这在使用一个项目中多个API或API分散在多个规范文件中的情况下提供了灵活性。

本地

## Spectator config

SPEC_SOURCE=local
SPEC_PATH=/spec/reference

远程

这是使用来自GitHub的原始访问链接，但可以指定任何远程来源。可以使用SPEC_URL_PARAMS来附加远程URL所需的任何附加参数。

## Spectator config

SPEC_PATH="https://raw.githubusercontent.com/path/to/repo"
SPEC_URL_PARAMS="?token=ABEDC3E5AQ3HMUBPPCDTTMDAFPMSM"

GitHub

这使用GitHub个人访问令牌，允许您访问包含您的合同的远程仓库。

您可以从此处查看如何从GitHub获取个人访问令牌的说明。

请注意，SPEC_GITHUB_PATH必须包含分支（例如：main）以及包含您的合同的目录的路径。

## Spectator config

SPEC_GITHUB_PATH='main/contracts'
SPEC_GITHUB_REPO='orgOruser/repo'
SPEC_GITHUB_TOKEN='your personal access token'

指定目标规范文件

在您的测试中，您将声明您想要测试的规范文件

public function testBasicExample()
{
    Spectator::using('Api.v1.json');

    // ...

测试

范式转变

现在，让我们谈谈重点。

起初，规范测试或合同测试可能看起来有些反直觉，尤其是在与Laravel支持的“功能”或“功能”测试相比时。

虽然功能测试确保当人们与您的API交互时，您的请求验证、控制器行为、事件、响应等行为符合预期，但合同测试确保的是请求和响应符合规范 - 仅此而已。数据本身可能是错误的，但这超出了合同测试的范围。

编写测试

Spectator引入了一些简单的工具，以补充现有的Laravel测试工具箱。

以下是一个典型的JSON API测试示例

<?php

class ExampleTest extends TestCase
{
    /**
     * A basic functional test example.
     *
     * @return void
     */
    public function testBasicExample()
    {
        $response = $this->postJson('/user', ['name' => 'Sally']);

        $response
            ->assertStatus(201)
            ->assertJson([
                'created' => true,
            ]);
    }
}

以下是一个合同测试的示例

<?php

use Spectator\Spectator;

class ExampleTest extends TestCase
{
    /**
     * A basic functional test example.
     *
     * @return void
     */
    public function testBasicExample()
    {
        Spectator::using('Api.v1.json');

        $response = $this->postJson('/user', ['name' => 'Sally']);

        $response
            ->assertValidRequest()
            ->assertValidResponse(201);
    }
}

该测试验证请求和响应是否根据规范有效，在这种情况下，规范位于 Api.v1.json 中。这种类型的测试促进了TDD：您可以在端点之前首先编写端点合同测试，然后确保您的规范和实现是一致的。

在您的规范中，应该记录每个可能响应。例如，单个 POST 端点可能会导致 2xx、4xx 或甚至 5xx 代码响应。此外，您的端点可能需要遵循特定的参数验证。

这就是合同测试与功能测试不同的地方

• 在 功能测试 中，测试成功和失败的响应以检查结果
• 在 合同测试 中，测试请求和响应的符合性，结果并不重要。

调试

对于某些验证错误，会抛出一个特殊的异常消息，显示与预期模式一起显示的错误消息。例如

  ---

The properties must match schema: data
All array items must match schema
The required properties (name) are missing

object++ <== The properties must match schema: data
    status*: string
    data*: array <== All array items must match schema
        object <== The required properties (name) are missing
            id*: string
            name*: string
            slug: string?

  ---

使用了一些自定义符号

• "++": 对象支持 additionalProperties
• "*": 项是 required
• "?": 项可以是 nullable

用法

提供规范

定义要测试的规范文件。这可以在您的 setUp() 方法或特定的测试方法中定义。

<?php

use Spectator\Spectator;

class ExampleTest extends TestCase
{
    public function setUp(): void
    {
        parent::setUp();

        Spectator::using('Api.v1.json');
    }

    public function testApiEndpoint()
    {
        // Test request and response...
    }

    public function testDifferentApiEndpoint()
    {
        Spectator::using('Other.v1.json');

        // Test request and response...
    }
}

测试请求

当测试端点时，有一些新的方法

$this->assertValidRequest();
$this->assertValidResponse($status = null);
$this->assertValidationMessage('Expected validation message');
$this->assertErrorsContain('Check for single error');
$this->assertErrorsContain(['Check for', 'Multiple Errors']);

当然，您可以继续使用所有现有的HTTP测试方法

$this
    ->actingAs($user)
    ->postJson('/comments', [
        'message' => 'Just over here spectating',
    ])
    ->assertCreated()
    ->assertValidRequest()
    ->assertValidResponse();

但是，混合功能测试和合同测试可能会在以后变得更加难以管理和阅读。强烈建议将这两种类型的测试分开。

测试响应

除了使用内置的 ->assertStatus($status) 方法之外，您还可以验证有效的响应是否实际上是您想要检查的响应。例如，您可能从单个端点收到 200 或 202，并确保您正在验证正确的响应。

$this
    ->actingAs($user)
    ->postJson('/comments', [
        'message' => 'Just over here spectating',
    ])
    ->assertValidRequest()
    ->assertValidResponse(201);

当抛出不是此包目的的异常时，例如拼写错误或缺少导入，默认情况下将以相当简短的消息和没有堆栈跟踪的格式输出。可以通过禁用Laravel内置的验证处理程序来更改此行为，以便在运行测试时更容易调试。

这可以通过几种不同的方式完成

class ExampleTestCase
{
    public function setUp(): void
    {
        parent::setUp();

        Spectator::using('Api.v1.json');

        // Disable exception handling for all tests in this file
        $this->withoutExceptionHandling();
    }

    // ...
}

class ExampleTestCase
{
    public function test_some_contract_test_example(): void
    {
        // Only disable exception handling for this test
        $this->withouthExceptionHandling();

        // Test request and response ...

    }
}

禁用Spectator

如果您想为特定测试禁用Spectator，可以使用 Spectator::reset 方法

<?php

use Spectator\Spectator;

class ExampleTest extends TestCase
{
    public function setUp(): void
    {
        parent::setUp();

        Spectator::using('Api.v1.json');
    }

    public function testWithoutSpectator()
    {
        Spectator::reset();
        
        // Run your test without Spectator
    }
}

核心概念

方法

Spectator通过注册一个自定义中间件来工作，该中间件根据规范执行请求和响应验证。

依赖项

对于有兴趣为Spectator做出贡献的人来说，熟悉用于规范测试的核心依赖项是有价值的

• cebe/php-openapi：用于将规范解析成可用的数组
• opis/json-schema：用于执行对象/数组对规范的验证

赞助商

非常感谢所有帮助推动Spectator发展的赞助商！

如果您想成为赞助商，请点击这里获取更多信息。💪

鸣谢

• 由Adam Campbell创建
• 由Bastien Philippe、Jarrod Parkes和Adam Campbell维护
• 灵感来源于 Dustin Wheeler 的 Laravel OpenAPI 包
• 所有贡献者

由 contributors-img 制作。

许可证

MIT 许可证（MIT）。请参阅 许可证文件 获取更多信息。