feat: support Within in verification expectations (#73)

Adds opt-in time-bounded (“Within”) verification support for Mockolate `VerificationResult` expectations by introducing a new `AndOrWithinResult` wrapper + `WithinOptions`, updating relevant constraints to run async verification, and extending the test suite to cover background-invocation scenarios.

### Key Changes:
- Introduces `AndOrWithinResult` + `WithinOptions` to enable `.Within(...)` and improved cancellation handling for verification expectations.
- Updates `ThatVerificationResult` constraints (`Once`/`Twice`/`Exactly`/`AtLeast*`/`Times`/`Between`) to support async verification via `IAsyncVerificationResult`.
- Expands/adjusts tests and API snapshots; adds `aweXpect.Chronology` for time helpers in tests.

Author: vbreuss

Directory.Packages.props

@@ -4,8 +4,9 @@
 	</PropertyGroup>
 	<ItemGroup>
 		<PackageVersion Include="aweXpect" Version="2.30.0" />
-		<PackageVersion Include="aweXpect.Core" Version="2.27.0" />
-		<PackageVersion Include="Mockolate" Version="1.4.1" />
+		<PackageVersion Include="aweXpect.Core" Version="2.28.0" />
+		<PackageVersion Include="aweXpect.Chronology" Version="1.0.0" />
+		<PackageVersion Include="Mockolate" Version="1.5.4" />
 	</ItemGroup>
 	<ItemGroup>
 		<PackageVersion Include="Nullable" Version="1.3.1" />

README.md

@@ -30,6 +30,39 @@ await That(mock.VerifyMock.Invoked.MyMethod()).AtMost(4.Times());  // At most 4
 await That(mock.VerifyMock.Invoked.MyMethod()).Exactly(2.Times()); // Exactly 2 times
 ```
 
+#### Asynchronous verification
+
+With `Within(TimeSpan timeout)`, you can check whether the expected number of calls occurred within a given time
+interval. This is useful for asynchronous or delayed invocations in the background.
+
+```csharp
+var mock = Mock.Create<IMyService>();
+
+// Start asynchronous calls, e.g., in a Task
+Task.Run(async () =>
+{
+    await Task.Delay(500);
+    mock.MyMethod();
+});
+
+// Verifies that MyMethod was called at least once within 1 second
+await That(mock.VerifyMock.Invoked.MyMethod())
+    .AtLeastOnce()
+    .Within(TimeSpan.FromSeconds(1));
+```
+
+Instead of a fixed time span, you can also provide a `CancellationToken` to limit how long the verification should wait
+for the expected interactions:
+
+```csharp
+var token = new CancellationTokenSource(TimeSpan.FromSeconds(1)).Token;
+
+// Verifies that MyMethod was called at least once within 1 second
+await That(mock.VerifyMock.Invoked.MyMethod())
+    .AtLeastOnce()
+    .WithCancellation(token);
+```
+
 ### Interaction order
 
 Verify that methods were called in a specific sequence:

Source/aweXpect.Mockolate/Options/WithinOptions.cs

@@ -0,0 +1,21 @@
+using System;
+using System.Threading;
+
+namespace aweXpect.Options;
+
+/// <summary>
+///     The options for a verification result which allows specifying a timeout and/or cancellation token for the
+///     verification.
+/// </summary>
+public class WithinOptions
+{
+	/// <summary>
+	///     The timeout that is applied to the verification.
+	/// </summary>
+	public TimeSpan? Timeout { get; set; }
+
+	/// <summary>
+	///     The cancellation token that is used to cancel the verification.
+	/// </summary>
+	public CancellationToken? CancellationToken { get; set; }
+}

Source/aweXpect.Mockolate/Results/AndOrWithinResult.cs

@@ -0,0 +1,55 @@
+using System;
+using System.Threading;
+using aweXpect.Core;
+using aweXpect.Options;
+
+namespace aweXpect.Results;
+
+/// <summary>
+///     The result of a verification result which allows specifying a timeout and/or cancellation token for the
+///     verification.
+/// </summary>
+/// <remarks>
+///     <seealso cref="AndOrResult{TCollection, TThat}" />
+/// </remarks>
+public class AndOrWithinResult<TType, TThat>(
+	ExpectationBuilder expectationBuilder,
+	TThat returnValue,
+	WithinOptions options)
+	: AndOrWithinResult<TType, TThat, AndOrWithinResult<TType, TThat>>(
+		expectationBuilder,
+		returnValue,
+		options);
+
+/// <inheritdoc cref="AndOrWithinResult{TType, TThat}" />
+public class AndOrWithinResult<TType, TThat, TSelf> : AndOrResult<TType, TThat>
+	where TSelf : AndOrWithinResult<TType, TThat, TSelf>
+{
+	private readonly WithinOptions _options;
+
+	/// <inheritdoc cref="AndOrWithinResult{TType, TThat, TSelf}" />
+	protected AndOrWithinResult(ExpectationBuilder expectationBuilder, TThat returnValue, WithinOptions options)
+		: base(expectationBuilder, returnValue)
+	{
+		_options = options;
+	}
+
+	/// <summary>
+	///     …within the given <paramref name="timeout" />.
+	/// </summary>
+	public TSelf Within(TimeSpan timeout)
+	{
+		_options.Timeout = timeout;
+		return (TSelf)this;
+	}
+
+	/// <summary>
+	///     …with the given <paramref name="cancellationToken" />.
+	/// </summary>
+	public new TSelf WithCancellation(CancellationToken cancellationToken)
+	{
+		_options.CancellationToken = cancellationToken;
+		base.WithCancellation(cancellationToken);
+		return (TSelf)this;
+	}
+}

Source/aweXpect.Mockolate/ThatVerificationResult.AtLeast.cs

@@ -1,5 +1,6 @@
 using aweXpect.Core;
 using aweXpect.Helpers;
+using aweXpect.Options;
 using aweXpect.Results;
 using Mockolate.Verify;
 
@@ -8,11 +9,16 @@ namespace aweXpect;
 public static partial class ThatVerificationResult
 {
 	/// <summary>
-	///     Verifies that the checked interaction happened at least the number of <paramref name="times"/>.
+	///     Verifies that the checked interaction happened at least the number of <paramref name="times" />.
 	/// </summary>
-	public static AndOrResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>> AtLeast<TVerify>(
-		this IThat<VerificationResult<TVerify>> subject, Times times)
-		=> new(subject.Get().ExpectationBuilder.AddConstraint((expectationBuilder, it, grammars)
-				=> new HasAtLeastConstraint<TVerify>(expectationBuilder, it, grammars, times.Value)),
-			subject);
+	public static AndOrWithinResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>>
+		AtLeast<TVerify>(this IThat<VerificationResult<TVerify>> subject, Times times)
+	{
+		WithinOptions options = new();
+		return new AndOrWithinResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>>(
+			subject.Get().ExpectationBuilder.AddConstraint((expectationBuilder, it, grammars)
+				=> new HasAtLeastConstraint<TVerify>(expectationBuilder, it, grammars, times.Value, options)),
+			subject,
+			options);
+	}
 }

Source/aweXpect.Mockolate/ThatVerificationResult.AtLeastOnce.cs

@@ -1,5 +1,6 @@
 using aweXpect.Core;
 using aweXpect.Helpers;
+using aweXpect.Options;
 using aweXpect.Results;
 using Mockolate.Verify;
 
@@ -10,9 +11,14 @@ public static partial class ThatVerificationResult
 	/// <summary>
 	///     Verifies that the checked interaction happened at least once.
 	/// </summary>
-	public static AndOrResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>> AtLeastOnce<TVerify>(
-		this IThat<VerificationResult<TVerify>> subject)
-		=> new(subject.Get().ExpectationBuilder.AddConstraint((expectationBuilder, it, grammars)
-				=> new HasAtLeastConstraint<TVerify>(expectationBuilder, it, grammars, 1)),
-			subject);
+	public static AndOrWithinResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>>
+		AtLeastOnce<TVerify>(this IThat<VerificationResult<TVerify>> subject)
+	{
+		WithinOptions options = new();
+		return new AndOrWithinResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>>(
+			subject.Get().ExpectationBuilder.AddConstraint((expectationBuilder, it, grammars)
+				=> new HasAtLeastConstraint<TVerify>(expectationBuilder, it, grammars, 1, options)),
+			subject,
+			options);
+	}
 }

Source/aweXpect.Mockolate/ThatVerificationResult.AtLeastTwice.cs

@@ -1,5 +1,6 @@
 using aweXpect.Core;
 using aweXpect.Helpers;
+using aweXpect.Options;
 using aweXpect.Results;
 using Mockolate.Verify;
 
@@ -10,9 +11,14 @@ public static partial class ThatVerificationResult
 	/// <summary>
 	///     Verifies that the checked interaction happened at least twice.
 	/// </summary>
-	public static AndOrResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>> AtLeastTwice<TVerify>(
-		this IThat<VerificationResult<TVerify>> subject)
-		=> new(subject.Get().ExpectationBuilder.AddConstraint((expectationBuilder, it, grammars)
-				=> new HasAtLeastConstraint<TVerify>(expectationBuilder, it, grammars, 2)),
-			subject);
+	public static AndOrWithinResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>>
+		AtLeastTwice<TVerify>(this IThat<VerificationResult<TVerify>> subject)
+	{
+		WithinOptions options = new();
+		return new AndOrWithinResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>>(
+			subject.Get().ExpectationBuilder.AddConstraint((expectationBuilder, it, grammars)
+				=> new HasAtLeastConstraint<TVerify>(expectationBuilder, it, grammars, 2, options)),
+			subject,
+			options);
+	}
 }

Source/aweXpect.Mockolate/ThatVerificationResult.AtMost.cs

@@ -8,10 +8,10 @@ namespace aweXpect;
 public static partial class ThatVerificationResult
 {
 	/// <summary>
-	///     Verifies that the checked interaction happened at most the number of <paramref name="times"/>.
+	///     Verifies that the checked interaction happened at most the number of <paramref name="times" />.
 	/// </summary>
-	public static AndOrResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>> AtMost<TVerify>(
-		this IThat<VerificationResult<TVerify>> subject, Times times)
+	public static AndOrResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>>
+		AtMost<TVerify>(this IThat<VerificationResult<TVerify>> subject, Times times)
 		=> new(subject.Get().ExpectationBuilder.AddConstraint((expectationBuilder, it, grammars)
 				=> new HasAtMostConstraint<TVerify>(expectationBuilder, it, grammars, times.Value)),
 			subject);

Source/aweXpect.Mockolate/ThatVerificationResult.AtMostOnce.cs

@@ -10,8 +10,8 @@ public static partial class ThatVerificationResult
 	/// <summary>
 	///     Verifies that the checked interaction happened at most once.
 	/// </summary>
-	public static AndOrResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>> AtMostOnce<TVerify>(
-		this IThat<VerificationResult<TVerify>> subject)
+	public static AndOrResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>>
+		AtMostOnce<TVerify>(this IThat<VerificationResult<TVerify>> subject)
 		=> new(subject.Get().ExpectationBuilder.AddConstraint((expectationBuilder, it, grammars)
 				=> new HasAtMostConstraint<TVerify>(expectationBuilder, it, grammars, 1)),
 			subject);

Source/aweXpect.Mockolate/ThatVerificationResult.AtMostTwice.cs

@@ -10,8 +10,8 @@ public static partial class ThatVerificationResult
 	/// <summary>
 	///     Verifies that the checked interaction happened at most twice.
 	/// </summary>
-	public static AndOrResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>> AtMostTwice<TVerify>(
-		this IThat<VerificationResult<TVerify>> subject)
+	public static AndOrResult<VerificationResult<TVerify>, IThat<VerificationResult<TVerify>>>
+		AtMostTwice<TVerify>(this IThat<VerificationResult<TVerify>> subject)
 		=> new(subject.Get().ExpectationBuilder.AddConstraint((expectationBuilder, it, grammars)
 				=> new HasAtMostConstraint<TVerify>(expectationBuilder, it, grammars, 2)),
 			subject);