Nunit Constraint Documentation

NUnit Constraint Documentation

This skill describes how to create and update documentation for NUnit constraints.

Documentation Template Structure

Each constraint documentation file in docs/articles/nunit/writing-tests/constraints/ should follow this structure:

---
uid: constraint-<name>
---

# <Name> Constraint

Brief description (2-3 sentences) explaining what the constraint tests and when to use it.

## Usage

```csharp
Is.<Method>(args)           // Primary syntax
Does.<Method>(args)         // If applicable
Has.<Method>(args)          // If applicable
```

## Modifiers

```csharp
.IgnoreCase                 // Makes comparison case-insensitive
.Using(IComparer comparer)  // Uses custom comparison logic
.Within(tolerance)          // Allows approximate matching
```

> [!NOTE]
> Only include this section if the constraint has modifiers.

## Examples

Inline one-liners showing common patterns:

```csharp
Assert.That(actual, Is.<Method>(expected));
Assert.That(actual, Is.Not.<Method>(expected));
Assert.That(actual, Is.<Method>(expected).IgnoreCase);
```

### [Scenario Section - only if complex setup needed]

Brief explanation of the scenario.

[!code-csharp[ScenarioExample](~/snippets/Snippets.NUnit/ConstraintExamples.cs#ScenarioExample)]

## Notes

1. Important behavioral notes
2. Edge cases
3. Compatibility information

## See Also

* [Related Constraint](related.md)
* [Another Related](another.md)

Key Structural Principles

Inline vs External Examples

Inline examples (in the markdown itself):

• Usage section: Always inline - shows the API surface (1-3 lines of just the syntax)
• Examples section: One-liners demonstrating common patterns without test boilerplate

## Usage

```csharp
Is.Null
Is.Not.Null
```

## Examples

```csharp
Assert.That(myObject, Is.Null);
Assert.That(myString, Is.Not.Null);
Assert.That(GetResult(), Is.Null.Or.Empty);  // Combined with other constraints
```

External snippets (from Snippets.NUnit):

• Complex scenarios requiring setup code (custom comparers, test data, helper classes)
• Full compilable test methods that verify the documentation is correct
• Scenarios where the setup/context is important to understand

### Using Custom Comparers

[!code-csharp[EqualWithComparer](~/snippets/Snippets.NUnit/ConstraintExamples.cs#EqualWithComparer)]

Never inline:

• Full [Test] public void... methods - those go in external snippets
• Examples requiring helper classes or significant setup

UID Standardization

All constraint UIDs should follow the pattern: constraint-<lowercase-name>

Examples:

• equalconstraint → constraint-equal
• nullconstraint → constraint-null
• greaterthanconstraint → constraint-greaterthan

Workflow for Updating Constraint Documentation

Repository Layout Assumption: This workflow assumes you have cloned both repositories as siblings:

• <workspace>/nunit/ - The NUnit framework source code (nunit/nunit)
• <workspace>/docs/ - This documentation repository (nunit/docs)

Adjust paths below to match your local setup.

Step 1: Find the Source Code

Search for the constraint class in the NUnit framework:

# Find the constraint source file (adjust path to your nunit repo location)
grep -r "class <Name>Constraint" ../nunit/src/NUnitFramework/framework/Constraints --include="*.cs"

The source is typically at: <nunit-repo>/src/NUnitFramework/framework/Constraints/<Name>Constraint.cs

Step 2: Analyze the Source Code

From the source file, extract:

• Available syntax helpers (check Is.cs, Does.cs, Has.cs, Contains.cs)
• Modifier methods and their purposes
• Constructor parameters (for reference, not for documentation focus)
• Any special behaviors or edge cases from XML doc comments

Step 3: Check for Existing Unit Tests

# Find unit tests for the constraint (adjust path to your nunit repo location)
grep -r "<Name>Constraint" ../nunit/src/NUnitFramework/tests --include="*.cs"

Unit tests provide good examples of usage patterns and edge cases.

Step 4: Update the Markdown Documentation

Follow the template structure above. Key points:

• Lead with Usage section showing the fluent API
• Include inline examples for quick reference
• Add external snippet references for complex scenarios
• Document all available modifiers with brief descriptions

Step 5: Update or Create Snippet Examples

If complex scenarios need external snippets, add them to: docs/snippets/Snippets.NUnit/ConstraintExamples.cs

Use regions to organize:

#region <Name>ConstraintExamples
[Test]
public void <Name>Constraint_WithCustomComparer()
{
    // Example with setup that's too complex for inline
    var comparer = new MyCustomComparer();
    Assert.That(actual, Is.<Method>(expected).Using(comparer));
}
#endregion

Step 6: Build and Test

Always verify the snippets compile and tests pass. From the docs repository root:

# Build
dotnet build docs/snippets/Snippets.slnx

# Run all tests
dotnet test docs/snippets/Snippets.slnx --no-build

# Run specific constraint tests
dotnet test docs/snippets/Snippets.slnx --no-build --filter "FullyQualifiedName~ConstraintExamples" --verbosity normal

Quality Checklist

Before marking a constraint as done:

• UID follows constraint-<name> pattern
• Description is 2-3 sentences explaining purpose
• Usage section shows fluent API methods (inline, 1-3 lines)
• Modifiers section (if applicable) with brief descriptions
• Examples section with inline one-liners for common patterns
• External snippets for complex scenarios (custom comparers, setup-heavy)
• Examples have subsection headers if multiple scenarios exist
• Notes section for edge cases/important behaviors
• See Also links to related constraints
• Version info for features added after NUnit 3.0

Common Constraint Patterns

Simple Constraints (no modifiers)

Examples: NullConstraint, TrueConstraint, FalseConstraint, NaNConstraint

These need minimal documentation but should still have:

• Clear description
• Usage showing Is.<Name> and Is.Not.<Name>
• 2-3 inline examples

Comparison Constraints (with Using/Within modifiers)

Examples: EqualConstraint, GreaterThanConstraint, LessThanConstraint

These need:

• Modifiers section documenting .Using() and .Within() variants
• Examples showing basic comparison and modifier usage
• External snippets for custom comparer scenarios

Collection Constraints (with collection-specific modifiers)

Examples: CollectionEquivalentConstraint, UniqueItemsConstraint, AllItemsConstraint

These need:

• Modifiers section with .IgnoreCase, .Using(), .UsingPropertiesComparer()
• Examples showing different collection types
• Notes about element comparison behavior

String Constraints (with string-specific modifiers)

Examples: StartsWithConstraint, SubstringConstraint, RegexConstraint

These need:

• Modifiers for .IgnoreCase, .Using(StringComparison), .Using(CultureInfo)
• Examples showing case-sensitive and case-insensitive usage
• Notes about culture-specific behavior where applicable

Source: nunit/docs — distributed by TomeVault.