README

ApiTestCase 是一个 PHPUnit 测试用例，可以让 Symfony API 开发者的生活变得更加容易。它扩展了基本的 Symfony WebTestCase，并添加了一些酷炫的功能。

感谢 PHP-Matcher，你可以像它自述中所说那样“像黑帮一样编写预期的 JSON 响应”。我们完全同意。

它还使用了 Alice，以便轻松加载 Doctrine 固定数据。

功能

• 使用 Symfony 进行 API 开发的清晰 TDD 工作流程；
• 具有清晰错误信息的 JSON/XML 匹配；
• 使用 Alice 加载固定数据（可选）；

安装

假设您已经全局安装了 Composer

composer require --dev lchrusciel/api-test-case

完成了！ApiTestCase 正在使用默认配置工作。

使用方法

我们为您提供了两个基础类用于测试用例：JsonApiTestCase 和 XmlApiTestCase。根据您想要创建的 API 格式选择一个。

JSON 示例

基本的 TDD 工作流程如下

1. 编写一个测试用例，发送请求，并使用 assertResponse 断言方法检查响应内容是否符合预期。您需要一个响应文件的名称；
2. 创建一个名为您在步骤 1 中选择的文件，并将预期的响应内容放在其中。例如，应该放在 src/AppBundle/Tests/Responses/Expected/hello_world.json 中。
3. 让它变红。
4. 让它变绿。
5. 重构。

让我们看看一个简单的例子！编写以下测试

namespace AppBundle\Tests\Controller\HelloWorldTest;

use ApiTestCase\JsonApiTestCase;

class HelloWorldTest extends JsonApiTestCase
{
    public function testGetHelloWorldResponse()
    {
        $this->client->request('GET', '/');

        $response = $this->client->getResponse();

        $this->assertResponse($response, 'hello_world');
    }
}

现在定义预期的响应文件

{
    "message": "Hello ApiTestCase World!"
}

运行您的测试

vendor/bin/phpunit

您的测试应该因为一些错误而失败，您可能缺少控制器和路由，所以请继续并定义它们！一旦您实现了控制器并配置了适当的路由，您可以再次运行测试

如果响应内容与我们的预期相符，控制台将显示一条简单消息

OK (1 tests, 2 assertions)

否则，它将显示接收到的消息的 diff

"Hello ApiTestCase World" does not match "Hello ApiTestCase World!".
@@ -1,4 +1,3 @@
 {
-    "message": "Hello ApiTestCase World!"
+    "message": "Hello ApiTestCase World"
 }
-

首先，函数 assertResponse 将检查响应代码（默认响应代码为 200），然后检查响应头是否包含 application/json 内容类型。最后，它将检查响应内容是否与预期相符。有时您无法预测响应中的某些值，例如数据库中自动生成的日期或 id。这里不需要任何魔法，因为 PHP-Matcher 提供了帮助。以下是一些可用的模式示例

• @string@
• @integer@
• @boolean@
• @array@

有关更多信息，请参阅 PHP-Matcher 的文档。

有了这些模式，您的预期响应将如下所示

{
    "message": "@string@"
}

有了这个，任何在 message 键下的字符串都将匹配该模式。更复杂的预期响应可能如下所示

[
    {
        "id": "@integer@",
        "name": "Star-Wars T-shirt",
        "sku": "SWTS",
        "price": 5500,
        "sizes": "@array@",
        "created_at": "@string@.isDateTime()"
    },
    {
        "id": "@integer@",
        "name": "Han Solo Mug",
        "sku": "HSM",
        "price": 500,
        "sizes": "@array@",
        "created_at": "@string@.isDateTime()"
    }
]

它将匹配以下产品列表

array(
    array(
        'id' => 1,
        'name' => 'Star-Wars T-shirt',
        'sku' => 'SWTS',
        'price' => 5500,
        'sizes' => array('S', 'M', 'L'),
        'created_at' => new \DateTime(),
    ),
    array(
        'id' => 2,
        'name' => 'Han Solo Mug',
        'sku' => 'HSM',
        'price' => 500,
        'sizes' => array('S', 'L'),
        'created_at' => new \DateTime(),
    ),
)

使用数据库固定数据测试

ApiTestCase 集成了 nelmio/alice。感谢这个优秀的库，您可以在需要时轻松加载 fixtures。您需要定义您的 fixtures 并将它们放置在合适的目录中。以下是一些如何定义 fixtures 和用例的示例。有关如何定义 fixtures 的更多信息，请参阅Alice 的文档。

为了使用 Alice 与 Doctrine，您应该启用两个附加的包

Symfony 4.0+

// config/bundles.php
return [
    // ...
    
    Nelmio\Alice\Bridge\Symfony\NelmioAliceBundle::class => ['test' => true],
    Fidry\AliceDataFixtures\Bridge\Symfony\FidryAliceDataFixturesBundle::class => ['test' => true],
];

现在，假设您在应用程序中有一个映射的 Doctrine 实体称为 Book

    class Book 
    {
        private $id;
        private $title;
        private $author;
    
        // ... 
    }

要为测试加载 fixtures，您需要在 src/AppBundle/Tests/DataFixtures/ORM/books.yml 中定义一个简单的 YAML 文件

    ApiTestCase\Test\Entity\Book:
        book1:
            title: "Lord of The Rings"
            author: "J. R. R. Tolkien"
        book2:
            title: "Game of Thrones"
            price: "George R. R. Martin"

最后，要使用这些 fixtures 进行测试，只需调用适当的方法

    public function testBooksIndexAction()
    {
        // This method require subpath to locate specific fixture file in your DataFixtures/ORM directory.
        $this->loadFixturesFromFile('books.yml');  
      
        // There is another method that allows you to load fixtures from directory.
        $this->loadFixturesFromDirectory('big_library');
    }

配置参考

要自定义测试套件的配置，您可以在 phpunit.xml 中添加一些额外的选项

<php>
    <server name="KERNEL_CLASS" value="Acme\Kernel" />
    <server name="EXPECTED_RESPONSE_DIR" value="/path/to/expected/responses/" />
    <server name="FIXTURES_DIR" value="/path/to/DataFixtures/ORM/" />
    <server name="OPEN_ERROR_IN_BROWSER" value="true/false" />
    <server name="OPEN_BROWSER_COMMAND" value="open %s" />
    <server name="IS_DOCTRINE_ORM_SUPPORTED" value="true/false" />
    <server name="TMP_DIR" value="/tmp/path/to/temporary/folder/" />
    <server name="ESCAPE_JSON" value="true/false" />
</php>

• KERNEL_CLASS 允许您指定用于设置 Kernel 的确切类。
• ERESPONSE_DIR 变量包含预期响应文件夹的路径。当 API 结果与现有的 json 文件进行比较时使用。如果没有设置此值，ApiTestCase 将尝试猜测响应的位置，在控制器测试类相对于的文件夹中查找响应：'../Responses'。
• FIXTURES_DIR 变量包含包含您的数据 fixtures 的文件夹路径。默认情况下，如果没有设置此变量，它将相对位于您的测试类中搜索 ../DataFixtures/ORM/。ApiTestCase 如果文件夹不存在或没有文件可加载，将抛出 RunTimeException。
• OPEN_ERROR_IN_BROWSER 是一个标志，用于在浏览器窗口中显示错误。默认值是 false。
• OPEN_BROWSER_COMMAND 是用于打开浏览器异常的命令。
• IS_DOCTRINE_ORM_SUPPORTED 是一个标志，用于启用 doctrine 支持，包括方便的数据 fixtures 加载器和数据库清理器。
• TMP_DIR 变量包含用于存储日志文件的临时文件夹的路径。
• ESCAPE_JSON 是一个标志，用于在比较预期数据之前对您的 JSON 输出进行转义（Unicode 字符和反斜杠）。默认值是 false。此标志仅存在于与 ApiTestCase 的先前版本的后向兼容性中，并将在未来版本中删除。

示例项目

在 test/ 目录中，您可以找到一个使用此库所需的最小配置的示例 Symfony 项目。

测试

要运行我们的 PHPUnit 测试套件，请执行以下命令

composer install
test/app/console doctrine:database:create
test/app/console doctrine:schema:create
vendor/bin/phpunit

错误跟踪和建议

如果您发现了一个错误或有一个很好的改进想法，请在此存储库中打开一个问题。

版本管理

版本将采用 major.minor.patch 格式编号。

并按照以下准则构建。

• 破坏向后兼容性将增加主要版本。
• 没有破坏向后兼容性的新功能将增加次要版本。
• 错误修复和其它更改将增加补丁版本。

有关 SemVer 的更多信息，请访问semver.org 网站。

MIT 许可证

许可证可以在此处找到。

作者

该库最初由以下人员创建

• Łukasz Chruściel
• Michał Marcinkowski
• Paweł Jędrzejewski
• Arkadiusz Krakowiak

在 Lakion 公司，在 https://github.com/Lakion/ApiTestCase 存储库下。

查看贡献者列表。