Merge pull request #959 from nunit/958_EnterMultipleScope

Add documentation for EnterMultipleScope

docs/articles/nunit/writing-tests/assertions/multiple-asserts.md

@@ -10,43 +10,51 @@ object initialization and UI appearance as well as certain kinds of integration
 
 ## Syntax / Example
 
-Multiple asserts are implemented using the `Assert.Multiple` method.
+Multiple asserts are implemented using the `Assert.EnterMultipleScope` method.
 
 Let's assume we have production code that looks like the following:
 
 [!code-csharp[MultipleAssertsProdCode](~/snippets/Snippets.NUnit/MultipleAsserts.cs#MultipleAssertsProdCode)]
 
 In that case, we could write a test with multiple assertions, such as:
 
-[!code-csharp[MultipleAssertsTests](~/snippets/Snippets.NUnit/MultipleAsserts.cs#MultipleAssertsTests)]
+[!code-csharp[MultipleAssertsScopes](~/snippets/Snippets.NUnit/MultipleAsserts.cs#MultipleAssertsScopes)]
 
 Functionally, this results in NUnit storing any failures encountered in the block and reporting all of them together
 upon exit from the block. If both asserts failed, then both would be reported. The test itself would terminate at the
 end of the block if any failures were encountered, but would continue otherwise.
 
+### Older NUnit versions
+
+Earlier than  NUnit 4.2 you can must  use  `Assert.Multiple`:
+
+[!code-csharp[MultipleAssertsTests](~/snippets/Snippets.NUnit/MultipleAsserts.cs#MultipleAssertsTests)]
+
 ## Notes
 
-1. The multiple assert block may contain any arbitrary code, not just asserts.
+1. For more information on `EnterMultipleScope` see this [Feature Request](https://github.com/nunit/nunit/issues/4587).
+
+2. The multiple assert block may contain any arbitrary code, not just asserts.
 
-2. Multiple assert blocks may be nested. Failure is not reported until the  outermost block exits.
+3. Multiple assert blocks may be nested. Failure is not reported until the outermost block exits.
 
-3. If the code in the block calls a method, that method may also contain multiple assert blocks.
+4. If the code in the block calls a method, that method may also contain multiple assert blocks.
 
-4. The test will be terminated immediately if any exception is thrown that is not handled. An unexpected exception is
+5. The test will be terminated immediately if any exception is thrown that is not handled. An unexpected exception is
    often an indication that the test itself is in error, so it must be terminated. If the exception occurs after one or
    more assertion failures have been recorded, those failures will be reported along with the terminating exception
    itself.
 
-5. Assert.Fail is handled just as any other assert failure. The message and stack trace are recorded but the test
+6. Assert.Fail is handled just as any other assert failure. The message and stack trace are recorded but the test
    continues to execute until the end of the block.
 
-6. An error is reported if any of the following are used inside a multiple assert block:
+7. An error is reported if any of the following are used inside a multiple assert block:
    * Assert.Pass
    * Assert.Ignore
    * Assert.Inconclusive
    * Assume.That
 
-7. Use of Warnings (Assert.Warn, Warn.If, Warn.Unless) is permitted inside a multiple assert block. Warnings are
+8. Use of Warnings (Assert.Warn, Warn.If, Warn.Unless) is permitted inside a multiple assert block. Warnings are
    reported normally along with any failures that occur inside the block.
 
 ### Runner Support

docs/snippets/Snippets.NUnit/MultipleAsserts.cs

@@ -48,4 +48,26 @@ public void MultipleAssertsDemo()
         });
     }
     #endregion
+
+    #region MultipleAssertsScopes
+    [Test]
+    public void MultipleAssertsScopeDemo()
+    {
+        var situationUnderTest = new SomeCalculator();
+        var result = situationUnderTest.DoCalculation();
+
+        using (Assert.EnterMultipleScope())
+        {
+            Assert.That(result.RealPart, Is.EqualTo(5.2));
+            Assert.That(result.ImaginaryPart, Is.EqualTo(3.9));
+        }
+
+        // Can also work with the classic assertion syntax
+        using (Assert.EnterMultipleScope())
+        {
+            ClassicAssert.AreEqual(5.2, result.RealPart, "Real Part");
+            ClassicAssert.AreEqual(3.9, result.ImaginaryPart, "Imaginary Part");
+        }
+    }
+    #endregion
 }