fix: improve exception message to wait for issue

Author: egil

src/bunit.core/Extensions/WaitForHelpers/WaitForFailedException.cs

@@ -15,10 +15,36 @@ public WaitForFailedException(string? errorMessage, Exception? innerException =
 	}
 
 	internal WaitForFailedException(string errorMessage, int checkCount, int componentRenderCount, int totalRenderCount, Exception? innerException = null)
-		: base(errorMessage + $" Check count: {checkCount}. Component render count: {componentRenderCount}. Total render count: {totalRenderCount}.", innerException)
+		: base(CreateMessage(errorMessage, checkCount, componentRenderCount, totalRenderCount), innerException)
 	{
 	}
 
+	private static string CreateMessage(
+		string errorMessage,
+		int checkCount,
+		int componentRenderCount,
+		int totalRenderCount)
+	{
+		return $"""
+			{errorMessage}
+
+			If this test does not fail consistently, the reason may be that
+			the wait timeout is too short, and the runtime did not have enough
+			time to complete the necessary number of renders of the component under test.
+			This can happen on highly utilized or slower hardware, for example.
+
+			To determine if this is the cause, compare the check and render count(s) below
+			and see if they match what is expected. If they do not,
+			consider increasing the timeout, either at the individual
+			method call level, e.g. WaitForElement("div", TimeSpan.FromSeconds(15)),
+			or via the static TestContext.DefaultWaitTimeout property.
+
+			Check count: {checkCount}.
+			Component render count: {componentRenderCount}.
+			Total render count across all components: {totalRenderCount}.
+			""";
+	}
+
 	private WaitForFailedException(SerializationInfo info, StreamingContext context)
 		: base(info, context) { }
 }

src/bunit.core/Extensions/WaitForHelpers/WaitForHelper.cs

@@ -59,19 +59,24 @@ protected WaitForHelper(
 			.GetRequiredService<TestContextBase>()
 			.Renderer;
 		checkPassedCompletionSource = new TaskCompletionSource<T>(TaskCreationOptions.RunContinuationsAsynchronously);
-		timer = new Timer(_ =>
-		{
-			logger.LogWaiterTimedOut(renderedFragment.ComponentId);
-			checkPassedCompletionSource.TrySetException(
-				new WaitForFailedException(
-					TimeoutErrorMessage ?? string.Empty,
-					checkCount,
-					renderedFragment.RenderCount,
-					renderer.RenderCount,
-					capturedException));
-		});
+
 		WaitTask = CreateWaitTask();
-		timer.Change(GetRuntimeTimeout(timeout), Timeout.InfiniteTimeSpan);
+		timer = new Timer(
+			static (state) =>
+			{
+				var @this = (WaitForHelper<T>)state!;
+				@this.logger.LogWaiterTimedOut(@this.renderedFragment.ComponentId);
+				@this.checkPassedCompletionSource.TrySetException(
+					new WaitForFailedException(
+						@this.TimeoutErrorMessage ?? string.Empty,
+						@this.checkCount,
+						@this.renderedFragment.RenderCount,
+						@this.renderer.RenderCount,
+						@this.capturedException));
+			},
+			this,
+			GetRuntimeTimeout(timeout),
+			Timeout.InfiniteTimeSpan);
 
 		InitializeWaiting();
 	}

tests/bunit.web.tests/Extensions/WaitForHelpers/RenderedFragmentWaitForElementsHelperExtensions.Async.Test.cs

@@ -61,8 +61,7 @@ public async Task Test022()
 		expected.InnerException.ShouldBeNull();
 	}
 
-	[Fact(DisplayName = "WaitForElements with specific count N throws exception after timeout when cssSelector does not result in N matching elements",
-		Skip = "Need to figure out how to make this deterministic.")]
+	[Fact(DisplayName = "WaitForElements with specific count N throws exception after timeout when cssSelector does not result in N matching elements")]
 	[Trait("Category", "async")]
 	public async Task Test023()
 	{

tests/bunit.web.tests/Extensions/WaitForHelpers/RenderedFragmentWaitForElementsHelperExtensionsTest.cs

@@ -61,7 +61,7 @@ public void Test022()
 		expected.InnerException.ShouldBeNull();
 	}
 
-	[Fact(DisplayName = "WaitForElements with specific count N throws exception after timeout when cssSelector does not result in N matching elements", Skip = "Need to figure out how to make this deterministic.")]
+	[Fact(DisplayName = "WaitForElements with specific count N throws exception after timeout when cssSelector does not result in N matching elements")]
 	[Trait("Category", "sync")]
 	public void Test023()
 	{