yew-e2e
Browser tests for web applications, and the runner that drives them.
Written for Yew applications built with Trunk, though nothing here depends
on either: a suite names the Fixture that starts the application under test
for every test, and each test is handed a TestDriver pointed at it.
What the runner takes care of:
- One binary and one entrypoint in place of libtest, declared with
harness!, running several browsers at once (--parallel). - Firefox through
geckodriveror Chrome throughchromedriver, with achromedrivermatching the installed Chrome fetched when none is on thePATH. - The frontend built once per run with
trunk build, or served fromE2E_DISTwhen it is already built. - A record of every run, so
--last-sessionruns only what did not pass. - One run at a time per build directory (
--lock). - Waits that say what they were waiting for when they give up, and a report of what the page was doing when it never came up.
Example
A test is an async fn taking the driver and the fixture. The fixture starts
the application for one test and says where the browser should go:
use *;
use ;
harness!
The suite is registered as a test without libtest's harness:
[[]]
= "e2e"
= "tests/e2e/main.rs"
= false
A test that needs something other than the bare fixture names it in
parentheses after its name, each word setting a bool field of the fixture's
Setup:
harness!
examples/static_page.rs is a suite that runs as it is, against a page its
fixture serves itself:
The frontend
By default the fixture's frontend is built once per run with trunk build, in
the workspace root, into target/e2e-dist. dist() says where it is, for
the fixture to serve. Frontend::Trunk(dir) runs it somewhere else under
the workspace root, Frontend::Trug(dir) does the same with trug build
for an app built with trug, and Frontend::None builds nothing, for a
fixture that serves its own pages. E2E_DIST names a frontend already built,
to serve in place of building one.
Everything else a run leaves behind goes under the build directory too: the
record of every run in target/e2e-sessions, the run lock, a fetched
chromedriver in target/e2e, named for the Chrome build it matches so that
an updated Chrome fetches a new one. Two suites sharing one build directory give
each other room with Config::sessions_dir and Config::lock_name.
Running
| Flag | |
|---|---|
-j, --parallel N |
How many tests run at once, each in its own browser. Defaults to 2. |
--headed |
Show the browsers. |
--browser firefox|chrome |
Which browser to drive. Detected where not given. |
--exact |
Filters match whole names rather than parts of them. |
--list |
List the selected tests and run nothing. |
--allow-empty |
A run that selects nothing passes rather than fails. |
--last-session, --session NAME |
Run only what did not pass in that session. |
--timeout SECONDS |
How long one test may run. Defaults to 30; 0 waits for ever. |
--grace SECONDS |
How long a running test is given to finish after Ctrl-C or SIGTERM. |
--lock target|project|none |
Which other runs this one waits for: those in the same build directory (the default), every worktree of the Git project, or none. |
--lock-wait SECONDS |
How long to wait for that lock. |
| Variable | |
|---|---|
E2E_HEADED |
As --headed. |
E2E_BROWSER |
As --browser. |
E2E_DIST |
A frontend that is already built, served in place of building one. |
E2E_THEME |
dark or light, for the colour scheme the browser reports (Firefox). |
E2E_MOTION |
reduce or normal, for the motion preference the browser reports (Firefox). |
E2E_SCALE |
The device pixel ratio the browser reports. |
E2E_SHOTS |
Where TestDriver::snapshot writes; relative to target/e2e-shots. |