Updates docs with guide for using render tree property

egil · egil · commit 7168943deffb · 2020-10-24T13:40:48.000Z
diff --git a/docs/.editorconfig b/docs/.editorconfig
@@ -10,6 +10,7 @@ trim_trailing_whitespace = false
 
 [*.{cs,razor}]
 tab_size = 2
+indent_style = space
 dotnet_diagnostic.BL0001.severity = none
 dotnet_diagnostic.BL0002.severity = none
 dotnet_diagnostic.BL0003.severity = none
diff --git a/docs/samples/components/PrintCascadingValue.razor b/docs/samples/components/PrintCascadingValue.razor
@@ -0,0 +1,6 @@
+Cascading value: @Value
+@code 
+{
+  [CascadingParameter]
+  public string Value { get; set; }
+}
diff --git a/docs/samples/tests/mstest/BunitTestContext.cs b/docs/samples/tests/mstest/BunitTestContext.cs
@@ -6,7 +6,7 @@
 
 namespace Bunit.Docs.Samples
 {
-  public abstract class BunitTestContext : ITestContext, IDisposable
+  public abstract class BunitTestContext : IDisposable
   {
     private Bunit.TestContext _context;
 
diff --git a/docs/samples/tests/nunit/BunitTestContext.cs b/docs/samples/tests/nunit/BunitTestContext.cs
@@ -6,7 +6,7 @@
 
 namespace Bunit.Docs.Samples
 {
-  public abstract class BunitTestContext : ITestContext, IDisposable
+  public abstract class BunitTestContext : IDisposable
   {
     private Bunit.TestContext _context;
 
diff --git a/docs/samples/tests/razor/_Imports.razor b/docs/samples/tests/razor/_Imports.razor
@@ -8,5 +8,5 @@
 @using Microsoft.Extensions.DependencyInjection
 @using AngleSharp.Dom
 @using Bunit
-@using Bunit.TestDoubles.JSInterop
+@using Bunit.TestDoubles
 @using Xunit
diff --git a/docs/samples/tests/xunit/InjectAuthServiceTest.cs b/docs/samples/tests/xunit/InjectAuthServiceTest.cs
@@ -1,4 +1,4 @@
-﻿using Bunit.TestDoubles.Authorization;
+﻿using Bunit.TestDoubles;
 using System;
 using Xunit;
 
diff --git a/docs/samples/tests/xunit/RenderTreeTest.cs b/docs/samples/tests/xunit/RenderTreeTest.cs
@@ -0,0 +1,48 @@
+using Xunit;
+using Bunit;
+using System.Collections.Generic;
+using Microsoft.AspNetCore.Components;
+using Microsoft.AspNetCore.Components.Web;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Bunit.Docs.Samples
+{
+  public class RenderTreeTest
+  {
+    [Fact]
+    public void PrintCascadingValueTest()
+    {
+      using var ctx = new TestContext();
+
+      // Add a cascading value to the test contexts root render tree.
+      ctx.RenderTree.Add<CascadingValue<string>>(parameters => parameters
+        .Add(p => p.Value, "FOO")
+      );
+
+      // The component will be rendered as a chld of last 
+      // component added to the RenderTree property.
+      var cut = ctx.RenderComponent<PrintCascadingValue>();
+
+      // Verify that the cascading value was passed correctly.
+      cut.MarkupMatches($"Cascading value: FOO");
+    }
+
+    [Fact]
+    public void PrintCascadingValue2Test()
+    {
+      using var ctx = new TestContext();
+
+      // Add a cascading value to the test contexts root render tree.
+      ctx.RenderTree.TryAdd<CascadingValue<string>>(parameters => parameters
+        .Add(p => p.Value, "BAR?")
+      );
+
+      // The component will be rendered as a chld of last 
+      // component added to the RenderTree property.
+      var cut = ctx.RenderComponent<PrintCascadingValue>();
+
+      // Verify that the cascading value was passed correctly.
+      cut.MarkupMatches($"Cascading value: BAR?");
+    }
+  }
+}
diff --git a/docs/samples/tests/xunit/UserInfoTest.cs b/docs/samples/tests/xunit/UserInfoTest.cs
@@ -1,4 +1,4 @@
-using Bunit.TestDoubles.Authorization;
+using Bunit.TestDoubles;
 using Xunit;
 
 namespace Bunit.Docs.Samples
diff --git a/docs/samples/tests/xunit/UserRightsTest.cs b/docs/samples/tests/xunit/UserRightsTest.cs
@@ -1,4 +1,4 @@
-using Bunit.TestDoubles.Authorization;
+using Bunit.TestDoubles;
 using System.Security.Claims;
 using System.Globalization;
 using Xunit;
diff --git a/docs/samples/tests/xunit/bunit.docs.xunit.samples.csproj b/docs/samples/tests/xunit/bunit.docs.xunit.samples.csproj
@@ -15,6 +15,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="../../../../src/bunit.core/bunit.core.csproj" />
     <ProjectReference Include="../../../../src/bunit.web/bunit.web.csproj" />
     <ProjectReference Include="../../../../src/bunit.xunit/bunit.xunit.csproj" />
     <ProjectReference Include="../../components/bunit.docs.samples.csproj" />
diff --git a/docs/site/docs/providing-input/index.md b/docs/site/docs/providing-input/index.md
@@ -9,4 +9,5 @@ This section covers the various ways to provide input to a component under test.
 
 - **<xref:passing-parameters-to-components>:** This covers passing regular parameters, child content, cascading values, event callbacks, etc. This topic is mostly relevant when writing tests in C# only.
 - **<xref:inject-services>:** This covers injecting services into components under test. This topic is relevant for both Razor-based tests and C# only tests.
+- **<xref:root-render-tree>:** This covers how to modify the root render tree that components under tests are rendered in.
 - **<xref:configure-3rd-party-libs>:** This covers setting up 3rd party libraries in a bUnit testing scenario so that components under test that use them can be tested easily.
diff --git a/docs/site/docs/providing-input/root-render-tree.md b/docs/site/docs/providing-input/root-render-tree.md
@@ -0,0 +1,33 @@
+---
+uid: root-render-tree
+title: Controlling the Root Render Tree
+---
+
+# Controlling the Root Render Tree
+
+The root render tree, the render tree in which components under test are rendered, can be added to, before components are rendered with bUnit's test context. This is mostly useful when a component under test or a component it depends on, must be rendered inside another component, that provides a cascading value to it. 
+
+For example, when using Blazor’s authentication, it is common to add the `CascadingAuthenticationState` component higher up the render tree, such that it can provide authentication state to those components below it that needs it. Adding this through the <xref:Bunit.TestContext.RenderTree> property on the <xref:Bunit.TestContext> type makes it possible to add it once in a shared setup method, and not having to do so in every test method during the call to [`RenderComponent()`](xref:Bunit.TestContext.RenderComponent``1(System.Action{Bunit.ComponentParameterCollectionBuilder{``0}})).
+
+This can also be useful when writing tests that use a 3rd party component library, that require a special root component to be added to the render tree, but which otherwise doesn’t change between tests.
+
+## Adding a Component to the Root Render Tree
+
+The following example verifies that the `PrintCascadingValue` component correctly prints out the cascading value passed to it. This value is passed to it by adding the `CascadingValue<string>` component to the render tree and then rendering the `PrintCascadingValue` component. The `PrintCascadingValue` component looks like this:
+
+[!code-cshtml[PrintCascadingValue.razor](../../../samples/components/PrintCascadingValue.razor)]
+
+Here is the test that adds the `CascadingValue<string>` component to the render tree and then renders the `PrintCascadingValue` component.
+
+[!code-csharp[PrintCascadingValueTest.cs](../../../samples/tests/xunit/RenderTreeTest.cs#L15-L27)]
+
+> [!NOTE]
+> The call to [`Add`](xref:Bunit.Rendering.RootRenderTree.Add``1(System.Action{Bunit.ComponentParameterCollectionBuilder{``0}})) can be done in a common setup method, outside the context of the test method listed here, for easy reuse between tests.
+
+## Add Only if Not Already in Root Render Tree
+
+Sometimes common test setup logic exists outside the test class, perhaps abstracted away in other libraries. In those cases, the [`TryAdd`](xref:Bunit.Rendering.RootRenderTree.TryAdd``1(System.Action{Bunit.ComponentParameterCollectionBuilder{``0}})) can be used add the component to the render tree, _only if_ it has not already been added. [`TryAdd`](xref:Bunit.Rendering.RootRenderTree.TryAdd``1(System.Action{Bunit.ComponentParameterCollectionBuilder{``0}})) returns true if the component was added, false otherwise.
+
+[!code-csharp[](../../../samples/tests/xunit/RenderTreeTest.cs#L36-L38)]
+
+In the listing above, the cascading value `BAR?` is only added if there is not another `CascadingValue<string>` component added to the render tree already.
diff --git a/docs/site/docs/test-doubles/faking-auth.md b/docs/site/docs/test-doubles/faking-auth.md
@@ -15,7 +15,7 @@ The test implementation of Blazor's authentication and authorization can be put
 - **Authenticated** and **authorized** 
 - **Authenticated** and **authorized** with one or more **roles**, **claims**, and/or **policies**
 
-bUnit's authentication and authorization implementation is easily available by calling [`AddTestAuthorization()`](xref:Bunit.TestDoubles.Authorization.FakeAuthorizationExtensions.AddTestAuthorization(Bunit.TestServiceProvider)) on a test context's `Services` collection. This returns an instance of the <xref:Bunit.TestDoubles.Authorization.TestAuthorizationContext> type that allows you to control the authentication and authorization state for a test.
+bUnit's authentication and authorization implementation is easily available by calling [`AddTestAuthorization()`](xref:Bunit.TestDoubles.FakeAuthorizationExtensions.AddTestAuthorization(Bunit.TestServiceProvider)) on a test context's `Services` collection. This returns an instance of the <xref:Bunit.TestDoubles.TestAuthorizationContext> type that allows you to control the authentication and authorization state for a test.
 
 The following sections will show how to set each of these states in a test.
 
@@ -43,23 +43,23 @@ To set the state to authenticating and authorizing, do the following:
 
 [!code-csharp[UserInfoTest.cs](../../../samples/tests/xunit/UserInfoTest.cs?start=26&end=36&highlight=4)]
 
-After calling `AddTestAuthorization()`, the returned <xref:Bunit.TestDoubles.Authorization.TestAuthorizationContext> is used to set the authenticating and authorizing state through the <xref:Bunit.TestDoubles.Authorization.TestAuthorizationContext.SetAuthorizing> method.
+After calling `AddTestAuthorization()`, the returned <xref:Bunit.TestDoubles.TestAuthorizationContext> is used to set the authenticating and authorizing state through the <xref:Bunit.TestDoubles.TestAuthorizationContext.SetAuthorizing> method.
 
 ### Authenticated and Unauthorized State
 
 To set the state to authenticated and unauthorized, do the following:
 
 [!code-csharp[UserInfoTest.cs](../../../samples/tests/xunit/UserInfoTest.cs?start=42&end=52&highlight=4)]
 
-After calling `AddTestAuthorization()`, the returned <xref:Bunit.TestDoubles.Authorization.TestAuthorizationContext> is used to set the authenticated and unauthorized state through the <xref:Bunit.TestDoubles.Authorization.TestAuthorizationContext.SetAuthorized(System.String,Bunit.TestDoubles.Authorization.AuthorizationState)> method.
+After calling `AddTestAuthorization()`, the returned <xref:Bunit.TestDoubles.TestAuthorizationContext> is used to set the authenticated and unauthorized state through the <xref:Bunit.TestDoubles.TestAuthorizationContext.SetAuthorized(System.String,Bunit.TestDoubles.AuthorizationState)> method.
 
 ### Authenticated and Authorized state
 
 To set the state to authenticated and authorized, do the following:
 
 [!code-csharp[UserInfoTest.cs](../../../samples/tests/xunit/UserInfoTest.cs?start=58&end=68&highlight=4)]
 
-After calling `AddTestAuthorization()`, the returned <xref:Bunit.TestDoubles.Authorization.TestAuthorizationContext> is used to set the authenticated and authorized state through the <xref:Bunit.TestDoubles.Authorization.TestAuthorizationContext.SetAuthorized(System.String,Bunit.TestDoubles.Authorization.AuthorizationState)> method. 
+After calling `AddTestAuthorization()`, the returned <xref:Bunit.TestDoubles.TestAuthorizationContext> is used to set the authenticated and authorized state through the <xref:Bunit.TestDoubles.TestAuthorizationContext.SetAuthorized(System.String,Bunit.TestDoubles.AuthorizationState)> method. 
 
 Note, the second parameter, `AuthorizationState`, is optional, and defaults to `AuthorizationState.Authorized`, if not specified.
 
@@ -77,7 +77,7 @@ To specify one or more roles for the authenticated and authorized user, do the f
 
 [!code-csharp[UserRightsTest.cs](../../../samples/tests/xunit/UserRightsTest.cs?start=29&end=42&highlight=5)]
 
-The highlighted line shows how the <xref:Bunit.TestDoubles.Authorization.TestAuthorizationContext.SetRoles(System.String[])> method is used to specify one role. To specify multiple roles, do the following:
+The highlighted line shows how the <xref:Bunit.TestDoubles.TestAuthorizationContext.SetRoles(System.String[])> method is used to specify one role. To specify multiple roles, do the following:
 
 [!code-csharp[UserRightsTest.cs](../../../samples/tests/xunit/UserRightsTest.cs?start=48&end=62&highlight=5)]
 
@@ -87,7 +87,7 @@ To specify one or more policies for the authenticated and authorized user, do th
 
 [!code-csharp[UserRightsTest.cs](../../../samples/tests/xunit/UserRightsTest.cs?start=68&end=81&highlight=5)]
 
-The highlighted line shows how the <xref:Bunit.TestDoubles.Authorization.TestAuthorizationContext.SetPolicies(System.String[])> method is used to specify one policy. To specify multiple policies, do the following:
+The highlighted line shows how the <xref:Bunit.TestDoubles.TestAuthorizationContext.SetPolicies(System.String[])> method is used to specify one policy. To specify multiple policies, do the following:
 
 [!code-csharp[](../../../samples/tests/xunit/UserRightsTest.cs?start=91&end=91)]
 
@@ -97,7 +97,7 @@ To specify one or more claims for the authenticated and authorized user, do the
 
 [!code-csharp[UserRightsTest.cs](../../../samples/tests/xunit/UserRightsTest.cs?start=106&end=123&highlight=5-8)]
 
-The highlighted line shows how the <xref:Bunit.TestDoubles.Authorization.TestAuthorizationContext.SetClaims(System.Security.Claims.Claim[])> method is used to pass two instances of the `Claim` types.
+The highlighted line shows how the <xref:Bunit.TestDoubles.TestAuthorizationContext.SetClaims(System.Security.Claims.Claim[])> method is used to pass two instances of the `Claim` types.
 
 ### Example of passing both roles, claims, and policies
 
diff --git a/docs/site/docs/toc.md b/docs/site/docs/toc.md
@@ -8,6 +8,7 @@
 # [Providing Input](xref:providing-input)
 ## [Parameters and Cascading Values](xref:passing-parameters-to-components)
 ## [Inject Services into Components](xref:inject-services)
+## [Controlling the Root Render Tree](xref:root-render-tree)
 ## [Configure 3rd Party Libraries](xref:configure-3rd-party-libs)
 
 # [Interaction](xref:interaction)

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`
`7`	`7`	`namespace Bunit.Docs.Samples`
`8`	`8`	`{`
`9`		`- public abstract class BunitTestContext : ITestContext, IDisposable`
	`9`	`+ public abstract class BunitTestContext : IDisposable`
`10`	`10`	`{`
`11`	`11`	`private Bunit.TestContext _context;`
`12`	`12`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-using Bunit.TestDoubles.Authorization;`
	`1`	`+using Bunit.TestDoubles;`
`2`	`2`	`using System;`
`3`	`3`	`using Xunit;`
`4`	`4`