yew-e2e 0.2.1

Browser tests for Yew applications, and the runner that drives them.
Documentation

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 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, 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.