Merge branch 'main' into dev

# Conflicts:
#	docs/samples/tests/xunit/VerifyMarkupExamples.cs
#	docs/site/docs/verification/verify-component-state.md
#	docs/site/docs/verification/verify-markup.md

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>Hello World</p>"), TimeSpan.FromSeconds(2));
+    }
   }
 }

docs/samples/tests/xunit/VerifyMarkupExamples.cs

@@ -141,4 +141,4 @@ public void GetChangesSinceX()
         .ShouldBeRemoval("<li>Second item</li>");
     }
   }
-}
+}

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.

docs/site/docs/verification/verify-component-state.md

@@ -3,12 +3,49 @@ uid: verify-component-state
 title: Verifying the State of a Component Under Test
 ---
 
-# Verifying the State of a Component Under Test
+# Verifying the State of a Component
 
-Describe IRenderedComponent interface
+Calling [`RenderComponent<TComponent>`()](xref:Bunit.TestContext.RenderComponent``1(System.Action{Bunit.ComponentParameterBuilder{``0}})) on a <xref:Bunit.TestContext> or calling <xref:Bunit.Fixture.GetComponentUnderTest``1> on a <xref:Bunit.Fixture> returns an instance of the <xref:Bunit.IRenderedComponent`1> type. 
 
-Show Instance prop
+The <xref:Bunit.IRenderedComponent`1> type makes it possible to inspect the instance of the component under test (`TComponent`), and trigger re-renders explicitly.
 
-Warn against setting props directly
+> [!NOTE]
+> Since <xref:Bunit.IRenderedComponent`1> inherits from <xref:Bunit.IRenderedFragment>, all the markup verification techniques covered on the <xref:verify-markup> page also applies to the <xref:Bunit.IRenderedComponent`1> type.
 
-FindComponent/FindComponents
+## Inspecting the Component Under Test
+
+The <xref:Bunit.IRenderedComponentBase`1.Instance> property on the <xref:Bunit.IRenderedComponent`1> type provides access to the component under test. For example:
+
+```csharp
+using var ctx = new TestContext();
+
+IRenderedComponent<Alert> cut = ctx.RenderComponent<Alert>();
+
+Alert alert = cut.Instance;
+
+// Assert against <Alert /> instance
+```
+
+> [!WARNING]
+> While it is possible to set `[Parameter]` and `[CascadingParameter]` properties directly through the <xref:Bunit.IRenderedComponentBase`1.Instance> property on the <xref:Bunit.IRenderedComponent`1> type, doing so does not implicitly trigger a render and the component life-cycle methods are not called. 
+> 
+> The correct approach is to set parameters through the [`SetParametersAndRender()`](xref:Bunit.IRenderedComponentBase`1.SetParametersAndRender(Bunit.Rendering.ComponentParameter[])) methods. See the <xref:trigger-renders> page for more on this.
+
+## Finding Components in the Render Tree
+
+To get the instance of components nested inside the component under test, use the 
+[`FindComponent<TComponent>()`](xref:Bunit.RenderedFragmentExtensions.FindComponent``1(Bunit.IRenderedFragment)) and [`FindComponents<TComponent>()`](xref:Bunit.RenderedFragmentExtensions.FindComponents``1(Bunit.IRenderedFragment)) methods on the <xref:Bunit.IRenderedComponent`1> type. Suppose we have a `<TodoList>` component with `<Task>` components nested inside for each task in the todo list, then the `<Task>` components can be found like this:
+
+```csharp
+using var ctx = new TestContext();
+var cut = ctx.RenderComponent<TodoList>(parameter => parameter
+  .Add(p => p.Tasks, new [] { "Task 1", "Task 2" })
+);
+
+var tasks = cut.FindComponents<Task>();
+
+Assert.Equal(2, tasks.Count);
+```
+
+Both the [`FindComponent<TComponent>()`](xref:Bunit.RenderedFragmentExtensions.FindComponent``1(Bunit.IRenderedFragment)) and [`FindComponents<TComponent>()`](xref:Bunit.RenderedFragmentExtensions.FindComponents``1(Bunit.IRenderedFragment)) methods performs a **depth-first search** of the render tree, with the first method returning only the first found matching component, while latter returning all matching components in the render tree.
+Both the [`FindComponent<TComponent>()`](xref:Bunit.RenderedFragmentExtensions.FindComponent``1(Bunit.IRenderedFragment)) and [`FindComponents<TComponent>()`](xref:Bunit.RenderedFragmentExtensions.FindComponents``1(Bunit.IRenderedFragment)) methods performs a **depth-first search** of the render tree, with the first method returning only the first found matching component, while latter returning all matching components in the render tree.

docs/site/docs/verification/verify-markup.md

@@ -177,4 +177,4 @@ This is what happens in the test:
 7. A new snapshot is saved, replacing the previous one, with a another call to the <xref:Bunit.IRenderedFragment.SaveSnapshot> method.
 8. Finally the last item in the list is found and clicked, and the <xref:Bunit.IRenderedFragment.GetChangesSinceSnapshot> method is used to find the changes, a single diff, which is verified as a removal of the second item.
 
-As mentioned earlier, the `IDiff` assertion helpers are still experimental. Any feedback and suggestions for improvements should be directed to the [related issue](https://github.com/egil/bUnit/issues/84) on GitHub.
+As mentioned earlier, the `IDiff` assertion helpers are still experimental. Any feedback and suggestions for improvements should be directed to the [related issue](https://github.com/egil/bUnit/issues/84) on GitHub.