Added MarkupMatches(this string actual ...) extension methods. Make it easier to compare just the text content from a DON text node with a string, while still getting the benefit of the semantic HTML comparer.

Author: egil

CHANGELOG.md

@@ -9,50 +9,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Added
 List of new features.
 
-- Authorization fakes added to make it much easier to test components that use authentication and authorization. By [@DarthPedro](https://github.com/DarthPedro) in [#151](https://github.com/egil/bUnit/pull/151).
+- Authorization fakes added to make it much easier to test components that use authentication and authorization. Learn more in the [Faking Blazor's Authentication and Authorization](https://bunit.egilhansen.com/docs/test-doubles/faking-auth) page. By [@DarthPedro](https://github.com/DarthPedro) in [#151](https://github.com/egil/bUnit/pull/151).
 
-#### Authorization Fakes
-Added authentication/authorization fake services to make it easy to test Blazor components that use authorization either through code or the AuthorizeView component.
-You just need to call the AddTestAuthorization method on your TestContext.Services collection.
-
-First define your component that uses AuthorizeView to render differently based on the user's authorization state:
-```
-@using Microsoft.AspNetCore.Authorization
-@using Microsoft.AspNetCore.Components.Authorization
-
-<CascadingAuthenticationState>
-	<AuthorizeView>
-		<Authorized>
-			Authorized!
-		</Authorized>
-		<NotAuthorized>
-			Not authorized?
-		</NotAuthorized>
-	</AuthorizeView>
-</CascadingAuthenticationState>
-```
-Then define your test method to specify the authorization state with a user name, and run your test.
-```c#
-public void Test002()
-{
-	// arrange
-	using var ctx = new TestContext();
-	var authContext = ctx.Services.AddTestAuthorization();
-	authContext.SetAuthorized("TestUser", AuthorizationState.Authorized);
-
-	// act
-	var cut = ctx.RenderComponent<SimpleAuthView>();
-
-	// assert
-	cut.MarkupMatches("Authorized!");
-}
-```
+- Added `MarkupMatches(this string actual ...)`  extension methods. Make it easier to compare just the text content from a DON text node with a string, while still getting the benefit of the semantic HTML comparer.
 
 ### Changed
 List of changes in existing functionality.
 
 - `TestContextBase.Dispose` made virtual to allow inheritor's to override it. By [@SimonCropp](https://github.com/SimonCropp) in [#137](https://github.com/egil/bunit/pull/137).
-- Changed naming convention for JSMock feature. All classes and methods containing `Js` (meaning JavaScript) renamed to `JS`. By [yourilima](https://github.com/yourilima) in [#150](https://github.com/egil/bUnit/pull/150)
+- **[Breaking change]** Changed naming convention for JSMock feature and moved to new namespace, `Bunit.TestDoubles.JSInterop`. All classes and methods containing `Js` (meaning JavaScript) renamed to `JS` for consistency with Blazor's `IJSRuntime`. By [@yourilima](https://github.com/yourilima) in [#150](https://github.com/egil/bUnit/pull/150)
 
 ### Deprecated
 List of soon-to-be removed features.

docs/samples/tests/xunit/VerifyMarkupExamples.cs

@@ -45,16 +45,16 @@ public void MarkupMatchesOnNode()
       smallElm.MarkupMatches(@"<small class=""mark text-muted"">Secondary text</small>");
     }
 
-    // [Fact]
-    // public void MarkupMatchesOnTextNode()
-    // {
-    //   using var ctx = new TestContext();
+    [Fact]
+    public void MarkupMatchesOnTextNode()
+    {
+      using var ctx = new TestContext();
 
-    //   var cut = ctx.RenderComponent<Heading>();
+      var cut = ctx.RenderComponent<Heading>();
 
-    //   var smallElmText = cut.Find("small").TextContent;
-    //   smallElmText.MarkupMatches("Secondary text");
-    // }
+      var smallElmText = cut.Find("small").TextContent;
+      smallElmText.MarkupMatches("Secondary text");
+    }
 
     [Fact]
     public void FindAndFindAll()

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

@@ -83,11 +83,9 @@ Here we use the `Find(string cssSelector)` method to find the `<small>` element,
 > [!TIP]
 > Working with `Find()`, `FindAll()`, `INode` and `INodeList` is covered later on this page.
 
-<!-- TODO UNCOMMENT WHEN MarkupMatches(this string markup ... ) IS DONE
 Text content can also be verified with the `MarkupMatches()` method, e.g. the text inside the `<small>` element. It has the advantage over regular string comparison that it removes insignificant whitespace in the text automatically, even between words, where a normal string `Trim()` method isn't enough. For example:
 
 [!code-csharp[](../../../samples/tests/xunit/VerifyMarkupExamples.cs?start=51&end=56&highlight=5)]
--->
 
 The semantic HTML comparer can be customized to make a test case even more stable and easier to maintain. It is e.g. possible to ignore an element or attribute during comparison, or provide an regular expression to the comparer when comparing a specific element or attribute, to make the comparer work with generated data.
 

src/bunit.web/Asserting/MarkupMatchesAssertExtensions.cs

@@ -13,6 +13,72 @@ namespace Bunit
 	/// </summary>
 	public static class MarkupMatchesAssertExtensions
 	{
+		/// <summary>
+		/// Verifies that the rendered markup from the <paramref name="actual"/> markup fragment matches
+		/// the <paramref name="expected"/> markup fragment, using the <see cref="HtmlComparer"/> type.
+		/// </summary>
+		/// <exception cref="HtmlEqualException">Thrown when the <paramref name="actual"/> markup does not match the <paramref name="expected"/> markup.</exception>
+		/// <param name="actual">The markup fragment to verify.</param>
+		/// <param name="expected">The expected markup fragment.</param>
+		/// <param name="userMessage">A custom user message to display in case the verification fails.</param>
+		public static void MarkupMatches(this string actual, string expected, string? userMessage = null)
+		{
+			using var parser = new HtmlParser();
+			var actualNodes = parser.Parse(actual);
+			var expectedNodes = parser.Parse(expected);
+			actualNodes.MarkupMatches(expectedNodes, userMessage);
+		}
+
+		/// <summary>
+		/// Verifies that the rendered markup from the <paramref name="actual"/> markup fragment matches
+		/// the <paramref name="expected"/> <see cref="IRenderedFragmentBase"/>, using the <see cref="HtmlComparer"/> type.
+		/// </summary>
+		/// <exception cref="HtmlEqualException">Thrown when the <paramref name="actual"/> markup does not match the <paramref name="expected"/> markup.</exception>
+		/// <param name="actual">The markup fragment to verify.</param>
+		/// <param name="expected">The expected <see cref="IRenderedFragmentBase"/>.</param>
+		/// <param name="userMessage">A custom user message to display in case the verification fails.</param>
+		public static void MarkupMatches(this string actual, IRenderedFragment expected, string? userMessage = null)
+		{
+			if (expected is null)
+				throw new ArgumentNullException(nameof(expected));
+
+			var actualNodes = actual.ToNodeList(expected.Services.GetRequiredService<HtmlParser>());
+			actualNodes.MarkupMatches(expected, userMessage);
+		}
+
+		/// <summary>
+		/// Verifies that the rendered markup from the <paramref name="actual"/> markup fragment matches
+		/// the <paramref name="expected"/> <see cref="INodeList"/>, using the <see cref="HtmlComparer"/> type.
+		/// </summary>
+		/// <exception cref="HtmlEqualException">Thrown when the <paramref name="actual"/> markup does not match the <paramref name="expected"/> markup.</exception>
+		/// <param name="actual">The markup fragment to verify.</param>
+		/// <param name="expected">The expected <see cref="INodeList"/>.</param>
+		/// <param name="userMessage">A custom user message to display in case the verification fails.</param>
+		public static void MarkupMatches(this string actual, INodeList expected, string? userMessage = null)
+		{
+			if (expected is null)
+				throw new ArgumentNullException(nameof(expected));
+
+			var actualNodes = actual.ToNodeList(expected.GetHtmlParser());
+			actualNodes.MarkupMatches(expected, userMessage);
+		}
+
+		/// <summary>
+		/// Verifies that the rendered markup from the <paramref name="actual"/> markup fragment matches
+		/// the <paramref name="expected"/> <see cref="INode"/>, using the <see cref="HtmlComparer"/> type.
+		/// </summary>
+		/// <exception cref="HtmlEqualException">Thrown when the <paramref name="actual"/> markup does not match the <paramref name="expected"/> markup.</exception>
+		/// <param name="actual">The markup fragment to verify.</param>
+		/// <param name="expected">The expected <see cref="INode"/>.</param>
+		/// <param name="userMessage">A custom user message to display in case the verification fails.</param>
+		public static void MarkupMatches(this string actual, INode expected, string? userMessage = null)
+		{
+			if (expected is null)
+				throw new ArgumentNullException(nameof(expected));
+
+			var actualNodes = actual.ToNodeList(expected.GetHtmlParser());
+			actualNodes.MarkupMatches(expected, userMessage);
+		}
 
 		/// <summary>
 		/// Verifies that the rendered markup from the <paramref name="actual"/> <see cref="IRenderedFragmentBase"/> matches
@@ -29,9 +95,7 @@ public static void MarkupMatches(this IRenderedFragment actual, string expected,
 			if (expected is null)
 				throw new ArgumentNullException(nameof(expected));
 
-			var htmlParser = actual.Services.GetRequiredService<HtmlParser>();
-			var expectedNodes = htmlParser.Parse(expected);
-
+			var expectedNodes = expected.ToNodeList(actual.Services.GetRequiredService<HtmlParser>());
 			actual.Nodes.MarkupMatches(expectedNodes, userMessage);
 		}
 
@@ -105,17 +169,8 @@ public static void MarkupMatches(this INode actual, string expected, string? use
 			if (actual is null)
 				throw new ArgumentNullException(nameof(actual));
 
-			INodeList expectedNodes;
-			if (actual.GetHtmlParser() is { } parser)
-			{
-				expectedNodes = parser.Parse(expected);
-			}
-			else
-			{
-				using var newParser = new HtmlParser();
-				expectedNodes = newParser.Parse(expected);
-			}
-			MarkupMatches(actual, expectedNodes, userMessage);
+			var expectedNodes = expected.ToNodeList(actual.GetHtmlParser());
+			actual.MarkupMatches(expectedNodes, userMessage);
 		}
 
 		/// <summary>
@@ -132,17 +187,8 @@ public static void MarkupMatches(this INodeList actual, string expected, string?
 			if (actual is null)
 				throw new ArgumentNullException(nameof(actual));
 
-			INodeList expectedNodes;
-			if (actual.Length > 0 && actual[0].GetHtmlParser() is { } parser)
-			{
-				expectedNodes = parser.Parse(expected);
-			}
-			else
-			{
-				using var newParser = new HtmlParser();
-				expectedNodes = newParser.Parse(expected);
-			}
-			MarkupMatches(actual, expectedNodes, userMessage);
+			var expectedNodes = expected.ToNodeList(actual.GetHtmlParser());
+			actual.MarkupMatches(expectedNodes, userMessage);
 		}
 
 		/// <summary>
@@ -195,5 +241,18 @@ public static void MarkupMatches(this INode actual, INodeList expected, string?
 			if (diffs.Count != 0)
 				throw new HtmlEqualException(diffs, expected, actual, userMessage);
 		}
+
+		private static INodeList ToNodeList(this string markup, HtmlParser? htmlParser)
+		{
+			if (htmlParser is null)
+			{
+				using var newHtmlParser = new HtmlParser();
+				return newHtmlParser.Parse(markup);
+			}
+			else
+			{
+				return htmlParser.Parse(markup);
+			}
+		}
 	}
 }