xRetry 1.9.0

dotnet add package xRetry --version 1.9.0
NuGet\Install-Package xRetry -Version 1.9.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="xRetry" Version="1.9.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add xRetry --version 1.9.0
#r "nuget: xRetry, 1.9.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install xRetry as a Cake Addin
#addin nuget:?package=xRetry&version=1.9.0

// Install xRetry as a Cake Tool
#tool nuget:?package=xRetry&version=1.9.0

xRetry

Retry flickering test cases for xUnit.

pipeline status

When to use this

This is intended for use on flickering tests, where the reason for failure is an external dependency and the failure is transient, e.g:

  • HTTP request over the network
  • Database call that could deadlock, timeout etc...

Whenever a test includes real-world infrastructure, particularly when communicated with via the internet, there is a risk of the test randomly failing so we want to try and run it again. This is the intended use case of the library.

If you have a test that covers some flaky code, where sporadic failures are caused by a bug, this library should not be used to cover it up!

Usage: xUnit

Add the xRetry nuget package to your project.

Facts

Above any Fact test case that should be retried, replace the Fact attribute, with RetryFact, e.g:

private static int defaultNumCalls = 0;

[RetryFact]
public void Default_Reaches3()
{
    defaultNumCalls++;

    Assert.Equal(3, defaultNumCalls);
}

This will attempt to run the test until it passes, up to 3 times by default. You can optionally specify a number of times to attempt to run the test as an argument, e.g. [RetryFact(5)].

You can also optionally specify a delay between each retry (in milliseconds) as a second parameter, e.g. [RetryFact(5, 100)] will run your test up to 5 times, waiting 100ms between each attempt.

Theories

If you have used the library for retrying Fact tests, using it to retry a Theory should be very intuitive.
Above any Theory test case that should be retried, replace the Theory attribute with RetryTheory, e.g:

// testId => numCalls
private static readonly Dictionary<int, int> defaultNumCalls = new Dictionary<int, int>()
{
    { 0, 0 },
    { 1, 0 }
};

[RetryTheory]
[InlineData(0)]
[InlineData(1)]
public void Default_Reaches3(int id)
{
    defaultNumCalls[id]++;

    Assert.Equal(3, defaultNumCalls[id]);
}

The same optional arguments (max attempts and delay between each retry) are supported as for facts, and can be used in the same way.

Skipping tests at Runtime

In addition to retries, RetryFact and RetryTheory both support dynamically skipping tests at runtime. To make a test skip just use Skip.Always() within your test code.
It also supports custom exception types so you can skip a test if a type of exception gets thrown. You do this by specifying the exception type to the attribute above your test, e.g.

[RetryFact(typeof(TestException))]
public void CustomException_SkipsAtRuntime()
{
    throw new TestException();
}

This functionality also allows for skipping to work when you are already using another library for dynamically skipping tests by specifying the exception type that is used by that library to the RetryFact. e.g. if you are using the popular Xunit.SkippableFact nuget package and want to add retries, converting the test is as simple as replacing [SkippableFact] with [RetryFact(typeof(Xunit.SkipException))] above the test and you don't need to change the test itself.

Viewing retry logs

By default, you won't see whether your tests are being retried as we make this information available via the xunit diagnostic logs but test runners will hide these detailed logs by default.
To enable them you must configure your xUnit test project to have diagnosticMessages set to true in the xunit.runner.json. See the xUnit docs for a full setup guide of their config file, or see this projects own unit tests which has been set up with this enabled.

Issues

If you find a bug whilst using this library, please report it on GitHub.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net452 is compatible.  net46 was computed.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on xRetry:

Package Downloads
xRetry.SpecFlow

Allows for a @retry(n) tag to be placed above scenarios in SpecFlow.XUnit. This can be used to re-run a failed test up to n times, allowing for transient failures (e.g. network related) to be tolerated.

Xunit.DependencyInjection.xRetry

Support xRetry. public void ConfigureServices(IServiceCollection services) { services.AddXRetrySupport(); }

GitHub repositories (11)

Showing the top 5 popular GitHub repositories that depend on xRetry:

Repository Stars
microsoft/semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
ravendb/ravendb
ACID Document Database
Azure/Industrial-IoT
Azure Industrial IoT Platform
planetarium/libplanet
Blockchain in C#/.NET for on-chain, decentralized gaming
pengweiqhca/Xunit.DependencyInjection
Use Microsoft.Extensions.DependencyInjection to resolve xUnit test cases.
Version Downloads Last updated
1.9.0 1,456,887 1/1/2023
1.9.0-alpha1 1,482 12/19/2022
1.8.0 828,176 2/26/2022
1.7.0 248,257 10/30/2021
1.6.0 163,810 6/23/2021
1.5.0 100,907 5/12/2021
1.4.1 242,959 2/23/2021
1.4.0 3,463 2/16/2021
1.3.0 34,600 1/22/2021
1.2.0 12,294 11/13/2020
1.1.0 30,818 8/19/2020
1.0.0 9,697 6/27/2020
0.5.0 35,101 4/10/2020
0.5.0-alpha1 1,166 3/27/2020
0.4.1 2,348 3/26/2020
0.4.1-alpha 1,218 3/26/2020
0.4.0 2,275 3/10/2020
0.3.2 4,667 8/2/2019
0.3.1 1,867 6/24/2019
0.3.0 1,785 5/22/2019
0.2.0 1,782 5/20/2019
0.2.0-alpha01 1,517 5/20/2019
0.1.1-alpha05 395 5/20/2019
0.1.1-alpha04 422 5/20/2019
0.1.1-alpha03 404 5/20/2019
0.1.1-alpha02 416 5/12/2019
0.1.1-alpha01 424 5/12/2019
0.1.0 1,504 5/9/2019
0.1.0-alpha9 415 5/8/2019
0.1.0-alpha8 445 5/8/2019
0.1.0-alpha6 414 5/8/2019
0.1.0-alpha5 395 5/8/2019
0.1.0-alpha3 397 5/8/2019
0.1.0-alpha2 434 5/8/2019
0.1.0-alpha14 417 5/9/2019
0.1.0-alpha13 407 5/9/2019
0.1.0-alpha12 412 5/9/2019
0.1.0-alpha11 370 5/8/2019
0.1.0-alpha10 420 5/8/2019
0.1.0-alpha1 489 5/8/2019