Await anything & custom awaitable types

[stakx]

This is an improved redo of my previous PR #1008, and closes #1007.

What is this?

This PR achieves "await anything, anywhere" for Moq. It allows you to await tasks and other custom awaitable types right inside setup expressions:

using static Moq.AwaitOperator;

var mock = new Mock<ICommandBus>();
var x = mock.Object;

mock.Setup(_ => Await(_.SubmitAsync(It.IsAny<Command>()))).Returns("ok");
                ¨¨¨¨¨ ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
                await x.SubmitAsync(    someCommand    );    // => "ok"

If the await keyword were supported in LINQ expression trees, we wouldn't need a substitute method; but this is probably as close as we can get to C# syntax today.

See #1007 for a few more examples how to use this.

Benefits over the existing async API (.ReturnsAsync, .ThrowsAsync, etc.)

• Using Await, you can chain across async calls inside a single setup expressions; something that the existing APIs don't cover at all:

  bird.Setup(b => Await(b.WaitForDaylightAsync()).StartSinging());

• It works in places where there currently aren't any dedicated async methods, e.g. in Mock.Of:

  Mock.Of<Restaurant>(r => Await(r.CountTeaCupsAsync()) == 734);

• The existing dedicated async methods aren't as feature-complete as the main setup API, and bringing them up to feature parity is a constant effort. Because Await is designed in a way that does not add any new setup methods, any feature added to the main API should automatically work for async methods, too.

Writing a custom await operator: task.Result() instead of .Await(task)

Would you rather have your setup look like this?

-mock.Setup(_ => Await(_.SubmitAsync(It.IsAny<Command>())        )).Returns("ok");
+mock.Setup(_ =>       _.SubmitAsync(It.IsAny<Command>()).Result()).Returns("ok");

This is fairly easy to do. Simply add this to your code:

static class ResultExtension
{
    public static TResult Result<TResult>(this Task<TResult> task) => task.Result;
    public static TResult Result<TResult>(this ValueTask<TResult> task) => task.Result;
}

Note that custom await-like operators need to return an actual value in order to work properly with .SetupSet, .SetupAdd, and .SetupRemove. In all other cases, the representation of your await method in the setup expression will only get inspected, but never actually called. (And even when it does get called by .SetupSet and friends, the passed-in tasks / awaitable should already have completed successfully, so .Result will be non-blocking.)

Custom awaitable types

If you have any custom awaitable type that you want to use with Moq, you'll have to provide a little guidance and register a dedicated handler. Say this is your custom awaitable:

partial class Cup<TContents>
{
    public TContents Contents => …
    public CupAwaiter<TContents> GetAwaiter();
}

You will need to instruct Moq...

1. how to create a successfully completed Cup<>,
2. how to create a faulted Cup<>, and
3. how to get the TContents value out of an existing Cup<>.

This is done by registering an implementation of Moq.Async.AwaitableHandler:

class CupHandler<TContents> : AwaitableHandler
{
    public override Type ResultType => typeof(TContents);
    public override object CreateCompleted(object contents) => new Cup<TContents>((TContents)contents);
    public override object CreateFaulted(Exception exception) => …
}

A third method TryGetResult for extracting the TContents value is provided by the base class. (It will attempt to fetch the result via the awaiter.) Consider providing your own implementation for better performance.

Once you register your handler with the Moq infrastructure, it will recognize your type and be able to provide default values etc.:

AwaitableHandler.Register(
    typeof(Cup<>),
    type => Activator.CreateInstance(typeof(CupHandler<>).MakeGenericType(type.GetGenericArguments())));

If you want to await your cups in setup expressions, you'll need a custom Await method for static type safety:

public static class AwaitCupOperator
{
    public static TContents Await<TContents>(Cup<TContents> cup) => cup.Contents;
}

(As mentioned above, the return value is only a dummy value to help along .SetupSet and friends.)

You're done:

using static AwaitCupOperator;

mock.Setup(m => Await(m.OrderCupAsync<Tea>()).Drink()).Callback(() => Console.WriteLine("Splendid!");
var tea = await mock.Object.OrderCupAsync<Tea>();  // this `tea` was made by the mock's default value provider
tea.Drink();  // => Splendid!

[stakx]

An AwaitExpression appears to get thrown away here. This might cause the "await" to disappear from the resulting setup's Expression.

[stakx]

Perhaps, for overall consistency, all setup expressions should be post-processed to rewrite Await calls as (await …). That might not be worth the trouble if we later decide to go in the oppsosite direction (i.e. if we want to try and preserve the original Await method identity in expression trees reconstructed from delegates).