Retry

This feature requires the Microsoft.Testing.Extensions.Retry NuGet package.

Tip

When using Microsoft.Testing.Platform.MSBuild (included transitively by MSTest, NUnit, and xUnit runners), this extension is auto-registered when you install its NuGet package — no code changes needed. The manual registration in the following section is only required if you disabled the auto-generated entry point by setting <GenerateTestingPlatformEntryPoint>false</GenerateTestingPlatformEntryPoint>.

Manual registration

var builder = await TestApplication.CreateBuilderAsync(args);
builder.AddRetryProvider();

Retry

A .NET test resilience and transient-fault-handling extension.

This extension is intended for integration tests where the test depends heavily on the state of the environment and could experience transient faults.

Note

The package is shipped with the restrictive Microsoft.Testing.Platform Tools license. The full license is available at https://www.nuget.org/packages/Microsoft.Testing.Extensions.Retry/1.0.0/License.

Options

Option	Description
--retry-failed-tests	Reruns any failed tests until they pass or until the maximum number of attempts is reached. Required to activate the extension.
--retry-failed-tests-max-percentage	Avoids rerunning tests when the percentage of failed test cases crosses the specified threshold. Can't be combined with --retry-failed-tests-max-tests. Requires --retry-failed-tests.
--retry-failed-tests-max-tests	Avoids rerunning tests when the number of failed test cases crosses the specified limit. Can't be combined with --retry-failed-tests-max-percentage. Requires --retry-failed-tests.
--retry-failed-tests-delay	Adds a delay between retries. The delay is expressed as a time value, for example 200, 500ms, 1s, 2.5m, 1h, or 1d. Default unit is milliseconds. Requires --retry-failed-tests. Available in MTP starting with version 2.3.0.

Both threshold options (--retry-failed-tests-max-percentage and --retry-failed-tests-max-tests) require --retry-failed-tests to also be set.

Starting with MTP 2.4.0, the retry summary reports separate flaky and retried counts and lists recovered test names under Flaky tests. To avoid misleading totals, MTP doesn't print a full-suite summary for filtered retry attempts after the first attempt. Use the terminal reporter's --show-flaky-tests option to show or hide flaky details.

Each retry attempt writes its report artifacts under the Retries directory. For JUnit, the top-level report represents only the final filtered retry attempt, not the original full suite; collect the earlier attempt reports from Retries when your CI requires complete coverage. This layout applies to --retry-failed-tests. MSTest's in-process [Retry] instead collapses superseded attempts into one final JUnit or TRX result per test.

Examples

Retry failed tests up to 3 times:

dotnet run --project Contoso.MyTests -- --retry-failed-tests 3

Retry failed tests up to 2 times, but stop retrying if more than 50% of tests failed:

dotnet run --project Contoso.MyTests -- --retry-failed-tests 2 --retry-failed-tests-max-percentage 50

Retry failed tests up to 3 times, but stop retrying if more than 10 tests failed:

dotnet run --project Contoso.MyTests -- --retry-failed-tests 3 --retry-failed-tests-max-tests 10

Limitations

• Not supported on browser platforms.
• Not supported in hot reload mode.