added attributes for standard labels and attribute sets support (fixes #33, via #58)

Author: remorhaz

README.md

@@ -19,5 +19,56 @@ In order to use this API you simply need to add the following to **composer.json
 }
 ```
 
-## Usage examples
-See [allure-phpunit](https://github.com/allure-framework/allure-phpunit) project.
+## Custom attributes
+You can easily implement custom attributes and use them with your test framework. In most cases you would like
+to implement [`Qameta\Allure\Attribute\AttributeSetInterface`](./src/Attribute/AttributeSetInterface.php) that allows to set several attributes at once:
+
+```php
+<?php
+
+use Qameta\Allure\Attribute\AttributeSetInterface;
+use Qameta\Allure\Attribute\DisplayName;
+use Qameta\Allure\Attribute\Tag;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
+class MyAttribute implements AttributeSetInterface
+{
+    private array $tags;
+
+    public function __construct(
+        private string $displayName,
+        string ...$tags,
+    ) {
+        $this->tags = $tags;
+    }
+    
+    public function getAttributes() : array
+    {
+        return [
+            new DisplayName($this->displayName),
+            ...array_map(
+                fn (string $tag): Tag => new Tag($tag),
+                $this->tags,
+            ),
+        ];
+    }
+}
+
+// Example of usage
+#[MyAttribute('Test name', 'tag 1', 'tag 2')]
+class MyTestClass
+{
+}
+```
+
+You can also implement particular attribute interfaces instead of using one of the standard implementations:
+
+- [`Qameta\Allure\Attribute\DescriptionInterface`](./src/Attribute/DescriptionInterface.php)
+- [`Qameta\Allure\Attribute\DisplayNameInterface`](./src/Attribute/DisplayNameInterface.php)
+- [`Qameta\Allure\Attribute\LabelInterface`](./src/Attribute/LabelInterface.php)
+- [`Qameta\Allure\Attribute\LinkInterface`](./src/Attribute/LinkInterface.php)
+- [`Qameta\Allure\Attribute\ParameterInterface`](./src/Attribute/ParameterInterface.php)
+
+## Other usage examples
+See [allure-phpunit](https://github.com/allure-framework/allure-phpunit)
+and [allure-codeception](https://github.com/allure-framework/allure-codeception) projects.

src/Allure.php

@@ -193,6 +193,11 @@ public static function package(string $value): void
         self::getInstance()->doLabel(Label::package($value));
     }
 
+    public static function layer(string $value): void
+    {
+        self::getInstance()->doLabel(Label::layer($value));
+    }
+
     public static function label(string $name, string $value): void
     {
         self::getInstance()->doLabel(

src/Attribute/AttributeParser.php

@@ -18,6 +18,8 @@
 use ReflectionProperty;
 
 use function array_merge;
+use function array_pop;
+use function array_push;
 use function array_reverse;
 use function is_string;
 
@@ -107,7 +109,12 @@ public static function createForChain(
 
     private function processAnnotations(AttributeInterface ...$attributes): void
     {
-        foreach ($attributes as $attribute) {
+        while (!empty($attributes)) {
+            $attribute = array_shift($attributes);
+            if ($attribute instanceof AttributeSetInterface) {
+                array_unshift($attributes, ...$attribute->getAttributes());
+                continue;
+            }
             if ($attribute instanceof DisplayNameInterface) {
                 $this->displayName = $attribute->getValue();
             }

src/Attribute/AttributeSetInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qameta\Allure\Attribute;
+
+interface AttributeSetInterface extends AttributeInterface
+{
+    /**
+     * @return list<AttributeInterface>
+     */
+    public function getAttributes(): array;
+}

src/Attribute/Label.php

@@ -21,11 +21,14 @@ final class Label extends AbstractLabel
     public const TAG = Model\Label::TAG;
     public const OWNER = Model\Label::OWNER;
     public const LEAD = Model\Label::LEAD;
+    public const PACKAGE = Model\Label::PACKAGE;
+    public const LAYER = Model\Label::LAYER;
+
+    // Technical labels, set by framework automatically
     public const HOST = Model\Label::HOST;
     public const THREAD = Model\Label::THREAD;
     public const TEST_METHOD = Model\Label::TEST_METHOD;
     public const TEST_CLASS = Model\Label::TEST_CLASS;
-    public const PACKAGE = Model\Label::PACKAGE;
     public const FRAMEWORK = Model\Label::FRAMEWORK;
     public const LANGUAGE = Model\Label::LANGUAGE;
 }

src/Attribute/Layer.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qameta\Allure\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
+final class Layer extends AbstractLabel
+{
+    public function __construct(string $value)
+    {
+        parent::__construct(Label::LAYER, $value);
+    }
+}

src/Attribute/Lead.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qameta\Allure\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+final class Lead extends AbstractLabel
+{
+    public function __construct(string $value)
+    {
+        parent::__construct(Label::LEAD, $value);
+    }
+}

src/Attribute/Owner.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qameta\Allure\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+final class Owner extends AbstractLabel
+{
+    public function __construct(string $value)
+    {
+        parent::__construct(Label::OWNER, $value);
+    }
+}

src/Attribute/Package.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qameta\Allure\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
+final class Package extends AbstractLabel
+{
+    public function __construct(string $value)
+    {
+        parent::__construct(Label::PACKAGE, $value);
+    }
+}

src/Attribute/ParentSuite.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qameta\Allure\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+final class ParentSuite extends AbstractLabel
+{
+    public function __construct(string $value)
+    {
+        parent::__construct(Label::PARENT_SUITE, $value);
+    }
+}

src/Attribute/SubSuite.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qameta\Allure\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+final class SubSuite extends AbstractLabel
+{
+    public function __construct(string $value)
+    {
+        parent::__construct(Label::SUB_SUITE, $value);
+    }
+}

src/Attribute/Suite.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qameta\Allure\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+final class Suite extends AbstractLabel
+{
+    public function __construct(string $value)
+    {
+        parent::__construct(Label::SUITE, $value);
+    }
+}

src/Attribute/Tag.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Qameta\Allure\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+final class Tag extends AbstractLabel
+{
+    public function __construct(string $value)
+    {
+        parent::__construct(Label::TAG, $value);
+    }
+}

src/Legacy/Annotation/AllureId.php

@@ -5,13 +5,13 @@
 namespace Yandex\Allure\Adapter\Annotation;
 
 use Doctrine\Common\Annotations\Annotation\Required;
-use Qameta\Allure\Attribute\AllureId as QametaAllureId;
+use Qameta\Allure\Attribute;
 use Qameta\Allure\Legacy\Annotation\LegacyAnnotationInterface;
 
 /**
  * @Annotation
  * @Target({"METHOD"})
- * @deprecated Use native PHP attribute {@see \Qameta\Allure\Attribute\AllureId}
+ * @deprecated Use native PHP attribute {@see Attribute\AllureId}
  * @psalm-suppress MissingConstructor
  */
 class AllureId implements LegacyAnnotationInterface
@@ -22,8 +22,8 @@ class AllureId implements LegacyAnnotationInterface
      */
     public string $value;
 
-    public function convert(): QametaAllureId
+    public function convert(): Attribute\AllureId
     {
-        return new QametaAllureId($this->value);
+        return new Attribute\AllureId($this->value);
     }
 }

src/Legacy/Annotation/Description.php

@@ -5,14 +5,14 @@
 namespace Yandex\Allure\Adapter\Annotation;
 
 use Doctrine\Common\Annotations\Annotation\Required;
-use Qameta\Allure\Attribute\Description as QametaDescription;
+use Qameta\Allure\Attribute;
 use Qameta\Allure\Legacy\Annotation\LegacyAnnotationInterface;
 use Yandex\Allure\Adapter\Model\DescriptionType;
 
 /**
  * @Annotation
  * @Target({"CLASS", "METHOD"})
- * @deprecated Use native PHP attribute {@see \Qameta\Allure\Attribute\Description}
+ * @deprecated Use native PHP attribute {@see Attribute\Description}
  * @psalm-suppress MissingConstructor
  */
 class Description implements LegacyAnnotationInterface
@@ -29,10 +29,10 @@ class Description implements LegacyAnnotationInterface
      */
     public string $type = DescriptionType::TEXT;
 
-    public function convert(): QametaDescription
+    public function convert(): Attribute\Description
     {
         /** @psalm-suppress DeprecatedClass */
-        return new QametaDescription(
+        return new Attribute\Description(
             $this->value,
             DescriptionType::HTML == $this->type,
         );

src/Legacy/Annotation/Epics.php

@@ -5,15 +5,15 @@
 namespace Yandex\Allure\Adapter\Annotation;
 
 use Doctrine\Common\Annotations\Annotation\Required;
-use Qameta\Allure\Attribute\Epic;
+use Qameta\Allure\Attribute;
 use Qameta\Allure\Legacy\Annotation\LegacyAnnotationInterface;
 
 use function array_map;
 
 /**
  * @Annotation
  * @Target({"CLASS", "METHOD"})
- * @deprecated Use native PHP attribute {@see \Qameta\Allure\Annotation\Epics}
+ * @deprecated Use native PHP attribute {@see Attribute\Epic}
  * @psalm-suppress MissingConstructor
  */
 class Epics implements LegacyAnnotationInterface
@@ -33,12 +33,12 @@ public function getEpicNames(): array
     }
 
     /**
-     * @return list<Epic>
+     * @return list<Attribute\Epic>
      */
     public function convert(): array
     {
         return array_map(
-            fn (string $name) => new Epic($name),
+            fn (string $name) => new Attribute\Epic($name),
             $this->epicNames,
         );
     }

src/Legacy/Annotation/Features.php

@@ -5,15 +5,15 @@
 namespace Yandex\Allure\Adapter\Annotation;
 
 use Doctrine\Common\Annotations\Annotation\Required;
-use Qameta\Allure\Attribute\Feature;
+use Qameta\Allure\Attribute;
 use Qameta\Allure\Legacy\Annotation\LegacyAnnotationInterface;
 
 use function array_map;
 
 /**
  * @Annotation
  * @Target({"CLASS", "METHOD"})
- * @deprecated Use native PHP attribute {@see \Qameta\Allure\Annotation\Features}
+ * @deprecated Use native PHP attribute {@see Attribute\Features}
  * @psalm-suppress MissingConstructor
  */
 class Features implements LegacyAnnotationInterface
@@ -30,12 +30,12 @@ public function getFeatureNames(): array
     }
 
     /**
-     * @return list<Feature>
+     * @return list<Attribute\Feature>
      */
     public function convert(): array
     {
         return array_map(
-            fn (string $name) => new Feature($name),
+            fn (string $name) => new Attribute\Feature($name),
             $this->featureNames,
         );
     }