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 的HTTP 测试支持的“功能”或“功能”测试相比。

虽然 功能 测试确保您的请求验证、控制器行为、事件、响应等在人们与您的 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 维护
• 受Laravel OpenAPI 包的启发，该包由Dustin Wheeler 提供
• 所有贡献者

由contributors-img制作。

许可协议

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