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