Summary

Asserting on a delegate that returns a value task previously meant going through the Awaiting adapter or calling .AsTask() by hand, purely to reach the assertions that task-returning delegates already get directly. This gives value tasks the same first-class treatment, so ThrowAsync, NotThrowAsync, CompleteWithinAsync and friends work straight off a Func<ValueTask> or Func<ValueTask<T>>.

Closes #3269.

Reviewer note: this is a source-breaking change

Issue #3269 states that these delegate shapes "currently do not resolve to any existing Should() overload, so this is purely additive". That is not correct, and I want to flag it clearly rather than let it slip through.

AssertionExtensions already has a catch-all overload:

public static FunctionAssertions<T> Should<T>(this Func<T> func)

A Func<ValueTask> binds to it with T = ValueTask, and a Func<ValueTask<int>> binds with T = ValueTask<int>. So today this compiles:

Func<ValueTask> act = () => DoSomethingAsync();

act.Should().NotThrow();   // binds to FunctionAssertions<ValueTask>

It compiles, but it does not do what it looks like it does. FunctionAssertions<T> invokes the delegate and treats the returned value task as an ordinary return value. It never awaits it, so any exception thrown after the first suspension point goes unobserved and the assertion passes regardless. In other words, the existing binding is close to useless — but it is there, and people may have written it.

What changes

C# prefers a non-generic applicable overload over a generic one, so the new Should(this Func<ValueTask>) now wins. Two consequences:

1. Compile errors (CS1061). The synchronous members disappear from the returned type:

Anyone hitting this gets a loud compiler error and a one-line fix that also makes their test correct for the first time, so I think the break is worth taking.

2. A silent behaviour change on Subject. Members shared by both types — Subject, BeSameAs, Match, Satisfy — still compile but can now behave differently, because Subject no longer returns the delegate you passed in:

Func<ValueTask> act = () => DoSomethingAsync();

act.Should().Subject.Should().BeSameAs(act);   // passed before, fails now

This one I could not avoid. The asynchronous assertions derive from AsyncFunctionAssertions<TTask, TAssertions> where TTask : Task, so Subject is a Func<TTask> and a Func<ValueTask> can never be it. Preserving the original identity would need a whole new assertions type duplicating the existing async logic, which the issue explicitly rules out in favour of reusing the existing classes. Instead the adapter is documented in <remarks> on both overloads and pinned down by specs, so the behaviour is intentional rather than incidental.

Note this is source-breaking only. No existing type, member or signature is removed, so already-compiled assemblies keep working; only recompilation is affected.

How I verified it

I built origin/main in Release, compiled a scratch console app against the resulting FluentAssertions.dll, then swapped the reference to this branch's build and recompiled the same call sites. act.Should().NotThrow() compiles against main and fails with CS1061 against this branch. Reflection over FunctionAssertions<ValueTask> versus NonGenericAsyncFunctionAssertions produced the member table above.

What I would like you to decide

The api-approved label on #3269 was granted on the assumption that the change is additive. Given it is not, please confirm you are happy to take the break in the next release — the signatures themselves are unchanged from what was approved.

Design notes

Value tasks are common in modern, performance-sensitive code, but there was no direct entry point for them, which made the assertions harder to discover and inconsistent with their task-based counterparts.

Two new entry points accept a value-task-returning delegate and reuse the existing asynchronous assertions, so behaviour, chaining and failure messages stay identical to the task-based ones. The returned value task is converted exactly once per invocation, which respects the rule that a value task must not be awaited more than once. A null delegate is still reported as <null> rather than throwing.

Verification

• 15 new specs cover throwing, not throwing, completing within a time limit, generic results, null delegates, the delegate being invoked exactly once, and the adapted subject.
• FluentAssertions.Specs (6036 tests on net8.0/net6.0, 111 on net47), FluentAssertions.Equivalency.Specs and the API approval tests all pass.
• The release notes record the break under "Breaking Changes (for users)".
• Rebased onto the latest upstream/main; the only conflict was in the release notes, where this PR's "What's new" entry collided with a newly landed entry for HaveLineCount/ContainLine (Add HaveLineCount()/NotHaveLineCount() and ContainLine()/NotContainLine() to StringAssertions #3297) — resolved by keeping both.