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..8fc14dd 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,42 @@ 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 +429,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 +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.");
+ throw new TimeoutException(
+ $"Navigating to {url} did not finish loading within {NavigationTimeout.TotalSeconds:0} seconds." + await StateAsync().ConfigureAwait(false)
+ );
}
}
@@ -461,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.");
+ 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..b3300cb 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();
+ await page.GotoAsync(server.Url + "links");
+ page.NavigationTimeout = TimeSpan.FromMilliseconds(300);
+
+ 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();
}