Should bUnit provide MarkupMatches() functionality that instead returns a bool?

[domn1995]

First of all, I love this library! We've been comparing this with some React testing libraries (jest, react-testing-library, Enzyme, etc.) and it's amazing how much easier it is to test with bUnit.

One use case I found myself desiring is using the MarkupMatches() method due to the HTML semantics but not wanting to throw. Usually this happens when I'm building additional helper methods to help me traverse my component hierarchy. I find myself wanting to use MarkupMatches() in order to conditionally return one or more components or not.

Another issue but not as big of a deal with MarkupMatches() returning void is some static analyzers do not detect it as an assertion and warn that our tests are missing an assertion.

We are also prevented from combining bUnit with other assertion libraries. For example, we use FluentAssertions throughout our codebase and would sometimes like to use it like this: cut.MarkupMatches("...").Should().BeFalse() and cut.MarkupMatches("...").Should().BeTrue().

Again, awesome library! Keep up the amazing work :)

Cheers!

[egil]

Thanks @domn1995, appreciate the positive feedback.

MarkupMatches uses another method under the hood, that does almost what you want. CompareTo will return a list of IDiff, where a IDiff represents a difference between the actual and expected, so you can quite easily create your own variant that suites your needs. See https://github.com/egil/bUnit/blob/main/src/bunit.web/Asserting/MarkupMatchesAssertExtensions.cs#L237 to get an idea of how MarkupMatches uses it.

E.g. you could probably create an extension to Should() named Match(other markup) that does the same as MarkupMatches. If you do, please share the code, I am sure other FluentAssertions users would love to see it.

As for the static analyzers not recognizing MarkupMatches as an asssert method. Can you share which analyzers you are referring to. I might be able to change that.

[egil]

@manuelzelenka, as for making a custom assertion helper method for FluentAssertions, I have not done that myself yet, but this tutorial seems pretty straight forward: https://fluentassertions.com/extensibility/

In the custom assertion extension, you can then basically call MarkupMatches().
Alternative, if you want more control, you can call CompareTo(), that doesnt through when comparing two markup strings/nodes, but simply returns a list of differences.

The pretty error message produced when MarkupMatches fails comes from HtmlEqualException. If FluentAssertions work like that, you can simply through that exception passing in the list of diffs like MarkupMatches does, or you can copy the logic out.

Either way, if you create an extensions like this to FluentAsssertions, I would love if you could share it here in the Show and Tell section. Even better, if you make a nuget package out of it, I will be happy to future in bUnits docs.

[dev-in-disguise]

@egil now I went on and wanted to write a lengthy reply on why this doesn't really answer my question. But I feel like I found the answer while writing this comment myself.

Did you basically mean that we can use the CompareTo extensions instead of creating an overload of MarkupMatches which returns a bool? If that's the way bunit is planned to be used in that regard that's also an acceptable answer for me.

For this case I already made an own extension class which is basically just a copy of the CompareToDiffingExtensions with the count check on the diff results. If anyone wants to copy that:

public static class MarkupMatchesExtensions
{
	/// <summary>
	/// Compare the rendered markup in the <paramref name="actual"/> <see cref="IRenderedFragmentBase"/>
	/// with that in the <paramref name="expected"/> markup string.
	/// </summary>
	/// <param name="actual">Source of rendered markup to check.</param>
	/// <param name="expected">Markup to compare with.</param>
	/// <returns>Whether any differences were found.</returns>
	public static bool MarkupMatches(this IRenderedFragment actual, string expected)
	{
		var diffResults = actual.CompareTo(expected);
		return MarkupMatches(diffResults);
	}

	/// <summary>
	/// Compare the rendered markup in the <paramref name="actual"/> <see cref = "IRenderedFragmentBase" /> to
	/// the rendered markup in the <paramref name="expected"/> <see cref = "IRenderedFragmentBase" />
	/// </summary>
	/// <param name="actual">Source of rendered markup to check.</param>
	/// <param name="expected">Source of rendered markup to compare with.</param>
	/// <returns>Whether any differences were found.</returns>
	public static bool MarkupMatches(this IRenderedFragment actual, IRenderedFragment expected)
	{
		var diffResults = actual.CompareTo(expected);
		return MarkupMatches(diffResults);
	}

	/// <summary>
	/// Compares an <paramref name="actual"/> <see cref="INode"/> with an <paramref name="expected"/>
	/// <see cref="INodeList"/>.
	/// </summary>
	/// <param name="actual">The node to check.</param>
	/// <param name="expected">The node list to compare with</param>
	/// <returns>Whether any differences were found.</returns>
	public static bool MarkupMatches(this INode actual, INodeList expected)
	{
		var diffResults = actual.CompareTo(expected);
		return MarkupMatches(diffResults);
	}

	/// <summary>
	/// Compares an <paramref name="actual"/> <see cref="INodeList"/> with an <paramref name="expected"/>
	/// <see cref="INode"/>.
	/// </summary>
	/// <param name="actual">The node list to check.</param>
	/// <param name="expected">The node to compare with</param>
	/// <returns>Whether any differences were found.</returns>
	public static bool MarkupMatches(this INodeList actual, INode expected)
	{
		var diffResults = actual.CompareTo(expected);
		return MarkupMatches(diffResults);
	}

	/// <summary>
	/// Compares an <paramref name="actual"/> <see cref="INodeList"/> with an <paramref name="expected"/>
	/// <see cref="INodeList"/>.
	/// </summary>
	/// <param name="actual">The node list to check.</param>
	/// <param name="expected">The node list to compare with</param>
	/// <returns>Whether any differences were found.</returns>
	public static bool MarkupMatches(this INodeList actual, INodeList expected)
	{
		var diffResults = actual.CompareTo(expected);
		return MarkupMatches(diffResults);
	}

	private static bool MarkupMatches(IReadOnlyList<IDiff> diffResults) => diffResults.Count == 0;
}

[egil]

My understanding of @domn1995's original need for MarkupMatches to return a bool was because it was not recognized as an assertion method by SonarSource. This is fixed as far as bUnit is concerned.

CompareTo serve a different purpose than MarkupMatches, so they are not really interchangeable. CompareTo is not an assertion method.

The reason I suggested cresting an extension to FluentAssertions was to get the functionality of MarkupMatches better integrated with the FluentAssertions syntax, making tests using them easier to read.

Your extensions are not assertion method either. Assertion methods are supposed to either throw or proceed.

Hope this clears up any confusion I might have caused.

[dev-in-disguise]

I finally fully understand what you meant! Thanks for clearing everything up for me @egil
And you're totally right! I fully got caught in the mindset that I want to use FluentAssertions in the cut.MarkupMatches(...).Should.BeTrue() style which is actually quite bad.

If I get around to making an extension for FluentAssertions itself I'll keep you posted here! And if I get the chance may I add you to the PR?

[egil]

Great to hear @manuelzelenka. I am sure it would be useful as well, and I will be happy to review a PR.