feat: Add overloads to InvokeAsync with a return value (#1305)

* Add overloads to InvokeAsync with a return value

Closes #1296

* Add more docs for InvokeAsync, fix line numbers in code references

* Update wording

Author: Jcparkyn

CHANGELOG.md

@@ -14,6 +14,10 @@ All notable changes to **bUnit** will be documented in this file. The project ad
 
 - When the `TestContext` was disposed, the Blazor Renderer itself didn't dispose components under test. By [@linkdotnet](https://github.com/linkdotnet).
 
+### Added
+
+- New overloads for `IRenderedFragmentBase.InvokeAsync` that allow retrieving the work item's return value. By [@jcparkyn](https://github.com/jcparkyn).
+
 ## [1.25.3] - 2023-11-14
 
 -   Upgrade all .NET 8 preview dependencies to .NET 8 stable.

docs/samples/components/CalcWithLoading.razor

@@ -0,0 +1,16 @@
+<output>@(result is null ? "Loading" : result.ToString())</output>
+
+@code
+{
+  int? result = 0;
+
+  public async Task Calculate(int x, int y)
+  {
+      result = null;
+      StateHasChanged();
+      // Simulate an asynchronous operation, like fetching data.
+      await Task.Delay(500);
+      result = x + y;
+      StateHasChanged();
+  }
+}

docs/samples/components/CalcWithReturnValue.razor

@@ -0,0 +1,13 @@
+<output>@result</output>
+
+@code
+{
+  int result = 0;
+
+  public int Calculate(int x, int y)
+  {
+    result = x + y;
+    StateHasChanged();
+    return result;
+  }
+}

docs/samples/tests/xunit/ReRenderTest.cs

@@ -25,7 +25,7 @@ public void RenderAgainUsingRender()
   [Fact]
   public void RenderAgainUsingSetParametersAndRender()
   {
-    // Arrange - renders the Heading component
+    // Arrange - renders the Item component
     var cut = RenderComponent<Item>(parameters => parameters
       .Add(p => p.Value, "Foo")
     );
@@ -42,7 +42,7 @@ public void RenderAgainUsingSetParametersAndRender()
   [Fact]
   public void RendersViaInvokeAsync()
   {
-    // Arrange - renders the Heading component
+    // Arrange - renders the Calc component
     var cut = RenderComponent<Calc>();
 
     // Indirectly re-renders through the call to StateHasChanged
@@ -51,4 +51,34 @@ public void RendersViaInvokeAsync()
 
     cut.MarkupMatches("<output>3</output>");
   }
+
+  [Fact]
+  public async Task RendersViaInvokeAsyncWithReturnValue()
+  {
+    // Arrange - renders the CalcWithReturnValue component
+    var cut = RenderComponent<CalcWithReturnValue>();
+
+    // Indirectly re-renders and returns a value.
+    var result = await cut.InvokeAsync(() => cut.Instance.Calculate(1, 2));
+
+    Assert.Equal(3, result);
+    cut.MarkupMatches("<output>3</output>");
+  }
+
+  [Fact]
+  public async Task RendersViaInvokeAsyncWithLoading()
+  {
+    // Arrange - renders the CalcWithLoading component
+    var cut = RenderComponent<CalcWithLoading>();
+
+    // Indirectly re-renders and returns the task returned by Calculate().
+    // The explicit <Task> here is important, otherwise the call to Calculate()
+    // will be awaited automatically.
+    var task = await cut.InvokeAsync<Task>(() => cut.Instance.Calculate(1, 2));
+    cut.MarkupMatches("<output>Loading</output>");
+
+    // Wait for the task to complete.
+    await task;
+    cut.WaitForAssertion(() => cut.MarkupMatches("<output>3</output>"));
+  }
 }

docs/site/docs/interaction/trigger-renders.md

@@ -19,7 +19,7 @@ Let's look at how to use each of these methods to cause a re-render.
 
 The [`Render()`](xref:Bunit.RenderedComponentRenderExtensions.Render``1(Bunit.IRenderedComponentBase{``0})) method tells the renderer to re-render the component, i.e. go through its life-cycle methods (except for `OnInitialized()` and `OnInitializedAsync()` methods). To use it, do the following:
 
-[!code-csharp[](../../../samples/tests/xunit/ReRenderTest.cs?start=17&end=23&highlight=5)]
+[!code-csharp[](../../../samples/tests/xunit/ReRenderTest.cs?start=16&end=22&highlight=5)]
 
 The highlighted line shows the call to [`Render()`](xref:Bunit.RenderedComponentRenderExtensions.Render``1(Bunit.IRenderedComponentBase{``0})).
 
@@ -30,7 +30,7 @@ The highlighted line shows the call to [`Render()`](xref:Bunit.RenderedComponent
 
 The [`SetParametersAndRender(...)`](xref:Bunit.RenderedComponentRenderExtensions.SetParametersAndRender``1(Bunit.IRenderedComponentBase{``0},System.Action{Bunit.ComponentParameterCollectionBuilder{``0}})) methods tells the renderer to re-render the component with new parameters, i.e. go through its life-cycle methods (except for `OnInitialized()` and `OnInitializedAsync()` methods), passing the new parameters — _but only the new parameters_ — to the `SetParametersAsync()` method. To use it, do the following:
 
-[!code-csharp[](../../../samples/tests/xunit/ReRenderTest.cs?start=30&end=40&highlight=7-9)]
+[!code-csharp[](../../../samples/tests/xunit/ReRenderTest.cs?start=29&end=39&highlight=7-9)]
 
 The highlighted line shows the call to [`SetParametersAndRender()`](xref:Bunit.RenderedComponentRenderExtensions.SetParametersAndRender``1(Bunit.IRenderedComponentBase{``0},System.Action{Bunit.ComponentParameterCollectionBuilder{``0}})), which is also available as a version that takes the zero or more component parameters, e.g. created through the component parameter factory helper methods, if you prefer that method of passing parameters.
 
@@ -51,9 +51,25 @@ Let’s look at an example of this, using the `<Calc>` component listed below:
 
 To invoke the `Calculate()` method on the component instance, do the following:
 
-[!code-csharp[](../../../samples/tests/xunit/ReRenderTest.cs?start=47&end=53&highlight=5)]
+[!code-csharp[](../../../samples/tests/xunit/ReRenderTest.cs?start=46&end=52&highlight=5)]
 
 The highlighted line shows the call to `InvokeAsync()`, which is passed an `Action` delegate that calls the `Calculate` method.
 
 > [!TIP]
 > The instance of a component under test is available through the <xref:Bunit.IRenderedComponentBase`1.Instance> property.
+
+### Advanced use cases
+
+In some scenarios, the method being invoked may also return a value, as demonstrated in the following example.
+
+[!code-cshtml[CalcWithReturnValue.razor](../../../samples/components/CalcWithReturnValue.razor)]
+
+Testing this scenario follows the same procedure as before, with the addition of using the return value from `InvokeAsync()`:
+
+[!code-csharp[](../../../samples/tests/xunit/ReRenderTest.cs?start=59&end=65&highlight=4)]
+
+This can also be used to assert intermediate states during an asynchronous operation, like the example below:
+
+[!code-cshtml[CalcWithLoading.razor](../../../samples/components/CalcWithLoading.razor)]
+
+[!code-csharp[](../../../samples/tests/xunit/ReRenderTest.cs?start=71&end=82&highlight=7)]

src/bunit.core/Extensions/RenderedFragmentInvokeAsyncExtensions.cs

@@ -36,4 +36,34 @@ public static Task InvokeAsync(this IRenderedFragmentBase renderedFragment, Func
 		return renderedFragment.Services.GetRequiredService<ITestRenderer>()
 			.Dispatcher.InvokeAsync(workItem);
 	}
+
+	/// <summary>
+	/// Invokes the given <paramref name="workItem"/> in the context of the associated <see cref="ITestRenderer"/>.
+	/// </summary>
+	/// <param name="renderedFragment">The rendered component whose dispatcher to invoke with.</param>
+	/// <param name="workItem">The work item to execute on the renderer's thread.</param>
+	/// <returns>A <see cref="Task"/> that will be completed when the action has finished executing, with the return value from <paramref name="workItem"/>.</returns>
+	public static Task<T> InvokeAsync<T>(this IRenderedFragmentBase renderedFragment, Func<T> workItem)
+	{
+		if (renderedFragment is null)
+			throw new ArgumentNullException(nameof(renderedFragment));
+
+		return renderedFragment.Services.GetRequiredService<ITestRenderer>()
+			.Dispatcher.InvokeAsync(workItem);
+	}
+
+	/// <summary>
+	/// Invokes the given <paramref name="workItem"/> in the context of the associated <see cref="ITestRenderer"/>.
+	/// </summary>
+	/// <param name="renderedFragment">The rendered component whose dispatcher to invoke with.</param>
+	/// <param name="workItem">The work item to execute on the renderer's thread.</param>
+	/// <returns>A <see cref="Task"/> that will be completed when the action has finished executing, with the return value from <paramref name="workItem"/>.</returns>
+	public static Task<T> InvokeAsync<T>(this IRenderedFragmentBase renderedFragment, Func<Task<T>> workItem)
+	{
+		if (renderedFragment is null)
+			throw new ArgumentNullException(nameof(renderedFragment));
+
+		return renderedFragment.Services.GetRequiredService<ITestRenderer>()
+			.Dispatcher.InvokeAsync(workItem);
+	}
 }