diff --git a/docs/ciBadge.md b/docs/ciBadge.md index a98713c..58984b7 100644 --- a/docs/ciBadge.md +++ b/docs/ciBadge.md @@ -1 +1,3 @@ -[![pipeline status](https://github.com/JoshKeegan/xRetry/actions/workflows/cicd.yaml/badge.svg)](https://github.com/JoshKeegan/xRetry/actions) \ No newline at end of file +[![pipeline status](https://github.com/JoshKeegan/xRetry/actions/workflows/cicd.yaml/badge.svg)](https://github.com/JoshKeegan/xRetry/actions) +[![xRetry NuGet package](https://buildstats.info/nuget/xRetry)](https://www.nuget.org/packages/xRetry "Download xRetry from NuGet") +[![xRetry.SpecFlow NuGet package](https://buildstats.info/nuget/xRetry.SpecFlow?includePreReleases=true)](https://www.nuget.org/packages/xRetry.SpecFlow "Download xRetry.SpecFlow from NuGet") diff --git a/docs/contributing.md b/docs/contributing.md index 545ecc4..157fc7a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,17 +1,24 @@ ## Contributing + Feel free to open a pull request! If you want to start any sizeable chunk of work, consider opening an issue first to discuss, and make sure nobody else is working on the same problem. ### Developing locally + #### In an IDE + To build and run locally, always build `xRetry.SpecFlowPlugin` with the Release profile before the tests to ensure MSBuild uses the latest version of your changes when building the UnitTests project. #### From the terminal -If you install `make` and go to the `build` directory, you can run the following command to run CI locally (run lint, build, run tests and create the nuget packages): + +If you install `make` and go to the `build` directory, you can run the following command to run CI locally (run lint, build, run tests and create the NuGet packages): + ```bash make ci ``` + If that works, all is well! ### Code formatting -Code formatting rules followed for xRetry are fairly standard for C# and are enforced during CI via `dotnet format`. You can see any non-standard rules in the [.editorconfig](.editorconfig) file. If you find your build fails due to this lint check, you can fix all formatting issues by running the `dotnet format` command from the root of the project. \ No newline at end of file + +Code formatting rules followed for xRetry are fairly standard for C# and are enforced during CI via `dotnet format`. You can see any non-standard rules in the [.editorconfig](.editorconfig) file. If you find your build fails due to this lint check, you can fix all formatting issues by running the `dotnet format` command from the root of the project. diff --git a/docs/repo/header.md b/docs/repo/header.md index 9c1751f..e39ad29 100644 --- a/docs/repo/header.md +++ b/docs/repo/header.md @@ -1,2 +1,3 @@ # xRetry -Retry flickering test cases for xUnit and SpecFlow in dotnet. \ No newline at end of file + +Retry flickering test cases for xUnit and SpecFlow in .NET. diff --git a/docs/xRetry.SpecFlow/usage.md b/docs/xRetry.SpecFlow/usage.md index 0c853fd..e9c50ea 100644 --- a/docs/xRetry.SpecFlow/usage.md +++ b/docs/xRetry.SpecFlow/usage.md @@ -1,25 +1,30 @@ ## Usage: SpecFlow 3 -Add the `xRetry.SpecFlow` nuget package to your project. + +Add the [`xRetry.SpecFlow` NuGet package](https://www.nuget.org/packages/xRetry.SpecFlow "xRetry NuGet.SpecFlow package") to your project. ### Scenarios (and outlines) + Above any scenario or scenario outline that should be retried, add a `@retry` tag, e.g: + ```gherkin @retry Scenario: Retry three times by default When I increment the default retry count Then the default result should be 3 ``` + 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 in brackets, e.g. `@retry(5)`. -You can also optionally specify a delay between each retry (in milliseconds) as a second +You can also optionally specify a delay between each retry (in milliseconds) as a second parameter, e.g. `@retry(5,100)` will run your test up to 5 times, waiting 100ms between each attempt. Note that you must not include a space between the parameters, as Cucumber/SpecFlow uses a space to separate tags, i.e. `@retry(5, 100)` would not work due to the space after the comma. - ### Features + You can also make every test in a feature retryable by adding the `@retry` tag to the feature, e.g: + ```gherkin @retry Feature: Retryable Feature @@ -28,7 +33,8 @@ Scenario: Retry scenario three times by default When I increment the retry count Then the result should be 3 ``` + All options that can be used against an individual scenario can also be applied like this at the feature level. If a `@retry` tag exists on both the feature and a scenario within that feature, the tag on the scenario will take -precedent over the one on the feature. This is useful if you wanted all scenarios in a feature to be retried -by default but for some cases also wanted to wait some time before each retry attempt. You can also use this to prevent a specific scenario not be retried, even though it is within a feature with a `@retry` tag, by adding `@retry(1)` to the scenario. \ No newline at end of file +precedent over the one on the feature. This is useful if you wanted all scenarios in a feature to be retried +by default but for some cases also wanted to wait some time before each retry attempt. You can also use this to prevent a specific scenario not be retried, even though it is within a feature with a `@retry` tag, by adding `@retry(1)` to the scenario. diff --git a/docs/xRetry/usage.md b/docs/xRetry/usage.md index bff9a1e..d15108b 100644 --- a/docs/xRetry/usage.md +++ b/docs/xRetry/usage.md @@ -1,10 +1,15 @@ ## Usage: xUnit -Add the `xRetry` nuget package to your project. + +Add the [`xRetry` NuGet package](https://www.nuget.org/packages/xRetry "xRetry NuGet package") to your project. ### Facts -Above any `Fact` test case that should be retried, replace the `Fact` attribute, with + +Above any `Fact` test case that should be retried, replace the `Fact` attribute, with `RetryFact`, e.g: + ```cs +using xRetry; + private static int defaultNumCalls = 0; [RetryFact] @@ -14,18 +19,19 @@ public void Default_Reaches3() Assert.Equal(3, defaultNumCalls); } - ``` -This will attempt to run the test until it passes, up to 3 times by default. + +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 +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: + ```cs // testId => numCalls private static readonly Dictionary defaultNumCalls = new Dictionary() @@ -44,13 +50,16 @@ public void Default_Reaches3(int 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 +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. + ```cs [RetryFact(typeof(TestException))] public void CustomException_SkipsAtRuntime() @@ -58,6 +67,7 @@ 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. \ No newline at end of file +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.