Expand description
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 yew_e2e::prelude::*;
use yew_e2e::{Config, Fixture, Frontend};
struct App {
url: String,
}
impl Fixture for App {
type Setup = ();
fn config() -> Config {
Config::default().frontend(Frontend::None)
}
async fn start((): ()) -> Result<Self> {
// Start the application here, on a port of its own.
Ok(App { url: String::from("http://127.0.0.1:8080") })
}
fn url(&self) -> String {
self.url.clone()
}
async fn quit(self) -> Result<()> {
Ok(())
}
}
mod greeting {
use yew_e2e::prelude::*;
pub async fn says_hello<F>(driver: &mut TestDriver, _: &mut F) -> Result<()> {
driver.wait_texts("h1", ["Hello"]).await
}
}
yew_e2e::harness! {
App;
greeting::{says_hello},
}The suite is registered as a test without libtest’s harness:
[[test]]
name = "e2e"
path = "tests/e2e/main.rs"
harness = falseA 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:
yew_e2e::harness! {
App;
cart::{adds_an_item, removes_an_item},
login::{remembers_the_user(signed_in)},
}examples/static_page.rs is a suite that runs as it is, against a page its
fixture serves itself:
cargo run -p yew-e2e --example static_page§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, and Frontend::None builds nothing, for a fixture that
serves its own pages.
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
cargo test -p app-e2e # everything
cargo test -p app-e2e -- cart:: # everything whose name contains cart::
cargo test -p app-e2e -- --exact cart::adds_an_item
cargo test -p app-e2e -- --list # the names, one per line, on stdout
cargo test -p app-e2e -- --last-session # what did not pass last time| 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. |
Modules§
- harness
- The suite’s own runner, in place of libtest.
- prelude
- What a test file needs in scope, in one
use yew_e2e::prelude::*;.
Macros§
- harness
- Declare the suite and the entrypoint that runs it.
Structs§
- Canvas
Size - A canvas’s own reported size – see
TestDriver::canvas_size. - Config
- How a suite is run; see
Fixture::config. - Test
Driver - Wrapper for
WebDriverwhich adds convenience methods for testing. - Test
Element - A wrapped WebElement.
Enums§
- Engine
- A browser this suite knows how to drive.
- Frontend
- The frontend a suite serves, built once for the whole run;
distis where it ends up.
Constants§
- POLL_
INTERVAL - How often a pending observation is repeated.
Traits§
- Fixture
- The application under test, started afresh for every test and taken down after it.
- IntoBy
- Anything that names elements to find, taken by every lookup on
TestDriverthat saysby.
Functions§
- dist
- Where this run’s frontend is, once
Frontendhas been built. - target_
dir - The build’s own target directory, which is where everything the suite leaves behind goes.
- workspace_
root - The workspace root: the nearest directory above the package under test
whose
Cargo.tomldeclares a[workspace], or the package itself where none does.