README

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

这是用来做什么的？

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

示例项目

示例项目位于：https://github.com/allure-framework/allure-phpunit-example

如何生成报告

此适配器仅生成包含测试信息的XML文件。请参阅wiki部分了解如何生成报告。

安装 && 用法

注意：此适配器仅支持Allure 1.4.x。为了使用此适配器，您需要在您的composer.json文件中添加一个新的依赖项

{
    "require": {
	    "php": ">=7.0.0",
	    "allure-framework/allure-phpunit": "~1.2.0"
    }
}

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

<listeners>
    <listener class="Yandex\Allure\Adapter\AllureAdapter" file="vendor/allure-framework/allure-phpunit/src/Yandex/Allure/Adapter/AllureAdapter.php">
        <arguments>
            <string>build/allure-results</string> <!-- XML files output directory -->
            <boolean>true</boolean> <!-- Whether to delete previous results on rerun -->
			<array> <!-- A list of custom annotations to ignore (optional) -->
                <element key="0">
                    <string>someCustomAnnotation</string>
                </element>
            </array>
        </arguments>
    </listener>
</listeners>

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

主要功能

此适配器提供了一套PHP注释和特质，允许使用主要的Allure功能。

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

为了将此类标题添加到任何测试类或测试用例方法，您需要使用@Title注释来注释它

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Yandex\Allure\Adapter\Annotation\Title;

/**
 * @Title("Human-readable test class title")
 */
class SomeTest extends TestCase
{
    /**
     * @Title("Human-readable test method title")
     */
    public function testCase()
    {
        //Some implementation here...
    }
}

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

同样，您可以添加每个测试类和测试用例的详细描述。要添加此类描述，请简单地使用@Description注释

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Yandex\Allure\Adapter\Annotation\Description;
use Yandex\Allure\Adapter\Model\DescriptionType;

/**
 * @Description("Detailed description for test class")
 */
class SomeTest extends TestCase
{
    /**
     * @Description(value = "Detailed description for <b>test class</b>.", type = DescriptionType::HTML)
     */
    public function testCase()
    {
        //Some implementation here...
    }
}

描述可以是纯文本、HTML或Markdown格式——只需分配不同的类型值。

设置测试严重性

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

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Yandex\Allure\Adapter\Annotation\Severity;
use Yandex\Allure\Adapter\Model\SeverityLevel;

class SomeTest extends TestCase
{
    /**
     * @Severity(level = SeverityLevel::MINOR)
     */
    public function testCase()
    {
        //Some implementation here...
    }
}

指定测试参数信息

为了添加有关测试方法参数的信息，您应该使用@Parameter注释

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Yandex\Allure\Adapter\Annotation\Parameter;
use Yandex\Allure\Adapter\Model\ParameterKind;

class SomeTest extends TestCase
{
    /**
     * @Parameter(name = "param1", value = "value1")
     * @Parameter(name = "param2", value = "value2", kind = ParameterKind::SYSTEM_PROPERTY)
     */
    public function testCase()
    {
        //Some implementation here...
    }
}

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

在某些开发方法中，测试根据用户故事和特性进行分类。如果您使用这种方法，则可以使用 @Stories 和 @Features 注解来标注测试。

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Yandex\Allure\Adapter\Annotation\Features;
use Yandex\Allure\Adapter\Annotation\Stories;

/**
 * @Stories({"story1", "story2"})
 * @Features({"feature1", "feature2", "feature3"})
 */
class SomeTest extends TestCase
{
    /**
     * @Features({"feature2"})
     * @Stories({"story1"})
     */
    public function testCase()
    {
        //Some implementation here...
    }
}

然后您可以在生成的 Allure 报告中通过指定的特性和故事来过滤测试。

将文件附加到报告

如果您想在报告中将 PHPUnit 运行期间生成的某些文件（如截图、日志文件、转储等）附加到报告，则需要在使用测试类时使用 AttachmentSupport 特性。

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Yandex\Allure\Adapter\Support\AttachmentSupport;

class SomeTest extends TestCase
{

    use AttachmentSupport;

    public function testCase()
    {
        //Some implementation here...
        $filePath = $this->outputSomeContentToTemporaryFile();
        $this->addAttachment($filePath, 'Attachment human-readable name', 'text/plain');
        //Some implementation here...
    }

    private function outputSomeContentToTemporaryFile()
    {
        $tmpPath = tempnam(sys_get_temp_dir(), 'test');
        file_put_contents($tmpPath, 'Some content to be outputted to temporary file.');
        return $tmpPath;
    }

}

为了创建一个附件，只需调用 AttachmentSupport::addAttachment() 方法。此方法接受附件类型、人类可读名称以及一个字符串，该字符串存储要附加的文件的完整路径或文件内容。

将测试方法分为步骤

Allure 框架还支持一个非常有用的特性，称为步骤。考虑一个具有复杂逻辑和多个断言的测试方法。当抛出异常或其中一个断言失败时，有时很难确定哪个导致了失败。Allure 步骤允许将测试方法的逻辑分为几个独立的片段，这些片段具有独立的运行状态，如通过或失败。这使您可以更清楚地了解真正发生了什么。为了使用步骤，只需在测试类中导入 StepSupport 特性。

namespace Example\Tests;

use PHPUnit\Framework\TestCase;
use Yandex\Allure\Adapter\Support\StepSupport;

class SomeTest extends TestCase
{

    use StepSupport;

    public function testCase()
    {
        //Some implementation here...
        $this->executeStep("This is step one", function () {
            $this->stepOne();
        });

        $this->executeStep("This is step two", function () {
            $this-stepTwo();
        });

        $this->executeStep("This is step three", function () {
            $this->stepThree('someArgument');
        });
        //Some implementation here...
    }

    private function stepOne()
    {
        //Some implementation here...
    }

    private function stepTwo()
    {
        //Some implementation here...
    }

    private function stepThree($argument)
    {
        //Some implementation here...
    }

}

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

polozpavlo / allure-phpunit

维护者

详细信息