WIP: Add programmatic constraint examples & surface in docs (#810)

* Add and use programmatic example * some better formatting on the table * more table formatting on constraints * Add example column * rest of the columns * Example in markdown * lint: newline * more * Add two one-liner examples * Move into common file to move faster * New example * Fix alphabetical list * more * Add C# devkit to devcontainer * example * Cast to IComparer Because NUnit supports both * Fix constraint with note * Use example * more
nunit · Oct 16, 2023 · 5c1d71a · 5c1d71a
1 parent beafc7a
commit 5c1d71a
Show file tree

Hide file tree

Showing 7 changed files with 196 additions and 138 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -17,7 +17,8 @@
  "shuworks.vscode-table-formatter",
  "ms-dotnettools.csharp",
  "github.vscode-github-actions",
- "ms-azuretools.vscode-docker"
+ "ms-azuretools.vscode-docker",
+ "ms-dotnettools.csdevkit"
  ]
  }
  }

diff --git a/docs/articles/nunit/writing-tests/constraints/AllItemsConstraint.md b/docs/articles/nunit/writing-tests/constraints/AllItemsConstraint.md
@@ -10,18 +10,10 @@ AllItemsConstraint(Constraint itemConstraint)
 
 ## Syntax
 
-```csharp
-Is.All...
-Has.All...
-```
+You can use `Is.All` or `Has.All` to refer to all items in an `IEnumerable`.
 
 ## Examples of Use
 
-```csharp
-int[] iarray = new int[] { 1, 2, 3 };
-string[] sarray = new string[] { "a", "b", "c" };
-Assert.That(iarray, Is.All.Not.Null);
-Assert.That(sarray, Is.All.InstanceOf<string>());
-Assert.That(iarray, Is.All.GreaterThan(0));
-Assert.That(iarray, Has.All.GreaterThan(0));
-```
+[!code-csharp[IsBasedFormat](~/snippets/Snippets.NUnit/Constraints/ConstraintExamples.cs#AllItemsIsExample)]
+
+[!code-csharp[HasBasedFormat](~/snippets/Snippets.NUnit/Constraints/ConstraintExamples.cs#AllItemsHasExample)]
diff --git a/docs/articles/nunit/writing-tests/constraints/AndConstraint.md b/docs/articles/nunit/writing-tests/constraints/AndConstraint.md
@@ -16,9 +16,7 @@ AndConstraint(Constraint left, Constraint right)
 
 ## Examples of Use
 
-```csharp
-Assert.That(2.3, Is.GreaterThan(2.0).And.LessThan(3.0));
-```
+[!code-csharp[AndExample](~/snippets/Snippets.NUnit/Constraints/ConstraintExamples.cs#AndExample)]
 
 ## Evaluation Order and Precedence
 

diff --git a/docs/articles/nunit/writing-tests/constraints/AnyOfConstraint.md b/docs/articles/nunit/writing-tests/constraints/AnyOfConstraint.md
@@ -30,9 +30,6 @@ Is.AnyOf(object[] expected)
 
 ## Examples of Use
 
-```csharp
-Assert.That(42, Is.AnyOf(0, -1, 42, 100));
+[!code-csharp[AnyOfExample](~/snippets/Snippets.NUnit/Constraints/ConstraintExamples.cs#AnyOfExample)]
 
-// You can use a custom comparer as well
-Assert.That(myOwnObject, Is.AnyOf(myArray).Using(myComparer));
-```
+[!code-csharp[AnyOfWithCustomComparison](~/snippets/Snippets.NUnit/Constraints/ConstraintExamples.cs#AnyOfWithCustomComparison)]
diff --git a/docs/articles/nunit/writing-tests/constraints/AssignableFromConstraint.md b/docs/articles/nunit/writing-tests/constraints/AssignableFromConstraint.md
@@ -17,7 +17,4 @@ Is.AssignableFrom<T>()
 
 ## Examples of Use
 
-```csharp
-Assert.That("Hello", Is.AssignableFrom(typeof(string)));
-Assert.That(5, Is.Not.AssignableFrom(typeof(string)));
-```
+[!code-csharp[AssignableFromExample](~/snippets/Snippets.NUnit/Constraints/ConstraintExamples.cs#AssignableFromExample)]
diff --git a/docs/articles/nunit/writing-tests/constraints/Constraints.md b/docs/articles/nunit/writing-tests/constraints/Constraints.md
@@ -4,148 +4,150 @@ uid: constraints
 
 # Constraints
 
+<!-- markdownlint-disable MD033 -->
+
 This page lists all the constraints available in NUnit.
 
 * [Alphabetical List of Constraints](#alphabetical-list-of-constraints)
 * [Constraints by Category](#constraints-by-category)
 
 ## Alphabetical List of Constraints
 
-Constraint Name |
--------------------------------------|
-[AllItemsConstraint](AllItemsConstraint.md) |
-[AndConstraint](AndConstraint.md) |
-[AssignableFromConstraint](AssignableFromConstraint.md) |
-[AssignableToConstraint](AssignableToConstraint.md)   |
-[AttributeConstraint](AttributeConstraint.md)   |
-[AttributeExistsConstraint](AttributeExistsConstraint.md) |
-[AnyOfConstraint](AnyOfConstraint.md)   |
-[BinarySerializableConstraint](BinarySerializableConstraint.md) |
-[CollectionContainsConstraint](CollectionContainsConstraint.md) |
-[CollectionEquivalentConstraint](CollectionEquivalentConstraint.md) |
-[CollectionOrderedConstraint](CollectionOrderedConstraint.md) |
-[CollectionSubsetConstraint](CollectionSubsetConstraint.md) |
-[CollectionSupersetConstraint](CollectionSupersetConstraint.md) |
-[DelayedConstraint](DelayedConstraint.md) |
-[DictionaryContainsKeyConstraint](DictionaryContainsKeyConstraint.md) |
-[DictionaryContainsKeyValuePairConstraint](DictionaryContainsKeyValuePairConstraint.md) |
-[DictionaryContainsValueConstraint](DictionaryContainsValueConstraint.md)|
-[EmptyCollectionConstraint](EmptyCollectionConstraint.md) |
-[EmptyConstraint](EmptyConstraint.md) |
-[EmptyDirectoryConstraint](EmptyDirectoryConstraint.md) |
-[EmptyStringConstraint](EmptyStringConstraint.md) |
-[EndsWithConstraint](EndsWithConstraint.md) |
-[EqualConstraint](EqualConstraint.md) |
-[ExactCountConstraint](ExactCountConstraint.md) |
-[ExactTypeConstraint](ExactTypeConstraint.md) |
-[FalseConstraint](FalseConstraint.md) |
-[FileOrDirectoryExistsConstraint](FileOrDirectoryExistsConstraint.md) |
-[GreaterThanConstraint](GreaterThanConstraint.md) |
-[GreaterThanOrEqualConstraint](GreaterThanOrEqualConstraint.md) |
-[InstanceOfTypeConstraint](InstanceOfTypeConstraint.md) |
-[LessThanConstraint](LessThanConstraint.md) |
-[LessThanOrEqualConstraint](LessThanOrEqualConstraint.md) |
-[NaNConstraint](NaNConstraint.md) |
-[NoItemConstraint](NoItemConstraint.md) |
-[NotConstraint](NotConstraint.md) |
-[NullConstraint](NullConstraint.md) |
-[OrConstraint](OrConstraint.md) |
-[PropertyConstraint](PropertyConstraint.md) |
-[PropertyExistsConstraint](PropertyExistsConstraint.md) |
-[RangeConstraint](RangeConstraint.md) |
-[RegexConstraint](RegexConstraint.md) |
-[ReusableConstraint](ReusableConstraint.md) |
-[SameAsConstraint](SameAsConstraint.md) |
-[SamePathConstraint](SamePathConstraint.md) |
-[SamePathOrUnderConstraint](SamePathOrUnderConstraint.md) |
-[SomeItemsConstraint](SomeItemsConstraint.md) |
-[StartsWithConstraint](StartsWithConstraint.md) |
-[SubPathConstraint](SubPathConstraint.md) |
-[SubstringConstraint](SubstringConstraint.md) |
-[ThrowsConstraint](ThrowsConstraint.md) |
-[ThrowsNothingConstraint](ThrowsNothingConstraint.md) |
-[TrueConstraint](TrueConstraint.md) |
-[UniqueItemsConstraint](UniqueItemsConstraint.md) |
-[XmlSerializableConstraint](XmlSerializableConstraint.md) |
+| Constraint Name  | Quick Example |
+| ------------------------------------- | ------------- |
+| [AllItemsConstraint](AllItemsConstraint.md)  | `Assert.That(myEnumerable, Has.All.GreaterThan(32))`<br/>`Assert.That(myEnumerable, Is.All.InstanceOf<string>()` |
+| [AndConstraint](AndConstraint.md)  | `Assert.That(2.3, Is.GreaterThan(2.0).And.LessThan(3.0))` |
+| [AnyOfConstraint](AnyOfConstraint.md)  | `Assert.That(42, Is.AnyOf(0, -1, 42, 100));` |
+| [AssignableFromConstraint](AssignableFromConstraint.md) | `Assert.That("Hello", Is.AssignableFrom(typeof(string)));`<br/>`Assert.That(5, Is.Not.AssignableFrom<string>());` |
+| [AssignableToConstraint](AssignableToConstraint.md) | |
+| [AttributeConstraint](AttributeConstraint.md)  | |
+| [AttributeExistsConstraint](AttributeExistsConstraint.md) | |
+| [BinarySerializableConstraint](BinarySerializableConstraint.md)  | |
+| [CollectionContainsConstraint](CollectionContainsConstraint.md)  | |
+| [CollectionEquivalentConstraint](CollectionEquivalentConstraint.md)  | |
+| [CollectionOrderedConstraint](CollectionOrderedConstraint.md)  | |
+| [CollectionSubsetConstraint](CollectionSubsetConstraint.md)  | |
+| [CollectionSupersetConstraint](CollectionSupersetConstraint.md)  | |
+| [DelayedConstraint](DelayedConstraint.md)  | |
+| [DictionaryContainsKeyConstraint](DictionaryContainsKeyConstraint.md)  | |
+| [DictionaryContainsKeyValuePairConstraint](DictionaryContainsKeyValuePairConstraint.md)  | |
+| [DictionaryContainsValueConstraint](DictionaryContainsValueConstraint.md)| |
+| [EmptyCollectionConstraint](EmptyCollectionConstraint.md)  | |
+| [EmptyConstraint](EmptyConstraint.md)  | |
+| [EmptyDirectoryConstraint](EmptyDirectoryConstraint.md)  | |
+| [EmptyStringConstraint](EmptyStringConstraint.md)  | |
+| [EndsWithConstraint](EndsWithConstraint.md)  | |
+| [EqualConstraint](EqualConstraint.md)  | |
+| [ExactCountConstraint](ExactCountConstraint.md)  | |
+| [ExactTypeConstraint](ExactTypeConstraint.md)  | |
+| [FalseConstraint](FalseConstraint.md)  | |
+| [FileOrDirectoryExistsConstraint](FileOrDirectoryExistsConstraint.md)  | |
+| [GreaterThanConstraint](GreaterThanConstraint.md)  | |
+| [GreaterThanOrEqualConstraint](GreaterThanOrEqualConstraint.md)  | |
+| [InstanceOfTypeConstraint](InstanceOfTypeConstraint.md)  | |
+| [LessThanConstraint](LessThanConstraint.md)  | |
+| [LessThanOrEqualConstraint](LessThanOrEqualConstraint.md)  | |
+| [NaNConstraint](NaNConstraint.md)  | |
+| [NoItemConstraint](NoItemConstraint.md)  | |
+| [NotConstraint](NotConstraint.md)  | |
+| [NullConstraint](NullConstraint.md)  | |
+| [OrConstraint](OrConstraint.md)  | |
+| [PropertyConstraint](PropertyConstraint.md)  | |
+| [PropertyExistsConstraint](PropertyExistsConstraint.md)  | |
+| [RangeConstraint](RangeConstraint.md)  | |
+| [RegexConstraint](RegexConstraint.md)  | |
+| [ReusableConstraint](ReusableConstraint.md)  | |
+| [SameAsConstraint](SameAsConstraint.md)  | |
+| [SamePathConstraint](SamePathConstraint.md)  | |
+| [SamePathOrUnderConstraint](SamePathOrUnderConstraint.md)  | |
+| [SomeItemsConstraint](SomeItemsConstraint.md)  | |
+| [StartsWithConstraint](StartsWithConstraint.md)  | |
+| [SubPathConstraint](SubPathConstraint.md)  | |
+| [SubstringConstraint](SubstringConstraint.md)  | |
+| [ThrowsConstraint](ThrowsConstraint.md)  | |
+| [ThrowsNothingConstraint](ThrowsNothingConstraint.md)  | |
+| [TrueConstraint](TrueConstraint.md)  | |
+| [UniqueItemsConstraint](UniqueItemsConstraint.md)  | |
+| [XmlSerializableConstraint](XmlSerializableConstraint.md)  | |
 
 ## Constraints by Category
 
 ### Collection Constraints
- 
-Constraint Name |
--------------------------------------|
-[AllItemsConstraint](AllItemsConstraint.md) |
-[AnyOfConstraint](AnyOfConstraint.md) |
-[CollectionContainsConstraint](CollectionContainsConstraint.md) |
-[CollectionEquivalentConstraint](CollectionEquivalentConstraint.md) |
-[CollectionOrderedConstraint](CollectionOrderedConstraint.md) |
-[CollectionSubsetConstraint](CollectionSubsetConstraint.md) |
-[CollectionSupersetConstraint](CollectionSupersetConstraint.md) |
-[DictionaryContainsKeyConstraint](DictionaryContainsKeyConstraint.md) |
-[DictionaryContainsKeyValuePairConstraint](DictionaryContainsKeyValuePairConstraint.md) |
-[DictionaryContainsValueConstraint](DictionaryContainsValueConstraint.md)|
-[EmptyCollectionConstraint](EmptyCollectionConstraint.md) |
-[ExactCountConstraint](ExactCountConstraint.md) |
-[NoItemConstraint](NoItemConstraint.md) |
-[SomeItemsConstraint](SomeItemsConstraint.md) |
-[UniqueItemsConstraint](UniqueItemsConstraint.md) |
+
+| Constraint Name  | Quick Example |
+| -------------------------------------| ------------- |
+| [AllItemsConstraint](AllItemsConstraint.md)  | |
+| [AnyOfConstraint](AnyOfConstraint.md)  | |
+| [CollectionContainsConstraint](CollectionContainsConstraint.md)  | |
+| [CollectionEquivalentConstraint](CollectionEquivalentConstraint.md)  | |
+| [CollectionOrderedConstraint](CollectionOrderedConstraint.md)  | |
+| [CollectionSubsetConstraint](CollectionSubsetConstraint.md)  | |
+| [CollectionSupersetConstraint](CollectionSupersetConstraint.md)  | |
+| [DictionaryContainsKeyConstraint](DictionaryContainsKeyConstraint.md)  | |
+| [DictionaryContainsKeyValuePairConstraint](DictionaryContainsKeyValuePairConstraint.md)  | |
+| [DictionaryContainsValueConstraint](DictionaryContainsValueConstraint.md)| |
+| [EmptyCollectionConstraint](EmptyCollectionConstraint.md)  | |
+| [ExactCountConstraint](ExactCountConstraint.md)  | |
+| [NoItemConstraint](NoItemConstraint.md)  | |
+| [SomeItemsConstraint](SomeItemsConstraint.md)  | |
+| [UniqueItemsConstraint](UniqueItemsConstraint.md)  | |
 
 ### Comparison Constraints
 
-Constraint Name |
--------------------------------------|
-[GreaterThanConstraint](GreaterThanConstraint.md) |
-[GreaterThanOrEqualConstraint](GreaterThanOrEqualConstraint.md) |
-[LessThanConstraint](LessThanConstraint.md) |
-[LessThanOrEqualConstraint](LessThanOrEqualConstraint.md) |
-[RangeConstraint](RangeConstraint.md) |
+| Constraint Name  | Quick Example |
+| -------------------------------------| ------------- |
+| [GreaterThanConstraint](GreaterThanConstraint.md)  | |
+| [GreaterThanOrEqualConstraint](GreaterThanOrEqualConstraint.md)  | |
+| [LessThanConstraint](LessThanConstraint.md)  | |
+| [LessThanOrEqualConstraint](LessThanOrEqualConstraint.md)  | |
+| [RangeConstraint](RangeConstraint.md)  | |
 
 ### Compound Constraints
 
-Constraint Name |
--------------------------------------|
-[AndConstraint](AndConstraint.md) |
-[NotConstraint](NotConstraint.md) |
-[OrConstraint](OrConstraint.md) |
+| Constraint Name  | Quick Example |
+| -------------------------------------| ------------- |
+| [AndConstraint](AndConstraint.md)  | |
+| [NotConstraint](NotConstraint.md)  | |
+| [OrConstraint](OrConstraint.md)  | |
 
 ### Condition Constraints
 
-Constraint Name |
--------------------------------------|
-[EmptyConstraint](EmptyConstraint.md) |
-[FalseConstraint](FalseConstraint.md) |
-[NaNConstraint](NaNConstraint.md) |
-[NullConstraint](NullConstraint.md) |
-[TrueConstraint](TrueConstraint.md) |
+| Constraint Name  | Quick Example |
+| -------------------------------------| ------------- |
+| [EmptyConstraint](EmptyConstraint.md)  | |
+| [FalseConstraint](FalseConstraint.md)  | |
+| [NaNConstraint](NaNConstraint.md)  | |
+| [NullConstraint](NullConstraint.md)  | |
+| [TrueConstraint](TrueConstraint.md)  | |
 
 ### File and Directory Constraints
 
-Constraint Name |
--------------------------------------|
-[EmptyDirectoryConstraint](EmptyDirectoryConstraint.md) |
-[FileOrDirectoryExistsConstraint](FileOrDirectoryExistsConstraint.md) |
-[SamePathConstraint](SamePathConstraint.md) |
-[SamePathOrUnderConstraint](SamePathOrUnderConstraint.md) |
-[SubPathConstraint](SubPathConstraint.md) |
+| Constraint Name  | Quick Example |
+| -------------------------------------| ------------- |
+| [EmptyDirectoryConstraint](EmptyDirectoryConstraint.md)  | |
+| [FileOrDirectoryExistsConstraint](FileOrDirectoryExistsConstraint.md)  | |
+| [SamePathConstraint](SamePathConstraint.md)  | |
+| [SamePathOrUnderConstraint](SamePathOrUnderConstraint.md)  | |
+| [SubPathConstraint](SubPathConstraint.md)  | |
 
 ### String Constraints
 
-Constraint Name |
--------------------------------------|
-[EmptyStringConstraint](EmptyStringConstraint.md) |
-[EndsWithConstraint](EndsWithConstraint.md) |
-[RegexConstraint](RegexConstraint.md) |
-[StartsWithConstraint](StartsWithConstraint.md) |
-[SubstringConstraint](SubstringConstraint.md) |
+| Constraint Name  | Quick Example |
+| -------------------------------------| ------------- |
+| [EmptyStringConstraint](EmptyStringConstraint.md)  | |
+| [EndsWithConstraint](EndsWithConstraint.md)  | |
+| [RegexConstraint](RegexConstraint.md)  | |
+| [StartsWithConstraint](StartsWithConstraint.md)  | |
+| [SubstringConstraint](SubstringConstraint.md)  | |
 
 ### Type Constraints
 
-Constraint Name |
--------------------------------------|
-[AssignableFromConstraint](AssignableFromConstraint.md) |
-[AssignableToConstraint](AssignableToConstraint.md) |
-[ExactTypeConstraint](ExactTypeConstraint.md) |
-[InstanceOfTypeConstraint](InstanceOfTypeConstraint.md) |
+| Constraint Name  | Quick Example |
+| -------------------------------------| ------------- |
+| [AssignableFromConstraint](AssignableFromConstraint.md)  | |
+| [AssignableToConstraint](AssignableToConstraint.md)  | |
+| [ExactTypeConstraint](ExactTypeConstraint.md)  | |
+| [InstanceOfTypeConstraint](InstanceOfTypeConstraint.md)  | |
 
 ## See also