Skip to content

docs: promote Equivalency to a top-level page #941

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vbreuss merged 7 commits into from
May 5, 2026
Merged

docs: promote Equivalency to a top-level page #941

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
9652541
docs: promote Equivalency to a top-level page
vbreuss May 5, 2026
4350356
docs: refine Equivalency page
vbreuss May 5, 2026
cb49b36
docs: correct immutability claim for EquivalencyOptions
vbreuss May 5, 2026
4166225
docs: standardize subject and exception naming
vbreuss May 5, 2026
533c633
docs: rethink object/equivalency examples around an Album/Music domain
vbreuss May 5, 2026
116c6f4
docs: dust the music theme into string, callback, and getting-started…
vbreuss May 5, 2026
abfa802
Fix review issue
vbreuss May 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions Docs/pages/01-getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,9 @@ Write your first expectation:

```csharp
[Fact]
public async Task SomeMethod_WhenInputIsInvalid_ShouldReturnFalse()
public async Task IsInLibrary_WhenAlbumIsMissing_ShouldReturnFalse()
{
bool result = SomeMethod("invalid input");
bool result = IsInLibrary("Unknown Album");

await Expect.That(result).IsFalse();
}
Expand All @@ -54,17 +54,17 @@ You can add a reason for all expectations, that will be included in the exceptio

```csharp
[Fact]
public async Task SomeMethod_WhenInputIsInvalid_ShouldReturnFalse()
public async Task IsInLibrary_WhenAlbumIsMissing_ShouldReturnFalse()
{
bool result = SomeMethod("invalid input");
bool result = IsInLibrary("Unknown Album");

await Expect.That(result).IsFalse().Because("the input was invalid");
await Expect.That(result).IsFalse().Because("the album is not in the library");
}
```

This will result in
> ```
> Expected result to
> be False, because the input was invalid,
> be False, because the album is not in the library,
> but it was True
> ```
44 changes: 22 additions & 22 deletions Docs/pages/03-collections.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,14 +65,14 @@ await Expect.That([1, 1, 1]).All().AreEqualTo(1);
```

You can also use a [custom comparer](/docs/expectations/common-types/object#custom-comparer) or
configure [equivalence](/docs/expectations/common-types/object#equivalence):
configure [equivalency](/docs/expectations/equivalency):

```csharp
IEnumerable<MyClass> values = //...
MyClass expected = //...
IEnumerable<Album> albums = //...
Album expected = //...

await Expect.That(values).All().AreEqualTo(expected).Equivalent();
await Expect.That(values).All().AreEqualTo(expected).Using(new MyClassComparer());
await Expect.That(albums).All().AreEqualTo(expected).Equivalent();
await Expect.That(albums).All().AreEqualTo(expected).Using(new AlbumComparer());
```

For strings, you can configure this expectation to ignore case, ignore newline style, ignoring leading or trailing
Expand Down Expand Up @@ -172,9 +172,9 @@ await Expect.That(["a", "B", "c"]).IsInAscendingOrder().Using(StringComparer.Ord
For objects, you can also verify the sort order on a member:

```csharp
MyClass[] values = //...
Album[] albums = //...

await Expect.That(values).IsInAscendingOrder(x => x.Value);
await Expect.That(albums).IsInAscendingOrder(x => x.Title);
```

*Note: The same expectation works also for `IAsyncEnumerable<T>`.*
Expand Down Expand Up @@ -204,14 +204,14 @@ await Expect.That(values).Contains(1).Between(1).And(5.Times());
```

You can also use a [custom comparer](/docs/expectations/common-types/object#custom-comparer) or
configure [equivalence](/docs/expectations/common-types/object#equivalence):
configure [equivalency](/docs/expectations/equivalency):

```csharp
IEnumerable<MyClass> values = //...
MyClass expected = //...
IEnumerable<Album> albums = //...
Album expected = //...

await Expect.That(values).Contains(expected).Equivalent();
await Expect.That(values).Contains(expected).Using(new MyClassComparer());
await Expect.That(albums).Contains(expected).Equivalent();
await Expect.That(albums).Contains(expected).Using(new AlbumComparer());
```

*Note: The same expectation works also for `IAsyncEnumerable<T>`.*
Expand Down Expand Up @@ -290,14 +290,14 @@ await Expect.That(values).DoesNotStartWith(2, 3);
```

You can also use a [custom comparer](/docs/expectations/common-types/object#custom-comparer) or
configure [equivalence](/docs/expectations/common-types/object#equivalence):
configure [equivalency](/docs/expectations/equivalency):

```csharp
IEnumerable<MyClass> values = //...
MyClass expected = //...
IEnumerable<Album> albums = //...
Album expected = //...

await Expect.That(values).StartsWith(expected).Equivalent();
await Expect.That(values).StartsWith(expected).Using(new MyClassComparer());
await Expect.That(albums).StartsWith(expected).Equivalent();
await Expect.That(albums).StartsWith(expected).Using(new AlbumComparer());
```

For strings, you can configure this expectation to ignore case, ignore newline style, ignoring leading or trailing
Expand All @@ -321,14 +321,14 @@ await Expect.That(values).DoesNotEndWith(3, 5);
```

You can also use a [custom comparer](/docs/expectations/common-types/object#custom-comparer) or
configure [equivalence](/docs/expectations/common-types/object#equivalence):
configure [equivalency](/docs/expectations/equivalency):

```csharp
IEnumerable<MyClass> values = //...
MyClass expected = //...
IEnumerable<Album> albums = //...
Album expected = //...

await Expect.That(values).EndsWith(expected).Equivalent();
await Expect.That(values).EndsWith(expected).Using(new MyClassComparer());
await Expect.That(albums).EndsWith(expected).Equivalent();
await Expect.That(albums).EndsWith(expected).Using(new AlbumComparer());
```

For strings, you can configure this expectation to ignore case, ignore newline style, ignoring leading or trailing
Expand Down
2 changes: 1 addition & 1 deletion Docs/pages/04-delegates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ await Expect.That(Act).ThrowsException().WithRecursiveInnerExceptions(innerExcep
You can recursively verify additional members of the exception:

```csharp
var exception = new MyException("outer", paramName: "paramName", hResult: 12345);
var exception = new CustomException("outer", paramName: "paramName", hResult: 12345);
void Act() => throw exception;

await Expect.That(Act).ThrowsException().WithParamName("paramName")
Expand Down
44 changes: 22 additions & 22 deletions Docs/pages/05-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,11 @@ class MyClass
public void OnThresholdReached(ThresholdReachedEventArgs e)
=> ThresholdReached?.Invoke(this, e);
}
MyClass sut = new MyClass();
MyClass subject = new MyClass();

// ↓ Records all events
IEventRecording<MyClass> recording = sut.Record().Events();
IEventRecording<MyClass> recording = sut.Record().Events(nameof(MyClass.ThresholdReached));
IEventRecording<MyClass> recording = subject.Record().Events();
IEventRecording<MyClass> recording = subject.Record().Events(nameof(MyClass.ThresholdReached));
// ↑ Records only the ThresholdReached event
```

Expand All @@ -32,10 +32,10 @@ You can verify that a recording recorded an event:

```csharp
// Start the recording
IEventRecording<MyClass> recording = sut.Record().Events();
IEventRecording<MyClass> recording = subject.Record().Events();

// Perform some action on the subject under test
sut.OnThresholdReached(new ThresholdReachedEventArgs());
subject.OnThresholdReached(new ThresholdReachedEventArgs());

// Expect that the ThresholdReached event was triggered at least once
await Expect.That(recording).Triggered(nameof(MyClass.ThresholdReached));
Expand All @@ -46,10 +46,10 @@ await Expect.That(recording).Triggered(nameof(MyClass.ThresholdReached));
You can filter the recorded events based on their parameters.

```csharp
IEventRecording<MyClass> recording = sut.Record().Events();
IEventRecording<MyClass> recording = subject.Record().Events();

sut.OnThresholdReached(new ThresholdReachedEventArgs(5));
sut.OnThresholdReached(new ThresholdReachedEventArgs(15));
subject.OnThresholdReached(new ThresholdReachedEventArgs(5));
subject.OnThresholdReached(new ThresholdReachedEventArgs(15));

await Expect.That(recording).Triggered(nameof(MyClass.ThresholdReached))
.WithParameter<ThresholdReachedEventArgs>(e => e.Threshold > 10);
Expand All @@ -60,12 +60,12 @@ await Expect.That(recording).Triggered(nameof(MyClass.ThresholdReached))
You can specify a timeout within the expected events should be triggered:

```csharp
IEventRecording<MyClass> recording = sut.Record().Events();
IEventRecording<MyClass> recording = subject.Record().Events();

_ = Task.Delay(2.Seconds()).ContinueWith(_ => {
// Trigger the events in the background
sut.OnThresholdReached(new ThresholdReachedEventArgs(5));
sut.OnThresholdReached(new ThresholdReachedEventArgs(15));
subject.OnThresholdReached(new ThresholdReachedEventArgs(5));
subject.OnThresholdReached(new ThresholdReachedEventArgs(15));
});

await Expect.That(recording).Triggered(nameof(MyClass.ThresholdReached))
Expand All @@ -83,12 +83,12 @@ the [event best practices](https://learn.microsoft.com/en-us/dotnet/standard/asy
you can filter the recorded events based on the sender (the first parameter):

```csharp
IEventRecording<MyClass> recording = sut.Record().Events();
IEventRecording<MyClass> recording = subject.Record().Events();

sut.OnThresholdReached(new ThresholdReachedEventArgs(5));
subject.OnThresholdReached(new ThresholdReachedEventArgs(5));

await Expect.That(recording).Triggered(nameof(MyClass.ThresholdReached))
.WithSender(s => s == sut);
.WithSender(s => s == subject);
```

### EventArgs
Expand All @@ -98,9 +98,9 @@ the [event best practices](https://learn.microsoft.com/en-us/dotnet/standard/asy
you can filter the recorded events based on their `EventArgs` (the second parameter):

```csharp
IEventRecording<MyClass> recording = sut.Record().Events();
IEventRecording<MyClass> recording = subject.Record().Events();

sut.OnThresholdReached(new ThresholdReachedEventArgs(5));
subject.OnThresholdReached(new ThresholdReachedEventArgs(5));

await Expect.That(recording).Triggered(nameof(MyClass.ThresholdReached))
.With<ThresholdReachedEventArgs>(e => e < 10);
Expand All @@ -111,10 +111,10 @@ await Expect.That(recording).Triggered(nameof(MyClass.ThresholdReached))
You can verify that an event was recorded a specific number of times

```csharp
IEventRecording<MyClass> recording = sut.Record().Events();
IEventRecording<MyClass> recording = subject.Record().Events();

sut.OnThresholdReached(new ThresholdReachedEventArgs(5));
sut.OnThresholdReached(new ThresholdReachedEventArgs(15));
subject.OnThresholdReached(new ThresholdReachedEventArgs(5));
subject.OnThresholdReached(new ThresholdReachedEventArgs(15));

await Expect.That(recording).Triggered(nameof(MyClass.ThresholdReached))
.Between(1).And(2.Times();
Expand All @@ -135,11 +135,11 @@ Included are some overloads for the [
event:

```csharp
MyClass sut = // ...implements INotifyPropertyChanged
IEventRecording<MyClass> recording = sut.Record().Events();
MyClass subject = // ...implements INotifyPropertyChanged
IEventRecording<MyClass> recording = subject.Record().Events();

// do something that triggers the PropertyChanged event
sut.Execute();
subject.Execute();

await Expect.That(recording).TriggeredPropertyChanged()
.Because("it should trigger the PropertyChanged event for any property name");
Expand Down
Loading