Common attributes API (#647)

Author: delatrie

.github/workflows/test.yml

@@ -71,6 +71,10 @@ jobs:
             --no-restore\
             --no-build\
             --configuration ${{ env.BUILD_CONFIGURATION }}
+          dotnet run --project ./tests/Allure.Xunit.Tests\
+            --no-restore\
+            --no-build\
+            --configuration ${{ env.BUILD_CONFIGURATION }}
           dotnet test ./tests/Allure.SpecFlow.Tests\
             --no-restore\
             --no-build\

allure-csharp.slnx

@@ -86,6 +86,9 @@
     <Project Path="tests/Allure.Testing/Allure.Testing.csproj">
       <Build Solution="Publish|*" Project="false" />
     </Project>
+    <Project Path="tests/Allure.Xunit.Tests/Allure.Xunit.Tests.csproj">
+      <Build Solution="Publish|*" Project="false" />
+    </Project>
   </Folder>
   <Folder Name="/Solution Items/">
     <File Path=".gitignore" />

src/Allure.NUnit/Core/AllureNUnitHelper.cs

@@ -4,9 +4,10 @@
 using System.Linq;
 using System.Text;
 using Allure.Net.Commons;
+using Allure.Net.Commons.Attributes;
 using Allure.Net.Commons.Functions;
+using Allure.Net.Commons.Sdk;
 using Allure.Net.Commons.TestPlan;
-using Allure.NUnit.Attributes;
 using NUnit.Framework;
 using NUnit.Framework.Interfaces;
 using NUnit.Framework.Internal;
@@ -120,7 +121,8 @@ internal static TestResult CreateTestResult(ITest test)
                     ..ModelFunctions.EnumerateGlobalLabels(),
                 ]
             };
-            UpdateTestDataFromAllureAttributes(test, testResult);
+            ApplyLegacyAllureAttributes(test, testResult);
+            ApplyAllureAttributes(test, testResult);
             AddTestParametersFromNUnit(test, testResult);
             SetIdentifiers(test, testResult);
             return testResult;
@@ -262,40 +264,37 @@ static void SetLegacyIdentifiers(ITest test, TestResult testResult)
 
         static void AddTestParametersFromNUnit(ITest test, TestResult testResult)
         {
-            var arguments = CollectNUnitArguments(test);
+            var parameters = test.Method.MethodInfo.GetParameters();
+            var arguments = test.Arguments;
             var formatters = AllureLifecycle.TypeFormatters;
-            foreach (var (name, value) in arguments)
-            {
-                testResult.parameters.Add(new()
-                {
-                    name = name,
-                    value = FormatFunctions.Format(value, formatters)
-                });
-            }
+
+            testResult.parameters.AddRange(
+                ModelFunctions.CreateParameters(parameters, arguments, formatters)
+            );
         }
 
-        static IEnumerable<(string, object)> CollectNUnitArguments(ITest test) =>
-            test.Method.MethodInfo.GetParameters()
-                .Select(p => p.Name)
-                .Zip(
-                    test.Arguments,
-                    (n, v) => (n, v)
-                );
+        static void ApplyAllureAttributes(ITest test, TestResult testResult)
+        {
+            var testFixtureClass = GetTestFixture(test).TypeInfo.Type;
+
+            AllureApiAttribute.ApplyTypeAttributes(testFixtureClass, testResult);
+            AllureApiAttribute.ApplyMethodAttributes(test.Method.MethodInfo, testResult);
+        }
 
-        static void UpdateTestDataFromAllureAttributes(ITest test, TestResult testResult)
+        static void ApplyLegacyAllureAttributes(ITest test, TestResult testResult)
         {
             foreach (var attribute in IterateAllAllureAttribites(test))
             {
                 attribute.UpdateTestResult(testResult);
             }
         }
 
-        static IEnumerable<AllureTestCaseAttribute> IterateAllAllureAttribites(ITest test) =>
+        static IEnumerable<Attributes.AllureTestCaseAttribute> IterateAllAllureAttribites(ITest test) =>
             test.Method
-                .GetCustomAttributes<AllureTestCaseAttribute>(true)
+                .GetCustomAttributes<Attributes.AllureTestCaseAttribute>(true)
                 .Concat(
                     GetTestFixture(test)
-                        .GetCustomAttributes<AllureTestCaseAttribute>(true)
+                        .GetCustomAttributes<Attributes.AllureTestCaseAttribute>(true)
                 );
 
         static string GetNamespace(string classFullName)
@@ -309,6 +308,14 @@ static string GetNamespace(string classFullName)
                 );
         }
 
+        static string ResolveSubSuite(TestFixture testFixture)
+            => AllureApiAttribute
+                .GetTypeAttributes(testFixture.TypeInfo.Type)
+                .OfType<AllureNameAttribute>()
+                .LastOrDefault()
+                ?.Name
+                ?? GetClassName(testFixture.FullName);
+
         static string GetClassName(string classFullName)
         {
             var lastDotIndex = StripTypeArgs(classFullName)?.LastIndexOf('.') ?? -1;
@@ -349,39 +356,66 @@ static TestFixture GetTestFixture(ITest test)
 
         internal static void ApplyDefaultSuiteHierarchy(ITest test)
         {
-            var testClassFullName = GetTestFixture(test).FullName;
+            var testFixture = GetTestFixture(test);
+            var testClassFullName = testFixture.FullName;
             var assemblyName = test.TypeInfo?.Assembly?.GetName().Name;
             var @namespace = GetNamespace(testClassFullName);
-            var className = GetClassName(testClassFullName);
+            var subSuite = ResolveSubSuite(testFixture);
 
             AllureLifecycle.UpdateTestCase(
                 testResult => ModelFunctions.EnsureSuites(
                     testResult,
                     assemblyName,
                     @namespace,
-                    className
+                    subSuite
                 )
             );
         }
 
         private void UpdateTestDataFromNUnitProperties()
         {
-            foreach (var p in GetTestProperties(PropertyNames.Description))
+            this.ApplyNUnitDescriptions();
+            this.ApplyNUnitAuthors();
+            this.ApplyNUnitCategories();
+        }
+
+        void ApplyNUnitDescriptions()
+        {
+            bool hasDescription = false;
+            AllureLifecycle.UpdateTestCase((tr) =>
             {
-                AllureLifecycle.UpdateTestCase(x => x.description += $"{p}\n"
-                );
+                hasDescription = tr.description is not null || tr.descriptionHtml is not null;
+            });
+
+            if (hasDescription)
+            {
+                // If a description is provided via the Allure API,
+                // NUnit descriptions are ignored.
+                return;
             }
 
-            foreach (var p in GetTestProperties(PropertyNames.Author))
+            foreach (var p in EnumerateTestProperties(PropertyNames.Description))
             {
-                AllureLifecycle.UpdateTestCase(x => x.labels.Add(Label.Owner(p))
-                );
+                AllureLifecycle.UpdateTestCase(x =>
+                    x.description = string.IsNullOrEmpty(x.description)
+                        ? p
+                        : $"{x.description}\n\n{p}");
             }
+        }
 
-            foreach (var p in GetTestProperties(PropertyNames.Category))
+        void ApplyNUnitAuthors()
+        {
+            foreach (var p in EnumerateTestProperties(PropertyNames.Author))
             {
-                AllureLifecycle.UpdateTestCase(x => x.labels.Add(Label.Tag(p))
-                );
+                AllureLifecycle.UpdateTestCase(x => x.labels.Add(Label.Owner(p)));
+            }
+        }
+
+        void ApplyNUnitCategories()
+        {
+            foreach (var p in EnumerateTestProperties(PropertyNames.Category))
+            {
+                AllureLifecycle.UpdateTestCase(x => x.labels.Add(Label.Tag(p)));
             }
         }
 
@@ -402,30 +436,32 @@ private void AddConsoleOutputAttachment()
             }
         }
 
-        private IEnumerable<string> GetTestProperties(string name)
+        IEnumerable<string> EnumerateTestProperties(string name)
         {
-            var list = new List<string>();
-            var currentTest = _test;
-            while (currentTest.GetType() != typeof(TestSuite)
-                   && currentTest.GetType() != typeof(TestAssembly))
+            var propertyContainers = EnumeratePropertyContainers().Reverse();
+            foreach (var obj in propertyContainers)
             {
-                if (currentTest.Properties.ContainsKey(name))
+                if (obj.Properties.ContainsKey(name))
                 {
-                    if (currentTest.Properties[name].Count > 0)
+                    for (var i = 0; i < obj.Properties[name].Count; i++)
                     {
-                        for (var i = 0; i < currentTest.Properties[name].Count; i++)
-                        {
-                            list.Add(
-                                currentTest.Properties[name][i].ToString()
-                            );
-                        }
+                        yield return obj.Properties[name][i].ToString();
                     }
                 }
+            }
+        }
 
-                currentTest = currentTest.Parent;
+        IEnumerable<ITest> EnumeratePropertyContainers()
+        {
+            for (var test = this._test; ShouldContinue(test); test = test.Parent)
+            {
+                yield return test;
             }
 
-            return list;
+            static bool ShouldContinue(ITest test)
+                => test is not null
+                    && test.GetType() != typeof(TestSuite)
+                    && test.GetType() != typeof(TestAssembly);
         }
 
         private string ContainerId => $"tc-{_test.Id}";

src/Allure.NUnit/README.md

@@ -32,7 +32,155 @@ Some examples are available [here](https://github.com/allure-framework/allure-cs
 
 ## Notes
 
-### Namespace changed to Allure.NUnit
+### New in 2.15.0: the common Attribute API
+
+Use the attributes in `Allure.Net.Commons.Attributes` instead of `Allure.NUnit.Attributes`. Read more details [here](https://github.com/allure-framework/allure-csharp/pull/647).
+
+In most cases, the migration is as simple as swapping the using directive:
+
+```diff
+- using Allure.NUnit.Attributes;
++ using Allure.Net.Commons.Attributes;
+using Allure.NUnit;
+using NUnit.Framework;
+
+[AllureFeature("My feature")]
+class MyTestClass
+{
+    [AllureStory("My story")]
+    [Test]
+    public void MyTestMethod()
+    {
+
+    }
+}
+```
+
+In some cases, the usage must be updated. They are listed below.
+
+#### `[AllureDescription]`
+
+Set `Append` to keep the concatenation behavior:
+
+```diff
+- using Allure.NUnit.Attributes;
++ using Allure.Net.Commons.Attributes;
+using NUnit.Framework;
+
+-[AllureDescription("First description")]
++[AllureDescription("First description", Append = true)]
+class MyTestClass
+{
+-    [AllureDescription("Second description")]
++    [AllureDescription("Second description", Append = true)]
+    [Test]
+    public void MyTestMethod()
+    {
+
+    }
+}
+```
+
+Use `[AllureDescriptionHtml]` instead of setting `Html`:
+
+```diff
+- using Allure.NUnit.Attributes;
++ using Allure.Net.Commons.Attributes;
+using NUnit.Framework;
+
+class MyTestClass
+{
+-    [AllureDescription("<p>Html text</p>", Html = true)]
++    [AllureDescriptionHtml("<p>Html text</p>")]
+    [Test]
+    public void MyTestMethod()
+    {
+    }
+}
+```
+
+#### `[AllureFeature]`, `[AllureStory]` with multiple values
+
+Use multiple `[AllureFeature]` or `[AllureStory]` attributes instead:
+
+```diff
+- using Allure.NUnit.Attributes;
++ using Allure.Net.Commons.Attributes;
+
+-[AllureFeature("Feature 1", "Feature 2")]
++[AllureFeature("Feature 1")]
++[AllureFeature("Feature 2")]
+-[AllureStory("Story 1", "Story 2")]
++[AllureStory("Story 1")]
++[AllureStory("Story 2")]
+class MyTestClass
+{
+}
+```
+
+#### `[AllureLink]`, `[AllureIssue]`, `[AllureTms]`
+
+Pass the URL or ID as the only positional argument. Use the `Title` property to pass the display
+text. Also, use `[AllureTmsItem]` instead of `[AllureTms]`:
+
+```diff
+- using Allure.NUnit.Attributes;
++ using Allure.Net.Commons.Attributes;
+
+-[AllureLink("Homepage", "https://allurereport.org")]
++[AllureLink("https://allurereport.org", Title = "Homepage")]
+-[AllureIssue("ISSUE-123", "123")]
++[AllureIssue("123", Title = "ISSUE-123")]
+-[AllureTms("TMS-345", "345")]
++[AllureTmsItem("345", Title = "TMS-345")]
+class MyTestClass
+{
+}
+```
+
+#### `[AllureSeverity]`
+
+Always pass an explicit value as the argument:
+
+```diff
+- using Allure.NUnit.Attributes;
++ using Allure.Net.Commons.Attributes;
+
+-[AllureSeverity]
++[AllureSeverity(SeverityLevel.normal)]
+class MyTestClass
+{
+}
+```
+
+#### `[Name]` and `[Skip]`
+
+Use `[AllureParameter]` with `Name` and `Ignore` correspondingly:
+
+```diff
+- using Allure.NUnit.Attributes;
++ using Allure.Net.Commons.Attributes;
+
+class MyTestClass
+{
+    [AllureStep]
+    public void MyStepMethod(
+-        [Name("Foo")] int parameter1,
++        [AllureParameter(Name = "Foo")] int parameter1,
+-        [Skip] int parameter2
++        [AllureParameter(Ignore = true)] int parameter2
+    )
+    {
+    }
+}
+```
+
+#### Deprecation notice
+
+Attributes from the `Allure.NUnit.Attributes` namespace will be deprecated in one of the future
+releases. Please, migrate to `Allure.Net.Commons.Attributes`.
+
+### New in 2.12.0: Namespace changed to Allure.NUnit
 
 Starting from 2.12.0, the namespace `NUnit.Allure` is deprecated. The API in
 that namespace still works, but it will be removed in the future. Please use