Skip to main content

vertigo_testing/
ctx.rs

1//! What a browser test gets: a Chrome session plus helpers that know how a vertigo app
2//! behaves.
3
4use std::{
5    ops::Deref,
6    path::PathBuf,
7    sync::{Arc, Mutex, PoisonError},
8    time::Instant,
9};
10
11use anyhow::{Context, Result, anyhow, bail, ensure};
12use serde_json::Value;
13use thirtyfour::{BrowserLogEntry, By, Key, WebDriver, WebElement, prelude::ElementQueryable};
14
15use crate::env::{Env, POLL, WAIT};
16
17pub struct Ctx<E> {
18    pub env: Arc<E>,
19    pub driver: WebDriver,
20    /// Name of the test, as the runner lists it.
21    pub name: String,
22    allowed_console: Arc<Mutex<Vec<String>>>,
23}
24
25impl<E> Clone for Ctx<E> {
26    fn clone(&self) -> Self {
27        Self {
28            env: self.env.clone(),
29            driver: self.driver.clone(),
30            name: self.name.clone(),
31            allowed_console: self.allowed_console.clone(),
32        }
33    }
34}
35
36impl<E> Deref for Ctx<E> {
37    type Target = WebDriver;
38
39    fn deref(&self) -> &WebDriver {
40        &self.driver
41    }
42}
43
44/// What hydration reported about itself (`window.__vertigo_hydration`).
45#[derive(Debug, Clone, Copy)]
46pub struct HydrationReport {
47    pub root_found: bool,
48    pub matched: u64,
49    pub hydratable: u64,
50    pub skipped: u64,
51    pub total: u64,
52    /// Server-rendered elements hydration removed, as nothing in the browser's tree took them.
53    /// `matched == hydratable` can hold while the server's markup goes, so a check of complete
54    /// hydration needs this too. `None` from a vertigo that doesn't report it.
55    pub discarded: Option<u64>,
56}
57
58impl<E: Env> Ctx<E> {
59    pub(crate) fn new(env: Arc<E>, driver: WebDriver, name: &str) -> Self {
60        Self {
61            env,
62            driver,
63            name: name.to_string(),
64            allowed_console: Default::default(),
65        }
66    }
67
68    pub fn url(&self, path: &str) -> String {
69        self.env.url(path)
70    }
71
72    /// Loads `path` and waits for the app to take over the server-rendered page.
73    pub async fn open(&self, path: &str) -> Result<()> {
74        self.driver.goto(self.url(path)).await?;
75        self.wait_booted().await
76    }
77
78    /// Reloads the page, waits for the new document to replace the old one and for its app to
79    /// start.
80    pub async fn reload(&self) -> Result<()> {
81        self.mark_document().await?;
82        self.driver.refresh().await?;
83        self.wait_for_new_document().await
84    }
85
86    /// Waits for a document other than the one `mark_document` marked to replace it, and for
87    /// its app to start.
88    pub async fn wait_for_new_document(&self) -> Result<()> {
89        self.wait_for("a new document", async || {
90            let old = self.js("return window.__e2eDocument === true").await?;
91            Ok((old == Value::Bool(false)).then_some(()))
92        })
93        .await?;
94        self.wait_booted().await
95    }
96
97    /// Until the WASM app mounts, the server-rendered page doesn't react to clicks or typing
98    /// the way the app does, so tests interact with a page only after this. Hydration
99    /// publishes its report when the first DOM batch of the app arrives.
100    pub async fn wait_booted(&self) -> Result<()> {
101        self.wait_for(
102            "the app to start (window.__vertigo_hydration)",
103            async || {
104                let booted = self.js("return window.__vertigo_hydration != null").await?;
105                Ok((booted == Value::Bool(true)).then_some(()))
106            },
107        )
108        .await
109    }
110
111    /// Polls `check` until it returns a value. Errors count as "not yet" (an element vertigo
112    /// replaced in the meantime is stale) until the time limit passes.
113    pub async fn wait_for<T>(
114        &self,
115        what: &str,
116        mut check: impl AsyncFnMut() -> Result<Option<T>>,
117    ) -> Result<T> {
118        let deadline = Instant::now() + WAIT;
119        loop {
120            let result = check().await;
121            let timed_out = Instant::now() > deadline;
122            match result {
123                Ok(Some(value)) => return Ok(value),
124                Ok(None) if timed_out => bail!("timed out waiting for {what}"),
125                Err(err) if timed_out => {
126                    return Err(err.context(format!("timed out waiting for {what}")));
127                }
128                _ => tokio::time::sleep(POLL).await,
129            }
130        }
131    }
132
133    pub async fn js(&self, script: &str) -> Result<Value> {
134        self.js_with(script, vec![]).await
135    }
136
137    pub async fn js_with(&self, script: &str, args: Vec<Value>) -> Result<Value> {
138        let ret = self
139            .driver
140            .execute(script, args)
141            .await
142            .with_context(|| format!("script failed: {script}"))?;
143        Ok(ret.json().clone())
144    }
145
146    /// Visible text of the page, with whitespace normalized.
147    pub async fn page_text(&self) -> Result<String> {
148        let text = self.js("return document.body.innerText").await?;
149        Ok(normalize(text.as_str().unwrap_or_default()))
150    }
151
152    pub async fn wait_for_text(&self, text: &str) -> Result<()> {
153        let text = normalize(text);
154        self.wait_for(&format!("text {text:?}"), async || {
155            Ok(self.page_text().await?.contains(&text).then_some(()))
156        })
157        .await
158    }
159
160    pub async fn wait_for_no_text(&self, text: &str) -> Result<()> {
161        let text = normalize(text);
162        self.wait_for(&format!("text {text:?} to disappear"), async || {
163            Ok((!self.page_text().await?.contains(&text)).then_some(()))
164        })
165        .await
166    }
167
168    /// First match; waits for it to appear.
169    pub async fn find(&self, by: By) -> Result<WebElement> {
170        Ok(self.driver.query(by).first().await?)
171    }
172
173    /// All matches at the moment, without waiting.
174    pub async fn find_all(&self, by: By) -> Result<Vec<WebElement>> {
175        Ok(self.driver.find_all(by).await?)
176    }
177
178    pub async fn wait_for_none(&self, by: By) -> Result<()> {
179        self.wait_for(&format!("no {by}"), async || {
180            Ok(self.find_all(by.clone()).await?.is_empty().then_some(()))
181        })
182        .await
183    }
184
185    pub async fn testid(&self, id: &str) -> Result<WebElement> {
186        self.find(By::Testid(id)).await
187    }
188
189    /// First `tag` whose whole text is `text`. The client splits adjacent texts into separate
190    /// nodes while SSR merges them, so this compares the element's normalized text, not its
191    /// text nodes.
192    pub async fn by_text(&self, tag: &str, text: &str) -> Result<WebElement> {
193        self.find(By::XPath(format!(
194            "//{tag}[normalize-space(.)={}]",
195            xpath_literal(text)
196        )))
197        .await
198    }
199
200    pub async fn click_link(&self, text: &str) -> Result<()> {
201        self.by_text("a", text).await?.click().await?;
202        Ok(())
203    }
204
205    /// Normalized text of the first match.
206    pub async fn text_of(&self, by: By) -> Result<String> {
207        Ok(normalize(&self.find(by).await?.text().await?))
208    }
209
210    /// Waits until the first match has exactly the `expected` text.
211    pub async fn wait_for_text_of(&self, by: By, expected: &str) -> Result<()> {
212        let expected = normalize(expected);
213        let mut last = None;
214        self.wait_for(&format!("{by} with text {expected:?}"), async || {
215            let text = self.text_of(by.clone()).await?;
216            let matches = text == expected;
217            last = Some(text);
218            Ok(matches.then_some(()))
219        })
220        .await
221        .with_context(|| format!("last text: {last:?}"))
222    }
223
224    /// Texts of all current matches.
225    pub async fn texts(&self, by: By) -> Result<Vec<String>> {
226        let mut texts = Vec::new();
227        for element in self.find_all(by).await? {
228            texts.push(normalize(&element.text().await?));
229        }
230        Ok(texts)
231    }
232
233    /// For each current match of `xpath`, the texts of its child elements. Read by one script,
234    /// so vertigo can't replace a node halfway through.
235    pub async fn children_texts(&self, xpath: &str) -> Result<Vec<Vec<String>>> {
236        let value = self
237            .js_with(
238                "const found = document.evaluate(arguments[0], document, null,
239                     XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
240                 const texts = [];
241                 for (let i = 0; i < found.snapshotLength; i++) {
242                     texts.push(Array.from(found.snapshotItem(i).children, child => child.innerText));
243                 }
244                 return texts;",
245                vec![Value::String(xpath.to_string())],
246            )
247            .await?;
248        let texts: Vec<Vec<String>> = serde_json::from_value(value)?;
249        Ok(texts
250            .into_iter()
251            .map(|texts| texts.iter().map(|text| normalize(text)).collect())
252            .collect())
253    }
254
255    /// Hrefs of all current matches, as written in the markup.
256    pub async fn hrefs(&self, css: &str) -> Result<Vec<String>> {
257        let hrefs = self
258            .js_with(
259                "return [...document.querySelectorAll(arguments[0])].map(a => a.getAttribute('href'))",
260                vec![css.into()],
261            )
262            .await?;
263        Ok(serde_json::from_value(hrefs)?)
264    }
265
266    /// Replaces the value of a field the way a user does. WebDriver's `clear()` doesn't send an
267    /// `input` event, so vertigo would keep the old value.
268    ///
269    /// Selects all with the keyboard, in the same `send_keys` as the rest: chromedriver moves the
270    /// caret to the end before typing into a field it takes for unfocused, which a field of a
271    /// window without the system focus is (with `E2E_HEADLESS=0`, the windows of parallel tests
272    /// take it from each other). A selection made earlier would be gone.
273    pub async fn retype(&self, element: &WebElement, text: &str) -> Result<()> {
274        let select_all = if cfg!(target_os = "macos") {
275            Key::Command
276        } else {
277            Key::Control
278        };
279        element.click().await?;
280        element
281            .send_keys(select_all + "a" + Key::Null + Key::Backspace + text)
282            .await?;
283        Ok(())
284    }
285
286    pub async fn value(&self, element: &WebElement) -> Result<String> {
287        Ok(element.prop("value").await?.unwrap_or_default())
288    }
289
290    /// Waits until the first match is a field with the `expected` value.
291    pub async fn wait_for_value(&self, by: By, expected: &str) -> Result<()> {
292        let mut last = None;
293        self.wait_for(&format!("{by} with value {expected:?}"), async || {
294            let value = self.value(&self.find(by.clone()).await?).await?;
295            let matches = value == expected;
296            last = Some(value);
297            Ok(matches.then_some(()))
298        })
299        .await
300        .with_context(|| format!("last value: {last:?}"))
301    }
302
303    /// Waits until the first match is shown or hidden (`display`, `visibility`, size).
304    pub async fn wait_for_displayed(&self, by: By, displayed: bool) -> Result<()> {
305        let state = if displayed { "shown" } else { "hidden" };
306        self.wait_for(&format!("{by} to be {state}"), async || {
307            let element = self.find(by.clone()).await?;
308            Ok((element.is_displayed().await? == displayed).then_some(()))
309        })
310        .await
311    }
312
313    /// Computed style `property` (in CSS spelling, f. ex. `font-weight`) of `element`.
314    pub async fn style(&self, element: &WebElement, property: &str) -> Result<String> {
315        let value = self
316            .js_with(
317                "return getComputedStyle(arguments[0]).getPropertyValue(arguments[1])",
318                vec![element.to_json()?, Value::String(property.to_string())],
319            )
320            .await?;
321        value
322            .as_str()
323            .map(str::to_string)
324            .with_context(|| format!("no style {property}: {value}"))
325    }
326
327    /// Path and query of the current URL.
328    pub async fn path(&self) -> Result<String> {
329        let url = self.driver.current_url().await?;
330        Ok(match url.query() {
331            Some(query) => format!("{}?{query}", url.path()),
332            None => url.path().to_string(),
333        })
334    }
335
336    pub async fn wait_for_path(&self, expected: &str) -> Result<()> {
337        self.wait_for(&format!("the URL to become {expected}"), async || {
338            Ok((self.path().await? == expected).then_some(()))
339        })
340        .await
341    }
342
343    pub async fn wait_for_title(&self, expected: &str) -> Result<()> {
344        self.wait_for(&format!("the title to become {expected:?}"), async || {
345            Ok((self.driver.title().await? == expected).then_some(()))
346        })
347        .await
348    }
349
350    /// Marks the current document; `assert_same_document` then tells navigation inside the
351    /// app from a full page load.
352    pub async fn mark_document(&self) -> Result<()> {
353        self.js("window.__e2eDocument = true").await?;
354        Ok(())
355    }
356
357    pub async fn assert_same_document(&self) -> Result<()> {
358        let same = self.js("return window.__e2eDocument === true").await?;
359        ensure!(
360            same == Value::Bool(true),
361            "the browser loaded a new document instead of navigating in the app"
362        );
363        Ok(())
364    }
365
366    pub async fn scroll_y(&self) -> Result<f64> {
367        let y = self.js("return window.scrollY").await?;
368        y.as_f64().context("scrollY is not a number")
369    }
370
371    pub async fn hydration_report(&self) -> Result<HydrationReport> {
372        let raw = self.js("return window.__vertigo_hydration ?? null").await?;
373        ensure!(!raw.is_null(), "the page published no hydration report");
374
375        let number = |name: &str| {
376            raw.get(name)
377                .and_then(Value::as_u64)
378                .with_context(|| format!("no numeric {name:?} in {raw}"))
379        };
380        Ok(HydrationReport {
381            root_found: raw.get("rootFound").and_then(Value::as_bool) == Some(true),
382            matched: number("matched")?,
383            hydratable: number("hydratable")?,
384            skipped: number("skipped")?,
385            total: number("total")?,
386            discarded: raw.get("discarded").and_then(Value::as_u64),
387        })
388    }
389
390    /// Waits for a `window.confirm`/`alert`, checks its text and answers it.
391    pub async fn answer_dialog(&self, expected: &str, accept: bool) -> Result<()> {
392        let text = self
393            .wait_for("a dialog", async || {
394                Ok(self.driver.get_alert_text().await.ok())
395            })
396            .await?;
397        ensure!(
398            text == expected,
399            "dialog says {text:?}, expected {expected:?}"
400        );
401        if accept {
402            self.driver.accept_alert().await?;
403        } else {
404            self.driver.dismiss_alert().await?;
405        }
406        Ok(())
407    }
408
409    /// Console errors (SEVERE entries) containing `pattern` don't fail the test.
410    pub fn allow_console(&self, pattern: &str) {
411        self.allowed_console
412            .lock()
413            .unwrap_or_else(PoisonError::into_inner)
414            .push(pattern.to_string());
415    }
416
417    /// Runs after the test body: fails the test on console errors or a dialog left open and,
418    /// on any failure, saves a screenshot, the page source and the console log.
419    pub(crate) async fn finish(&self, result: Result<()>) -> Result<()> {
420        let dialog = self.driver.get_alert_text().await.ok();
421        if dialog.is_some() {
422            let _ = self.driver.dismiss_alert().await;
423        }
424        let logs = self.driver.browser_log().await.unwrap_or_default();
425
426        let result = result.and_then(|()| {
427            if let Some(text) = dialog {
428                bail!("the test left a dialog open: {text:?}");
429            }
430            self.check_console(&logs)
431        });
432
433        match result {
434            Ok(()) => Ok(()),
435            Err(err) => {
436                let dir = self.save_artifacts(&err, &logs).await;
437                Err(anyhow!(
438                    "{err:?}\n\nscreenshot, page and console log: {}",
439                    dir.display()
440                ))
441            }
442        }
443    }
444
445    fn check_console(&self, logs: &[BrowserLogEntry]) -> Result<()> {
446        let allowed = self
447            .allowed_console
448            .lock()
449            .unwrap_or_else(PoisonError::into_inner);
450        let errors: Vec<&str> = logs
451            .iter()
452            .filter(|entry| entry.level == "SEVERE")
453            .map(|entry| entry.message.as_str())
454            .filter(|message| !allowed.iter().any(|pattern| message.contains(pattern)))
455            .collect();
456
457        ensure!(
458            errors.is_empty(),
459            "the browser console reported {} error(s):\n  {}",
460            errors.len(),
461            errors.join("\n  ")
462        );
463        Ok(())
464    }
465
466    async fn save_artifacts(&self, err: &anyhow::Error, logs: &[BrowserLogEntry]) -> PathBuf {
467        let dir = self
468            .env
469            .work_dir
470            .join("artifacts")
471            .join(self.name.replace("::", "__"));
472        let _ = std::fs::remove_dir_all(&dir);
473        let _ = std::fs::create_dir_all(&dir);
474
475        if let Ok(png) = self.driver.screenshot_as_png().await {
476            let _ = std::fs::write(dir.join("screenshot.png"), png);
477        }
478        if let Ok(source) = self.driver.source().await {
479            let _ = std::fs::write(dir.join("page.html"), source);
480        }
481        let url = match self.driver.current_url().await {
482            Ok(url) => url.to_string(),
483            Err(err) => format!("(unknown: {err})"),
484        };
485        let _ = std::fs::write(dir.join("error.txt"), format!("{url}\n\n{err:?}\n"));
486        let console: String = logs
487            .iter()
488            .map(|entry| format!("{} {}\n", entry.level, entry.message))
489            .collect();
490        let _ = std::fs::write(dir.join("console.log"), console);
491
492        dir
493    }
494}
495
496/// Collapses whitespace, non-breaking spaces included.
497pub fn normalize(text: &str) -> String {
498    text.split(|c: char| c.is_whitespace())
499        .filter(|part| !part.is_empty())
500        .collect::<Vec<_>>()
501        .join(" ")
502}
503
504/// Quotes `text` as an XPath string literal.
505pub fn xpath_literal(text: &str) -> String {
506    if !text.contains('\'') {
507        format!("'{text}'")
508    } else if !text.contains('"') {
509        format!("\"{text}\"")
510    } else {
511        let parts: Vec<String> = text.split('\'').map(|part| format!("'{part}'")).collect();
512        format!("concat({})", parts.join(", \"'\", "))
513    }
514}
515
516#[cfg(test)]
517mod tests {
518    use super::{normalize, xpath_literal};
519
520    #[test]
521    fn normalize_collapses_whitespace() {
522        assert_eq!(normalize("  a \n\t b\u{a0}c  "), "a b c");
523        assert_eq!(normalize(""), "");
524    }
525
526    #[test]
527    fn xpath_literal_quotes() {
528        assert_eq!(xpath_literal("plain"), "'plain'");
529        assert_eq!(xpath_literal("it's"), "\"it's\"");
530        assert_eq!(
531            xpath_literal("it's \"x\""),
532            "concat('it', \"'\", 's \"x\"')"
533        );
534    }
535}