Skip to main content

vertigo_testing/
env.rs

1//! What a suite runs against. [`Core`] is the part every environment has: the settings, the
2//! address of the app, the work directory, an HTTP client and a chromedriver shared by the
3//! tests. A test crate wraps it in its own environment, which adds whatever its app needs (a
4//! backend, a database) and implements [`Env`].
5
6use std::{
7    net::TcpListener,
8    ops::Deref,
9    path::{Path, PathBuf},
10    sync::Arc,
11    time::Duration,
12};
13
14use anyhow::{Context, Result};
15use thirtyfour::{
16    CapabilitiesHelper, ChromiumLikeCapabilities, DesiredCapabilities, LoggingPrefsLogLevel,
17    WebDriver,
18    extensions::query::ElementPollerWithTimeout,
19    manager::{BrowserKind, WebDriverManager},
20};
21
22/// Time limit of element queries and of the `Ctx::wait_*` helpers.
23pub const WAIT: Duration = Duration::from_secs(10);
24pub const POLL: Duration = Duration::from_millis(100);
25
26/// The environment of one suite: started once, before the first test that needs it, shared by
27/// all the tests of the suite and shut down after the last one.
28///
29/// Implementations can write `async fn` for both methods.
30pub trait Env: Deref<Target = Core> + Send + Sync + Sized + 'static {
31    fn start(suite: &'static str) -> impl Future<Output = Result<Self>>;
32
33    /// Stops what `start` started. The process exits right after it, without running
34    /// destructors, so a container left here stays running.
35    fn shutdown(&self) -> impl Future<Output = ()>;
36}
37
38/// Settings from the `E2E_*` environment variables.
39#[derive(Debug, Clone)]
40pub struct Settings {
41    pub workspace_root: PathBuf,
42    pub target_dir: PathBuf,
43    /// `E2E_RELEASE`: builds in release mode.
44    pub release: bool,
45    /// `E2E_WASM_OPT`: runs `wasm-opt` on the apps, as a shipped build has it. Off by default:
46    /// it takes long and changes nothing a functional test looks at.
47    pub wasm_opt: bool,
48    /// `E2E_SKIP_BUILD`: uses the last build.
49    pub skip_build: bool,
50    /// `E2E_HEADLESS=0` shows the browser window.
51    pub headless: bool,
52    /// `E2E_CHROMEDRIVER`: chromedriver to use instead of downloading it.
53    pub chromedriver: Option<PathBuf>,
54    /// `E2E_WEBDRIVER`: URL of a running WebDriver (`http://localhost:9515`) to open the
55    /// sessions with, instead of a chromedriver started by the harness.
56    pub webdriver: Option<String>,
57}
58
59impl Settings {
60    /// `manifest_dir` is the `CARGO_MANIFEST_DIR` of the e2e crate, which lives directly in
61    /// the root of its workspace.
62    pub fn from_env(manifest_dir: &str) -> Result<Self> {
63        let workspace_root = Path::new(manifest_dir)
64            .parent()
65            .with_context(|| format!("{manifest_dir} is not inside a workspace"))?
66            .to_path_buf();
67
68        let target_dir = match std::env::var_os("CARGO_TARGET_DIR") {
69            Some(dir) => workspace_root.join(dir),
70            None => workspace_root.join("target"),
71        };
72
73        Ok(Self {
74            workspace_root,
75            target_dir,
76            release: flag("E2E_RELEASE", false),
77            wasm_opt: flag("E2E_WASM_OPT", false),
78            skip_build: flag("E2E_SKIP_BUILD", false),
79            headless: flag("E2E_HEADLESS", true),
80            chromedriver: std::env::var_os("E2E_CHROMEDRIVER").map(PathBuf::from),
81            webdriver: std::env::var("E2E_WEBDRIVER").ok(),
82        })
83    }
84
85    pub fn profile(&self) -> &'static str {
86        if self.release { "release" } else { "debug" }
87    }
88
89    /// `target/e2e/<profile>`, where the apps are built to.
90    pub fn build_dir(&self) -> PathBuf {
91        self.target_dir.join("e2e").join(self.profile())
92    }
93
94    /// `target/e2e/<suite>`: logs and artifacts of failed tests.
95    pub fn work_dir(&self, suite: &str) -> PathBuf {
96        self.target_dir.join("e2e").join(suite)
97    }
98}
99
100fn flag(name: &str, default: bool) -> bool {
101    match std::env::var(name) {
102        Ok(value) => parse_flag(&value),
103        Err(_) => default,
104    }
105}
106
107fn parse_flag(value: &str) -> bool {
108    !matches!(value, "" | "0" | "false" | "no")
109}
110
111/// How the Chrome sessions are set up, apart from what every app gets.
112#[derive(Debug, Clone)]
113pub struct ChromeConfig {
114    pub window_size: (u32, u32),
115    /// `--lang`, which also decides `Accept-Language`.
116    pub lang: &'static str,
117    /// Additional command line arguments.
118    pub args: &'static [&'static str],
119}
120
121impl Default for ChromeConfig {
122    fn default() -> Self {
123        Self {
124            window_size: (1400, 1000),
125            lang: "en-US",
126            args: &[],
127        }
128    }
129}
130
131/// The part of the environment every suite has. An [`Env`] dereferences to it.
132pub struct Core {
133    pub suite: &'static str,
134    pub settings: Settings,
135    /// `http://127.0.0.1:<port>`, without a trailing slash.
136    pub base_url: String,
137    /// `target/e2e/<suite>`: logs and artifacts of failed tests.
138    pub work_dir: PathBuf,
139    pub http: reqwest::Client,
140    chrome: ChromeConfig,
141    webdriver: Arc<WebDriverManager>,
142}
143
144impl Core {
145    /// Prepares the work directory, removing what the previous run left in `artifacts`.
146    pub fn new(
147        suite: &'static str,
148        settings: Settings,
149        base_url: String,
150        chrome: ChromeConfig,
151    ) -> Result<Self> {
152        let work_dir = settings.work_dir(suite);
153        std::fs::create_dir_all(&work_dir)
154            .with_context(|| format!("can't create {}", work_dir.display()))?;
155        // Only the failures of this run belong there
156        let _ = std::fs::remove_dir_all(work_dir.join("artifacts"));
157
158        let http = reqwest::Client::builder()
159            .timeout(Duration::from_secs(30))
160            .build()?;
161
162        Ok(Self {
163            suite,
164            webdriver: webdriver_manager(&settings),
165            settings,
166            base_url,
167            work_dir,
168            http,
169            chrome,
170        })
171    }
172
173    pub fn url(&self, path: &str) -> String {
174        format!("{}{path}", self.base_url)
175    }
176
177    /// A new Chrome session. Each browser test gets its own.
178    pub async fn new_browser(&self) -> Result<WebDriver> {
179        let mut caps = DesiredCapabilities::chrome();
180        if self.settings.headless {
181            caps.set_headless()?;
182        }
183        let (width, height) = self.chrome.window_size;
184        caps.add_arg(&format!("--window-size={width},{height}"))?;
185        caps.add_arg(&format!("--lang={}", self.chrome.lang))?;
186        for arg in [
187            "--no-first-run",
188            "--no-default-browser-check",
189            "--disable-search-engine-choice-screen",
190        ]
191        .iter()
192        .chain(self.chrome.args)
193        {
194            caps.add_arg(arg)?;
195        }
196        // After a login form is used, the password manager offers to save the password (and
197        // warns about it having leaked). Its bubble takes the clicks meant for the page.
198        caps.add_experimental_option(
199            "prefs",
200            serde_json::json!({
201                "credentials_enable_service": false,
202                "profile.password_manager_enabled": false,
203                "profile.password_manager_leak_detection": false,
204            }),
205        )?;
206        caps.add_arg("--disable-features=PasswordLeakDetection")?;
207        // The console is checked after each test
208        caps.set_browser_log_level(LoggingPrefsLogLevel::All)?;
209        // Leaves `window.alert`/`confirm` open for the test to answer
210        caps.set("unhandledPromptBehavior", "ignore")?;
211
212        let driver = match &self.settings.webdriver {
213            Some(url) => WebDriver::builder(url, caps)
214                .poller(poller())
215                .await
216                .with_context(|| format!("can't start Chrome through the WebDriver at {url}"))?,
217            None => self
218                .webdriver
219                .launch(caps)
220                .await
221                .context("can't start Chrome through chromedriver")?,
222        };
223
224        // With E2E_HEADLESS=0 the windows of parallel tests take the system focus from each
225        // other. A page losing it blurs its focused element, which closes drop-downs in the
226        // middle of a test. Emulated, the page keeps the focus, as it does headless.
227        let emulated = driver
228            .cdp()
229            .send_raw(
230                "Emulation.setFocusEmulationEnabled",
231                serde_json::json!({ "enabled": true }),
232            )
233            .await;
234        if let Err(err) = emulated {
235            let _ = driver.quit().await;
236            return Err(err).context("can't emulate the focus of the page");
237        }
238        Ok(driver)
239    }
240}
241
242/// A port nothing listens on at the moment, for a server the environment starts.
243pub fn free_port() -> Result<u16> {
244    let listener = TcpListener::bind("127.0.0.1:0")?;
245    Ok(listener.local_addr()?.port())
246}
247
248/// Element queries wait up to [`WAIT`], checking every [`POLL`].
249fn poller() -> Arc<ElementPollerWithTimeout> {
250    Arc::new(ElementPollerWithTimeout::new(WAIT, POLL))
251}
252
253fn webdriver_manager(settings: &Settings) -> Arc<WebDriverManager> {
254    let mut builder = WebDriverManager::builder().match_local().poller(poller());
255    if let Some(chromedriver) = &settings.chromedriver {
256        builder = builder.driver_binary(BrowserKind::Chrome, chromedriver);
257    }
258    builder.build()
259}
260
261#[cfg(test)]
262mod tests {
263    use super::parse_flag;
264
265    #[test]
266    fn flags() {
267        for off in ["", "0", "false", "no"] {
268            assert!(!parse_flag(off), "{off:?}");
269        }
270        for on in ["1", "true", "yes"] {
271            assert!(parse_flag(on), "{on:?}");
272        }
273    }
274}