pub struct TestDriver { /* private fields */ }Expand description
Wrapper for WebDriver which adds convenience methods for testing.
Implementations§
Source§impl TestDriver
impl TestDriver
Sourcepub async fn local_clock(&self, epoch_ms: u64) -> Result<[u32; 4]>
pub async fn local_clock(&self, epoch_ms: u64) -> Result<[u32; 4]>
epoch_ms on the browser’s own clock: its month (from one), day,
hour and minute, for a test reading a time the page shows in the
reader’s zone.
Sourcepub async fn rendered_texts(&self, selector: &str) -> Result<Vec<String>>
pub async fn rendered_texts(&self, selector: &str) -> Result<Vec<String>>
Every matching rendered text in one browser observation.
A live viewer can replace its rows while WebDriver walks a list of element handles. Read the list inside the document when the observation itself is the assertion, so it is one snapshot rather than a handle per row.
Sourcepub fn downloads(&self) -> &Path
pub fn downloads(&self) -> &Path
Files saved by this browser, cleared before each test and removed when it closes.
Sourcepub fn webdriver(&self) -> &WebDriver
pub fn webdriver(&self) -> &WebDriver
The WebDriver session underneath, for what this wrapper has no method for.
Sourcepub fn wait_timeout(&self) -> Duration
pub fn wait_timeout(&self) -> Duration
How long one observation of a page that is already up may take to
agree: the deadline Self::wait_until and the finds wait against.
Sourcepub fn load_timeout(&self) -> Duration
pub fn load_timeout(&self) -> Duration
How long the first look at a page may take: the browser starting, the bundle being fetched, the wasm compiled, none of which has happened when a page is first asked for.
Sourcepub async fn set_window_size(&self, width: u32, height: u32) -> Result<()>
pub async fn set_window_size(&self, width: u32, height: u32) -> Result<()>
Resize the browser window.
Sourcepub async fn set_style(
&self,
element: &TestElement,
property: &str,
value: &str,
) -> Result<()>
pub async fn set_style( &self, element: &TestElement, property: &str, value: &str, ) -> Result<()>
Force one inline CSS property on an element, the same lever a
hand-typed style="" pulls, for a size no real window is narrow
enough to produce on its own, such as a popover’s own row.
Sourcepub async fn set_class(
&self,
element: &TestElement,
class: &str,
on: bool,
) -> Result<()>
pub async fn set_class( &self, element: &TestElement, class: &str, on: bool, ) -> Result<()>
Force one class on or off an element, for a state the app has no way to put that element in yet but a stylesheet rule already answers for, such as a record button that is capturing and unavailable at once.
Sourcepub async fn set_value(
&self,
element: &TestElement,
value: &str,
event: &str,
) -> Result<()>
pub async fn set_value( &self, element: &TestElement, value: &str, event: &str, ) -> Result<()>
Give a field a value the way a native control would, then fire
event on it, for fields such as <input type="color"> whose own
picker the driver cannot reach.
Sourcepub async fn set_text(&self, element: &TestElement, text: &str) -> Result<()>
pub async fn set_text(&self, element: &TestElement, text: &str) -> Result<()>
Replace the text an element already shows, for content the test machine cannot be relied on to produce, such as a very long name. Only the existing text node’s data changes, so the page keeps owning the node.
Sourcepub async fn overflowing(&self, element: &TestElement) -> Result<Vec<String>>
pub async fn overflowing(&self, element: &TestElement) -> Result<Vec<String>>
Every box inside an element that has more to show than it has room for, one line each: a scroller with something to scroll, or a box that clips what it holds. Empty when everything in it fits. A box a pixel or less across is passed over, since that is how a control is hidden from sight while staying reachable, and it clips by design.
Sourcepub async fn small_text(
&self,
element: &TestElement,
floor: f64,
marks: &str,
) -> Result<Vec<String>>
pub async fn small_text( &self, element: &TestElement, floor: f64, marks: &str, ) -> Result<Vec<String>>
Every piece of text inside an element set smaller than floor
pixels, one line each, passing over whatever sits inside marks: the
numbers of a scale or a badge’s count, which are read at a glance rather
than as words. Text nobody can see is passed over too.
Sourcepub async fn wheel_consumed(
&self,
element: &TestElement,
delta: f64,
) -> Result<bool>
pub async fn wheel_consumed( &self, element: &TestElement, delta: f64, ) -> Result<bool>
Turn the wheel and report whether anything consumed it.
Dispatches the same event as Self::wheel, and returns true when a
listener called preventDefault() on it.
Sourcepub async fn wheel(&self, element: &TestElement, delta: f64) -> Result<()>
pub async fn wheel(&self, element: &TestElement, delta: f64) -> Result<()>
Turn the wheel over an element: a cancelable, bubbling wheel event
with deltaY set to delta (positive scrolls down), dispatched on it.
The event is synthesized in the page rather than sent through
WebDriver, so it reaches the element’s listeners but the browser does
not scroll anything by itself. Returns once the event is dispatched;
see Self::wheel_consumed to learn whether anything handled it.
Sourcepub async fn wheel_alt(
&self,
element: &TestElement,
delta: f64,
shift: bool,
) -> Result<()>
pub async fn wheel_alt( &self, element: &TestElement, delta: f64, shift: bool, ) -> Result<()>
Turn the wheel with alt held, and shift too where asked.
The pointer is put at the middle of the element rather than left at the
origin a fresh WheelEvent carries: this zoom holds still whatever is
under the pointer, so a notch at clientY zero anchors on the top edge
and walks what is shown straight out of the window.
Sourcepub async fn wheel_over(
&self,
element: &TestElement,
across: f64,
down: f64,
ctrl: bool,
) -> Result<bool>
pub async fn wheel_over( &self, element: &TestElement, across: f64, down: f64, ctrl: bool, ) -> Result<bool>
Turn the wheel over an element and say whether the page took it.
Both axes and ctrl are given, because that is what tells one turn from
another where an element answers for more than one of them, and the
pointer is put in the middle of the element so a zoom that holds still
whatever is under it has something to hold.
What comes back is whether the default was prevented, which is the only thing that separates a gesture the window answered from one it answered and let fall through to scroll the box it landed in.
Sourcepub async fn wheel_across(
&self,
element: &TestElement,
delta: f64,
) -> Result<()>
pub async fn wheel_across( &self, element: &TestElement, delta: f64, ) -> Result<()>
Turn the wheel sideways, reading as deltaX: the gesture a trackpad
makes to pan, and not the one wheel makes.
Sourcepub async fn capture_clipboard(&self) -> Result<()>
pub async fn capture_clipboard(&self) -> Result<()>
Capture clipboard writes in this page without accessing the system clipboard.
Replaces navigator.clipboard.writeText so the text it is handed is
kept on the page instead, where Self::wait_copied reads it. Lasts
until the page is next loaded.
Sourcepub async fn delay_websocket_sends(&self, millis: u64) -> Result<()>
pub async fn delay_websocket_sends(&self, millis: u64) -> Result<()>
Delay every WebSocket send in this page by millis, so what the page
shows while a request is in flight can be observed. Lasts until
Self::stop_delaying_websocket_sends or the page is next loaded.
This defers the call into the real WebSocket.send, which means it
must not defer with the caller’s own bytes: send_with_u8_array hands
JS a raw view over wasm linear memory, not a copy, and musli-web’s
client reuses one scratch buffer for every request, clearing it the
moment send returns. A connection something else keeps sending on
(a poll on a timer, say) would otherwise overwrite
that memory before a long enough delay’s deferred call ever reads it,
corrupting the frame it finally sends. data.slice() copies the
bytes out synchronously, before this function returns control to the
caller – the same moment a real, un-shimmed send() would – so the
delay only ever holds a snapshot, the way a slow network holds bytes
already handed off, never a live alias into memory the caller is free
to keep mutating.
Sourcepub async fn stop_delaying_websocket_sends(&self) -> Result<()>
pub async fn stop_delaying_websocket_sends(&self) -> Result<()>
Undo Self::delay_websocket_sends, now that whatever it was
installed to slow down has been observed. The patched send stays in
effect for the rest of the page’s life otherwise, taxing every later
request on the same connection by the same delay – fine for a test
that stops looking right after, a trap for one that keeps going and
pays it on every send from here to the next page load.
Sourcepub async fn wait_copied(&self, text: &str) -> Result<()>
pub async fn wait_copied(&self, text: &str) -> Result<()>
Wait until the text last written to the clipboard since
Self::capture_clipboard is exactly text.
Sourcepub async fn watch_for_errors(&self) -> Result<()>
pub async fn watch_for_errors(&self) -> Result<()>
Start watching for anything the page throws.
The listener is installed by a script that keeps its names to itself,
so it neither collides with the page’s globals nor claims any the page
declares later. It marks the body data-watching once it is in place,
and this fails if that mark does not appear, since a watch that never
started would let every throw pass unheard.
What it records for a thrown error is its message followed by its stack, since some browsers (Firefox) keep only the frames in the stack.
Sourcepub async fn what_the_page_says(&self) -> Result<String>
pub async fn what_the_page_says(&self) -> Result<String>
What a page that did not become what was asked for has to say for
itself, as a sentence to hang off a timeout: whether anything is
mounted, what data-page the body carries, what it threw, and how the
document and its bundle loaded.
Sourcepub async fn error_seen(&self) -> Result<Option<String>>
pub async fn error_seen(&self) -> Result<Option<String>>
What the page threw since Self::watch_for_errors, if anything did.
Sourcepub async fn pointer_drag_onto(
&self,
from: &TestElement,
to: &TestElement,
) -> Result<()>
pub async fn pointer_drag_onto( &self, from: &TestElement, to: &TestElement, ) -> Result<()>
Carry one element onto another and let go.
Sourcepub async fn native_drag_over(
&self,
from: &TestElement,
to: &TestElement,
) -> Result<()>
pub async fn native_drag_over( &self, from: &TestElement, to: &TestElement, ) -> Result<()>
Carry one element over another with the pointer, the way a hand
does, and keep hold: press on it, move off in small steps so the
browser starts its own drag, and come to rest over the target. Unlike
Self::drag_over nothing is dispatched, so whatever stops the browser
starting a drag, or a target taking one, stops this too. Let go with
Self::native_release.
Sourcepub async fn release_all_input(&self) -> Result<()>
pub async fn release_all_input(&self) -> Result<()>
Let go of every key and button the actions above hold, the WebDriver way, which also puts down a drag an engine would otherwise keep carrying into the next test.
Sourcepub async fn native_release(&self) -> Result<()>
pub async fn native_release(&self) -> Result<()>
Let go of what Self::native_drag_over is holding, where it is.
Sourcepub async fn watch_mutations(&self, element: &TestElement) -> Result<()>
pub async fn watch_mutations(&self, element: &TestElement) -> Result<()>
Start counting what changes in the document under element: every
node added or removed, attribute set and text changed there, and the
element itself taken out of the page (moving it does that), and every
canvas in it cleared to be drawn again, read back with
Self::mutations. Watching again starts the count over.
Sourcepub async fn mutations(&self) -> Result<(u64, Vec<String>)>
pub async fn mutations(&self) -> Result<(u64, Vec<String>)>
How many changes Self::watch_mutations has seen, and what each was:
its kind, the attribute where it was one, and the class of the node.
Sourcepub async fn external_files(&self, paths: &str) -> Result<TestElement>
pub async fn external_files(&self, paths: &str) -> Result<TestElement>
Load real local files into a browser FileList without starting an import.
Sourcepub async fn drag_external_files(
&self,
files: &TestElement,
to: &TestElement,
kind: &str,
) -> Result<bool>
pub async fn drag_external_files( &self, files: &TestElement, to: &TestElement, kind: &str, ) -> Result<bool>
Dispatch the browser file payload onto a drop target; report cancellation.
Sourcepub async fn drag_onto(
&self,
from: &TestElement,
to: &TestElement,
) -> Result<()>
pub async fn drag_onto( &self, from: &TestElement, to: &TestElement, ) -> Result<()>
Carry one element onto another through its HTML drag handlers.
Sourcepub async fn drag_over(
&self,
from: &TestElement,
to: &TestElement,
) -> Result<()>
pub async fn drag_over( &self, from: &TestElement, to: &TestElement, ) -> Result<()>
Carry one element over another without letting go, so that what the controller says about the offer can be read.
Sourcepub async fn drag_off(&self, left: &TestElement) -> Result<()>
pub async fn drag_off(&self, left: &TestElement) -> Result<()>
Carry a drag in progress back off the element it was over, which is the
dragleave a browser sends and neither Self::drag_over nor
Self::drag_onto does: both begin their own drag, so this is handed
the element the carry is leaving and nothing else.
Sourcepub async fn scroll_top(&self, element: &TestElement, top: i32) -> Result<()>
pub async fn scroll_top(&self, element: &TestElement, top: i32) -> Result<()>
Set a container’s vertical scroll, letting the browser emit its scroll event.
Sourcepub async fn scroll_to_far_end(&self, element: &TestElement) -> Result<()>
pub async fn scroll_to_far_end(&self, element: &TestElement) -> Result<()>
Pin whatever scrolls this element sideways to the far end of its travel.
Sourcepub async fn computed(
&self,
element: &TestElement,
pseudo: &str,
property: &str,
) -> Result<String>
pub async fn computed( &self, element: &TestElement, pseudo: &str, property: &str, ) -> Result<String>
What the browser settled on, rather than what a rule says.
Sourcepub async fn reduced_motion(&self) -> Result<bool>
pub async fn reduced_motion(&self) -> Result<bool>
Whether the page matches prefers-reduced-motion: reduce.
Where E2E_MOTION is set this is an error when the browser disagrees
with it, so a run meant to exercise one preference cannot quietly get
the other. Set it (Firefox only) to test the browser’s own media
preference rather than a replacement stylesheet.
Sourcepub async fn animation_time(
&self,
element: &TestElement,
name: &str,
millis: f64,
) -> Result<()>
pub async fn animation_time( &self, element: &TestElement, name: &str, millis: f64, ) -> Result<()>
Pause an actual CSS animation at a deterministic phase before reading its computed presentation. Missing animations are failures, not idle samples.
Sourcepub async fn color_alpha(
&self,
element: &TestElement,
property: &str,
) -> Result<f64>
pub async fn color_alpha( &self, element: &TestElement, property: &str, ) -> Result<f64>
Read a computed color’s alpha through the browser’s color parser so both legacy rgba() and CSS Color 4 serialization describe the same measurement.
Sourcepub async fn color_shift(
&self,
element: &TestElement,
property: &str,
) -> Result<f64>
pub async fn color_shift( &self, element: &TestElement, property: &str, ) -> Result<f64>
Which way a computed colour moves what is painted under it. The
property is filled over mid grey by the browser itself and the result
compared with it, so a band’s direction is measured rather than read off
a serialization: negative darkens, positive lightens, zero paints
nothing. color-mix() and a legacy rgba() are the same measurement.
Sourcepub async fn painted(
&self,
element: &TestElement,
property: &str,
) -> Result<[f64; 3]>
pub async fn painted( &self, element: &TestElement, property: &str, ) -> Result<[f64; 3]>
What a computed colour actually paints, as red, green and blue.
The browser fills the property over mid grey and the pixel is read back,
so a color-mix(), a legacy rgba() and a translucent wash all answer
as the colour that is seen rather than as whatever the property happens
to serialize to.
Sourcepub async fn canvas_columns(
&self,
canvas: &TestElement,
columns: usize,
) -> Result<Vec<(f64, f64, f64)>>
pub async fn canvas_columns( &self, canvas: &TestElement, columns: usize, ) -> Result<Vec<(f64, f64, f64)>>
A canvas’s own drawn envelope, read from its actual pixel buffer
rather than any DOM or SVG geometry: a <canvas> carries no
points/viewBox attribute a test could read instead. Samples up to columns evenly
spaced points across the canvas’s backing-buffer width; each entry is
(x, top, bottom), all fractions (0.0..=1.0) of the canvas’s own box
– x across its width, top/bottom the first and last drawn
(non-transparent) pixel row down its height. A sampled column with
nothing drawn reads (x, -1.0, -1.0).
Sourcepub async fn canvas_size(&self, canvas: &TestElement) -> Result<CanvasSize>
pub async fn canvas_size(&self, canvas: &TestElement) -> Result<CanvasSize>
A canvas’s backing-buffer size in device pixels alongside its own CSS box and the browser’s reported device pixel ratio, so a caller can check the three agree – that the buffer is sized for the actual visible box and pixel density, not a fixed or stale guess.
Sourcepub async fn middle_click(&self, element: &TestElement) -> Result<()>
pub async fn middle_click(&self, element: &TestElement) -> Result<()>
Press the middle button over an element.
Sourcepub async fn middle_drag_by(&self, element: &TestElement, dx: i64) -> Result<()>
pub async fn middle_drag_by(&self, element: &TestElement, dx: i64) -> Result<()>
Pan with a native middle-button drag, releasing the button at the end.
Sourcepub async fn move_held(&self, dx: i64, dy: i64) -> Result<()>
pub async fn move_held(&self, dx: i64, dy: i64) -> Result<()>
Carry a held drag somewhere else without letting go of it.
Sourcepub async fn drop_held(&self) -> Result<()>
pub async fn drop_held(&self) -> Result<()>
Let go of whatever TestElement::drag_by is holding.
Sourcepub async fn cancel_pointer(&self, element: &TestElement) -> Result<()>
pub async fn cancel_pointer(&self, element: &TestElement) -> Result<()>
Cancel a captured pointer without releasing the test’s held button, so a later mouse-up can prove that cancelled work is not committed.
Sourcepub async fn drop_held_alt(&self) -> Result<()>
pub async fn drop_held_alt(&self) -> Result<()>
The same for a drag that was begun with alt held, which has to give
the key back as well as the button.
Sourcepub async fn drawn_inside(&self, selector: &str, x: f64, y: f64) -> Result<bool>
pub async fn drawn_inside(&self, selector: &str, x: f64, y: f64) -> Result<bool>
Whether what is drawn at one point of the page belongs to selector and
nothing is standing over it. A frame says what is drawn somewhere but
not what drew it, so a test measuring a window’s own content has to be
able to tell that content from whatever floats in front of it.
Two questions, because one does not do. Hit testing says which element is uppermost at the point, which settles the ordinary case. But a menu, a drag ghost or a help bubble is drawn through a portal into the document body, over the top of a window and often wider than it, and a bubble takes no pointer events at all – hit testing looks straight through it and answers with the window underneath. So anything portaled beside the application is asked separately whether it covers the point.
The point is in the page’s own pixels, not the frame’s.
Sourcepub async fn screenshot_png(&self) -> Result<Vec<u8>>
pub async fn screenshot_png(&self) -> Result<Vec<u8>>
A screenshot of the whole page as the PNG the browser hands back, for a
test that reads a frame rather than writing one out. Taken whether or
not E2E_SHOTS is set, since an assertion that measures a frame has to
have one on every run rather than only when somebody is looking.
Sourcepub async fn screenshot(&self, path: impl AsRef<Path>) -> Result<()>
pub async fn screenshot(&self, path: impl AsRef<Path>) -> Result<()>
Write a screenshot of the whole page to path.
Sourcepub async fn snapshot(&self, name: &str) -> Result<()>
pub async fn snapshot(&self, name: &str) -> Result<()>
The same, into $E2E_SHOTS/<name>.png, and nothing at all when that is
unset. Left in a test rather than added and removed, since it costs nothing
on an ordinary run.
E2E_SHOTS is a directory, and it reads like a flag. A relative one
is taken under target/e2e-shots, where everything else the suite leaves
behind goes — so E2E_SHOTS=1, which is what a hand types when it means
yes, writes to target/e2e-shots/1 rather than making a directory
called 1 in whatever the test process’s working directory happens to
be, which under cargo is the package, in the checkout.
E2E_SHOTS=1 cargo test -p app-e2e -- cart::
E2E_SHOTS=/tmp/shots cargo test -p app-e2e -- cart::Sourcepub async fn press_nth(&self, by: impl IntoBy, index: usize) -> Result<()>
pub async fn press_nth(&self, by: impl IntoBy, index: usize) -> Result<()>
Press the indexth element matching by, re-finding it if the page
moves underneath.
Sourcepub async fn context_press_nth(
&self,
by: impl IntoBy,
index: usize,
) -> Result<()>
pub async fn context_press_nth( &self, by: impl IntoBy, index: usize, ) -> Result<()>
The same as TestDriver::press_nth, right-handed. A context menu that
belongs to a thing is opened on the thing itself, so there is no button
to press and this is how a test reaches one.
Sourcepub async fn local_storage(&self, key: &str) -> Result<Option<String>>
pub async fn local_storage(&self, key: &str) -> Result<Option<String>>
Read a browser-persisted setting without changing it.
Sourcepub async fn set_local_storage(&self, key: &str, value: &str) -> Result<()>
pub async fn set_local_storage(&self, key: &str, value: &str) -> Result<()>
Seed a persisted setting before mounting the component that reads it.
Sourcepub async fn block_local_storage(&self) -> Result<()>
pub async fn block_local_storage(&self) -> Result<()>
Deny access for the current document, as when browser policy blocks storage.
Sourcepub async fn reload(&self) -> Result<()>
pub async fn reload(&self) -> Result<()>
Reload the page, which is the only way to ask what the server holds.
Sourcepub async fn reopen_with(&self, query: &str) -> Result<()>
pub async fn reopen_with(&self, query: &str) -> Result<()>
Open the page again with query in the address.
Sourcepub async fn in_second_tab(
&self,
run: impl AsyncFnOnce() -> Result<()>,
) -> Result<()>
pub async fn in_second_tab( &self, run: impl AsyncFnOnce() -> Result<()>, ) -> Result<()>
Run run in a second tab showing the page this one shows, then close
it and come back. The tab is sized as every test’s first one is, and
run is what waits for the page to come up; what the page threw fails
it as it would the test.
Sourcepub async fn in_second_window(
&self,
run: impl AsyncFnOnce() -> Result<()>,
) -> Result<()>
pub async fn in_second_window( &self, run: impl AsyncFnOnce() -> Result<()>, ) -> Result<()>
The same in a second window.
Sourcepub async fn press_key(&self, key: Key) -> Result<()>
pub async fn press_key(&self, key: Key) -> Result<()>
Press a key with nothing in particular focused, the way a hand does when it has just opened something with the pointer.
Sourcepub async fn hold_key(&self, key: char) -> Result<()>
pub async fn hold_key(&self, key: char) -> Result<()>
Hold a real WebDriver key across observations, rather than sending a down/up pair too quickly for an animation frame to show it.
Sourcepub async fn release_key(&self, key: char) -> Result<()>
pub async fn release_key(&self, key: char) -> Result<()>
Let go of a key held with Self::hold_key.
Sourcepub async fn find_all_attrs(
&self,
selector: &str,
attr: &str,
) -> Result<Vec<String>>
pub async fn find_all_attrs( &self, selector: &str, attr: &str, ) -> Result<Vec<String>>
Every match’s attribute, read in one pass. Reading them one handle at a time is how a test goes stale against a window that redraws on the animation frame: the elements it is holding are replaced between two reads and the second one throws.
Sourcepub async fn bands(
&self,
selector: &str,
attr: &str,
) -> Result<Vec<(String, f64, f64)>>
pub async fn bands( &self, selector: &str, attr: &str, ) -> Result<Vec<(String, f64, f64)>>
Where every match sits down the page, with the attribute that names it, in one pass. A band is a top and a height, which is all two things drawn in different columns have to agree about.
Measuring a hundred elements one handle at a time is a round trip each for the attribute and another for the box, which is a test that runs out of time rather than one that fails. A node the browser is not drawing has no box and is left out, so a count is also an answer to what is shown.
Sourcepub async fn press_key_on(&self, selector: &str, key: &str) -> Result<()>
pub async fn press_key_on(&self, selector: &str, key: &str) -> Result<()>
Dispatch a named key on a focused element, including keys WebDriver cannot encode.
Sourcepub async fn press_key_with_ctrl(&self, selector: &str, key: &str) -> Result<()>
pub async fn press_key_with_ctrl(&self, selector: &str, key: &str) -> Result<()>
Press a key on one element with control held, which is how undo,
redo and select-all are reached.
Dispatched on the element so the press lands where the test says. The
event carries the code a real letter key does, since a listener on
the document may read the code and a press without one would never
reach it.
Sourcepub async fn press_key_with_shift(
&self,
selector: &str,
key: &str,
) -> Result<()>
pub async fn press_key_with_shift( &self, selector: &str, key: &str, ) -> Result<()>
Press a key on one element with shift held, dispatched for the
same reason Self::press_key_with_ctrl is.
Sourcepub async fn blur(&self) -> Result<()>
pub async fn blur(&self) -> Result<()>
Take keyboard focus off whatever has it, so the next key lands on the page rather than on a control.
Sourcepub async fn focused_attr(&self, name: &str) -> Result<Option<String>>
pub async fn focused_attr(&self, name: &str) -> Result<Option<String>>
One attribute of whatever element has keyboard focus, or None when
it has no such attribute. Where nothing is focused, that is the
document’s <body>.
Answers once, at the time of asking; it does not wait.
Sourcepub async fn wait_until(
&self,
what: impl Display,
condition: impl AsyncFnMut() -> Result<bool>,
) -> Result<()>
pub async fn wait_until( &self, what: impl Display, condition: impl AsyncFnMut() -> Result<bool>, ) -> Result<()>
Repeat condition until it holds, or the wait timeout passes.
Sourcepub async fn wait_until_within(
&self,
timeout: Duration,
what: impl Display,
condition: impl AsyncFnMut() -> Result<bool>,
) -> Result<()>
pub async fn wait_until_within( &self, timeout: Duration, what: impl Display, condition: impl AsyncFnMut() -> Result<bool>, ) -> Result<()>
Self::wait_until where the default deadline is the wrong one,
because what is being waited for has a length of its own that is
known and is close to it. A wait that habitually lands just inside
its cap is not passing, it is winning a race.
Sourcepub async fn wait_texts<const N: usize>(
&self,
by: impl IntoBy,
expected: [&str; N],
) -> Result<()>
pub async fn wait_texts<const N: usize>( &self, by: impl IntoBy, expected: [&str; N], ) -> Result<()>
Wait until the text of every node matching by reads expected.
Sourcepub async fn wait_count(&self, by: impl IntoBy, expected: usize) -> Result<()>
pub async fn wait_count(&self, by: impl IntoBy, expected: usize) -> Result<()>
Wait until exactly expected nodes match by.
Exact equality, polled, starting immediately – which is a trap
directly after an action. A call whose expected is the count that
was already on screen is answered by the very first poll, before the
action it is meant to be checking can have landed, so it asserts only
that the page has not caught up yet. It stays green for months and
then turns into a hard timeout the first time anything, however
unrelated, makes the page a few milliseconds slower to lay out –
and blames that change. Where the count is supposed to have changed,
read it before the action and say so with Self::wait_count_from,
which refuses the degenerate case instead of passing it. Plain
wait_count belongs where a count is being established rather than
changed: a page just loaded, a selector first asserted.
Sourcepub async fn count(&self, by: impl IntoBy) -> Result<usize>
pub async fn count(&self, by: impl IntoBy) -> Result<usize>
How many nodes match by right now, without waiting for any
particular number of them. The before-read Self::wait_count_from
asks for.
Sourcepub async fn wait_count_from(
&self,
by: impl IntoBy,
before: usize,
expected: usize,
) -> Result<()>
pub async fn wait_count_from( &self, by: impl IntoBy, before: usize, expected: usize, ) -> Result<()>
Wait until exactly expected nodes match by, having been told the
before count that the action in between was supposed to change.
The before-read is the whole point. Self::wait_count cannot
tell “the action landed” apart from “the action has not started”,
because both of those look exactly like the number it was given; this
can, because it knows which number meant “not yet”. When before
already equals expected it refuses outright rather than passing on
the first poll, so the assertion that verifies nothing fails loudly
the day it is written instead of years later on somebody else’s
change. Take before with Self::count immediately before the
action – at the top of the test it is a different question, and
anything landing in between makes it a lie.
Sourcepub async fn find_all_texts(&self, by: impl IntoBy) -> Result<Vec<String>>
pub async fn find_all_texts(&self, by: impl IntoBy) -> Result<Vec<String>>
Find the text contents of all nodes match the given By.
Sourcepub async fn find_one_by_xpath(&self, xpath: &str) -> Result<TestElement>
pub async fn find_one_by_xpath(&self, xpath: &str) -> Result<TestElement>
Find an element by xpath.
Sourcepub async fn find_one_by(&self, by: impl IntoBy) -> Result<TestElement>
pub async fn find_one_by(&self, by: impl IntoBy) -> Result<TestElement>
Find the one element matching by, waiting for it to appear.
Refusing a second match is the point. A selector that was meant
to name one thing and now names three is the way a guard goes quiet,
so this says so instead of picking. Where several is what the page
is, the question was never “the one”: see Self::find_nth.
Sourcepub async fn find_nth(
&self,
by: impl IntoBy,
index: usize,
) -> Result<TestElement>
pub async fn find_nth( &self, by: impl IntoBy, index: usize, ) -> Result<TestElement>
Find the indexth element matching by, waiting for that many to
appear.
What a test asks when several is the answer, and the reading twin
of TestDriver::press_nth: the row a test appended is the one at
the end, three related buttons are three whatever is measured, and
neither is a broken selector for Self::find_one_by to refuse.
Asked here rather than by reaching for Self::find_all and
indexing the answer, which drops the wait along with the sentence
saying which one was wanted.
A wait polling for an element to arrive still wants
Self::find_all: nothing there is an answer to that question, and
this has a deadline of its own to spend before it says so.
Sourcepub async fn find_first(&self, by: impl IntoBy) -> Result<TestElement>
pub async fn find_first(&self, by: impl IntoBy) -> Result<TestElement>
The first element matching by, however many there turn out to be.
Self::find_nth says when that is the question.
Sourcepub async fn find_all(&self, by: impl Into<By>) -> Result<Vec<TestElement>>
pub async fn find_all(&self, by: impl Into<By>) -> Result<Vec<TestElement>>
Find all elements matching by.
Sourcepub async fn find_all_within(
&self,
timeout: Duration,
by: impl Into<By>,
) -> Result<Vec<TestElement>>
pub async fn find_all_within( &self, timeout: Duration, by: impl Into<By>, ) -> Result<Vec<TestElement>>
Self::find_all with a bound of the caller’s choosing on the call
itself, for putting the question to a browser which is still
starting. See TestDriver::load_timeout.