Skip to main content

Crate yew_e2e

Crate yew_e2e 

Source
Expand description

github crates.io docs.rs

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 geckodriver or Chrome through chromedriver, with a chromedriver matching the installed Chrome fetched when none is on the PATH.
  • The frontend built once per run with trunk build, or served from E2E_DIST when it is already built.
  • A record of every run, so --last-session runs 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 = 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:

ⓘ
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. 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 NHow many tests run at once, each in its own browser. Defaults to 2.
--headedShow the browsers.
--browser firefox|chromeWhich browser to drive. Detected where not given.
--exactFilters match whole names rather than parts of them.
--listList the selected tests and run nothing.
--allow-emptyA run that selects nothing passes rather than fails.
--last-session, --session NAMERun only what did not pass in that session.
--timeout SECONDSHow long one test may run. Defaults to 30; 0 waits for ever.
--grace SECONDSHow long a running test is given to finish after Ctrl-C or SIGTERM.
--lock target|project|noneWhich other runs this one waits for: those in the same build directory (the default), every worktree of the Git project, or none.
--lock-wait SECONDSHow long to wait for that lock.
Variable
E2E_HEADEDAs --headed.
E2E_BROWSERAs --browser.
E2E_DISTA frontend that is already built, served in place of building one.
E2E_THEMEdark or light, for the colour scheme the browser reports (Firefox).
E2E_MOTIONreduce or normal, for the motion preference the browser reports (Firefox).
E2E_SCALEThe device pixel ratio the browser reports.
E2E_SHOTSWhere 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§

CanvasSize
A canvas’s own reported size – see TestDriver::canvas_size.
Config
How a suite is run; see Fixture::config.
TestDriver
Wrapper for WebDriver which adds convenience methods for testing.
TestElement
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; dist is 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 TestDriver that says by.

Functions§

dist
Where this run’s frontend is, once Frontend has 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.toml declares a [workspace], or the package itself where none does.