Faithlife.Testing

Faithlife.Testing uses the power of C# expression trees to help pinpoint exactly why your assertions are failing.

• Documentation
• Release Notes

Table of Contents

• Endorsements
• Why use Faithlife.Testing?
• Advanced Examples
  • Assertable<T>
  • Context
  • WaitUntil
• Limitations of Expressions

Endorsements

"AssertEx is such a blessing, [...] it feels like a whole new world of possibilities has opened up to me."

- Joseph Stewart

"My mind was blown the first time I tried out a failure with AssertEx in linqpad."

- Ryan Johnson

"Oh, wow. That's amazing."

- Patrick Nausha, upon learning how AssertEx handles boolean logic

Why use Faithlife.Testing?

Some of the main problems that Faithlife.Testing is attempting to solve is:

• The requirement to learn a new "syntax" when using a new test runner or assertion library.

  string actual = "ab";
  Assert.That(actual, Is.Not.Null.And.Length.AtLeast(3));

• Many assertion libraries have common pits of failure, like using something like Assert.True. You're never going to get a helpful failure message out of an assertion like that.

  bool isFrobbable = false;
  Assert.True(isFrobbable);
  ...
  Expected: True
  But was: False

• Needing to write "guard" assertions to get helpful failure messages. If you have a deeply nested object you want to assert on, you'd normally want to assert every property along the way isn't null, which can become quite tedious:

Assert.NotNull(foo);
Assert.NotNull(foo.Bar);
Assert.NotNull(foo.Bar.Baz);

• Having many assertions fail, but only seeing one failure-message. When multiple things fail, you want to see all the failures -- but no more than that.

var foo = new Foo
{
    Name = "name",
    Id = 1,
    Bar = null,
 }
 Assert.AreEqual("test", foo.Name);
 Assert.AreEqual(1, foo.Id);
 Assert.NotNull(foo.Bar.Baz);

With Faithlife.Testing, those problems go away!

• No learning a new syntax beyond calling AssertEx.IsTrue and AssertEx.HasValue, simply use C#!

  string actual = "ab";
  AssertEx.IsTrue(() => actual.Length >= 3);
  ...
  Expected:
  actual.Length >= 3
  
  Actual:
  actual.Length = 2

• No more checking boolean expression against IsTrue! Just run the boolean expression.

  bool isFrobbable = false;
  AssertEx.IsTrue(() => isFrobbable);
  ...
  Expected:
  isFrobbable
  
  Actual:
  isFrobbable = false

• There's no longer a need to use guard assertions so that you can know which property in a chain was the one that null.

  var foo = new Foo
  {
  Bar = null
  };
  AssertEx.HasValue(() => foo.Bar.Baz);
  ...
  Expected:
  foo.Bar.Baz != null
  
  Actual:
  foo.Bar = null

• AssertEx will deconstruct boolean logic to show exactly why each assertion failed, and will elide the branches which did not fail.

  var foo = new Foo
  {
  Name = "name",
  Id = 1,
  Bar = null,
  }
  AssertEx.IsTrue(() => foo.Name == "test" && foo.Id == 1 && foo.Bar.Baz != null);
  ...
  Expected:
  foo.Name == "test" && foo.Bar.Baz != null
  
  Actual:
  foo.Name = "name"
  foo.Bar = null

Advanced Examples

A common pattern in testing is to have methods for fetching data whose callers then assertions on it. Faithlife.Testing exposes tools for preserving helpful context that a single method alone often lack.

Assertable<T>

Assertable<T> allows methods to return values on which further assertions can be made.

Context

Helpful context -- in the form of name/value pairs displayed in assertion messages -- can be attached to an Assertable<T>, and can also be attached to all assertions made inside a using block.

WaitUntil

AssertEx.WaitUntil allows you to retry a function which fetches a value until all assertions chained on it pass.

Limitations of Expressions

Because Faithlife.Testing is based around expressions, some newer C# language features cannot be used inside assertions. These features can be used inside functions called by your expression -- just not inside the expression itself.

These features include:

• async/await - instead of using async/await in an expression, you can call a separate function to get an asynchronous value then make synchronous assertions on it.
• The null-coalescing operator -- instead of using the null-coalescing ?. operator, just let the NullReferenceExceptions fly! Faithlife.Testing will tell you exactly what was null. Use the null-forgiving operator (!) as needed to avoid compiler warnings.
• Modern pattern matching, e.g. is null, is not null, is "foo" or "bar", is { Year: 2023, Month: 8, Day: 24 }, etc.