Allure.Xunit

Allure.XUnit

Allure.XUnit is a library for display xunit tests in Allure report.

Allure.XUnit supports .NET Core 2.0 or later, and any .NET runtime compatible with .NET Standard 2.1.

How to run

Install the Allure.XUnit package and create allureConfig.json. Here is the basic content of the config:

{
    "allure": {}
}

Make sure the config is copied to the output directory:

• In Visual Studio select the file and set the following properties:
  • Build Action: Content
  • Copy to Output Directory: Always/Copy if newer OR
• In the .csproj file make sure the following entry exists:

  <ItemGroup>
      <Content Include="allureConfig.json">
          <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      </Content>
  </ItemGroup>
  

Then, run the tests as usual. In many cases allure should start automatically. The result files are created in the allure-results directory in the target directory. If that didn't happen, check out the Running tests in a CI pipeline section.

Running tests in a CI pipeline

There might be a chance another xunit reporter kicks in disabling allure. This typically happens in a CI pipeline when a pipeline-specific reporter detects the CI environment and signals xunit that it's ready to be used. Xunit's reporter pick is unreliable in such a case.

If that happens, you should explicitly tell xunit to use the allure reporter. How exactly - depends on what runner you use. For the most popular one - xunit.runner.visualstudio - you either specify it via the CLI argument:

dotnet test -- RunConfiguration.ReporterSwitch=allure

Or use a .runsettings file:

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <RunConfiguration>
    <ReporterSwitch>allure</ReporterSwitch>
  </<RunConfiguration>
</RunSettings>

Now pass the file to dotnet test:

dotnet test -s <path-to-.runsettings-file>

Or specify its path using your IDE.

By default Allure.XUnit tries to use additional environmentally enabled reporter (if any), so your tests are reported both to allure and, say, TeamCity. Due to how xunit configuration works, that behavior occures regardless of xunit's NoAutoReporters setting. If you want to disable this behavior, check out the Configuring a secondary reporter section.

Configuring a secondary reporter

Use the xunitRunnerReporter property of allureConfig.json to control an additional reporter used by Allure.XUnit:

{
    "allure": {
        "xunitRunnerReporter": "auto|none|<switch>|<AQ-classname>"
    }
}

We support the following values:

• auto - default value. Allure.XUnit uses the first environmentally enabled reporter it finds.
• none - use this value to disable an additional reporter.
• <switch> - Allure.XUnit looks for the reporter with the specified runner switch. If such reporter exists, it's used. Otherwise, the error is thrown.
• <AQ-classname> - the assembly qualified class name is used to find the reporter's class. If no such class can be found, the error is thrown.

Attributes:

The following attributes are at your disposal:

• AllureDescription
• AllureParentSuite
• AllureFeature
• AllureTag
• AllureSeverity
• AllureIssue
• AllureOwner
• AllureSuite
• AllureSubSuite
• AllureLink
• AllureEpic
• AllureLabel
• AllureId

All attributes are optional.

Attributes usage

Most of the attributes can be used both on methods and classes.

To override attribute value you can use overwrite param in attribute definition. In other case multiple values will be written in test results.

Example:

[AllureSuite("Suite A")]
public class TestClass
{
    [Fact(DisplayName = "Test Name")]
    [AllureSuite("Suite B", overwrite: true))]
    public void TestMethod
    {
    }
}

AllureXunit and AllureXunitTheory deprecation

Previously all test methods had to be marked with the AllureXunit or AllureXunitTheory attributes. There is no such need anymore. These attributes are still supported, but we advice you to use the built-in Fact and Theory attributes instead.

The AllureXunit and AllureXunitTheory attributes might be removed in future releases.

Steps

Use AllureStepAttribute, AllureBeforeAttribute, AllureAfterAttribute

See Examples.

Allure.XUnit.StepExtensions deprecation

There is no more need to use separate Allure.XUnit.StepExtensions package. You should remove it from dependencies and use attributes from Allure.XUnit.Attributes.Steps namespace directly.

using Allure.XUnit.Attributes.Steps;

...

    [AllureStep("Check that {someNumber} is the answer to life, the universe, and everything")]
    private void NestedStep([Name("number")] int someNumber, [Skip] bool skippedBoolean = true)
    {
        Assert.Equal(42, someNumber);
    }

Attachments

Use AllureAttachments class with its methods. (AttachmentAttribute coming soon)

Known issues and limitations

allureConfig.json is required even if no config properties are present

The configuration file must be present in the output directory. Allure.XUnit throws otherwise. This requirement will be lifted in the near future.

Here is the issue to track the progress: #381.

Arguments of some theories might be unreported

Under rare circumstances arguments of some theories might be missing in the report produced by allure-xunit. Issue #369 contains some additional details.

If you are affected by this, you may switch to the Debug configuration as a workaround until we come up with a solution.

Examples

See Examples.