Merge pull request #1069 from nunit/testcaseupdates

Updated testcase documentation

Author: OsirisTerje

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

@@ -42,6 +42,43 @@ TestCaseAttribute supports a number of additional named parameters:
   but may serve a purpose for the test author)
 * **TypeArgs** specifies the `Type`s to be used when targeting a generic test method. (_NUnit 4.1+_)
 
+## Be aware of mixing the syntax for named parameters and attributes with the same name
+
+### Correct `Ignore` Attribute Usage, by Example
+
+> [!WARNING]
+> When using the `Ignore` parameter (and others, see below), note that this has to be a named parameter. It is easy to accidentally add another `Ignore` attribute after the `TestCase` attribute. That will be the same as adding it separately, and it will apply to the complete fixture. This may apply to other named parameters, with names equal to other attributes, like the `Explicit` and `Category` parameters.
+
+Correct example usage:
+
+[!code-csharp[TestCaseWithIgnore](~/snippets/Snippets.NUnit/Attributes/TestCaseAttributeExamples.cs#TestCaseWithIgnore)]
+
+![TestCaseIgnoreDoneCorrect](../../../../images/TestCaseIgnoreDoneCorrect.png)
+
+> [!WARNING]
+> **Wrong way!** Below, we demonstrate an incorrect approach.
+>
+> (1) Adding it on the same line is the same as adding it on a separate line (3), both results in the fixture being ignored (2).
+
+![TestCaseIgnoreGoneWrong](../../../../images/TestCaseIgnoreGoneWrong.png)
+
+<!-- cspell:disable-next-line -->
+_Thanks to [Geir Marius Gjul](https://github.com/GeirMG) for raising this question again._
+
+### Correct `Explicit` Attribute Usage, by Example
+
+`Explicit`, used correctly, looks like the following:
+
+[!code-csharp[TestCaseWithExplicit](~/snippets/Snippets.NUnit/Attributes/TestCaseAttributeExamples.cs#TestCaseWithExplicit)]
+
+Note that adding the `Reason` is optional, and Visual Studio TestExplorer will not even show it.
+
+### Correct `Category` Attribute Usage, by Example
+
+Categories can be applied to a single `TestCase` the same way, as a named parameter. Otherwise, it will apply to the whole fixture. Be sure what you're asking for!
+
+[!code-csharp[TestCaseWithCategory](~/snippets/Snippets.NUnit/Attributes/TestCaseAttributeExamples.cs#TestCaseWithCategory)]
+
 ## Order of Execution
 
 Individual test cases are executed in the order in which NUnit discovers them. This order does **not** necessarily

docs/images/TestCaseIgnoreDoneCorrect.png

@@ -1,9 +1,4 @@
 using NUnit.Framework;
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
 namespace Snippets.NUnit.Attributes
 {
@@ -28,5 +23,38 @@ public int DivideTest(int n, int d)
             return n / d;
         }
         #endregion
+
+        #region TestCaseWithIgnore
+        [TestCase(1, 1)]
+        [TestCase(0, 0, Ignore = "Only ignore this")]
+        [TestCase(1, 3)]
+        public void AddTestWithIgnore(int a, int b)
+        {
+            var result = a + b;
+            Assert.That(result, Is.GreaterThan(1));
+        }
+        #endregion
+
+        #region TestCaseWithExplicit
+        [TestCase(1, 1)]
+        [TestCase(0, 0, Explicit = true, Reason = "This will fail so only run explicitly")]
+        [TestCase(1, 3)]
+        public void AddTestWithExplicit(int a, int b)
+        {
+            var result = a + b;
+            Assert.That(result, Is.GreaterThan(1));
+        }
+        #endregion
+
+        #region TestCaseWithCategory
+        [TestCase(1, 1)]
+        [TestCase(2, 0, Category = "Crazy")]
+        [TestCase(1, 3)]
+        public void AddTestWithCategory(int a, int b)
+        {
+            var result = a + b;
+            Assert.That(result, Is.GreaterThan(1));
+        }
+        #endregion
     }
 }