Allure xUnit.net reference

These are the attributes and methods that you can use to integrate your xUnit.net tests with Allure Report.

In most cases, Allure xUnit.net provides two different ways to use a feature: the Attributes API and the Runtime API.

• Attributes API: add a C# attribute to a test method or a whole class to add certain data to the test result. When using this approach, the data is guaranteed to be added regardless of how the test itself runs.

• Runtime API: use Allure's functions to add certain data to the test result during its execution. This approach allows for constructing the data dynamically.

  Note that it is recommended to call the Allure's functions as close to the beginning of the test as possible. This way, the data will be added even if the test fails early.

Metadata

Assign a test's description, links and other metadata.

Title

• [AllureName(string name)]
• AllureApi.SetTestName(string name)

Set the test's title.

Unlike most of the functions described here, the DisplayName argument is a part of xUnit.net itself.

If you need to construct a test's title dynamically, write a lambda function that does that and pass it to the updateTestCase() method of the AllureLifecycle object, see the example below.

C#
using Xunit;

public class TestLabels
{
    [Fact(DisplayName = "Create labels")]
    public void TestCreateLabel()
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestCreateLabel()
    {
        AllureApi.SetTestName("Create labels");
        // ...
    }
}

Description

• [AllureDescription(string description)]
• AllureApi.SetDescription(string description)

Set the test's description. Markdown formatting is allowed. Any HTML formatting, if present, will be stripped for security purposes.

C#
using Allure.Xunit.Attributes;
using Xunit;

public class TestLabels
{
    [Fact]
    [AllureDescription("This test attempts to create a label with specified title")]
    public void TestCreateLabel()
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestCreateLabel()
    {
        AllureApi.SetDescription("This test attempts to create a label with specified title");
        // ...
    }
}

Owner

• [AllureOwner(string value)]
• AllureApi.SetOwner(string owner)

Set the test's owner.

C#
using Allure.Xunit.Attributes;
using Xunit;

public class TestLabels
{
    [Fact]
    [AllureOwner("John Doe")]
    public void TestCreateLabel()
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestCreateLabel()
    {
        AllureApi.SetOwner("John Doe");
        // ...
    }
}

Tag

• [AllureTag(params string[] tags)]
• AllureApi.AddTags(params string[] tags)

Set the test's tags.

C#
using Allure.Xunit.Attributes;
using Xunit;

public class TestLabels
{
    [Fact]
    [AllureTag("UI", "Labels")]
    public void TestCreateLabel()
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestCreateLabel()
    {
        AllureApi.AddTags("UI", "Labels");
        // ...
    }
}

Severity

• [AllureSeverity(SeverityLevel value)]
• AllureApi.SetSeverity(SeverityLevel severity)

Set the test's severity.

C#
using Allure.Net.Commons;
using Allure.Xunit.Attributes;
using Xunit;

public class TestLabels
{
    [Fact]
    [AllureSeverity(SeverityLevel.critical)]
    public void TestCreateLabel()
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestCreateLabel()
    {
        AllureApi.SetSeverity(SeverityLevel.critical);
        // ...
    }
}

Label

• [AllureLabel(string label, string value, bool overwrite=false)]
• AllureApi.AddLabel(string name, string value)
• AllureApi.AddLabel(Label label)
• AllureApi.AddLabels(params Label[] labels)

Set an arbitrary label for the test. This is the underlying implementation for a lot of Allure's other APIs.

C#
using Allure.Xunit.Attributes;
using Xunit;

public class TestLabels
{
    [Fact]
    [AllureLabel("MyCustomLabel", "value")]
    public void TestCreateLabel()
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestCreateLabel()
    {
        AllureApi.AddLabel("MyCustomLabel", "value");
        // ...
    }
}

ID

• [AllureId(string value)]

Set the test's ID.

C#
using Allure.Xunit.Attributes;
using Xunit;

public class TestLabels
{
    [Fact]
    [AllureId("123")]
    public void TestCreateLabel()
    {
        // ...
    }
}

Link

• [AllureLink(string name, string url)]
• [AllureIssue(string name)]
• [AllureIssue(string name, string url)]
• [AllureTms(string name)]
• [AllureTms(string name, string url)]
• AllureApi.AddLink(string url)
• AllureApi.AddLink(string name, string url)
• AllureApi.AddLink(string name, string type, string url)
• AllureApi.AddLinks(params Link[] links)
• AllureApi.AddIssue(string url)
• AllureApi.AddIssue(string name, string url)
• AllureApi.AddTmsItem(string url)
• AllureApi.AddTmsItem(string name, string url)

Add a link related to the test.

Based on the type (which can be any string), Allure will try to load a corresponding link pattern to process the URL, as defined by the links configuration option. If no pattern found for the given type, the URL is left unmodified.

The name will be used as the link's text. If it is omitted, the unprocessed URL will be used instead.

For convenience, Allure provides shorthand attributes and methods with pre-selected link types: issue and tms.

C#
using Allure.Xunit.Attributes;
using Xunit;

public class TestLabels
{
    [Fact]
    [AllureLink("Website", "https://dev.example.com/")]
    [AllureIssue("UI-123")]
    [AllureTms("TMS-456")]
    public void TestCreateLabel()
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestCreateLabel()
    {
        AllureApi.AddLink("Website", "https://dev.example.com/");
        AllureApi.AddIssue("UI-123");
        AllureApi.AddTmsItem("TMS-456");
        // ...
    }
}

Behavior-based hierarchy

• [AllureEpic(string epic)]
• [AllureFeature(params string[] feature)]
• [AllureStory(params string[] story)]
• AllureApi.AddEpic(string epic)
• AllureApi.AddFeature(string feature)
• AllureApi.AddStory(string story)

Assign names of epics, features or user stories for a test, as part of Allure's behavior-based hierarchy.

C#
using Allure.Xunit.Attributes;
using Xunit;

[AllureEpic("Web interface")]
[AllureFeature("Essential features")]
public class TestLabels
{
    [Fact]
    [AllureStory("Labels")]
    public void TestCreateLabel()
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestCreateLabel()
    {
        AllureApi.AddEpic("Web interface");
        AllureApi.AddFeature("Essential features");
        AllureApi.AddStory("Labels");
        // ...
    }
}

Suite-based hierarchy

• [AllureParentSuite(string parentSuite)]
• [AllureSuite(string suite)]
• [AllureSubSuite(string subSuite)]
• AllureApi.AddParentSuite(string parentSuite)
• AllureApi.AddSuite(string suite)
• AllureApi.AddSubSuite(string subSuite)

Assign the name of suite, as part of Allure's suite-based hierarchy.

C#
using Allure.Xunit.Attributes;
using Xunit;

[AllureParentSuite("Web interface")]
[AllureSuite("Essential features")]
public class TestLabels
{
    [Fact]
    [AllureSubSuite("Labels")]
    public void TestCreateLabel()
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestCreateLabel()
    {
        AllureApi.AddParentSuite("Web interface");
        AllureApi.AddSuite("Essential features");
        AllureApi.AddSubSuite("Labels");
        // ...
    }
}

Test steps

• [AllureStep]
• [AllureStep(string name)]
• AllureApi.Step(string name)
• AllureApi.Step(string name, Action acti
• T AllureApi.Step<T>(string name, Func<T> function)
• async Task AllureApi.Step(string name, Func<Task> action)
• async Task<T> AllureApi.Step<T>(string name, Func<Task<T>> function)

Define test steps.

There are three ways of defining a step.

• Attribute-based steps

  Define a method containing a test step and add the [AllureStep] attribute to it, with an optional name argument (defaults to the function's name). Each time the function is called during the test execution, a new step will be created for the test report. If the function calls another function that also has the [AllureStep] attribute, Allure Report will create a sub-step inside the current step.

  If the step name contains placeholders (e.g., {url} or {0}), they will be replaced with the values of parameters passed to the function.

  Arguments passed to the function will be added to the list of step parameters. They are rendered the same way as described in Parametrized tests, but displayed in the current step's subtree in the report. Use the [Name(string name)] attribute to customize a parameter's name, as shown in the example below. Use the [Skip] attribute to not add a certain parameter to the report.

  Use AllureLifecycle.Instance.UpdateStep() to add custom parameters to the current step, as shown in the example below.

• Lambda steps

  Write a test step in a lambda function and pass it to Step(). If the lambda function returns a value, Step() will return it without modification, and it will not affect the report.

  Use AllureLifecycle.Instance.UpdateStep() to add custom parameters to the current step, as shown in the example below.

• No-op steps

  If you call Step() with a name but without a lambda function, Allure will add to the report a no-op step. This allows for a log-style reporting within a test or within a larger step. A no-op step finishes immediately after it started and cannot have any sub-steps, parameters or attachments.

C#
using Allure.Net.Commons;
using Allure.Xunit.Attributes.Steps;
using Xunit;

public class TestMyWebsite
{
    [Fact]
    public void TestVisitPages()
    {
        TestDomain("https://domain1.example.com/");
        TestDomain("https://domain2.example.com/");
    }

    [AllureStep("Test {url}")]
    private void TestDomain([Name("Webpage URL")] string url)
    {
        AllureLifecycle.Instance.UpdateStep(stepResult =>
            stepResult.parameters.Add(
                new Parameter {
                    name = "Started at",
                    value = DateTime.Now.ToString()
                }
            )
        );
        OpenBrowser();
        GoToWebpage(url);
        CloseBrowser();
    }

    [AllureStep("Open web browser")]
    private void OpenBrowser()
    {
        // ...
    }

    [AllureStep("Visit {url}")]
    private void GoToWebpage([Skip] string url)
    {
        // ...
    }

    [AllureStep("Close web browser")]
    private void CloseBrowser()
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestMyWebsite
{
    [Fact]
    public void TestVisitPages()
    {
        string[] urls =
        {
            "https://domain1.example.com/",
            "https://domain2.example.com/"
        };

        foreach (string url in urls)
        {
            AllureApi.Step($"Test {url}", () =>
            {
                AllureLifecycle.Instance.UpdateStep(stepResult =>
                {
                    stepResult.parameters.Add(
                        new Parameter { name = "Webpage URL", value = url }
                    );
                });

                AllureApi.Step("Opening web browser...");
                // ...

                AllureApi.Step($"Visiting {url}...");
                // ...

                AllureApi.Step("Closing web browser...");
                // ...
            });
        }
    }
}

Constructors and Dispose methods

• [AllureBefore(string name = null)]
• [AllureAfter(string name = null)]

Add information about a constructor or a Dispose() method that manage a test context, see the xUnit.net's documentation.

The methods will be displayed in the test report as special kinds of steps.

C#
using Allure.Xunit.Attributes.Steps;
using Xunit;

public class TestLabels : IDisposable
{
    [AllureBefore("Setup test context")]
    public TestLabels()
    {
        // ...
    }

    [Fact]
    public void TestCreateLabel()
    {
        // ...
    }

    [AllureAfter("Clean test context")]
    public void Dispose()
    {
        // ...
    }
}

Parametrized tests

• AllureApi.AddTestParameter(string name, object? value)
• AllureApi.AddTestParameter(string name, object? value, ParameterMode mode)
• AllureApi.AddTestParameter(string name, object? value, bool excluded)
• AllureApi.AddTestParameter(string name, object? value, ParameterMode mode, bool excluded)
• AllureApi.AddTestParameter(Parameter parameter)
• AllureLifecycle.Instance.AddTypeFormatter<T>(TypeFormatter<T> typeFormatter)

To support the parametrized tests pattern, Allure Report automatically detects the parameters specified via [Theory] and other xUnit.net's attributes. In addition to this, the Runtime API can be used for adding the parameters even to functions without xUnit.net's attributes.

If the excluded argument is set to true, Allure will not use the parameter when comparing the current test result with previous one in the history. This argument is only used by Allure TestOps.

The mode argument affects how the parameter will be displayed in the report. Available options are defined in the ParameterMode enumeration:

• ParameterMode.Default (same as not specifying any mode) — the parameter and its value will be shown in a table along with other parameters.
• ParameterMode.Masked — the parameter will be shown in the table, but its value will be hidden. Use this mode for passwords, tokens and other sensitive parameters.
• ParameterMode.Hidden — the parameter and its value will not be shown in the test report. Note, however, that it is still possible to extract the value from the allure_results directory if you publish it.

By default, Allure Report will render the parameter values via a basic JSON serialization. You can override this behavior for certain types by implementing a custom class that inherits from TypeFormatter and passing an object of this class to AddTypeFormatter().

The parameters can be added not only to whole test results, but also to individual steps within them, see Test steps for more details.

C#
using Xunit;

public class TestLabels
{
    [Theory]
    [InlineData("johndoe", "qwerty")]
    [InlineData("[email protected]", "qwerty")]
    public void TestCreateLabel(string login, string password)
    {
        // ...
    }
}

C#
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestAuthenticationWithUsername()
    {
        AllureApi.AddTestParameter("login", "johndoe");
        AllureApi.AddTestParameter("password", "qwerty", ParameterMode.Masked);
        // ...
    }

    [Fact]
    public void TestAuthenticationWithEmail()
    {
        AllureApi.AddTestParameter("login", "[email protected]");
        AllureApi.AddTestParameter("password", "qwerty", ParameterMode.Masked);
        // ...
    }
}

Attachments

• AllureApi.AddAttachment(string name, string type, string path)
• AllureApi.AddAttachment(string name, string type, byte[] content, string fileExtension = "")
• AllureApi.AddAttachment(string path, string? name = null)
• AllureApi.AddScreenDiff(string expectedPng, string actualPng, string diffPng)

Add an attachment to the test result under the given name.

You can use data produced by any function, not necessarily read from an actual file.

To create an attachment using the Runtime API, call AddAttachment() at any point during your test. Pass either the content or the path from which the data will be read.

To ensure that the reader's web browser will display attachments correctly, it is recommended to specify each attachment's type. To do so, pass the MIME type of the content as type and, optionally, a filename extension as fileExtension. The MIME type affects how the data will be displayed in the test report, while the filename extension is appended to the filename when user wants to save the file.

C#
using System.IO;
using System.Text;
using Allure.Net.Commons;
using Xunit;

public class TestLabels
{
    [Fact]
    public void TestCreateLabel()
    {
        // ...
        AllureApi.AddAttachment(
            "data.txt",
            "text/plain",
            Encoding.UTF8.GetBytes("This is the file content.")
        );
        AllureApi.AddAttachment(
            "image1.png",
            "image/png",
            File.ReadAllBytes("/path/to/image1.png")
        );
        AllureApi.AddAttachment(
          "image2.png",
          "image/png",
          "/path/to/image2.png"
        );
    }
}

Allure xUnit.net also provides a dedicated AddScreenDiff() function for attaching visual comparisons.