README

这是一个官方的PHPUnit适配器，用于Allure Framework - 一个灵活、轻量级且支持多语言的自文档测试框架。

这是什么？

此适配器的主要目的是收集有关测试的信息，并将其写入一组JSON文件：每个测试类一个。然后，您可以使用独立的命令行工具或流行的持续集成系统的插件来生成一个HTML页面，以良好的形式显示您的测试。

示例

请查看这些示例测试。

如何生成报告

此适配器仅生成包含测试信息的JSON文件。有关如何生成报告的说明，请参阅wiki部分。

安装 && 使用

注意：此适配器仅支持Allure 2.x.x。

支持的PHP版本：8.1-8.3。

为了使用此适配器，您需要在您的composer.json文件中添加一个新的依赖项

{
    "require": {
	    "php": "^8.1",
	    "allure-framework/allure-phpunit": "^3"
    }
}

然后，在phpunit.xml文件中添加Allure测试监听器

<extensions>
    <bootstrap class="Qameta\Allure\PHPUnit\AllureExtension">
          <!-- Path to config file (default is config/allure.config.php) -->
          <parameter name="config" value="config/allure.config.php" />
    </bootstrap>
</extensions>

配置是一个应返回数组的常见PHP文件

<?php

return [
    // Path to output directory (default is build/allure-results)
    'outputDirectory' => 'build/allure-results',
    'linkTemplates' => [
        // Class or object must implement \Qameta\Allure\Setup\LinkTemplateInterface
        'tms' => \My\LinkTemplate::class,
    ],
    'setupHook' => function (): void {
        // Some actions performed before starting the lifecycle
    },
     // Class or object must implement \Qameta\Allure\PHPUnit\Setup\ThreadDetectorInterface
    'threadDetector' => \My\ThreadDetector::class,
    'lifecycleHooks' => [
        // Class or object must implement one of \Qameta\Allure\Hook\LifecycleHookInterface descendants.
        \My\LifecycleHook::class,
    ],
];

运行PHPUnit测试后，将创建一个新文件夹（如示例中的build/allure-results）。此文件夹将包含生成的JSON文件。有关如何从JSON文件生成报告的详细信息，请参阅框架帮助。默认生成的报告将仅显示有限的信息，但您可以通过添加最少的测试代码更改来使用Allure的酷炫功能。有关详细信息，请参阅下一部分。

主要功能

此适配器包含一组PHP注释和特质，允许使用主要的Allure功能。

人类可读的测试类或测试方法标题

要为任何测试类或测试用例方法添加此类标题，您需要使用#[DisplayName]注释

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Qameta\Allure\Attribute\DisplayName;

#[DisplayName("Human-readable test class title")]
class SomeTest extends TestCase
{
    #[DisplayName("Human-readable test method title")]
    public function testCaseMethod(): void
    {
        //Some implementation here...
    }
}

扩展测试类或测试方法描述

同样，您可以为每个测试类和测试用例添加详细描述。要添加此类描述，只需使用#[Description]注释即可

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Qameta\Allure\Attribute\Description;

#[Description("Detailed description for **test** class")]
class SomeTest extends TestCase
{
    #[Description("Detailed description for <b>test class</b>", isHtml: true)]
    public function testCaseMethod(): void
    {
        //Some implementation here...
    }
}

描述可以以Markdown格式（这是默认格式）或HTML格式添加。对于HTML，只需为可选的isHtml参数传递true值。

设置测试严重性

#[Severity]注释用于根据严重性优先排序测试方法

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Qameta\Allure\Attribute\Severity;

class SomeTest extends TestCase
{
    #[Severity(Severity::MINOR)]
    public function testCaseMethod(): void
    {
        //Some implementation here...
    }
}

指定测试参数信息

要添加有关测试方法参数的信息，您应使用#[Parameter]注释。如果您参数具有动态值，您还可以使用静态快捷方式

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Qameta\Allure\Allure;
use Qameta\Allure\Attribute\Parameter;

class SomeTest extends TestCase
{
    #[
        Parameter("param1", "value1"),
        Parameter("param2", "value2"),
    ]
    public function testCaseMethod(): void
    {
        //Some implementation here...
        Allure::parameter("param3", $someVar);
    }
}

将测试类和测试方法映射到功能和故事

在一些开发方法中，测试根据用户故事和功能进行分类。如果您使用这种方法，则可以使用#[Story]和#[Feature]注释来注释您的测试。

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Qameta\Allure\Attribute\Feature;
use Qameta\Allure\Attribute\Story;

#[
    Story("story1"),
    Story("story2"),
    Feature("feature1"),
    Feature("feature2"),
    Feature("feature3"),
]
class SomeTest extends TestCase
{
    #[
        Story("story3"),
        Feature("feature4"),
    ]
    public function testCaseMethod(): void
    {
        //Some implementation here...
    }
}

然后您就可以在生成的Allure报告中通过指定的功能和用户故事来过滤测试。

将文件附加到报告中

如果您希望在报告中将PHPUnit运行期间生成的某些文件（如截图、日志文件、转储等）附加到报告中，则需要在测试类中使用静态快捷键。

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Qameta\Allure\Allure;

class SomeTest extends TestCase
{

    public function testCaseMethod()
    {
        //Some implementation here...
        Allure::attachment("Attachment 1", "attachment content", 'text/plain');
        Allure::attachmentFile("Attachment 2", "/path/to/file.png", 'image/png');
        //Some implementation here...
    }
}

要创建一个附件，只需调用Allure::attachment()方法。此方法接受可读名称、字符串内容和MIME附件类型。要附加文件，请使用接受文件名而不是字符串内容的Allure::attachmentFile()方法。

将测试方法划分为步骤

Allure框架还支持一个非常实用的功能，称为步骤。考虑一个测试方法，其中包含复杂的逻辑和多个断言。当抛出异常或某个断言失败时，有时很难确定是哪个导致了失败。Allure步骤允许将测试方法的逻辑划分为几个独立的片段，每个片段都有独立的运行状态，例如通过或失败。这允许对实际发生的事情有更清晰的理解。要使用步骤，只需使用静态快捷键。

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Qameta\Allure\Allure;
use Qameta\Allure\Attribute\Parameter;
use Qameta\Allure\Attribute\Title;
use Qameta\Allure\StepContextInterface;

class SomeTest extends TestCase
{

    public function testCaseMethod(): void
    {
        //Some implementation here...
        $x = Allure::runStep(
            #[Title('First step')]
            function (StepContextInterface $step): string {
                $step->parameter('param1', $someValue);
                
                return 'foo';
            },
        );
        Allure::runStep([$this, 'stepTwo']);
        //Some implementation here...
    }

    #[
        Title("Second step"),
        Parameter("param2", "value2"),
    ]
    private function stepTwo(): void
    {
        //Some implementation here...
    }
}

整个测试方法的执行状态将取决于每个步骤，但步骤状态的信息将被单独存储。

allure-framework / allure-phpunit

维护者

详细信息