Shouldly

https://docs.shouldly.org
Admin
Shouldly is an assertion framework that provides clear, human-readable error messages when...
Tokens:12,401
Snippets:195
Trust Score:5.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Shouldly via .NET Core CLI

Source: https://docs.shouldly.org/

Use this command to install Shouldly using the .NET Core command-line interface.

```bash
dotnet add package Shouldly
```

--------------------------------

### Check if a string starts with a specific prefix

Source: https://docs.shouldly.org/documentation/string/startwith.md

Use ShouldStartWith to assert that a string begins with a given substring. An exception is thrown if the string does not start with the specified prefix.

```cs
var target = "Homer";
target.ShouldStartWith("Bart");
```

--------------------------------

### Configure Diff Engine for Shouldly

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Install the Shouldly.DiffEngine nuget package and configure it in your test setup to display comparisons of approved and failed files in a diff viewer.

```csharp
// In your test setup
ShouldlyConfiguration.ShouldMatchApprovedDefaults.ConfigureDiffEngine();
```

--------------------------------

### Install Shouldly via Package Manager Console

Source: https://docs.shouldly.org/

Use this command to install Shouldly in Visual Studio via the Package Manager Console.

```powershell
Install-Package Shouldly
```

--------------------------------

### Query Documentation Index

Source: https://docs.shouldly.org/llms.txt

Use this GET request to query the documentation index with a specific question and an optional broader goal. The response includes a direct answer and relevant excerpts.

```http
GET https://docs.shouldly.org/documentation/3to4.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### Define Example Classes in C#

Source: https://docs.shouldly.org/documentation/equality/exampleclasses.md

These classes are used for demonstrating assertions in the documentation. They include abstract and concrete types for pets and a Person class.

```csharp
namespace Simpsons;

public abstract class Pet
{
    public abstract string? Name { get; set; }

    public override string? ToString() => Name;
}

public class Cat : Pet
{
    public override string? Name { get; set; }
}

public class Dog : Pet
{
    public override string? Name { get; set; }
}

public class Person
{
    public Person()
    {
    }

    public Person(string name)
    {
        Name = name ?? throw new ArgumentNullException(nameof(name));
    }

    public string? Name { get; set; }
    public int Salary { get; set; }

    public override string? ToString() => Name;
}
```

--------------------------------

### SubsetOf Failure Example

Source: https://docs.shouldly.org/documentation/enumerable/subsetof.md

This example demonstrates the exception message when a collection is not a subset of another. It clearly indicates which elements from the first collection were not found in the second collection.

```text
simpsonsKids
    should be subset of
[Lisa, Bart, Maggie, Homer, Marge]
    but
[Ralph]
    is outside subset
```

--------------------------------

### Check if a string does not start with a specific prefix

Source: https://docs.shouldly.org/documentation/string/startwith.md

Use ShouldNotStartWith to assert that a string does not begin with a given substring. An exception is thrown if the string unexpectedly starts with the specified prefix.

```cs
var target = "Homer Simpson";
target.ShouldNotStartWith("Homer");
```

--------------------------------

### Assertion Example with IndexOfValue

Source: https://docs.shouldly.org/readme.md

Demonstrates the difference in error reporting between a traditional assertion and Shouldly for checking the index of a value in a map. Shouldly's error message includes the expression that was evaluated.

```csharp
Assert.That(map.IndexOfValue("boo"), Is.EqualTo(2));
// -> Expected 2 but was -1
```

```csharp
map.IndexOfValue("boo").ShouldBe(2);
// -> map.IndexOfValue("boo") should be 2 but was -1
```

--------------------------------

### CompleteIn Timeout Exception Message - Text

Source: https://docs.shouldly.org/documentation/completein.md

This is an example of the exception message thrown when an action exceeds the specified timeout in Should.CompleteIn. It includes the expected timeout duration and any custom message provided.

```text
Delegate
    should complete in
00:00:00.5000000
    but did not

Additional Info:
    Some additional context
```

--------------------------------

### Class Constraint Added to ShouldNotBeNull

Source: https://docs.shouldly.org/documentation/3to4.md

In v4, a `class` constraint was added to `ShouldNotBeNull`. This prevents asserting non-nullable types, which logically makes no sense and could never fail. The example shows code that would compile in v3 but will not compile in v4.

```csharp
const long value = 1;

value.ShouldNotBeNull();
```

--------------------------------

### Initial Run of ShouldMatchApproved

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

When a `ShouldMatchApproved` test is run for the first time, the approved file will not exist, resulting in a failing test and a diff viewer.

```csharp
var simpsonsQuote = "Hi Super Nintendo Chalmers";
simpsonsQuote.ShouldMatchApproved();
```

--------------------------------

### Configure String Comparison Options

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Set specific string comparison rules, such as ignoring case or line endings, for the approval check.

```csharp
var options = StringCompareShould.IgnoreCase | StringCompareShould.IgnoreLineEndings;
toVerify.ShouldMatchApproved(c => c.WithStringCompareOptions(options))
```

--------------------------------

### Organize Approved Files in Subfolders

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Place approved and received files into a specified sub-directory relative to the test assembly.

```csharp
toVerify.ShouldMatchApproved(c => c.SubFolder("Approvals"))
```

--------------------------------

### Enable Diff Viewer for Mismatches

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Automatically opens a diff viewer when approved and received files do not match. Requires the Shouldly.DiffEngine package.

```csharp
toVerify.ShouldMatchApproved(c => c.Diff())
```

--------------------------------

### Basic ShouldMatchApproved Usage

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

The fundamental way to invoke ShouldMatchApproved, accepting a configuration builder.

```csharp
toVerify.ShouldMatchApproved(configurationBuilder => configurationBuilder.OPTION())
```

--------------------------------

### Assert all elements in a list meet a condition

Source: https://docs.shouldly.org/documentation/enumerable/allbe.md

Use AllBe to check if all persons in the list have a salary greater than 1,000,000. This snippet requires the Person class and a List<Person> to be defined.

```cs
var mrBurns = new Person { Name = "Mr.Burns", Salary = 3000000 };
var kentBrockman = new Person { Name = "Homer", Salary = 3000000 };
var homer = new Person { Name = "Homer", Salary = 30000 };
var millionaires = new List<Person> { mrBurns, kentBrockman, homer };
millionaires.ShouldAllBe(m => m.Salary > 1000000);
```

--------------------------------

### Discriminate Approved Files with a Suffix

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Append a custom string to the approved file name to differentiate multiple approval files generated from the same method.

```csharp
[Fact]
public void Simpsons()
{
  toVerify.ShouldMatchApproved(c => c.WithDiscriminator("Bart"));
}
```

--------------------------------

### Shouldly Should.Throw<TException> Action

Source: https://docs.shouldly.org/documentation/exceptions/throw.md

Use this to assert that a specific exception is thrown by an action. Ensure the action is correctly defined to reproduce the exception.

```cs
var homer = new Person { Name = "Homer", Salary = 30000 };
var denominator = 1;
Should.Throw<DivideByZeroException>(() =>
                {
                    var y = homer.Salary / denominator;
                });
```

--------------------------------

### Override Approved File Extension

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Change the default '.txt' file extension for approved and received files to a custom one.

```csharp
toVerify.ShouldMatchApproved(c => c.WithFileExtension(".cs"))
```

--------------------------------

### Assert String Equality

Source: https://docs.shouldly.org/documentation/equality/shouldbe-2.md

Use ShouldBe to assert that a string is exactly equal to an expected value. This will throw an exception if the strings differ, showing the expected and actual values.

```cs
var target = "Homer";
target.ShouldBe("Bart");
```

--------------------------------

### Assert String Matches Approved File

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Use this snippet to assert that a string value matches the content of an approved file. This is useful for verifying that text-based outputs remain consistent over time. Ensure the `Shouldly` namespace is imported.

```cs
var simpsonsQuote = "Me fail english? That's unpossible";
simpsonsQuote.ShouldMatchApproved();
```

--------------------------------

### Write a unit test with Shouldly in C#

Source: https://docs.shouldly.org/documentation/getting-started.md

This C# code demonstrates a basic NUnit test case that uses Shouldly's `ShouldBe` assertion to verify the output of the `TestWorks` method.

```csharp
using NUnit.Framework;
using Shouldly;

public class Tests
{
    [Test]
    public void Test1()
    {
        Program.TestWorks().ShouldBe("Works");
    }
}
```

--------------------------------

### Assert String Inequality

Source: https://docs.shouldly.org/documentation/equality/shouldbe-2.md

Use ShouldNotBe to assert that a string is not equal to an expected value. This will throw an exception if the strings are identical, indicating the value that should not have been present.

```cs
var target = "Bart";
target.ShouldNotBe("Bart");
```

--------------------------------

### Assert String Is Empty

Source: https://docs.shouldly.org/documentation/string/null.md

Use `ShouldBeEmpty` to assert that a string is an empty string. This will throw an exception if the string is null or contains characters.

```cs
var target = "Homer";
target.ShouldBeEmpty();
```

--------------------------------

### Use Caller's Stack Frame for Filename

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Instructs Shouldly to use the caller's stack frame for determining the approval filename, useful when calling from utility methods.

```csharp
[Fact]
public void MyTest()
{
    SomeUtilityMethod("Foo");
}

void SomeUtilityMethod(string toApprove)
{
    toApprove.ShouldMatchApproved(c => c.UseCallerLocation());
}

// -> MyTest.received.txt - without UseCallerLocation() the file would be called SomeUtilityMethod.received.txt
```

--------------------------------

### ShouldBe for Objects

Source: https://docs.shouldly.org/documentation/equality/shouldbe.md

Compares objects using their .Equals method. Ensure the objects being compared override .Equals appropriately if custom equality logic is needed.

```cs
var theSimpsonsCat = new Cat { Name = "Santas little helper" };
theSimpsonsCat.Name.ShouldBe("Snowball 2");
```

--------------------------------

### Scrub Dynamic Content from Received Files

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Define a scrubber function to replace dynamic parts of the received content, such as dates, with static placeholders for consistent approvals.

```csharp
toVerify.ShouldMatchApproved(c => c.WithScrubber(s => Regex.Replace(s, "\d{1,2}/\d{1,2}/\d{2,4}", "<date>"))

Will turn `Today is 01/01/2016` into `Today is <date>` in the received file.
```

--------------------------------

### Assert String Is Null Or Empty

Source: https://docs.shouldly.org/documentation/string/null.md

Use `ShouldBeNullOrEmpty` to assert that a string is either null or an empty string. This will throw an exception if the string has content.

```cs
var target = "Homer";
target.ShouldBeNullOrEmpty();
```

--------------------------------

### Assert String Is Not Null Or Empty

Source: https://docs.shouldly.org/documentation/string/null.md

Use `ShouldNotBeNullOrEmpty` to assert that a string is neither null nor empty. This is a common check for user input.

```cs
var target = "";
target.ShouldNotBeNullOrEmpty();
```

--------------------------------

### Locate Test Method Using Attribute

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Specify an attribute to locate the test method for generating approval filenames, supporting frameworks like XUnit and NUnit.

```csharp
// XUnit
"testAttributes".ShouldMatchApproved(b => b.LocateTestMethodUsingAttribute<FactAttribute>());
// NUnit
"testAttributes".ShouldMatchApproved(b => b.LocateTestMethodUsingAttribute<TestAttribute>());
```

--------------------------------

### ShouldBeEmpty

Source: https://docs.shouldly.org/documentation/enumerable/empty.md

Asserts that an enumerable collection is empty. If the collection contains items, it throws an exception detailing the number of items and their representation.

```APIDOC
## ShouldBeEmpty

### Description
Asserts that an enumerable collection is empty. This is useful for verifying that a collection, such as a list or array, contains no elements.

### Method Signature
```csharp
public static void ShouldBeEmpty(this IEnumerable<T> actual, string customMessage = null, ExceptionFactory factory = null)
```

### Usage Example
```csharp
var emptyList = new List<string>();
emptyList.ShouldBeEmpty(); // This assertion passes

var nonEmptyList = new List<string> { "item1" };
// nonEmptyList.ShouldBeEmpty(); // This assertion would throw an exception
```

### Exception Example
```
powerPlantOnTheWeekend
    should be empty but had
1
    item and was
[Homer]
```
```

--------------------------------

### Define a testable method in C#

Source: https://docs.shouldly.org/documentation/getting-started.md

This C# code defines a static class with a method that returns a string. It's used as the target for unit tests.

```csharp
using System;

public static class Program
{
    public static string TestWorks()
    {
        return "Works";
    }
}
```

--------------------------------

### Shouldly Should.Throw<TException> Func

Source: https://docs.shouldly.org/documentation/exceptions/throw.md

Assert that a Func delegate throws a specific exception. This is suitable for simple expressions that return a value but are expected to throw.

```cs
Should.Throw<ArgumentNullException>(() => new Person("Homer"));
```

--------------------------------

### ShouldNotBeEmpty

Source: https://docs.shouldly.org/documentation/enumerable/empty.md

Asserts that an enumerable collection is not empty. If the collection is empty, it throws an exception indicating that it was expected to have items.

```APIDOC
## ShouldNotBeEmpty

### Description
Asserts that an enumerable collection is not empty. This is useful for verifying that a collection contains at least one element.

### Method Signature
```csharp
public static void ShouldNotBeEmpty(this IEnumerable<T> actual, string customMessage = null, ExceptionFactory factory = null)
```

### Usage Example
```csharp
var nonEmptyList = new List<string> { "item1" };
nonEmptyList.ShouldNotBeEmpty(); // This assertion passes

var emptyList = new List<string>();
// emptyList.ShouldNotBeEmpty(); // This assertion would throw an exception
```

### Exception Example
```
moesTavernOnTheWeekend
    should not be empty but was
```
```

--------------------------------

### ShouldMatch String with Regex

Source: https://docs.shouldly.org/documentation/string/match.md

Use ShouldMatch to assert that a string conforms to a given regular expression pattern. This is useful for validating string formats.

```cs
var target = "Homer Simpson";
target.ShouldMatch("Bart .*?");
```

--------------------------------

### Should.NotThrow with Action

Source: https://docs.shouldly.org/documentation/exceptions/notthrow.md

Use this assertion when you want to verify that a block of code, represented by an Action, does not throw an exception. Ensure the Action is correctly defined to encapsulate the code to be tested.

```cs
var homer = new Person { Name = "Homer", Salary = 30000 };
var denominator = 0;
Should.NotThrow(() =>
                {
                    var y = homer.Salary / denominator;
                });
```

--------------------------------

### Assert String Is Null

Source: https://docs.shouldly.org/documentation/string/null.md

Use `ShouldBeNull` to assert that a string is null. This will throw an exception if the string is not null.

```cs
var target = "Homer";
target.ShouldBeNull();
```

--------------------------------

### Shouldly Action Extension Method for Throwing Exceptions

Source: https://docs.shouldly.org/documentation/exceptions/throw.md

Use this extension method on an Action delegate to assert that it throws a specific exception. This provides a more fluent syntax.

```cs
var homer = new Person { Name = "Homer", Salary = 30000 };
var denominator = 1;
var action = () =>
                {
                    var y = homer.Salary / denominator;
                };
action.ShouldThrow<DivideByZeroException>();
```

--------------------------------

### Verify object is not of a specific type

Source: https://docs.shouldly.org/documentation/equality/oftype.md

Use ShouldNotBeOfType to assert that an object is not an instance of a particular type. This assertion will fail if the object is of the expected type.

```cs
var theSimpsonsDog = new Cat { Name = "Santas little helper" };
theSimpsonsDog.ShouldNotBeOfType<Cat>();
```

--------------------------------

### Verify object is of a specific type

Source: https://docs.shouldly.org/documentation/equality/oftype.md

Use ShouldBeOfType to assert that an object is an instance of a particular type. This assertion will fail if the object is not of the expected type.

```cs
var theSimpsonsDog = new Cat { Name = "Santas little helper" };
theSimpsonsDog.ShouldBeOfType<Dog>();
```

--------------------------------

### Shouldly Should.ThrowAsync<TException> for Async Operations

Source: https://docs.shouldly.org/documentation/exceptions/throw.md

Assert that an asynchronous operation throws a specific exception. This is useful for testing methods that return a Task.

```cs
Task doSomething() => Task.CompletedTask;
var exception = await Should.ThrowAsync<DivideByZeroException>(() => doSomething());
```

--------------------------------

### Traditional Assert vs. Shouldly Assertion

Source: https://docs.shouldly.org/

Compares the syntax and error messages of traditional Assertions with Shouldly's more readable format. Shouldly uses the code before the assertion to improve error reporting.

```csharp
Assert.That(contestant.Points, Is.EqualTo(1337));
```

```csharp
contestant.Points.ShouldBe(1337);
```

```csharp
Assert.That(map.IndexOfValue("boo"), Is.EqualTo(2));
// -> Expected 2 but was -1
```

```csharp
map.IndexOfValue("boo").ShouldBe(2);
// -> map.IndexOfValue("boo") should be 2 but was -1
```

--------------------------------

### DateTime Comparison with ShouldNotBe and Tolerance

Source: https://docs.shouldly.org/documentation/equality/notbe.md

Compare DateTime values, asserting they are not equal within a specified TimeSpan tolerance. This is useful for date comparisons where exact matches are not required, but a range of acceptable difference is.

```csharp
var date = new DateTime(2000, 6, 1);
date.ShouldNotBe(new(2000, 6, 1, 1, 0, 1), TimeSpan.FromHours(1.5));
```

--------------------------------

### Shouldly Should.Throw<TException> Func<Task>

Source: https://docs.shouldly.org/documentation/exceptions/throw.md

Assert that a Func delegate returning a Task throws a specific exception. This is used for testing asynchronous operations that are wrapped in a Func.

```cs
var homer = new Person { Name = "Homer", Salary = 30000 };
var denominator = 1;
Should.Throw<DivideByZeroException>(() =>
                {
                    var task = Task.Factory.StartNew(
                        () =>
                        {
                            var y = homer.Salary / denominator;
                        });
                    return task;
                });
```

--------------------------------

### ShouldBe for Bools with Optional Context

Source: https://docs.shouldly.org/documentation/equality/shouldbe.md

Asserts that a boolean value is equal to the expected boolean. An optional message can be provided to give additional context in case of failure.

```cs
const bool myValue = false;
myValue.ShouldBe(true, "Some additional context");
```

--------------------------------

### Shouldly Func Extension Method for Throwing Exceptions

Source: https://docs.shouldly.org/documentation/exceptions/throw.md

Use this extension method on a Func delegate to assert that it throws a specific exception. This offers a concise way to test functions that are expected to fail.

```cs
var func = () => new Person("Homer");
func.ShouldThrow<ArgumentNullException>();
```

--------------------------------

### ShouldBe for DateTime(Offset) with Tolerance

Source: https://docs.shouldly.org/documentation/equality/shouldbe.md

Compares DateTime or DateTimeOffset values, allowing for a TimeSpan tolerance. This is useful when comparing timestamps that may have slight variations.

```cs
var date = new DateTime(2000, 6, 1);
date.ShouldBe(new(2000, 6, 1, 1, 0, 1), TimeSpan.FromHours(1));
```

--------------------------------

### Action Extension ShouldNotThrow

Source: https://docs.shouldly.org/documentation/exceptions/notthrow.md

This extension method provides an alternative syntax for asserting that an Action does not throw an exception. It is called directly on the Action delegate.

```cs
var homer = new Person { Name = "Homer", Salary = 30000 };
var denominator = 0;
var action = () =>
                {
                    var y = homer.Salary / denominator;
                };
action.ShouldNotThrow();
```

--------------------------------

### Should.NotThrow with Func<Task>

Source: https://docs.shouldly.org/documentation/exceptions/notthrow.md

This overload is used to assert that an asynchronous operation, represented by a Func that returns a Task, completes without throwing an exception. The Func must return the Task to be awaited.

```cs
var homer = new Person { Name = "Homer", Salary = 30000 };
var denominator = 0;
Should.NotThrow(() =>
                {
                    var task = Task.Factory.StartNew(
                        () =>
                        {
                            var y = homer.Salary / denominator;
                        });
                    return task;
                });
```

--------------------------------

### Verify Action Completes Within Timeout - C#

Source: https://docs.shouldly.org/documentation/completein.md

Use Should.CompleteIn to assert that an action finishes execution before the specified timeout. If the action takes longer than the timeout, an exception is thrown with a custom message.

```csharp
Should.CompleteIn(
                    action: () => { Thread.Sleep(TimeSpan.FromSeconds(15)); },
                    timeout: TimeSpan.FromSeconds(0.5),
                    customMessage: "Some additional context");
```

--------------------------------

### Verify Property Existence on Dynamic Object

Source: https://docs.shouldly.org/documentation/dynamicshould.md

Use DynamicShould.HaveProperty to assert that a dynamic object contains a specific property. This is useful when dealing with dynamically created objects or data from external sources.

```cs
dynamic theFuture = new ExpandoObject();
DynamicShould.HaveProperty(() => theFuture, "RobotTeachers");
```

--------------------------------

### Integer Comparison with ShouldNotBe

Source: https://docs.shouldly.org/documentation/equality/notbe.md

Assert that an integer value is not equal to another integer. This is a fundamental check for ensuring a numeric variable does not hold a specific forbidden value.

```csharp
const int one = 1;
one.ShouldNotBe(1);
```

--------------------------------

### TimeSpan Comparison with ShouldNotBe and Tolerance

Source: https://docs.shouldly.org/documentation/equality/notbe.md

Assert that a TimeSpan value is not equal to another TimeSpan within a given tolerance. This is helpful when checking durations where slight variations are permissible.

```csharp
var timeSpan = TimeSpan.FromHours(1);
timeSpan.ShouldNotBe(timeSpan.Add(TimeSpan.FromHours(1.1d)), TimeSpan.FromHours(1.5d));
```

--------------------------------

### ShouldNotMatch String with Regex

Source: https://docs.shouldly.org/documentation/string/match.md

Use ShouldNotMatch to assert that a string does not conform to a given regular expression pattern. This is useful for ensuring strings do not match certain formats.

```cs
var target = "Homer Simpson";
target.ShouldNotMatch("Homer .*?");
```

--------------------------------

### Check if a dictionary does not contain a specific key

Source: https://docs.shouldly.org/documentation/dictionary/containkey.md

Use ShouldNotContainKey to assert that a dictionary does not contain a given key. This is helpful for ensuring that certain keys are absent, preventing potential errors or unexpected behavior.

```cs
var websters = new Dictionary<string, string> { { "Chazzwazzers", "What Australians would have called a bull frog." } };
websters.ShouldNotContainKey("Chazzwazzers");
```

--------------------------------

### ShouldBeLessThanOrEqualTo Assertion

Source: https://docs.shouldly.org/documentation/equality/greaterlessthan.md

Use `ShouldBeLessThanOrEqualTo` to assert that a value is less than or equal to a specified value. This assertion fails only if the value is strictly greater than the specified value.

```cs
var homer = new Person { Name = "Homer", Salary = 30001 };
homer.Salary.ShouldBeLessThanOrEqualTo(30000);
```

--------------------------------

### Assert String Is Not Null

Source: https://docs.shouldly.org/documentation/string/null.md

Use `ShouldNotBeNull` to assert that a string is not null. This is useful for nullable reference types.

```cs
string? target = null;
target.ShouldNotBeNull();
```

--------------------------------

### Check multiple conditions on a common subject with ShouldSatisfy

Source: https://docs.shouldly.org/documentation/satisfyallconditions.md

Use `value.ShouldSatisfy([...])` when all assertions relate to a single subject. The subject is passed to each condition and appears in failure messages.

```csharp
var mrBurns = new Person { Name = null };
mrBurns.ShouldSatisfy(
                [
                    p => p.Name.ShouldNotBeNullOrEmpty(),
                    p => p.Name.ShouldBe("Mr.Burns")
                ]);
```

--------------------------------

### Should.NotThrow with Func

Source: https://docs.shouldly.org/documentation/exceptions/notthrow.md

Use this assertion when the code you want to test returns a value, represented by a Func. It verifies that the Func executes without throwing an exception. Note the use of the null-forgiving operator `!` when passing a potentially null string.

```cs
string? name = null;
Should.NotThrow(() => new Person(name!));
```

--------------------------------

### ShouldContainKeyAndValue for Dictionaries

Source: https://docs.shouldly.org/documentation/dictionary/containkeyandvalue.md

Use this assertion to verify that a dictionary contains a specific key and that the value associated with that key matches the expected value. This is useful for ensuring data integrity within dictionaries.

```cs
var websters = new Dictionary<string, string> { { "Cromulent", "I never heard the word before moving to Springfield." } };
websters.ShouldContainKeyAndValue("Cromulent", "Fine, acceptable.");
```

--------------------------------

### ShouldBe for Enumerables of Numerics with Tolerance

Source: https://docs.shouldly.org/documentation/equality/shouldbe.md

Compares enumerables of numeric types (float, decimal, double) with a specified tolerance for each element. This is useful for comparing collections of floating-point numbers.

```cs
var firstSet = new[] { 1.23m, 2.34m, 3.45001m };
var secondSet = new[] { 1.4301m, 2.34m, 3.45m };
firstSet.ShouldBe(secondSet, 0.1m);
```

--------------------------------

### ShouldNotContainKeyAndValue for Dictionaries

Source: https://docs.shouldly.org/documentation/dictionary/containkeyandvalue.md

Use this assertion to verify that a dictionary does not contain a specific key with a specific value. This is helpful when you need to ensure that certain data is absent from a dictionary.

```cs
var websters = new Dictionary<string, string> { { "Chazzwazzers", "What Australians would have called a bull frog." } };
websters.ShouldNotContainValueForKey("Chazzwazzers", "What Australians would have called a bull frog.");
```

--------------------------------

### ShouldBeEmpty Assertion

Source: https://docs.shouldly.org/documentation/enumerable/empty.md

Use `ShouldBeEmpty()` to assert that an enumerable collection contains no elements. This assertion will fail if the collection has one or more items.

```cs
var homer = new Person { Name = "Homer" };
var powerPlantOnTheWeekend = new List<Person> { homer };
powerPlantOnTheWeekend.ShouldBeEmpty();
```

--------------------------------

### Assert collection is unique

Source: https://docs.shouldly.org/documentation/enumerable/unique.md

Use `ShouldBeUnique()` to verify that a collection contains no duplicate elements. This is useful for validating data integrity where uniqueness is a requirement. The assertion will fail if any element appears more than once.

```cs
var lisa = new Person { Name = "Lisa" };
var bart = new Person { Name = "Bart" };
var maggie = new Person { Name = "Maggie" };
var simpsonsKids = new List<Person> { bart, lisa, maggie, maggie };
simpsonsKids.ShouldBeUnique();
```

--------------------------------

### Check if a reference type is not null

Source: https://docs.shouldly.org/documentation/equality/null.md

Use ShouldNotBeNull to assert that a reference type is not null. This will throw an exception if the value is null. The non-null value is returned for chaining.

```cs
string? myRef = null;
myRef.ShouldNotBeNull();
```

--------------------------------

### Object Comparison with ShouldNotBe

Source: https://docs.shouldly.org/documentation/equality/notbe.md

Use ShouldNotBe to assert that an object's property is not equal to a specific value. This is useful for verifying that a value has not been set to an expected but incorrect state.

```csharp
var theSimpsonsCat = new Cat { Name = "Santas little helper" };
thesSimpsonsCat.Name.ShouldNotBe("Santas little helper");
```

--------------------------------

### Asserting Enumerable Equality

Source: https://docs.shouldly.org/documentation/equality/shouldbe-1.md

Use ShouldBe to assert that an enumerable has the exact same elements in the same order as the expected array. This is useful for verifying the contents of collections.

```cs
var apu = new Person { Name = "Apu" };
var homer = new Person { Name = "Homer" };
var skinner = new Person { Name = "Skinner" };
var barney = new Person { Name = "Barney" };
var theBeSharps = new List<Person> { homer, skinner, barney };
theBeSharps.ShouldBe(new[] { apu, homer, skinner, barney });
```

--------------------------------

### ShouldBeLessThan Assertion

Source: https://docs.shouldly.org/documentation/equality/greaterlessthan.md

Use `ShouldBeLessThan` to assert that a value is strictly less than a specified value. This assertion fails if the value is equal to or greater than the specified value.

```cs
var homer = new Person { Name = "Homer", Salary = 300000000 };
homer.Salary.ShouldBeLessThan(30000);
```

--------------------------------

### ShouldBeSubsetOf Assertion

Source: https://docs.shouldly.org/documentation/enumerable/subsetof.md

Use ShouldBeSubsetOf to verify that all elements in `simpsonsKids` are present in `simpsonsFamily`. This assertion passes if every item in the first list exists in the second list, regardless of order or duplicates in the second list.

```cs
var lisa = new Person { Name = "Lisa" };
var bart = new Person { Name = "Bart" };
var maggie = new Person { Name = "Maggie" };
var homer = new Person { Name = "Homer" };
var marge = new Person { Name = "Marge" };
var ralph = new Person { Name = "Ralph" };
var simpsonsKids = new List<Person> { bart, lisa, maggie, ralph };
var simpsonsFamily = new List<Person> { lisa, bart, maggie, homer, marge };
simpsonsKids.ShouldBeSubsetOf(simpsonsFamily);
```

--------------------------------

### Check if a reference type is null

Source: https://docs.shouldly.org/documentation/equality/null.md

Use ShouldBeNull to assert that a reference type is null. This will throw an exception if the value is not null.

```cs
var myRef = "Hello World";
myRef.ShouldBeNull();
```

--------------------------------

### Disable Diff Viewer

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Prevents the diff viewer from opening, allowing verification through Shouldly's error messages and manual approval.

```csharp
toVerify.ShouldMatchApproved(c => c.NoDiff())
```

--------------------------------

### ShouldNotBeEmpty Assertion

Source: https://docs.shouldly.org/documentation/enumerable/empty.md

Use `ShouldNotBeEmpty()` to assert that an enumerable collection contains at least one element. This assertion will fail if the collection is empty.

```cs
var moesTavernOnTheWeekend = new List<Person>();
moesTavernOnTheWeekend.ShouldNotBeEmpty();
```

--------------------------------

### ShouldBe for Numeric Types with Tolerance

Source: https://docs.shouldly.org/documentation/equality/shouldbe.md

Asserts that a numeric value is within a specified tolerance of an expected value. Useful for floating-point comparisons where exact equality might fail due to precision issues.

```cs
const decimal pi = (decimal)Math.PI;
pi.ShouldBe(3.24m, 0.01m);
```

--------------------------------

### Assert a boolean is false

Source: https://docs.shouldly.org/documentation/equality/truefalse.md

Use ShouldBeFalse to assert that a boolean value is false. This method will throw an exception if the value is true.

```cs
var myValue = true;
myValue.ShouldBeFalse();
```

--------------------------------

### Long Comparison with ShouldNotBe

Source: https://docs.shouldly.org/documentation/equality/notbe.md

Verify that a long integer value is not equal to a specified number. This overload handles the 'long' data type, ensuring it does not match a particular value.

```csharp
const long aLong = 1L;
aLong.ShouldNotBe(1);
```

--------------------------------

### Assert a boolean is true

Source: https://docs.shouldly.org/documentation/equality/truefalse.md

Use ShouldBeTrue to assert that a boolean value is true. This method will throw an exception if the value is false.

```cs
var myValue = false;
myValue.ShouldBeTrue();
```

--------------------------------

### Check unrelated conditions with Should.Satisfy

Source: https://docs.shouldly.org/documentation/satisfyallconditions.md

Use `Should.Satisfy([...])` for a group of independent assertions. Each condition is a self-contained check as there is no common subject.

```csharp
var mrBurns = new Person { Name = null };
var homer = new Person { Name = "Homer" };
Should.Satisfy(
                [
                    () => mrBurns.Name.ShouldNotBeNullOrEmpty(),
                    () => homer.Name.ShouldBe("Mr.Burns")
                ]);
```

--------------------------------

### ShouldBeGreaterThanOrEqualTo Assertion

Source: https://docs.shouldly.org/documentation/equality/greaterlessthan.md

Use `ShouldBeGreaterThanOrEqualTo` to assert that a value is greater than or equal to a specified value. This assertion fails only if the value is strictly less than the specified value.

```cs
var mrBurns = new Person { Name = "Mr. Burns", Salary = 299999999 };
mrBurns.Salary.ShouldBeGreaterThanOrEqualTo(300000000);
```

--------------------------------

### ShouldBe for TimeSpan with Tolerance

Source: https://docs.shouldly.org/documentation/equality/shouldbe.md

Asserts that a TimeSpan value is within a specified TimeSpan tolerance of an expected value. This is helpful when comparing durations that might have minor differences.

```cs
var timeSpan = TimeSpan.FromHours(1);
timeSpan.ShouldBe(timeSpan.Add(TimeSpan.FromHours(1.1d)), TimeSpan.FromHours(1));
```

--------------------------------

### Func Extension ShouldNotThrow

Source: https://docs.shouldly.org/documentation/exceptions/notthrow.md

This extension method allows you to assert that a Func delegate does not throw an exception. It is called directly on the Func.

```cs
string? name = null;
var func = () => new Person(name!);
func.ShouldNotThrow();
```

--------------------------------

### Check if a nullable value type is not null

Source: https://docs.shouldly.org/documentation/equality/null.md

Use ShouldNotBeNull to assert that a nullable value type is not null. This will throw an exception if the value is null. The unwrapped value is returned for chaining.

```cs
int? myRef = null;
myRef.ShouldNotBeNull();
```

--------------------------------

### Disable Line Ending Normalization

Source: https://docs.shouldly.org/documentation/equality/matchapproved.md

Use this to perform a line-ending sensitive comparison, opting out of Shouldly's default behavior.

```csharp
toVerify.ShouldMatchApproved(c => c.DoNotIgnoreLineEndings())
```

--------------------------------

### Chain assertions after checking for non-null reference type

Source: https://docs.shouldly.org/documentation/equality/null.md

ShouldNotBeNull returns the non-null value, allowing for chaining of further assertions on the result.

```cs
var myRef = (string?)"1234";
myRef.ShouldNotBeNull().Length.ShouldBe(5);
```

--------------------------------

### ShouldBeGreaterThan Assertion

Source: https://docs.shouldly.org/documentation/equality/greaterlessthan.md

Use `ShouldBeGreaterThan` to assert that a value is strictly greater than a specified value. This assertion fails if the value is equal to or less than the specified value.

```cs
var mrBurns = new Person { Name = "Mr. Burns", Salary = 30000 };
mrBurns.Salary.ShouldBeGreaterThan(300000000);
```

--------------------------------

### ShouldBeInRange Assertion

Source: https://docs.shouldly.org/documentation/equality/inrange.md

Use `ShouldBeInRange` to assert that a value is within a specified inclusive range. This is the inverse of `ShouldNotBeInRange`.

```cs
var homer = new Person { Name = "Homer", Salary = 300000000 };
homer.Salary.ShouldBeInRange(30000, 40000);
```

--------------------------------

### Check if a dictionary contains a specific key

Source: https://docs.shouldly.org/documentation/dictionary/containkey.md

Use ShouldContainKey to assert that a dictionary contains a given key. This is useful for validating dictionary state before performing operations that rely on the key's existence.

```cs
var websters = new Dictionary<string, string> { { "Embiggen", "To empower or embolden." } };
websters.ShouldContainKey("Cromulent");
```

--------------------------------

### Check if a nullable value type is null

Source: https://docs.shouldly.org/documentation/equality/null.md

Use ShouldBeNull to assert that a nullable value type is null. This will throw an exception if the value is not null.

```cs
int? nullableValue = 42;
ullableValue.ShouldBeNull();
```

--------------------------------

### Check if an object is assignable to a type

Source: https://docs.shouldly.org/documentation/equality/assignableto.md

Use ShouldBeAssignableTo to assert that an object can be assigned to a specific type. This is useful for verifying inheritance or interface implementation.

```cs
var theSimpsonsDog = new Person { Name = "Santas little helper" };
theSimpsonsDog.ShouldBeAssignableTo<Pet>();
```

--------------------------------

### ShouldContain Element

Source: https://docs.shouldly.org/documentation/enumerable/contain.md

Use ShouldContain to assert that a collection includes a specific element. Ensure the element is present in the list.

```cs
var mrBurns = new Person { Name = "Mr.Burns", Salary = 3000000 };
var kentBrockman = new Person { Name = "Kent Brockman", Salary = 3000000 };
var homer = new Person { Name = "Homer", Salary = 30000 };
var millionaires = new List<Person> { kentBrockman, homer };
millionaires.ShouldContain(mrBurns);
```

--------------------------------

### ShouldNotContain Element

Source: https://docs.shouldly.org/documentation/enumerable/contain.md

Use ShouldNotContain to assert that a collection does not include a specific element. This is useful for verifying the absence of an item.

```cs
var homerSimpson = new Person { Name = "Homer" };
var homerGlumplich = new Person { Name = "Homer" };
var lenny = new Person { Name = "Lenny" };
var carl = new Person { Name = "carl" };
var clubOfNoHomers = new List<Person> { homerSimpson, homerGlumplich, lenny, carl };
clubOfNoHomers.ShouldNotContain(homerSimpson);
```

--------------------------------

### Exception when collection is not unique

Source: https://docs.shouldly.org/documentation/enumerable/unique.md

When `ShouldBeUnique()` is called on a collection with duplicate elements, it throws an `AssertionException`. The exception message clearly indicates which elements were duplicated, aiding in debugging.

```cs
simpsonsKids
    should be unique but
[Maggie]
    was duplicated
```

--------------------------------

### ShouldNotBeInRange Assertion

Source: https://docs.shouldly.org/documentation/equality/inrange.md

Use `ShouldNotBeInRange` to assert that a value is outside a specified inclusive range. This is the inverse of `ShouldBeInRange`.

```cs
var mrBurns = new Person { Name = "Mr. Burns", Salary = 30000 };
mrBurns.Salary.ShouldNotBeInRange(30000, 40000);
```

--------------------------------

### ShouldContainWithoutWhitespace String Assertion

Source: https://docs.shouldly.org/documentation/string/contain.md

Use ShouldContainWithoutWhitespace to assert that a string contains a specific substring after removing all whitespace from both strings. This is useful for comparing strings where whitespace might differ.

```cs
var target = "Homer Simpson";
target.ShouldContainWithoutWhitespace(" Bart Simpson ");
```

--------------------------------

### ShouldContain String Assertion

Source: https://docs.shouldly.org/documentation/string/contain.md

Use ShouldContain to assert that a string contains a specific substring. The comparison is case-insensitive by default.

```cs
var target = "Homer";
target.ShouldContain("Bart");
```

--------------------------------

### ShouldHaveSingleItem Assertion

Source: https://docs.shouldly.org/documentation/enumerable/have.md

Use ShouldHaveSingleItem to assert that a collection contains exactly one element. It throws an exception if the collection is empty or contains more than one element, providing details about the actual count and contents.

```cs
var maggie = new Person { Name = "Maggie" };
var homer = new Person { Name = "Homer" };
var simpsonsBabies = new List<Person> { homer, maggie };
simpsonsBabies.ShouldHaveSingleItem();
```

--------------------------------

### ShouldNotContain Element with Predicate

Source: https://docs.shouldly.org/documentation/enumerable/contain.md

Use ShouldNotContain with a predicate to assert that a collection does not contain any element satisfying a given condition. The predicate specifies the condition to check for absence.

```cs
var mrBurns = new Person { Name = "Mr.Burns", Salary = 3000000 };
var kentBrockman = new Person { Name = "Homer", Salary = 3000000 };
var homer = new Person { Name = "Homer", Salary = 30000 };
var millionaires = new List<Person> { mrBurns, kentBrockman, homer };
millionaires.ShouldNotContain(m => m.Salary < 1000000);
```

--------------------------------

### ShouldNotContain String Assertion

Source: https://docs.shouldly.org/documentation/string/contain.md

Use ShouldNotContain to assert that a string does not contain a specific substring. The comparison is case-insensitive by default.

```cs
var target = "Homer";
target.ShouldNotContain("Home");
```

--------------------------------

### ShouldBeSameAs Assertion in C#

Source: https://docs.shouldly.org/documentation/equality/sameas.md

Use ShouldBeSameAs to assert that two object references point to the same instance. This assertion will fail if the objects are different instances, even if they have the same values.

```cs
var principleSkinner = new Person { Name = "Armin Tamzarian" };
var seymourSkinner = new Person { Name = "Seymour Skinner" };
principleSkinner.ShouldBeSameAs(seymourSkinner);
```

--------------------------------

### ShouldNotBeOneOf Assertion

Source: https://docs.shouldly.org/documentation/enumerable/oneof.md

Use ShouldNotBeOneOf to assert that a value is not present within a given array of possibilities. This is helpful for ensuring an item is not part of a restricted set.

```cs
var apu = new Person { Name = "Apu" };
var homer = new Person { Name = "Homer" };
var skinner = new Person { Name = "Skinner" };
var barney = new Person { Name = "Barney" };
var wiggum = new Person { Name = "Wiggum" };
var theBeSharps = new List<Person> { apu, homer, skinner, barney, wiggum };
wiggum.ShouldNotBeOneOf(theBeSharps.ToArray());
```

--------------------------------

### Chain assertions after checking for non-null nullable value type

Source: https://docs.shouldly.org/documentation/equality/null.md

ShouldNotBeNull returns the unwrapped value of a nullable type, allowing for chaining of further assertions on the result.

```cs
SomeStruct? nullableValue = new SomeStruct { IntProperty = 41 };
ullableValue.ShouldNotBeNull().IntProperty.ShouldBe(42);
```

--------------------------------

### ShouldEndWith assertion in C#

Source: https://docs.shouldly.org/documentation/string/endwith.md

Use ShouldEndWith to assert that a string ends with a specific suffix. An exception is thrown if the string does not end with the expected suffix.

```cs
var target = "Homer";
target.ShouldEndWith("Bart");
```

--------------------------------

### ShouldContain Element with Predicate

Source: https://docs.shouldly.org/documentation/enumerable/contain.md

Use ShouldContain with a predicate to assert that a collection contains at least one element satisfying a given condition. The predicate is a lambda expression that defines the condition.

```cs
var homer = new Person { Name = "Homer", Salary = 30000 };
var moe = new Person { Name = "Moe", Salary = 20000 };
var barney = new Person { Name = "Barney", Salary = 0 };
var millionaires = new List<Person> { homer, moe, barney };
millionaires.ShouldContain(m => m.Salary > 1000000);
```

--------------------------------

### Assert Enum Does Not Have Flag

Source: https://docs.shouldly.org/documentation/equality/haveflag.md

Use ShouldNotHaveFlag to assert that an enum value does not contain a specific flag. This is useful for verifying the absence of a flag.

```cs
var actual = TestEnum.FlagOne;
var value = TestEnum.FlagOne;
actual.ShouldNotHaveFlag(value);
```

--------------------------------

### ShouldBeOneOf Assertion

Source: https://docs.shouldly.org/documentation/enumerable/oneof.md

Use ShouldBeOneOf to assert that a value is present within a given array of possibilities. This assertion is useful for validating that an item belongs to an expected set.

```cs
var apu = new Person { Name = "Apu" };
var homer = new Person { Name = "Homer" };
var skinner = new Person { Name = "Skinner" };
var barney = new Person { Name = "Barney" };
var theBeSharps = new List<Person> { homer, skinner, barney };
apu.ShouldBeOneOf(theBeSharps.ToArray());
```

--------------------------------

### ShouldNotBeSameAs Assertion in C#

Source: https://docs.shouldly.org/documentation/equality/sameas.md

Use ShouldNotBeSameAs to assert that two object references do not point to the same instance. This assertion will fail if the objects are the same instance, even if their values might differ.

```cs
var person = new Person { Name = "Armin Tamzarian" };
person.ShouldNotBeSameAs(person);
```

--------------------------------

### Assert Enum Has Flag

Source: https://docs.shouldly.org/documentation/equality/haveflag.md

Use ShouldHaveFlag to assert that an enum value contains a specific flag. Ensure the enum type supports flags.

```cs
var actual = TestEnum.FlagTwo;
var value = TestEnum.FlagOne;
actual.ShouldHaveFlag(value);
```

--------------------------------

### ShouldNotEndWith assertion in C#

Source: https://docs.shouldly.org/documentation/string/endwith.md

Use ShouldNotEndWith to assert that a string does not end with a specific suffix. An exception is thrown if the string unexpectedly ends with the specified suffix.

```cs
var target = "Homer Simpson";
target.ShouldNotEndWith("Simpson");
```
Tokens:
Raw