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!"
}

运行您的测试

$ bin/phpunit

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

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

OK (1 tests, 2 assertions)

否则它将显示接收到的消息的差异

"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 集成。多亏了这个不错的库，您可以在需要时轻松地加载您的数据填充。您必须定义您的数据填充并将它们放置在适当的目录中。以下是如何定义数据填充和使用案例的示例。有关如何定义数据填充的更多信息，请参阅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],
];

Symfony 3

// app/AppKernel.php
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        // ...

        if ('test' === $this->getEnvironment()) {
            new Nelmio\Alice\Bridge\Symfony\NelmioAliceBundle(),
            new Fidry\AliceDataFixtures\Bridge\Symfony\FidryAliceDataFixturesBundle(),
        }
    }
}

现在，假设你在应用程序中有一个映射的 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
$ bin/phpunit

错误跟踪和建议

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

版本控制

版本号将以 主要.次要.补丁 的格式编号。

以下是一些指南。

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

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

MIT 许可证

许可证可以在这里找到。

作者

此库最初由以下人员创建：

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

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

查看贡献者列表。