Merge branch 'main' into dev

Author: egil

docs/samples/components/AsyncData.razor

@@ -0,0 +1,12 @@
+<p>@text</p>
+
+@code
+{
+  string text = string.Empty;
+  [Parameter] public Task<string> TextService { get; set; }
+
+  protected override async Task OnInitializedAsync()
+  {
+    text = await TextService;
+  }
+}

docs/samples/components/ImparativeCalc.razor

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

docs/samples/tests/xunit/AsyncDataTest.cs

@@ -0,0 +1,52 @@
+using Microsoft.AspNetCore.Components.Web;
+using Xunit;
+using Bunit;
+using System;
+using System.Threading.Tasks;
+
+namespace Bunit.Docs.Samples
+{
+  public class AsyncDataTest
+  {
+    [Fact]
+    public void LoadDataAsync()
+    {
+      // Arrange
+      using var ctx = new TestContext();
+      var textService = new TaskCompletionSource<string>();
+      var cut = ctx.RenderComponent<AsyncData>(parameters => parameters
+        .Add(p => p.TextService, textService.Task)
+      );      
+
+      // Act - set the awaited result from the text service
+      textService.SetResult("Hello World");
+
+      // Wait for state before continuing test
+      cut.WaitForState(() => cut.Find("p").TextContent == "Hello World");
+
+      // Assert - verify result has been set
+      cut.MarkupMatches("<p>Hello World</p>");
+    }
+    
+    [Fact]
+    public void LoadDataAsyncWithTimeout()
+    {
+      // Arrange
+      using var ctx = new TestContext();
+      var textService = new TaskCompletionSource<string>();
+      var cut = ctx.RenderComponent<AsyncData>(parameters => parameters
+        .Add(p => p.TextService, textService.Task)
+      );      
+
+      // Act - set the awaited result from the text service
+      textService.SetResult("Long time");
+
+      // Wait for state before continuing test
+      cut.WaitForState(() => cut.Find("p").TextContent == "Long time", TimeSpan.FromSeconds(2));
+
+      // Assert - verify result has been set
+      cut.MarkupMatches("<p>Long time</p>");
+    }
+  
+  }
+}

docs/samples/tests/xunit/ReRenderTest.cs

@@ -0,0 +1,59 @@
+using Xunit;
+using Bunit;
+using System.Collections.Generic;
+using Microsoft.AspNetCore.Components;
+using Microsoft.AspNetCore.Components.Web;
+
+using static Bunit.ComponentParameterFactory;
+
+namespace Bunit.Docs.Samples
+{
+  public class ReRenderTest
+  {
+    [Fact]
+    public void RenderAgainUsingRender()
+    {
+      // Arrange - renders the Heading component
+      using var ctx = new TestContext();
+      var cut = ctx.RenderComponent<Heading>();
+      Assert.Equal(1, cut.RenderCount);
+
+      // Re-render without new parameters
+      cut.Render();
+
+      Assert.Equal(2, cut.RenderCount);
+    }
+
+    [Fact]
+    public void RenderAgainUsingSetParametersAndRender()
+    {
+      // Arrange - renders the Heading component
+      using var ctx = new TestContext();
+      var cut = ctx.RenderComponent<Item>(parameters => parameters
+        .Add(p => p.Value, "Foo")
+      );
+      cut.MarkupMatches("<span>Foo</span>");
+
+      // Re-render with new parameters
+      cut.SetParametersAndRender(parameters => parameters
+        .Add(p => p.Value, "Bar")
+      );
+
+      cut.MarkupMatches("<span>Bar</span>");
+    }
+
+    [Fact]
+    public void RendersViaInvokeAsync()
+    {
+      // Arrange - renders the Heading component
+      using var ctx = new TestContext();
+      var cut = ctx.RenderComponent<ImparativeCalc>();
+
+      // Indirectly re-renders through the call to StateHasChanged 
+      // in the Calculate(x, y) method.
+      cut.InvokeAsync(() => cut.Instance.Calculate(1, 2));
+
+      cut.MarkupMatches("<output>3</output>");
+    }
+  }
+}

docs/site/docs/interaction/awaiting-async-state.md

@@ -3,4 +3,42 @@ uid: awaiting-async-state
 title: Awaiting an Asynchronous State Change in a Component Under Test
 ---
 
-# Awaiting an Asynchronous State Change
+# Awaiting an Asynchronous State Change
+
+A test can fail if a component performs asynchronous renders, e.g. because it was awaiting an task to complete before continuing its render life-cycle. For example, if a component is waiting for a async web service to return data to it in the `OnInitializedAsync()` life-cycle method, before rendering it to the render tree.
+
+This happens because tests execute in the test framework's synchronization context and the test renderer executes renders in its own synchronization context.
+
+bUnit comes with two methods that helps deal with this issue, the [`WaitForState(Func<Boolean>, TimeSpan?)`](xref:Bunit.RenderedFragmentWaitForHelperExtensions.WaitForState(Bunit.IRenderedFragmentBase,System.Func{System.Boolean},System.Nullable{System.TimeSpan})) method covered on this page, and the [`WaitForAssertion(Action, TimeSpan?)`](xref:Bunit.RenderedFragmentWaitForHelperExtensions.WaitForAssertion(Bunit.IRenderedFragmentBase,System.Action,System.Nullable{System.TimeSpan})) method covered on the <xref:async-assertion> page.
+
+## Waiting for state using `WaitForState`
+
+The [`WaitForState(Func<Boolean>, TimeSpan?)`](xref:Bunit.RenderedFragmentWaitForHelperExtensions.WaitForState(Bunit.IRenderedFragmentBase,System.Func{System.Boolean},System.Nullable{System.TimeSpan})) method can be used to block and wait in a test method, until the provided predicate returns true, or the timeout is reached (the default timeout is one second).
+
+Let us look at an example. Consider the following `<AsyncData>` component, who awaits an async `TextService` in its `OnInitializedAsync()` life-cycle method. When the service returns the data, the component will automatically re-render, to update its rendered markup. 
+
+[!code-html[AsyncData.razor](../../../samples/components/AsyncData.razor)]
+
+To test the `<AsyncData>` component, do the following:
+
+[!code-csharp[AsyncDataTest.cs](../../../samples/tests/xunit/AsyncDataTest.cs?start=15&end=28&highlight=2,8,11,14)]
+
+This is what happens in the test:
+
+1. The test uses a `TaskCompletionSource<string>` to simulate an async web service.
+2. In the second highlighted line, the result is provided to the component through the `textService`. This causes the component to re-render.
+3. In the third highlighted line, the `WaitForState()` method is used to block the test until the predicate provided to it returns true.
+4. Finally, the tests assertion step can execute, knowing that the desired state has been reached.
+
+> [!NOTE]
+> The wait predicate and an assertion should not verify the same thing. Instead, use the [`WaitForAssertion(...)`](xref:Bunit.RenderedFragmentWaitForHelperExtensions.WaitForAssertion(Bunit.IRenderedFragmentBase,System.Action,System.Nullable{System.TimeSpan})) method covered on the <xref:async-assertion> page instead.
+ 
+### Controlling wait timeout
+
+The timeout, which defaults to one second, can be controlled by passing a `TimeSpan` as the second argument to the `WaitForState()` method, e.g.:
+
+[!code-csharp[](../../../samples/tests/xunit/AsyncDataTest.cs?start=45&end=45)]
+
+If the timeout is reached, a <xref:Bunit.Extensions.WaitForHelpers.WaitForFailedException> exception is thrown with the following error message:
+
+> The state predicate did not pass before the timeout period passed.

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

@@ -1,8 +1,59 @@
 ---
 uid: trigger-renders
-title: Triggering a Render Life-Cycle on a Component
+title: Triggering a Render Life Cycle on a Component
 ---
 
-# Triggering a Render Life-Cycle on a Component
+# Triggering a Render Life Cycle on a Component
 
-Describe how to trigger an explicit render life-cycle through the IRenderedComponent Render, SetParametersAndRender, and InvokeAsync methods.
+When a component under test is rendered, an instance of the <xref:Bunit.IRenderedComponent`1> type is returned. Through that, it is possible to cause the component under test to render again directly through the <xref:Bunit.IRenderedComponentBase`1.Render> method or one of the [`SetParametersAndRender(...)`](xref:Bunit.IRenderedComponentBase`1.SetParametersAndRender(Bunit.Rendering.ComponentParameter[])) methods or indirectly through the <xref:Bunit.IRenderedFragmentBase.InvokeAsync(System.Action)> method.
+
+> [!WARNING]
+> The `Render()` and `SetParametersAndRender()` methods are not available in the <xref:Bunit.IRenderedFragment> type that is returned when calling the _non_-generic version of `GetComponentUnderTest()` in `<Fixture>`-based Razor tests. Call the generic version of `GetComponentUnderTest<TComponent>()` to get a <xref:Bunit.IRenderedComponent`1>.
+
+> [!NOTE]
+> These methods are available and work the same in both C# and Razor-based tests. The examples below are from C# based tests only.
+
+Let's look at how to use each of these methods to cause a re-render.
+
+## Render
+
+The <xref:Bunit.IRenderedComponentBase`1.Render> 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=24&highlight=6)]
+
+The highlighted line shows the call to <xref:Bunit.IRenderedComponentBase`1.Render>. 
+
+> [!TIP]
+> The number of renders a component has been through can be inspected and verified using the <xref:Bunit.IRenderedFragmentBase.RenderCount> property.
+
+## SetParametersAndRender
+
+The [`SetParametersAndRender(...)`](xref:Bunit.IRenderedComponentBase`1.SetParametersAndRender(Bunit.Rendering.ComponentParameter[])) 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 to the `SetParametersAsync()` method, _but only the new parameters_. To use it, do the following:
+
+[!code-csharp[](../../../samples/tests/xunit/ReRenderTest.cs?start=31&end=42&highlight=8-10)]
+
+The highlighted line shows the call to <xref:Bunit.IRenderedComponentBase`1.SetParametersAndRender(System.Action{Bunit.ComponentParameterBuilder{`0}})>, which is also available as <xref:Bunit.IRenderedComponentBase`1.SetParametersAndRender(Bunit.Rendering.ComponentParameter[])> if you prefer that method of passing parameters.
+
+> [!NOTE]
+> Passing parameters to components through the [`SetParametersAndRender(...)`](xref:Bunit.IRenderedComponentBase`1.SetParametersAndRender(Bunit.Rendering.ComponentParameter[])) methods is identical to doing it with the [`RenderComponent<TComponent>(...)`](xref:Bunit.IRenderedComponentBase`1.SetParametersAndRender(Bunit.Rendering.ComponentParameter[])) methods, described in detail on the <xref:passing-parameters-to-components> page.
+
+## InvokeAsync
+
+Invoking methods on a component under test, which causes a render, e.g. by calling `StateHasChanged`, can result in the following error:
+
+> The current thread is not associated with the Dispatcher. Use InvokeAsync() to switch execution to the Dispatcher when triggering rendering or component state.
+
+If you receive this error, you need to invoke your method inside an `Action` delegate passed to the <xref:Bunit.IRenderedFragmentBase.InvokeAsync(System.Action)> method.
+
+Consider the `<ImparativeCalc>` component listed below:
+
+[!code-html[ImparativeCalc.razor](../../../samples/components/ImparativeCalc.razor)]
+
+To invoke the `Calculate()` method on the component instance, do the following:
+
+[!code-csharp[](../../../samples/tests/xunit/ReRenderTest.cs?start=49&end=56&highlight=6)]
+
+The highlighted line shows the call to <xref:Bunit.IRenderedFragmentBase.InvokeAsync(System.Action)>, 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.

docs/site/docs/toc.md

@@ -13,7 +13,7 @@
 # [Interaction](xref:interaction)
 ## [Trigger Event Handlers](xref:trigger-event-handlers)
 ## [Trigger Renders](xref:trigger-renders)
-## [Awaiting an Asynchronous State Change](xref:awaiting-async-state)
+## [Awaiting an Async State Change](xref:awaiting-async-state)
 
 # [Verifying output](xref:verification)
 ## [Verify Markup](xref:verify-markup)
@@ -22,7 +22,7 @@
 ## [Asynchronous Assertion of Changes](xref:async-assertion)
 
 # [Test Doubles](xref:test-doubles)
-## [Mocking Authorization](xref:mocking-auth)
+## [Faking Authorization](xref:faking-auth)
 ## [Mocking HttpClient](xref:mocking-httpclient)
 ## [Mocking IJsRuntime](xref:mocking-ijsruntime)
 ## [Mocking Localization](xref:mocking-localizer)