From 9827c6a2b6bf6c46eb9552cd02d00bda86bd2db0 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Mon, 16 Nov 2026 20:09:29 +0100 Subject: [PATCH 1/3] Say why a navigation wait timed out: URL, readyState, requests in flight and failed A 30 s stall in CI said only that 30 s passed. GotoAsync, an action's navigation wait and WaitForLoadState/WaitForUrl now append the page state: URL, readyState, lifecycle events reached, the requests still in flight with their age, the last failed or 4xx/5xx ones, and the last script error. Pages enable the Network domain on creation to keep that (URLs and counts only). The script is bounded to 2 s. Co-Authored-By: Claude Sonnet 5.5 --- DECISIONS.md | 8 ++ src/Nullean.Cdp/Page.cs | 39 ++++++++- src/Nullean.Cdp/PageActivity.cs | 84 +++++++++++++++++++ tests/Nullean.Cdp.Tests/Live/BrowserTests.cs | 41 +++++++++ .../Live/MoreCommandTests.cs | 2 +- 5 files changed, 170 insertions(+), 4 deletions(-) create mode 100644 src/Nullean.Cdp/PageActivity.cs diff --git a/DECISIONS.md b/DECISIONS.md index 6465c3c..0a3e811 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -82,6 +82,14 @@ joined with the target OS's separator, not the host's. `TimeoutException`. - The test for it uses a local `HttpListener` whose image answers 800 ms late: on a `file://` page `load` comes too fast to tell waiting from not waiting. +- **A navigation timeout says why.** `GotoAsync`, an action's navigation wait and `WaitForLoadState`/`WaitForUrl` append + `Page state when it gave up:` to their `TimeoutException`: the URL, `readyState`, the lifecycle events the document + reached, the requests still in flight (oldest first, five shown, with their age) and the last failed or 4xx/5xx ones, + and the page's last script error. A 30 s stall in CI otherwise says only that 30 s passed. +- **That needs the `Network` domain on from the start**, so every page enables it when it is created and keeps URLs + and counts of requests (`PageActivity`), never headers or bodies. `NetworkRecording` stays the opt-in for a request + list or HAR. The page-state script is bounded to two seconds: a hung renderer is reported as not answering, and the + timeout is never delayed by its own diagnosis. ## Accessibility tree diff --git a/src/Nullean.Cdp/Page.cs b/src/Nullean.Cdp/Page.cs index a6ae944..43bf9f5 100644 --- a/src/Nullean.Cdp/Page.cs +++ b/src/Nullean.Cdp/Page.cs @@ -45,6 +45,7 @@ internal Page(Browser browser, CdpConnection connection, string targetId, string internal int RecordingInteractions; private readonly PageLog _log = new(); + private readonly PageActivity _activity = new(); /// The page's console calls since it was created or last cleared, oldest first. public IReadOnlyList ConsoleMessages => _log.Console; @@ -356,11 +357,40 @@ private async Task PollAsync(Func> done, string what, CancellationTok while (!await done().ConfigureAwait(false)) { if (started.Elapsed >= NavigationTimeout) - throw new TimeoutException($"Timed out after {NavigationTimeout.TotalSeconds:0}s waiting for {what}."); + throw new TimeoutException($"Timed out after {NavigationTimeout.TotalSeconds:0}s waiting for {what}." + await StateAsync().ConfigureAwait(false)); await Task.Delay(50, cancellationToken).ConfigureAwait(false); } } + /// + /// What the page looked like when a wait gave up, as lines to append to the timeout message: the URL, readyState, the + /// lifecycle events the document reached, the requests still in flight and the failed ones, and the page's last script error. + /// Best effort and bounded: a page that does not answer within two seconds is reported as such, never waited on. + /// + private async Task StateAsync() + { + var lines = new List(); + try + { + using var limit = new CancellationTokenSource(TimeSpan.FromSeconds(2)); + var state = await EvaluateAsync("location.href + '\\n' + document.readyState", limit.Token).ConfigureAwait(false); + var parts = (state.GetString() ?? "").Split('\n'); + lines.Add($"url: {parts[0]}"); + lines.Add($"readyState: {(parts.Length > 1 ? parts[1] : "unknown")}"); + } + catch (Exception e) when (e is OperationCanceledException or CdpException or CdpDisconnectedException or PageScriptException) + { + lines.Add("the page did not answer a script within 2s, so its URL and readyState are unknown"); + } + + var reached = _lifecycle.Keys.Order(StringComparer.Ordinal).ToList(); + lines.Add($"lifecycle events of this document: {(reached.Count == 0 ? "none" : string.Join(", ", reached))}"); + lines.AddRange(_activity.Describe()); + if (_log.Errors is [.., var last]) + lines.Add($"last script error: {last}"); + return "\nPage state when it gave up:\n " + string.Join("\n ", lines); + } + /// Emulates prefers-color-scheme: dark, light or no-preference. public async Task SetColorSchemeAsync(string scheme, CancellationToken cancellationToken = default) { @@ -397,7 +427,10 @@ internal async Task InitializeAsync(CancellationToken cancellationToken) _lifecycle.TryAdd(name, 0); }); _ = Connection.On(SessionId, _log.OnEvent); + _ = Connection.On(SessionId, _activity.OnEvent); await SendAsync("Page.enable", null, cancellationToken).ConfigureAwait(false); + // Requests in flight and failed ones, so a timeout can say what the page was waiting on. + await SendAsync("Network.enable", null, cancellationToken).ConfigureAwait(false); // Console calls and uncaught errors arrive as Runtime events. await SendAsync("Runtime.enable", null, cancellationToken).ConfigureAwait(false); await SendAsync("Page.setLifecycleEventsEnabled", w => w.WriteBoolean("enabled", true), cancellationToken).ConfigureAwait(false); @@ -433,7 +466,7 @@ public async Task GotoAsync(string url, CancellationToken cancellationToken = de } catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) { - throw new TimeoutException($"Navigating to {url} did not finish loading within {NavigationTimeout.TotalSeconds:0} seconds."); + throw new TimeoutException($"Navigating to {url} did not finish loading within {NavigationTimeout.TotalSeconds:0} seconds." + await StateAsync().ConfigureAwait(false)); } } @@ -461,7 +494,7 @@ internal async Task WithNavigationAsync(Func action, CancellationToken can } catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) { - throw new TimeoutException($"A navigation the action started did not finish loading within {NavigationTimeout.TotalSeconds:0} seconds."); + throw new TimeoutException($"A navigation the action started did not finish loading within {NavigationTimeout.TotalSeconds:0} seconds." + await StateAsync().ConfigureAwait(false)); } } diff --git a/src/Nullean.Cdp/PageActivity.cs b/src/Nullean.Cdp/PageActivity.cs new file mode 100644 index 0000000..3ff75ac --- /dev/null +++ b/src/Nullean.Cdp/PageActivity.cs @@ -0,0 +1,84 @@ +using System.Collections.Concurrent; +using System.Diagnostics; +using System.Globalization; +using System.Text; +using Nullean.Cdp.Protocol; + +namespace Nullean.Cdp; + +/// +/// What the page is waiting on and what already went wrong, kept so a timeout can say why it timed out: the requests still in +/// flight (oldest first), and the last failed or error-status ones. Holds URLs and counts only, never bodies or headers. +/// +internal sealed class PageActivity +{ + private const int Shown = 5; + private const int Kept = 20; + + private readonly ConcurrentDictionary _open = new(StringComparer.Ordinal); + private readonly ConcurrentQueue _problems = new(); + + private readonly record struct InFlight(string Method, string Url, long Started); + + public void OnEvent(CdpEvent e) + { + var p = e.Params; + if (p.StringOrNull("requestId") is not { } id) + return; + switch (e.Method) + { + // A redirect reuses the id: the new hop replaces the old one. + case "Network.requestWillBeSent" when p.TryGetProperty("request", out var request) && request.StringOrNull("url") is { } url: + _open[id] = new InFlight(request.StringOrNull("method") ?? "GET", url, Stopwatch.GetTimestamp()); + break; + case "Network.responseReceived" when p.TryGetProperty("response", out var response) && response.TryGetProperty( + "status", + out var status + ) && status.GetInt32() >= 400: + Problem($"{status.GetInt32()} {(_open.TryGetValue(id, out var failed) ? failed.Url : response.StringOrNull("url"))}"); + break; + case "Network.loadingFinished": + _ = _open.TryRemove(id, out _); + break; + case "Network.loadingFailed": + var known = _open.TryRemove(id, out var open); + // A request the page cancelled itself, such as an image it replaced, is not a failure. + if (p.TryGetProperty("canceled", out var canceled) && canceled.ValueKind == System.Text.Json.JsonValueKind.True) + break; + Problem($"{p.StringOrNull("errorText") ?? "failed"} {(known ? open.Url : id)}"); + break; + } + } + + private void Problem(string text) + { + _problems.Enqueue(text); + while (_problems.Count > Kept && _problems.TryDequeue(out _)) + { } + } + + /// The lines that say what is in flight and what failed; none when neither. + public IReadOnlyList Describe() + { + var lines = new List(); + var now = Stopwatch.GetTimestamp(); + var open = _open.Values.OrderBy(r => r.Started).ToList(); + if (open.Count > 0) + { + var text = new StringBuilder(string.Create(CultureInfo.InvariantCulture, $"{open.Count} request{(open.Count == 1 ? "" : "s")} still in flight")); + foreach (var request in open.Take(Shown)) + _ = text.Append( + CultureInfo.InvariantCulture, + $"\n {request.Method} {request.Url} ({Stopwatch.GetElapsedTime(request.Started, now).TotalSeconds:0.0}s)" + ); + if (open.Count > Shown) + _ = text.Append(CultureInfo.InvariantCulture, $"\n and {open.Count - Shown} more"); + lines.Add(text.ToString()); + } + + var problems = _problems.ToArray(); + if (problems.Length > 0) + lines.Add("last failed requests: " + string.Join("; ", problems.TakeLast(Shown))); + return lines; + } +} diff --git a/tests/Nullean.Cdp.Tests/Live/BrowserTests.cs b/tests/Nullean.Cdp.Tests/Live/BrowserTests.cs index 90e8ad6..961925c 100644 --- a/tests/Nullean.Cdp.Tests/Live/BrowserTests.cs +++ b/tests/Nullean.Cdp.Tests/Live/BrowserTests.cs @@ -67,6 +67,47 @@ public async Task GotoWaitsForTheLoadEvent() (await page.EvaluateAsync("document.images[0].complete && document.images[0].naturalWidth")).GetInt32().Should().Be(1); } + [Test] + public async Task ANavigationTimeoutSaysWhatTheLoadWasWaitingOn() + { + _ = chrome.Browser; // skips without a Chrome + await using var server = new SlowServer(TimeSpan.FromSeconds(10)); + await using var context = await chrome.Browser.NewContextAsync(); + var page = await context.NewPageAsync(); + page.NavigationTimeout = TimeSpan.FromMilliseconds(600); + + var act = () => page.GotoAsync(server.Url); + + var thrown = await act.Should().ThrowAsync(); + thrown.Which.Message.Should().StartWith($"Navigating to {server.Url} did not finish loading within 1 seconds.\nPage state when it gave up:\n"); + thrown + .Which + .Message + .Should() + .Contain($"url: {server.Url}") + .And + .Contain("readyState: interactive") + .And + .Contain("1 request still in flight\n GET " + server.Url + "slow.png ("); + } + + [Test] + public async Task AWaitTimeoutNamesTheRequestsThatFailed() + { + _ = chrome.Browser; // skips without a Chrome + await using var server = new SlowServer(TimeSpan.Zero); + await using var context = await chrome.Browser.NewContextAsync(); + var page = await context.NewPageAsync(); + page.NavigationTimeout = TimeSpan.FromMilliseconds(300); + await page.GotoAsync(server.Url + "links"); + + var act = () => page.WaitForUrlAsync("**/never"); + + var thrown = await act.Should().ThrowAsync(); + thrown.Which.Message.Should().StartWith("Timed out after 0s waiting for the URL to match '**/never'.\nPage state when it gave up:\n"); + thrown.Which.Message.Should().Contain("readyState: complete").And.Contain("last failed requests: 404 " + server.Url + "missing.png"); + } + [Test] public async Task AFailedNavigationThrowsWithTheBrowsersError() { diff --git a/tests/Nullean.Cdp.Tests/Live/MoreCommandTests.cs b/tests/Nullean.Cdp.Tests/Live/MoreCommandTests.cs index 091231d..37fe567 100644 --- a/tests/Nullean.Cdp.Tests/Live/MoreCommandTests.cs +++ b/tests/Nullean.Cdp.Tests/Live/MoreCommandTests.cs @@ -176,7 +176,7 @@ await FluentActions .Awaiting(() => page.WaitForUrlAsync("**/never")) .Should() .ThrowAsync() - .WithMessage("Timed out after 0s waiting for the URL to match '**/never'."); + .WithMessage("Timed out after 0s waiting for the URL to match '**/never'.\nPage state when it gave up:*"); await FluentActions.Awaiting(() => page.WaitForLoadStateAsync("idle")).Should().ThrowAsync(); } From a2b8332a0a6d81e53e1ddb0007d2b937df1076c4 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Mon, 16 Nov 2026 20:09:52 +0100 Subject: [PATCH 2/3] Format Page.cs Co-Authored-By: Claude Sonnet 5.5 --- src/Nullean.Cdp/Page.cs | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/Nullean.Cdp/Page.cs b/src/Nullean.Cdp/Page.cs index 43bf9f5..8fc14dd 100644 --- a/src/Nullean.Cdp/Page.cs +++ b/src/Nullean.Cdp/Page.cs @@ -357,7 +357,9 @@ private async Task PollAsync(Func> done, string what, CancellationTok while (!await done().ConfigureAwait(false)) { if (started.Elapsed >= NavigationTimeout) - throw new TimeoutException($"Timed out after {NavigationTimeout.TotalSeconds:0}s waiting for {what}." + await StateAsync().ConfigureAwait(false)); + throw new TimeoutException( + $"Timed out after {NavigationTimeout.TotalSeconds:0}s waiting for {what}." + await StateAsync().ConfigureAwait(false) + ); await Task.Delay(50, cancellationToken).ConfigureAwait(false); } } @@ -466,7 +468,9 @@ public async Task GotoAsync(string url, CancellationToken cancellationToken = de } catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) { - throw new TimeoutException($"Navigating to {url} did not finish loading within {NavigationTimeout.TotalSeconds:0} seconds." + await StateAsync().ConfigureAwait(false)); + throw new TimeoutException( + $"Navigating to {url} did not finish loading within {NavigationTimeout.TotalSeconds:0} seconds." + await StateAsync().ConfigureAwait(false) + ); } } @@ -494,7 +498,11 @@ internal async Task WithNavigationAsync(Func action, CancellationToken can } catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) { - throw new TimeoutException($"A navigation the action started did not finish loading within {NavigationTimeout.TotalSeconds:0} seconds." + await StateAsync().ConfigureAwait(false)); + throw new TimeoutException( + $"A navigation the action started did not finish loading within {NavigationTimeout.TotalSeconds:0} seconds." + await StateAsync().ConfigureAwait( + false + ) + ); } } From a8cf56b2c5ce84a6995fefcc83fbb3f268657e5a Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Mon, 16 Nov 2026 20:26:39 +0100 Subject: [PATCH 3/3] Set the short timeout after the page loaded in the failed-requests test A slow runner hit the 300 ms timeout inside GotoAsync itself. Co-Authored-By: Claude Sonnet 5.5 --- tests/Nullean.Cdp.Tests/Live/BrowserTests.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/Nullean.Cdp.Tests/Live/BrowserTests.cs b/tests/Nullean.Cdp.Tests/Live/BrowserTests.cs index 961925c..b3300cb 100644 --- a/tests/Nullean.Cdp.Tests/Live/BrowserTests.cs +++ b/tests/Nullean.Cdp.Tests/Live/BrowserTests.cs @@ -98,8 +98,8 @@ public async Task AWaitTimeoutNamesTheRequestsThatFailed() await using var server = new SlowServer(TimeSpan.Zero); await using var context = await chrome.Browser.NewContextAsync(); var page = await context.NewPageAsync(); - page.NavigationTimeout = TimeSpan.FromMilliseconds(300); await page.GotoAsync(server.Url + "links"); + page.NavigationTimeout = TimeSpan.FromMilliseconds(300); var act = () => page.WaitForUrlAsync("**/never");