Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -573,4 +573,16 @@ published by hand by the owner.
- **No allow-list option was added**: `AllowedHosts` already is the run-level default.
- **A click that hits nothing is not this change**: at the phone viewport `find role link click` completed with no effect.
The default viewport is the fix for that site; a click that reports it missed its target is separate.
## A click that cannot land fails

- **Pointer actions hit-test their point.** Chrome delivers `Input.dispatchMouseEvent` to whatever is at the point, so a
click on a covered or off-screen element "succeeds" and does nothing, and the failure shows at a later step that
times out far from the cause. `click`, `dblclick`, `hover`, `check`, `uncheck` and the source of `drag` check
`elementFromPoint` at the point first (into shadow roots, like a click). Scrolling and the target of a drag press
nothing, so they do not.
- **It waits, as Playwright's "receives events" does**, because covers are often transient (a banner fading out); the
step fails with the element that would receive the click, or "nothing is there" off the screen or clipped.
- **Accepted as a hit:** the element, anything inside it, or a `<label>` whose control is the element (a custom switch
hides its input under the label). `pointer-events: none` is skipped by the browser, so the element under it counts.
- **No `force` option.** A journey that must click a covered element is describing something a user cannot do.

12 changes: 12 additions & 0 deletions docs/journeys/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,18 @@ unless the command is `find`.
Every action waits up to the action timeout (5 s) for its element: visible and enabled for input, visible for
`hover`. An action that starts a navigation waits for the new page's `load`.

An action that presses a point (`click`, `dblclick`, `hover`, `check`, `uncheck`, the source of `drag`) also waits until
the element at that point is the target, something inside it, or the label of the control it is. A modal or banner
that covers it, a point off the screen, or a menu that is clipped away is waited out like any other state, and when
it stays the step fails at the click, saying what is there:

```text
Timed out after 5s waiting for role link --name "Quick reference" --exact to receive a click at (84, 412): <div#cookie-banner.banner> would receive it instead.
```

An element with `pointer-events: none` is passed through, as a real click does. The Playwright runner gets the same
check from Playwright, whose actions wait to "receive events".

| Command | |
|---|---|
| `click <sel>`, `dblclick <sel>` | scroll into view and press at the element's centre |
Expand Down
63 changes: 60 additions & 3 deletions src/Nullean.Cdp/Locator.cs
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,27 @@ public sealed partial class Locator
}
""";

// Runs with `this` the element to click: what the browser would deliver a click at (x, y) to, and whether that is
// the element (or something inside it, or the label of a control that is it). Goes into shadow roots, as a click
// does. pointer-events: none is skipped by elementFromPoint, as it is by a click. Locators find elements of the
// top document only, so there are no iframe offsets to subtract.
private const string HitFunction = """
function(x, y) {
let hit = this.ownerDocument.elementFromPoint(x, y);
while (hit && hit.shadowRoot) {
const inner = hit.shadowRoot.elementFromPoint(x, y);
if (!inner || inner === hit) break;
hit = inner;
}
if (!hit) return null;
for (let n = hit; n; n = n.parentNode || n.host) if (n === this) return true;
const label = hit.closest && hit.closest('label');
if (label && label.control === this) return true;
const classes = (hit.getAttribute('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).map(c => '.' + c).join('');
return hit.tagName.toLowerCase() + (hit.id ? '#' + hit.id : '') + classes;
}
""";

private readonly Page _page;

// The object handles one locator holds, released after each action. A group per locator, so two locators acting on
Expand Down Expand Up @@ -226,7 +247,7 @@ await _page.SendAsync("DOM.scrollIntoViewIfNeeded", w => w.WriteString("objectId
public Task ScrollByAsync(double deltaX, double deltaY, CancellationToken cancellationToken = default) =>
UsingAsync(LocatorState.Visible, async element =>
{
var (x, y) = await ClickPointAsync(element, cancellationToken).ConfigureAwait(false);
var (x, y) = await PointOfAsync(element, cancellationToken).ConfigureAwait(false);
await _page.Mouse.WheelAsync(x, y, deltaX, deltaY, cancellationToken).ConfigureAwait(false);
}, cancellationToken);

Expand All @@ -246,11 +267,12 @@ public Task DragToAsync(Locator target, CancellationToken cancellationToken = de
}, cancellationToken);
}

// The centre of this locator's element, scrolled into view; for being the other end of a drag.
// The centre of this locator's element, scrolled into view; for being the other end of a drag. Nothing is pressed
// there, so what covers it does not matter.
private async Task<(double X, double Y)> PointAsync(CancellationToken cancellationToken)
{
(double, double) point = default;
await UsingAsync(LocatorState.Visible, async element => point = await ClickPointAsync(element, cancellationToken).ConfigureAwait(false),
await UsingAsync(LocatorState.Visible, async element => point = await PointOfAsync(element, cancellationToken).ConfigureAwait(false),
cancellationToken).ConfigureAwait(false);
return point;
}
Expand Down Expand Up @@ -678,7 +700,42 @@ private async Task<JsonElement> CallAsync(string objectId, string function, Acti
private async Task FocusAsync(string objectId, CancellationToken cancellationToken) =>
await _page.SendAsync("DOM.focus", w => w.WriteString("objectId", objectId), cancellationToken).ConfigureAwait(false);

// The point a click would press, once nothing else would receive it: a cover (a modal, a banner), or a point off the
// screen or clipped, is waited out like any other state, and reported with what is in the way when it does not go.
private async Task<(double X, double Y)> ClickPointAsync(string objectId, CancellationToken cancellationToken)
{
var timeout = _page.ActionTimeout;
var started = System.Diagnostics.Stopwatch.StartNew();
while (true)
{
var (x, y) = await PointOfAsync(objectId, cancellationToken).ConfigureAwait(false);
var hit = await CallAsync(objectId, HitFunction, w =>
{
w.WriteStartObject();
w.WriteNumber("value", x);
w.WriteEndObject();
w.WriteStartObject();
w.WriteNumber("value", y);
w.WriteEndObject();
}, cancellationToken).ConfigureAwait(false);
if (hit.ValueKind == JsonValueKind.True)
return (x, y);
if (started.Elapsed >= timeout)
{
var point = $"({x.ToString("0.#", CultureInfo.InvariantCulture)}, {y.ToString("0.#", CultureInfo.InvariantCulture)})";
var cause = hit.ValueKind == JsonValueKind.String
? $"<{hit.GetString()}> would receive it instead"
: "nothing is there: it is outside the viewport or clipped";
throw new LocatorTimeoutException(
$"Timed out after {timeout.TotalSeconds.ToString("0.#", CultureInfo.InvariantCulture)}s waiting for {this} to receive a click at {point}: {cause}.");
}

await Task.Delay(50, cancellationToken).ConfigureAwait(false);
}
}

// The centre of the element, scrolled into view.
private async Task<(double X, double Y)> PointOfAsync(string objectId, CancellationToken cancellationToken)
{
await _page.SendAsync("DOM.scrollIntoViewIfNeeded", w => w.WriteString("objectId", objectId), cancellationToken).ConfigureAwait(false);
var quads = await _page.SendAsync("DOM.getContentQuads", w => w.WriteString("objectId", objectId), cancellationToken).ConfigureAwait(false);
Expand Down
107 changes: 107 additions & 0 deletions tests/Nullean.Cdp.Tests/Live/ClickHitTests.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
using AwesomeAssertions;
using Nullean.Cdp.Journeys;

namespace Nullean.Cdp.Tests.Live;

[ClassDataSource<ChromeFixture>(Shared = SharedType.PerTestSession)]
public class ClickHitTests(ChromeFixture chrome)
{
private async Task<Page> OpenAsync()
{
var context = await chrome.Browser.NewContextAsync();
var page = await context.NewPageAsync();
page.ActionTimeout = TimeSpan.FromSeconds(2);
await page.GotoAsync(ChromeFixture.Site("cover.html"));
return page;
}

private static Task<string> Log(Page page) => page.Css("#log").TextAsync();

[Test]
public async Task AClickOnAnUncoveredButtonLands()
{
var page = await OpenAsync();
await page.Role("button", "Open").ClickAsync();

(await Log(page)).Should().Be("clicked open");
}

[Test]
public async Task AClickOnACoveredButtonFailsAndNamesWhatCoversIt()
{
var page = await OpenAsync();
var act = () => page.Role("button", "Covered").ClickAsync();

var failure = await act.Should().ThrowAsync<LocatorTimeoutException>();
failure.Which.Message.Should().StartWith("Timed out after 2s waiting for role button --name Covered to receive a click at (")
.And.EndWith("): <div#curtain.cover.modal> would receive it instead.");
(await Log(page)).Should().Be("nothing", "the click was never sent");
}

[Test]
public async Task AClickWaitsForACoverThatGoesAway()
{
var page = await OpenAsync();
await page.Role("button", "Cleared later").ClickAsync();

(await Log(page)).Should().Be("clicked later");
}

[Test]
public async Task AClickPassesThroughAnElementWithPointerEventsNone()
{
var page = await OpenAsync();
await page.Role("button", "Through").ClickAsync();

(await Log(page)).Should().Be("clicked through");
}

[Test]
public async Task AClickOffTheScreenFailsAndSaysNothingIsThere()
{
var page = await OpenAsync();
var act = () => page.Css("#offscreen").ClickAsync();

var failure = await act.Should().ThrowAsync<LocatorTimeoutException>();
failure.Which.Message.Should().EndWith("nothing is there: it is outside the viewport or clipped.");
}

[Test]
public async Task ACheckOnAHiddenInputIsReceivedByItsLabel()
{
var page = await OpenAsync();
await page.Css("#toggle").CheckAsync();

(await Log(page)).Should().Be("toggled true");
}

[Test]
public async Task AClickOnAnElementInsideAButtonIsReceivedByTheElement()
{
var page = await OpenAsync();
await page.Css("#inner").ClickAsync();

(await Log(page)).Should().Be("clicked inner");
}

[Test]
public async Task HoverAndDragSourceAreHitTestedToo()
{
var page = await OpenAsync();

await ((Func<Task>)(() => page.Role("button", "Covered").HoverAsync())).Should().ThrowAsync<LocatorTimeoutException>();
await ((Func<Task>)(() => page.Role("button", "Covered").DragToAsync(page.Role("button", "Open")))).Should().ThrowAsync<LocatorTimeoutException>();
}

[Test]
public async Task AJourneyClickOnACoveredButtonFailsTheStepAtTheClick()
{
var result = await JourneyRunner.RunAsync(
Journey.Parse("open cover.html\nfind role button click --name Covered\nget text #log\n", "cover.journey"), chrome.Browser,
new JourneyOptions { BaseUrl = new Uri(new Uri(ChromeFixture.Site("cover.html")), "./"), ActionTimeout = TimeSpan.FromSeconds(1) });

result.Failure!.Line.Should().Be(2);
result.Failure.Message.Should().Contain("<div#curtain.cover.modal> would receive it instead");
result.Checkpoints.Should().BeEmpty();
}
}
23 changes: 23 additions & 0 deletions tests/Nullean.Cdp.Tests/site/cover.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
<!doctype html>
<meta charset="utf-8">
<title>Covered</title>
<link rel="icon" href="data:,">
<style>
body { margin: 0; }
.row { position: relative; height: 80px; }
.cover { position: absolute; inset: 0; background: rgba(0, 0, 0, .5); }
.passthrough { pointer-events: none; }
#offscreen { position: fixed; left: -5000px; top: 10px; }
label.switch { position: relative; display: inline-block; width: 60px; height: 30px; background: #ccc; }
label.switch input { position: absolute; inset: 0; opacity: 0; }
label.switch span { position: absolute; inset: 0; }
</style>
<p id="log">nothing</p>
<div class="row"><button onclick="log.textContent = 'clicked open'">Open</button></div>
<div class="row"><button onclick="log.textContent = 'clicked covered'">Covered</button><div class="cover modal" id="curtain"></div></div>
<div class="row"><button onclick="log.textContent = 'clicked later'">Cleared later</button><div class="cover banner" id="banner"></div></div>
<div class="row"><button onclick="log.textContent = 'clicked through'">Through</button><div class="cover passthrough"></div></div>
<div class="row"><button id="offscreen" onclick="log.textContent = 'clicked offscreen'">Offscreen</button></div>
<div class="row"><label class="switch"><input type="checkbox" id="toggle" onchange="log.textContent = 'toggled ' + this.checked"><span></span></label></div>
<div class="row"><button onclick="log.textContent = 'clicked inner'"><span id="inner">Inner span</span></button></div>
<script>setTimeout(() => document.getElementById('banner').remove(), 600);</script>
Loading