{"id":13665232,"url":"https://github.com/allure-framework/allure-phpunit","last_synced_at":"2025-04-05T03:10:30.872Z","repository":{"id":16459214,"uuid":"19211209","full_name":"allure-framework/allure-phpunit","owner":"allure-framework","description":"Allure integrations for PHP test frameworks: PHPUnit","archived":false,"fork":false,"pushed_at":"2024-04-03T13:02:02.000Z","size":159,"stargazers_count":60,"open_issues_count":16,"forks_count":30,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-02-15T21:03:59.043Z","etag":null,"topics":["allure","phpunit","reporting","reporting-engine"],"latest_commit_sha":null,"homepage":"https://allurereport.org/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/allure-framework.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2014-04-27T17:23:51.000Z","updated_at":"2024-06-20T09:51:25.000Z","dependencies_parsed_at":"2023-12-15T20:08:04.493Z","dependency_job_id":"e6935772-30de-4faf-9bb4-d8a29d5938ae","html_url":"https://github.com/allure-framework/allure-phpunit","commit_stats":{"total_commits":77,"total_committers":14,"mean_commits":5.5,"dds":0.5454545454545454,"last_synced_commit":"f946318bfa0b5abebbeb0341ef444e2073ff4595"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allure-framework%2Fallure-phpunit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allure-framework%2Fallure-phpunit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allure-framework%2Fallure-phpunit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allure-framework%2Fallure-phpunit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allure-framework","download_url":"https://codeload.github.com/allure-framework/allure-phpunit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239934028,"owners_count":19720868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["allure","phpunit","reporting","reporting-engine"],"created_at":"2024-08-02T06:00:30.106Z","updated_at":"2025-02-23T02:17:32.141Z","avatar_url":"https://github.com/allure-framework.png","language":"PHP","readme":"# Allure PHPUnit adapter\n\n[![Latest Stable Version](http://poser.pugx.org/allure-framework/allure-phpunit/v)](https://packagist.org/packages/allure-framework/allure-phpunit)\n[![Build](https://github.com/allure-framework/allure-phpunit/actions/workflows/build.yml/badge.svg)](https://github.com/allure-framework/allure-phpunit/actions/workflows/build.yml)\n[![Type Coverage](https://shepherd.dev/github/allure-framework/allure-phpunit/coverage.svg)](https://shepherd.dev/github/allure-framework/allure-phpunit)\n[![Psalm Level](https://shepherd.dev/github/allure-framework/allure-phpunit/level.svg)](https://shepherd.dev/github/allure-framework/allure-phpunit)\n[![Total Downloads](http://poser.pugx.org/allure-framework/allure-phpunit/downloads)](https://packagist.org/packages/allure-framework/allure-phpunit)\n[![License](http://poser.pugx.org/allure-framework/allure-phpunit/license)](https://packagist.org/packages/allure-framework/allure-phpunit)\n\nThis an official PHPUnit adapter for Allure Framework - a flexible, lightweight and multi-language framework for writing self-documenting tests.\n\n## Table of Contents\n* [What is this for?](#what-is-this-for)\n* [Example Project](#example-project)\n* [How to Generate Report](#how-to-generate-report)\n* [Installation and Usage](#installation-and-usage)\n* [Main Features](#main-features)\n  * [Title](#human-readable-test-class-or-test-method-title)\n  * [Description](#extended-test-class-or-test-method-description)\n  * [Test severity](#set-test-severity)\n  * [Test parameters](#specify-test-parameters-information)\n  * [Features and Stories](#map-test-classes-and-test-methods-to-features-and-stories)\n  * [Attachments](#attach-files-to-report)\n  * [Steps](#divide-test-methods-into-steps)\n\n## What is this for?\nThe main purpose of this adapter is to accumulate information about your tests and write it out to a set of JSON files: one for each test class. Then you can use a standalone command line tool or a plugin for popular continuous integration systems to generate an HTML page showing your tests in a good form.\n\n## Examples\nPlease take a look at [these example tests](./test/report/Generate).\n\n## How to generate report\nThis adapter only generates JSON files containing information about tests. See [wiki section](https://docs.qameta.io/allure/#_reporting) on how to generate report.\n\n## Installation \u0026\u0026 Usage\n**Note:** this adapter supports Allure 2.x.x only.\n\nSupported PHP versions: 8.1-8.3.\n\nIn order to use this adapter you need to add a new dependency to your **composer.json** file:\n```\n{\n    \"require\": {\n\t    \"php\": \"^8.1\",\n\t    \"allure-framework/allure-phpunit\": \"^3\"\n    }\n}\n```\nThen add Allure test listener in **phpunit.xml** file:\n```xml\n\u003cextensions\u003e\n    \u003cbootstrap class=\"Qameta\\Allure\\PHPUnit\\AllureExtension\"\u003e\n          \u003c!-- Path to config file (default is config/allure.config.php) --\u003e\n          \u003cparameter name=\"config\" value=\"config/allure.config.php\" /\u003e\n    \u003c/bootstrap\u003e\n\u003c/extensions\u003e\n```\nConfig is common PHP file that should return an array: \n```php\n\u003c?php\n\nreturn [\n    // Path to output directory (default is build/allure-results)\n    'outputDirectory' =\u003e 'build/allure-results',\n    'linkTemplates' =\u003e [\n        // Class or object must implement \\Qameta\\Allure\\Setup\\LinkTemplateInterface\n        'tms' =\u003e \\My\\LinkTemplate::class,\n    ],\n    'setupHook' =\u003e function (): void {\n        // Some actions performed before starting the lifecycle\n    },\n     // Class or object must implement \\Qameta\\Allure\\PHPUnit\\Setup\\ThreadDetectorInterface\n    'threadDetector' =\u003e \\My\\ThreadDetector::class,\n    'lifecycleHooks' =\u003e [\n        // Class or object must implement one of \\Qameta\\Allure\\Hook\\LifecycleHookInterface descendants.\n        \\My\\LifecycleHook::class,\n    ],\n];\n```\n\nAfter running PHPUnit tests a new folder will be created (**build/allure-results** in the example above). This folder will contain generated JSON files. See [framework help](https://docs.qameta.io/allure/#_reporting) for details about how to generate report from JSON files. By default generated report will only show a limited set of information but you can use cool Allure features by adding a minimum of test code changes. Read next section for details.\n\n## Main features\nThis adapter comes with a set of PHP annotations and traits allowing to use main Allure features.\n\n### Human-readable test class or test method title\nIn order to add such title to any test class or [test case](https://github.com/allure-framework/allure1/wiki/Glossary#test-case) method you need to annotate it with **#[DisplayName]** annotation:\n```php\nnamespace Example\\Tests;\n\nuse PHPUnit\\Framework\\TestCase;\nuse Qameta\\Allure\\Attribute\\DisplayName;\n\n#[DisplayName(\"Human-readable test class title\")]\nclass SomeTest extends TestCase\n{\n    #[DisplayName(\"Human-readable test method title\")]\n    public function testCaseMethod(): void\n    {\n        //Some implementation here...\n    }\n}\n```\n\n### Extended test class or test method description\nSimilarly you can add detailed description for each test class and [test method](https://github.com/allure-framework/allure1/wiki/Glossary#test-case). To add such description simply use **#[Description]** annotation:\n```php\nnamespace Example\\Tests;\n\nuse PHPUnit\\Framework\\TestCase;\nuse Qameta\\Allure\\Attribute\\Description;\n\n#[Description(\"Detailed description for **test** class\")]\nclass SomeTest extends TestCase\n{\n    #[Description(\"Detailed description for \u003cb\u003etest class\u003c/b\u003e\", isHtml: true)]\n    public function testCaseMethod(): void\n    {\n        //Some implementation here...\n    }\n}\n```\nDescription can be added in Markdown format (which is default one) or in HTML format. For HTML simply pass `true` value for optional `isHtml` argument.\n\n### Set test severity\n**#[Severity]** annotation is used in order to prioritize test methods by severity:\n\n```php\nnamespace Example\\Tests;\n\nuse PHPUnit\\Framework\\TestCase;\nuse Qameta\\Allure\\Attribute\\Severity;\n\nclass SomeTest extends TestCase\n{\n    #[Severity(Severity::MINOR)]\n    public function testCaseMethod(): void\n    {\n        //Some implementation here...\n    }\n}\n```\n\n### Specify test parameters information\nIn order to add information about test method [parameters](https://github.com/allure-framework/allure-core/wiki/Glossary#parameter) you should use **#[Parameter]** annotation. You can also use static shortcut if your marameter has dynamic value:\n\n```php\nnamespace Example\\Tests;\n\nuse PHPUnit\\Framework\\TestCase;\nuse Qameta\\Allure\\Allure;\nuse Qameta\\Allure\\Attribute\\Parameter;\n\nclass SomeTest extends TestCase\n{\n    #[\n        Parameter(\"param1\", \"value1\"),\n        Parameter(\"param2\", \"value2\"),\n    ]\n    public function testCaseMethod(): void\n    {\n        //Some implementation here...\n        Allure::parameter(\"param3\", $someVar);\n    }\n}\n```\n\n### Map test classes and test methods to features and stories\nIn some development approaches tests are classified by [stories](https://github.com/allure-framework/allure-core/wiki/Glossary#user-story) and [features](https://github.com/allure-framework/allure-core/wiki/Glossary#feature). If you're using this then you can annotate your test with **#[Story]** and **#[Feature]** annotations:\n```php\nnamespace Example\\Tests;\n\nuse PHPUnit\\Framework\\TestCase;\nuse Qameta\\Allure\\Attribute\\Feature;\nuse Qameta\\Allure\\Attribute\\Story;\n\n#[\n    Story(\"story1\"),\n    Story(\"story2\"),\n    Feature(\"feature1\"),\n    Feature(\"feature2\"),\n    Feature(\"feature3\"),\n]\nclass SomeTest extends TestCase\n{\n    #[\n        Story(\"story3\"),\n        Feature(\"feature4\"),\n    ]\n    public function testCaseMethod(): void\n    {\n        //Some implementation here...\n    }\n}\n```\nYou will then be able to filter tests by specified features and stories in generated Allure report.\n\n### Attach files to report\nIf you wish to [attach some files](https://github.com/allure-framework/allure-core/wiki/Glossary#attachment) generated during PHPUnit run (screenshots, log files, dumps and so on) to report - then you need to use static shortcuts in your test class:\n```php\nnamespace Example\\Tests;\n\nuse PHPUnit\\Framework\\TestCase;\nuse Qameta\\Allure\\Allure;\n\nclass SomeTest extends TestCase\n{\n\n    public function testCaseMethod()\n    {\n        //Some implementation here...\n        Allure::attachment(\"Attachment 1\", \"attachment content\", 'text/plain');\n        Allure::attachmentFile(\"Attachment 2\", \"/path/to/file.png\", 'image/png');\n        //Some implementation here...\n    }\n}\n```\nIn order to create an [attachment](https://github.com/allure-framework/allure-core/wiki/Glossary#attachment) simply call **Allure::attachment()** method. This method accepts human-readable name, string content and MIME attachment type. To attach a file, use **Allure::attachmentFile()** method that accepts file name instead of string content.\n\n### Divide test methods into steps\nAllure framework also supports very useful feature called [steps](https://github.com/allure-framework/allure-core/wiki/Glossary#test-step). Consider a test method which has complex logic inside and several assertions. When an exception is thrown or one of assertions fails sometimes it's very difficult to determine which one caused the failure. Allure steps allow dividing test method logic into several isolated pieces having independent run statuses such as **passed** or **failed**. This allows to have much cleaner understanding of what really happens. In order to use steps simply use static shortcuts:\n\n```php\nnamespace Example\\Tests;\n\nuse PHPUnit\\Framework\\TestCase;\nuse Qameta\\Allure\\Allure;\nuse Qameta\\Allure\\Attribute\\Parameter;\nuse Qameta\\Allure\\Attribute\\Title;\nuse Qameta\\Allure\\StepContextInterface;\n\nclass SomeTest extends TestCase\n{\n\n    public function testCaseMethod(): void\n    {\n        //Some implementation here...\n        $x = Allure::runStep(\n            #[Title('First step')]\n            function (StepContextInterface $step): string {\n                $step-\u003eparameter('param1', $someValue);\n                \n                return 'foo';\n            },\n        );\n        Allure::runStep([$this, 'stepTwo']);\n        //Some implementation here...\n    }\n\n    #[\n        Title(\"Second step\"),\n        Parameter(\"param2\", \"value2\"),\n    ]\n    private function stepTwo(): void\n    {\n        //Some implementation here...\n    }\n}\n```\nThe entire test method execution status will depend on every step but information about steps status will be stored separately.\n","funding_links":[],"categories":["Programming languages and frameworks"],"sub_categories":["PHP"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallure-framework%2Fallure-phpunit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallure-framework%2Fallure-phpunit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallure-framework%2Fallure-phpunit/lists"}