README

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

这是为什么？

此适配器的主要目的是收集有关测试的信息，并将其写入一组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...
    }
}

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

metafoxapp / allure-phpunit

维护者

详细信息