Docs: async assertions

Author: egil

docs/samples/tests/xunit/AsyncDataTest.cs

@@ -16,7 +16,7 @@ public void LoadDataAsync()
       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");
@@ -27,7 +27,7 @@ public void LoadDataAsync()
       // Assert - verify result has been set
       cut.MarkupMatches("<p>Hello World</p>");
     }
-    
+
     [Fact]
     public void LoadDataAsyncWithTimeout()
     {
@@ -36,7 +36,7 @@ public void LoadDataAsyncWithTimeout()
       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");
@@ -47,6 +47,23 @@ public void LoadDataAsyncWithTimeout()
       // Assert - verify result has been set
       cut.MarkupMatches("<p>Long time</p>");
     }
-  
+
+    [Fact]
+    public void LoadDataAsyncAssertion()
+    {
+      // 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 assertion to pass
+      cut.WaitForAssertion(() => cut.MarkupMatches("<p>Hello World</p>"));
+      cut.WaitForAssertion(() => cut.MarkupMatches("<p>xHello World</p>"), TimeSpan.FromSeconds(2));
+    }
   }
 }

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

@@ -5,16 +5,19 @@ title: Awaiting an Asynchronous State Change in a Component Under Test
 
 # 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.
+A test can fail if a component performs asynchronous renders, e.g. because it was awaiting a task to complete before continuing its render life-cycle. For example, if a component is waiting for an 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`
+## 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).
 
+> [!NOTE]
+> The `WaitForState()` method will try the predicate pass to it when the `WaitForState()` method is called, and every time the component under test renders.
+
 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)]
@@ -30,10 +33,10 @@ This is what happens in the test:
 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]
+> [!WARNING]
 > 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
+### 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.:
 

docs/site/docs/toc.md

@@ -19,7 +19,7 @@
 ## [Verify Markup](xref:verify-markup)
 ## [Verify Component State](xref:verify-component-state)
 ## [Customizing Semantic Comparison](xref:semantic-html-comparison)
-## [Asynchronous Assertion of Changes](xref:async-assertion)
+## [Assertion of Asynchronous Changes](xref:async-assertion)
 
 # [Test Doubles](xref:test-doubles)
 ## [Faking Authorization](xref:faking-auth)

docs/site/docs/verification/async-assertion.md

@@ -1,6 +1,43 @@
 ---
 uid: async-assertion
-title: Asynchronous Assertion of Change in a Component Under Test
+title: Assertion of Asynchronous Changes
 ---
 
-# Asynchronous Assertion of Change in a Component Under Test
+# Assertion of Asynchronous Changes
+
+A test can fail if a component performs asynchronous renders, e.g. because it was awaiting a task to complete before continuing its render life-cycle. For example, if a component is waiting for an 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 [`WaitForAssertion(Action, TimeSpan?)`](xref:Bunit.RenderedFragmentWaitForHelperExtensions.WaitForAssertion(Bunit.IRenderedFragmentBase,System.Action,System.Nullable{System.TimeSpan})) method covered on this page, and the [`WaitForState(Func<Boolean>, TimeSpan?)`](xref:Bunit.RenderedFragmentWaitForHelperExtensions.WaitForState(Bunit.IRenderedFragmentBase,System.Func{System.Boolean},System.Nullable{System.TimeSpan})) method covered on the <xref:awaiting-async-state> page.
+
+## Waiting for Assertion to Pass Using `WaitForAssertion`
+
+The [`WaitForAssertion(Action, TimeSpan?)`](xref:Bunit.RenderedFragmentWaitForHelperExtensions.WaitForAssertion(Bunit.IRenderedFragmentBase,System.Action,System.Nullable{System.TimeSpan})) method can be used to block and wait in a test method, until the provided assert action does not throw an exception, or the timeout is reached (the default timeout is one second).
+
+> [!NOTE]
+> The `WaitForAssertion()` method will try the assert action pass to it when the `WaitForAssertion()` method is called, and every time the component under test renders.
+
+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=54&end=65&highlight=3,9,12)]
+
+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. Finally, in the third highlighted line, the `WaitForAssertion()` method is used to block the test until the predicate assertion action runs without throwing an exception.
+ 
+### Controlling Wait Timeout
+
+The timeout, which defaults to one second, can be controlled by passing a `TimeSpan` as the second argument to the `WaitForAssertion()` method, e.g.:
+
+[!code-csharp[](../../../samples/tests/xunit/AsyncDataTest.cs?start=66&end=66)]
+
+If the timeout is reached, a <xref:Bunit.Extensions.WaitForHelpers.WaitForFailedException> exception is thrown with the following error message:
+
+> The assertion did not pass within the timeout period.