Add Retry and Retry with RetryExceptions examples

Author: manfred-brands

docs/articles/nunit/writing-tests/attributes/retry.md

@@ -2,12 +2,16 @@
 
 RetryAttribute is used on a test method to specify that it should be rerun if it fails, up to a maximum number of times.
 
+[!code-csharp[Retry](~/snippets/Snippets.NUnit/Attributes/RetryAttributeExamples.cs#Retry)]
+
 Notes:
 
 1. The argument you specify is the total number of attempts and __not__ the number of retries after an initial failure.
    So `[Retry(1)]` does nothing and should not be used.
 2. It is not currently possible to use `RetryAttribute` on a `TestFixture` or any other type of test suite. Only single
    tests may be repeated.
-3. If a test has an unexpected exception, an error result is returned and it is not retried. Only assertion failures can
-   trigger a retry. To convert an unexpected exception into an assertion failure, see the
-   [ThrowsConstraint](xref:throwsconstraint).
+3. If a test has an unexpected exception, an error result is returned and it is not retried.
+   You can enable retry on an expected exception such as `TimeoutException` by setting the `RetryExceptions` property.
+   The value of this property is an array of anticipated exceptions that should be retried.
+
+[!code-csharp[RetryWithRetryExceptions](~/snippets/Snippets.NUnit/Attributes/RetryAttributeExamples.cs#RetryWithRetryExceptions)]

docs/snippets/Snippets.NUnit/Attributes/RetryAttributeExamples.cs

@@ -0,0 +1,69 @@
+using System.Diagnostics;
+using System.Threading.Tasks;
+using NUnit.Framework;
+
+namespace Snippets.NUnit;
+
+public class RetryAttributeExamples
+{
+    #region Retry
+    [TestFixture]
+    public sealed class RetryTests
+    {
+        private readonly Random _random = new(42);
+
+        [Test]
+        [Retry(5)]
+        public async Task OperationShouldPassIn1s()
+        {
+            var sw = Stopwatch.StartNew();
+            string result = await ExpensiveOperation();
+            sw.Stop();
+            Assert.That(sw.ElapsedMilliseconds, Is.LessThan(1000), "Operation did not complete in time");
+            Assert.That(result, Is.Not.Null);
+        }
+
+        private async Task<string> ExpensiveOperation()
+        {
+            // Simulate an expensive operation
+            int duration = _random.Next(500, 1500);
+            await Task.Delay(duration); // Simulate work
+            return "Actual Result"; // Simulate a response
+        }
+    }
+    #endregion
+
+    #region RetryWithRetryExceptions
+    [TestFixture]
+    public sealed class Retry
+    {
+        private int _delayInMilliseconds;
+
+        [OneTimeSetUp]
+        public void Setup()
+        {
+            _delayInMilliseconds = 2500;
+        }
+
+        [Test]
+        [Retry(5, RetryExceptions = [typeof(OperationCanceledException)])]
+        [CancelAfter(2000)]
+        public async Task QueryServiceAsync(CancellationToken cancellationToken)
+        {
+            string result = await CallExternalServiceAsync(cancellationToken);
+            Assert.That(result, Is.Not.Null);
+        }
+
+        private async Task<string> CallExternalServiceAsync(CancellationToken cancellationToken)
+        {
+            // Call an external service that may time out
+            int delayInMilliseconds = _delayInMilliseconds;
+            if (_delayInMilliseconds > 1000)
+                _delayInMilliseconds -= 1000; // Decrease delay for next attempt
+
+            await Task.Delay(delayInMilliseconds, cancellationToken); // Simulate a delay that may exceed
+            return "Actual Result"; // Simulate a response
+        }
+    }
+    #endregion
+}