Docs: Finished awaiting-async-state

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/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/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.