Updated doc on repeat attribute

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

@@ -1,23 +1,25 @@
 # Repeat
 
 **RepeatAttribute** is used on a test method to specify that it should be
-executed multiple times. If any repetition fails, the remaining ones are
-not run and a failure is reported.
+executed multiple times.
 
-## Notes
+By default, the test is repeated until a failure occurs. If no failures occur, it runs for the specified number of repetitions.
 
-1. If RepeatAttribute is used on a parameterized method, each individual
-   test case created for that method is repeated.
-2. It is not currently possible to use RepeatAttribute on a TestFixture
-   or any higher level suite. Only test cases may be repeated.
+You can change this behavior in case of a failure, so that it continues to run after the failure by setting the property `StopOnFailure` to `false`.  (From version 4.3.0)
 
 ## Examples
 
-```csharp
-[Test]
-[Repeat(25)]
-public void MyTest()
-{
-    /* The contents of this test will be run 25 times. */
-}
-```
+### The default behavior
+
+[!code-csharp[RepeatDefaultAttributeExample](~/snippets/Snippets.NUnit/Attributes/RepeatAttributeExample.cs#RepeatDefaultAttributeExample)]
+
+### Run all regardless of failures
+
+[!code-csharp[RepeatWithFaultAttributeExample](~/snippets/Snippets.NUnit/Attributes/RepeatAttributeExample.cs#RepeatWithFaultAttributeExample)]
+
+> [!WARNING]
+> There is currently (as of 4.4.0) a [bug](https://github.com/nunit/nunit/issues/5031) which causes only the last successful console statement to be output.  Also, in case of failures, only the latest failure is shown.
+> [!NOTE]
+> If RepeatAttribute is used on a parameterized method,
+> each individual test case created for that method is repeated.
+> It is not currently possible to use RepeatAttribute on a TestFixture or any higher level suite. Only test cases may be repeated.

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

@@ -0,0 +1,47 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using NUnit.Framework;
+
+namespace Snippets.NUnit.Attributes;
+
+
+public class RepeatAttributeExample
+{
+    #region RepeatDefaultAttributeExample
+    [Test]
+    [Repeat(5)]
+    public void TestMethod1()
+    {
+        Assert.Pass();
+    }
+    #endregion
+
+    private int count1 = 0;
+    #region RepeatWithFaultAndOutputAttributeExample
+    [Test, Explicit("Issue 5031 must be fixed")]
+    [Repeat(5, StopOnFailure = false)]
+    public void TestMethod2()
+    {
+
+        TestContext.Out.WriteLine(count1);
+        count1++;
+        Assert.That(count1, Is.Not.EqualTo(3).And.Not.EqualTo(4));
+    }
+    #endregion
+
+    #region RepeatWithFaultAttributeExample
+
+    private int count2 = 0;
+
+    [Test,Explicit]  // Marking the test as Explicit to avoid failing our doc build. You can skip this.
+    [Repeat(5, StopOnFailure = false)]
+    public void TestMethod3()
+    {
+        count2++;
+        Assert.That(count2, Is.Not.EqualTo(3)); // Intentional failure on 3rd iteration
+    }
+    #endregion
+}