Skip to main content

yew_e2e/
driver.rs

1//! Which browser the suite drives, and the WebDriver server that drives it.
2
3use std::fmt;
4use std::future::Future;
5use std::net::SocketAddr;
6use std::path::PathBuf;
7use std::str::FromStr;
8use std::time::Duration;
9
10use anyhow::{Context, Result, anyhow, bail, ensure};
11use thirtyfour::common::capabilities::firefox::FirefoxPreferences;
12use thirtyfour::prelude::*;
13use tokio::time::{Instant, timeout};
14
15pub(crate) const STARTUP_TIMEOUT: Duration = Duration::from_secs(30);
16pub(crate) const QUIT_TIMEOUT: Duration = Duration::from_secs(5);
17pub(crate) const REAP_TIMEOUT: Duration = Duration::from_secs(5);
18
19/// Cancellation must not leave a browser behind. On Unix the driver starts a
20/// new process group, so the kill reaches only descendants of this test's
21/// driver, never a person's existing browser. We reap the direct driver child;
22/// adoption and reaping of its terminated descendants belongs to the OS.
23/// Windows currently has only the
24/// child handle fallback; descendant job ownership is separate platform work.
25struct OwnedProcess {
26    child: tokio::process::Child,
27    #[cfg(unix)]
28    group: Option<i32>,
29}
30
31impl OwnedProcess {
32    fn spawn(command: &mut tokio::process::Command) -> Result<Self> {
33        command.kill_on_drop(true);
34        #[cfg(unix)]
35        command.process_group(0);
36        let child = command.spawn()?;
37        Ok(Self {
38            #[cfg(unix)]
39            group: child.id().and_then(|pid| i32::try_from(pid).ok()),
40            child,
41        })
42    }
43
44    fn stop(&mut self) -> Result<()> {
45        #[cfg(unix)]
46        if let Some(group) = self.group.take() {
47            // This is the positive PID returned by our process_group(0) spawn.
48            // Forget it before reaping, so Drop cannot target a reused group.
49            ensure!(group > 0, "invalid owned driver process group");
50            if unsafe { libc::kill(-group, libc::SIGKILL) } != 0 {
51                let error = std::io::Error::last_os_error();
52                if error.raw_os_error() != Some(libc::ESRCH) {
53                    return Err(error).context("terminating the test driver process group");
54                }
55            }
56        }
57        self.child
58            .start_kill()
59            .context("terminating the test driver")
60    }
61
62    async fn reap(&mut self) -> Result<()> {
63        let stopped = self.stop();
64        let reaped = timeout(REAP_TIMEOUT, self.child.wait())
65            .await
66            .context("test driver reap timed out")?
67            .context("reaping the test driver");
68        stopped?;
69        reaped?;
70        Ok(())
71    }
72}
73
74impl Drop for OwnedProcess {
75    fn drop(&mut self) {
76        if let Err(error) = self.stop() {
77            tracing::warn!(%error, "stopping a dropped test driver");
78        }
79        // Tokio's kill_on_drop child guard also arranges orphan reaping when
80        // an async startup/cleanup future is cancelled before wait completes.
81    }
82}
83
84/// A browser this suite knows how to drive.
85#[derive(Debug, Clone, Copy, PartialEq, Eq)]
86pub enum Engine {
87    /// Firefox, driven through `geckodriver`.
88    Firefox,
89    /// Chrome, driven through `chromedriver`, which is fetched to match the
90    /// installed Chrome when none is on the `PATH`.
91    Chrome,
92}
93
94/// Which colour scheme `E2E_THEME` asks the browser to report, or `None` where
95/// it says nothing and the machine answers for itself. Without it every run is
96/// read in whatever the machine prefers, and the other scheme is never looked
97/// at.
98fn forced_dark() -> Result<Option<bool>> {
99    match std::env::var("E2E_THEME") {
100        Ok(value) => theme_preference(&value).map(Some),
101        Err(std::env::VarError::NotPresent) => Ok(None),
102        Err(error) => Err(error).context("reading E2E_THEME"),
103    }
104}
105
106fn theme_preference(value: &str) -> Result<bool> {
107    match value {
108        "dark" => Ok(true),
109        "light" => Ok(false),
110        _ => bail!("E2E_THEME must be dark or light, got {value:?}"),
111    }
112}
113
114fn motion_preference(value: &str) -> Result<bool> {
115    match value {
116        "reduce" => Ok(true),
117        "normal" => Ok(false),
118        _ => bail!("E2E_MOTION must be reduce or normal, got {value:?}"),
119    }
120}
121
122fn forced_motion() -> Result<Option<bool>> {
123    match std::env::var("E2E_MOTION") {
124        Ok(value) => motion_preference(&value).map(Some),
125        Err(std::env::VarError::NotPresent) => Ok(None),
126        Err(error) => Err(error).context("reading E2E_MOTION"),
127    }
128}
129
130/// The device pixel ratio `E2E_SCALE` asks the browser to report, or `None`
131/// where it says nothing and a session runs at the platform's own ratio --
132/// ordinarily 1, so a high-DPI-specific path is never actually exercised
133/// without this. Unlike `E2E_THEME`/`E2E_MOTION`, both engines answer it:
134/// Firefox through a preference, Chrome through a launch flag.
135fn forced_scale() -> Result<Option<f64>> {
136    match std::env::var("E2E_SCALE") {
137        Ok(value) => {
138            let scale: f64 = value
139                .parse()
140                .with_context(|| format!("E2E_SCALE must be a number, got {value:?}"))?;
141            ensure!(scale > 0.0, "E2E_SCALE must be positive, got {scale}");
142            Ok(Some(scale))
143        }
144        Err(std::env::VarError::NotPresent) => Ok(None),
145        Err(error) => Err(error).context("reading E2E_SCALE"),
146    }
147}
148
149impl Engine {
150    /// Every engine, in the order a run with no preference tries them.
151    pub const ALL: [Engine; 2] = [Engine::Firefox, Engine::Chrome];
152
153    /// The WebDriver server that drives this engine.
154    pub fn driver(self) -> &'static str {
155        match self {
156            Engine::Firefox => "geckodriver",
157            Engine::Chrome => "chromedriver",
158        }
159    }
160
161    /// What to call this engine where somebody reads it.
162    pub fn name(self) -> &'static str {
163        match self {
164            Engine::Firefox => "firefox",
165            Engine::Chrome => "chrome",
166        }
167    }
168
169    /// The capabilities a session is opened with, headless unless asked
170    /// otherwise.
171    pub fn capabilities(self, headed: bool) -> Result<Capabilities> {
172        self.with_preferences(headed, forced_dark()?, forced_motion()?, forced_scale()?)
173    }
174
175    fn with_preferences(
176        self,
177        headed: bool,
178        dark: Option<bool>,
179        reduced_motion: Option<bool>,
180        scale: Option<f64>,
181    ) -> Result<Capabilities> {
182        match self {
183            Engine::Firefox => {
184                let mut caps = DesiredCapabilities::firefox();
185
186                if !headed {
187                    caps.add_arg("--headless")?;
188                }
189
190                if dark.is_some() || reduced_motion.is_some() || scale.is_some() {
191                    let mut prefs = FirefoxPreferences::new();
192                    if let Some(dark) = dark {
193                        prefs.set("ui.systemUsesDarkTheme", i64::from(dark))?;
194                    }
195                    if let Some(reduced) = reduced_motion {
196                        prefs.set("ui.prefersReducedMotion", i64::from(reduced))?;
197                    }
198                    if let Some(scale) = scale {
199                        prefs.set("layout.css.devPixelsPerPx", scale.to_string())?;
200                    }
201                    caps.set_preferences(prefs)?;
202                }
203
204                Ok(caps.into())
205            }
206            Engine::Chrome => {
207                let mut caps = DesiredCapabilities::chrome();
208
209                if !headed {
210                    caps.add_arg("--headless=new")?;
211                }
212
213                if dark.is_some() {
214                    bail!("E2E_THEME is a Firefox preference and chrome has no answer for it");
215                }
216                if reduced_motion.is_some() {
217                    bail!("E2E_MOTION is a Firefox preference and chrome has no answer for it");
218                }
219
220                if let Some(scale) = scale {
221                    caps.add_arg(&format!("--force-device-scale-factor={scale}"))?;
222                    caps.add_arg("--high-dpi-support=1")?;
223                }
224
225                Ok(caps.into())
226            }
227        }
228    }
229
230    /// Where this engine's driver already is, or `None` for a machine that has
231    /// not got one.
232    pub(crate) fn installed(self) -> Option<PathBuf> {
233        if let Some(path) = on_path(self.driver()) {
234            return Some(path);
235        }
236
237        let cached = crate::fetch::cached(self).ok()?;
238        cached.is_file().then_some(cached)
239    }
240
241    /// Whether this engine can be driven without fetching anything.
242    pub fn available(self) -> bool {
243        self.installed().is_some()
244    }
245
246    /// Whether this engine's browser is here, whether or not its driver is.
247    pub fn browser_present(self) -> bool {
248        match self {
249            Engine::Firefox => false,
250            Engine::Chrome => crate::fetch::chrome_present(),
251        }
252    }
253
254    /// The first engine whose driver this machine has — failing that, the first
255    /// whose *browser* it has, which a fetch can finish.
256    pub fn detect() -> Option<Engine> {
257        Engine::ALL
258            .into_iter()
259            .find(|engine| engine.available())
260            .or_else(|| {
261                Engine::ALL
262                    .into_iter()
263                    .find(|engine| engine.browser_present())
264            })
265    }
266
267    /// [`Engine::detect`], or an error naming what would have satisfied it.
268    pub fn require() -> Result<Engine> {
269        if let Some(engine) = Engine::detect() {
270            return Ok(engine);
271        }
272
273        let drivers = Engine::ALL
274            .map(|engine| format!("{} (for {})", engine.driver(), engine.name()))
275            .join(", ");
276
277        bail!(
278            "No browser this suite can drive. It needs either a WebDriver server \
279             on PATH — one of: {drivers} — or a Chrome it can fetch a matching \
280             chromedriver for, which it does by itself into e2e/ under the \
281             build directory."
282        )
283    }
284
285    /// Where this engine's driver is, fetching one if that is the only way.
286    pub(crate) fn provision(self) -> Result<PathBuf> {
287        if let Some(path) = self.installed() {
288            return Ok(path);
289        }
290
291        crate::fetch::fetch(self)
292    }
293}
294
295impl fmt::Display for Engine {
296    #[inline]
297    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
298        f.write_str(self.name())
299    }
300}
301
302impl FromStr for Engine {
303    type Err = anyhow::Error;
304
305    fn from_str(input: &str) -> Result<Self> {
306        for engine in Engine::ALL {
307            if input.eq_ignore_ascii_case(engine.name()) {
308                return Ok(engine);
309            }
310        }
311
312        match input.to_ascii_lowercase().as_str() {
313            "gecko" => Ok(Engine::Firefox),
314            "chromium" => Ok(Engine::Chrome),
315            _ => {
316                let names = Engine::ALL.map(Engine::name).join(", ");
317                Err(anyhow!(
318                    "{input:?} is not a browser this suite drives: {names}"
319                ))
320            }
321        }
322    }
323}
324
325/// Where `name` is on `PATH`, taking the platform's executable suffix into
326/// account.
327fn on_path(name: &str) -> Option<PathBuf> {
328    let path = std::env::var_os("PATH")?;
329
330    let suffixes: Vec<String> = match cfg!(windows) {
331        true => std::env::var("PATHEXT")
332            .unwrap_or_else(|_| String::from(".EXE"))
333            .split(';')
334            .map(str::to_ascii_lowercase)
335            .chain([String::new()])
336            .collect(),
337        false => vec![String::new()],
338    };
339
340    for dir in std::env::split_paths(&path) {
341        for suffix in &suffixes {
342            let candidate = dir.join(format!("{name}{suffix}"));
343
344            if candidate.is_file() {
345                return Some(candidate);
346            }
347        }
348    }
349
350    None
351}
352
353/// A running WebDriver server, and the address it answers on.
354pub(crate) struct Driver {
355    engine: Engine,
356    process: OwnedProcess,
357    stdout: tokio::io::BufReader<tokio::process::ChildStdout>,
358    stderr: tokio::io::BufReader<tokio::process::ChildStderr>,
359    stdout_line: Vec<u8>,
360    stderr_line: Vec<u8>,
361    stdout_open: bool,
362    stderr_open: bool,
363    log: String,
364    pub(crate) address: SocketAddr,
365}
366
367impl Driver {
368    /// Start one, and do not return until it says where it is answering.
369    pub(crate) async fn new(engine: Engine, deadline: Instant) -> Result<Self> {
370        use tokio::process::Command;
371
372        let binary = engine.installed().with_context(|| {
373            anyhow!(
374                "No {} to drive {engine} with. It is provisioned once before the \
375                 run starts; see `harness::choose`.",
376                engine.driver()
377            )
378        })?;
379
380        let mut command = Command::new(&binary);
381        command.args(engine.port_args());
382        Self::start_until_it_keeps_a_port(engine, &mut command, deadline).await
383    }
384
385    /// Start one with `command`, and start it again each time it exits having
386    /// lost the port it picked to another process, up to [`PORT_RETRIES`] times
387    /// and all within `deadline`.
388    ///
389    /// chromedriver told to take any port takes one on `[::1]` and then tries to
390    /// take the same number on `127.0.0.1`. The two are handed out separately,
391    /// so under parallel runs that number is sometimes already taken on IPv4
392    /// and chromedriver gives up. Another start picks another number.
393    pub(crate) async fn start_until_it_keeps_a_port(
394        engine: Engine,
395        command: &mut tokio::process::Command,
396        deadline: Instant,
397    ) -> Result<Self> {
398        let mut lost = 0;
399
400        loop {
401            match Self::start(engine, command, deadline).await {
402                Err(error) if error.downcast_ref::<PortTaken>().is_some() => {
403                    lost += 1;
404
405                    if lost > PORT_RETRIES {
406                        return Err(error.context(format!(
407                            "{} lost the port it picked {lost} times in a row",
408                            engine.driver()
409                        )));
410                    }
411
412                    tracing::warn!(
413                        driver = engine.driver(),
414                        attempt = lost,
415                        "test driver lost the port it picked; starting it again: {error:#}"
416                    );
417                }
418                result => return result,
419            }
420        }
421    }
422
423    pub(crate) async fn start(
424        engine: Engine,
425        command: &mut tokio::process::Command,
426        deadline: Instant,
427    ) -> Result<Self> {
428        use std::process::Stdio;
429        use tokio::io::BufReader;
430
431        command
432            .stdout(Stdio::piped())
433            .stderr(Stdio::piped())
434            .stdin(Stdio::null());
435        let mut process = OwnedProcess::spawn(command).context("spawning the test driver")?;
436        let stdout = BufReader::new(process.child.stdout.take().context("missing stdout")?);
437        let stderr = BufReader::new(process.child.stderr.take().context("missing stderr")?);
438        let mut driver = Self {
439            engine,
440            process,
441            stdout,
442            stderr,
443            stdout_line: Vec::new(),
444            stderr_line: Vec::new(),
445            stdout_open: true,
446            stderr_open: true,
447            log: String::new(),
448            address: SocketAddr::from(([127, 0, 0, 1], 0)),
449        };
450        let ready = tokio::time::timeout_at(deadline, async {
451            for _ in 0..READY_LINES {
452                if !driver.io().await? {
453                    if engine.lost_its_port(&driver.log) {
454                        return Err(PortTaken.into());
455                    }
456
457                    bail!("driver stopped before announcing its address");
458                }
459                if let Some(address) = driver.log.lines().find_map(|line| engine.address_of(line)) {
460                    driver.address = address;
461                    return Ok(());
462                }
463            }
464            bail!("driver did not announce its address in its first {READY_LINES} lines")
465        })
466        .await
467        .context("test browser startup timed out while waiting for the driver address")
468        .and_then(|result| result);
469        if let Err(error) = ready {
470            let error = error.context(driver.diagnostics());
471            return Err(with_cleanup(error, driver.terminate().await));
472        }
473        Ok(driver)
474    }
475
476    /// Which engine this is driving, for whatever reads it back.
477    #[inline]
478    pub(crate) fn engine(&self) -> Engine {
479        self.engine
480    }
481
482    #[inline]
483    pub(crate) async fn io(&mut self) -> Result<bool> {
484        use tokio::io::AsyncBufReadExt;
485        while self.stdout_open || self.stderr_open {
486            let (n, stderr) = tokio::select! {
487                n = self.stdout.read_until(b'\n', &mut self.stdout_line), if self.stdout_open => (n?, false),
488                n = self.stderr.read_until(b'\n', &mut self.stderr_line), if self.stderr_open => (n?, true),
489            };
490            if n == 0 {
491                if stderr {
492                    self.stderr_open = false;
493                } else {
494                    self.stdout_open = false;
495                }
496                continue;
497            }
498            // Keep each pipe's partial line across select cancellation.
499            let bytes = if stderr {
500                &mut self.stderr_line
501            } else {
502                &mut self.stdout_line
503            };
504            let line = String::from_utf8_lossy(bytes);
505            self.log.push_str(&line);
506            if self.log.len() > 8192 {
507                let mut at = self.log.len() - 8192;
508                while !self.log.is_char_boundary(at) {
509                    at += 1;
510                }
511                self.log.drain(..at);
512            }
513            tracing::trace!(driver = self.engine.driver(), stderr, line = %line.trim(), "test driver output");
514            bytes.clear();
515            return Ok(true);
516        }
517        Ok(false)
518    }
519
520    pub(crate) fn diagnostics(&self) -> String {
521        format!("{}{}", self.engine.driver(), quoted(&self.log))
522    }
523
524    /// Drain both pipes while a protocol operation is pending: a full stderr
525    /// pipe during browser boot must not masquerade as a hung session request.
526    pub(crate) async fn during<T>(
527        &mut self,
528        deadline: Instant,
529        stage: &str,
530        operation: impl Future<Output = Result<T>>,
531    ) -> Result<T> {
532        let mut operation = std::pin::pin!(operation);
533        let result = loop {
534            tokio::select! {
535                biased;
536                _ = tokio::time::sleep_until(deadline) => break Err(TimedOut(stage.to_owned()).into()),
537                result = operation.as_mut() => break result,
538                read = self.io(), if self.stdout_open || self.stderr_open => {
539                    if let Err(error) = read { break Err(error); }
540                    // A driver may close logging pipes before replying to quit.
541                    // Keep polling the protocol, still under the same deadline.
542                }
543            }
544        };
545        result.with_context(|| format!("browser {stage}: {}", self.diagnostics()))
546    }
547
548    pub(crate) async fn terminate(&mut self) -> Result<()> {
549        self.process.reap().await
550    }
551}
552
553/// A driver that exited before announcing its address because the port it
554/// picked was taken before it could listen on it, which starting it again
555/// gets past.
556#[derive(Debug)]
557pub(crate) struct PortTaken;
558
559impl fmt::Display for PortTaken {
560    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
561        f.write_str(
562            "driver stopped before announcing its address: the port it picked \
563             was taken before it could listen on it",
564        )
565    }
566}
567
568impl std::error::Error for PortTaken {}
569
570/// A browser operation that did not answer by its deadline, named by stage.
571#[derive(Debug)]
572pub(crate) struct TimedOut(pub(crate) String);
573
574impl fmt::Display for TimedOut {
575    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
576        write!(f, "test browser {} timed out", self.0)
577    }
578}
579
580impl std::error::Error for TimedOut {}
581
582pub(crate) fn with_cleanup(error: anyhow::Error, cleanup: Result<()>) -> anyhow::Error {
583    match cleanup {
584        Ok(()) => error,
585        Err(cleanup) => error.context(format!("test browser cleanup also failed: {cleanup:#}")),
586    }
587}
588
589/// How many lines of a driver's greeting are read while waiting for it to say it
590/// is listening. chromedriver takes four; the rest is headroom for a version
591/// that says more.
592const READY_LINES: usize = 16;
593
594/// How many more times a driver that lost the port it picked is started before
595/// its start fails. Losing it is rare, so losing it again on the next try is
596/// rarer still; a driver that keeps losing has something else wrong with it.
597const PORT_RETRIES: usize = 3;
598
599impl Engine {
600    /// How this engine's driver is told to serve on a port of its own choosing.
601    fn port_args(self) -> &'static [&'static str] {
602        match self {
603            Engine::Firefox => &["--port", "0"],
604            Engine::Chrome => &["--port=0"],
605        }
606    }
607
608    /// Whether what the driver said before it exited says that the port it
609    /// picked was taken before it could listen on it.
610    ///
611    /// Only chromedriver loses one: geckodriver listens on the port the system
612    /// gives it, while chromedriver listens on `[::1]` first and then asks for
613    /// the same number on `127.0.0.1`, saying `IPv4 port not available` when it
614    /// is taken (or the IPv6 one, the other way around).
615    fn lost_its_port(self, said: &str) -> bool {
616        match self {
617            Engine::Firefox => false,
618            Engine::Chrome => said.contains("port not available"),
619        }
620    }
621
622    /// The address a line of the driver's greeting announces, if it is the line
623    /// that announces one.
624    fn address_of(self, line: &str) -> Option<SocketAddr> {
625        match self {
626            Engine::Firefox => {
627                let at = line.find("Listening on ")? + "Listening on ".len();
628                line[at..].trim().parse().ok()
629            }
630            Engine::Chrome => {
631                const SAID: &str = "started successfully on port ";
632
633                let at = line.find(SAID)? + SAID.len();
634                let port: u16 = line[at..].trim().trim_end_matches('.').parse().ok()?;
635
636                Some(SocketAddr::from(([127, 0, 0, 1], port)))
637            }
638        }
639    }
640}
641
642/// Whatever the driver managed to say, set off so it reads as its words rather
643/// than as this suite's.
644fn quoted(said: &str) -> String {
645    match said.trim() {
646        "" => String::from(" It printed nothing."),
647        said => format!(" It said:\n{said}"),
648    }
649}
650
651#[cfg(test)]
652mod tests {
653    use super::{Engine, motion_preference, theme_preference};
654
655    #[test]
656    fn theme_preferences_are_explicit() {
657        assert!(theme_preference("dark").unwrap());
658        assert!(!theme_preference("light").unwrap());
659        for invalid in ["", "Dark", "LIGHT", "drak", "auto"] {
660            let error = theme_preference(invalid).unwrap_err();
661            assert!(error.to_string().contains("E2E_THEME"));
662        }
663    }
664
665    #[test]
666    fn motion_preferences_are_explicit_and_do_not_replace_theme_preferences() {
667        assert!(motion_preference("reduce").unwrap());
668        assert!(!motion_preference("normal").unwrap());
669        for invalid in ["", "false", "off", "reduced"] {
670            assert!(motion_preference(invalid).is_err());
671        }
672        for reduced in [false, true] {
673            let caps = Engine::Firefox
674                .with_preferences(false, Some(true), Some(reduced), None)
675                .unwrap();
676            let prefs = &caps.get("moz:firefoxOptions").unwrap()["prefs"];
677            assert_eq!(prefs["ui.systemUsesDarkTheme"], 1);
678            assert_eq!(prefs["ui.prefersReducedMotion"], i64::from(reduced));
679            let error = Engine::Chrome
680                .with_preferences(false, None, Some(reduced), None)
681                .unwrap_err();
682            assert!(error.to_string().contains("E2E_MOTION"));
683        }
684        let caps = Engine::Firefox
685            .with_preferences(false, None, None, None)
686            .unwrap();
687        assert!(
688            caps.get("moz:firefoxOptions")
689                .unwrap()
690                .get("prefs")
691                .is_none()
692        );
693        assert!(
694            Engine::Chrome
695                .with_preferences(false, None, None, None)
696                .is_ok()
697        );
698    }
699
700    /// **A forced device pixel ratio reaches both engines**, unlike theme and
701    /// motion, which are Firefox-only preferences.
702    #[test]
703    fn a_forced_scale_reaches_both_engines() {
704        let caps = Engine::Firefox
705            .with_preferences(false, None, None, Some(2.0))
706            .unwrap();
707        let prefs = &caps.get("moz:firefoxOptions").unwrap()["prefs"];
708        assert_eq!(prefs["layout.css.devPixelsPerPx"], "2");
709
710        let caps = Engine::Chrome
711            .with_preferences(false, None, None, Some(2.0))
712            .unwrap();
713        let args = caps.get("goog:chromeOptions").unwrap()["args"]
714            .as_array()
715            .unwrap();
716        assert!(args.iter().any(|a| a == "--force-device-scale-factor=2"));
717    }
718
719    /// **Every engine is named, parses back, and has a driver of its own.** The
720    /// list is short enough that this looks like ceremony and is not: a third
721    /// entry added with a copied `name` would make `--browser` reach the wrong
722    /// one, silently, and the suite would report the engine it was not running.
723    #[test]
724    fn every_engine_round_trips_through_its_name() {
725        for engine in Engine::ALL {
726            assert_eq!(engine.name().parse::<Engine>().unwrap(), engine);
727
728            assert_eq!(
729                engine.name().to_uppercase().parse::<Engine>().unwrap(),
730                engine
731            );
732        }
733
734        for pair in Engine::ALL.windows(2) {
735            assert_ne!(pair[0].name(), pair[1].name());
736            assert_ne!(pair[0].driver(), pair[1].driver());
737        }
738    }
739
740    /// A name nothing answers to says what would have worked, rather than
741    /// failing somewhere further in with a spawn error naming one binary.
742    #[test]
743    fn a_browser_nothing_drives_is_refused_with_the_list() {
744        let error = "safari".parse::<Engine>().unwrap_err().to_string();
745
746        for engine in Engine::ALL {
747            assert!(
748                error.contains(engine.name()),
749                "{error} does not offer {engine}"
750            );
751        }
752    }
753
754    /// **Each driver's greeting is read for the port it took, and only the line
755    /// that carries one counts.**
756    #[test]
757    fn each_driver_is_read_for_the_port_it_took() {
758        use std::net::SocketAddr;
759
760        let gecko = "1730000000\tgeckodriver\tINFO\tListening on 127.0.0.1:51234";
761
762        let chrome = [
763            "Starting ChromeDriver 151.0.7922.138 (abcdef) on port 0",
764            "Only local connections are allowed.",
765            "Please see https://chromedriver.chromium.org/security-considerations \
766             for suggestions on keeping ChromeDriver safe.",
767            "ChromeDriver was started successfully on port 52725.",
768        ];
769
770        let expect = |port| Some(SocketAddr::from(([127, 0, 0, 1], port)));
771
772        assert_eq!(Engine::Firefox.address_of(gecko), expect(51234));
773        assert_eq!(Engine::Chrome.address_of(gecko), None);
774
775        assert_eq!(Engine::Chrome.address_of(chrome[3]), expect(52725));
776
777        for line in &chrome[..3] {
778            assert_eq!(
779                Engine::Chrome.address_of(line),
780                None,
781                "{line:?} is not where the port is"
782            );
783            assert_eq!(Engine::Firefox.address_of(line), None);
784        }
785    }
786
787    /// **Only chromedriver saying its port was not available counts as losing
788    /// the port it picked**, so no other early exit is started again.
789    #[test]
790    fn only_a_taken_port_is_read_as_losing_it() {
791        let lost = [
792            "Starting ChromeDriver 154.0.8037.92 (abcdef) on port 0",
793            "[1759451000.123][SEVERE]: bind() failed: Address already in use (98)",
794            "IPv4 port not available. Exiting...",
795        ]
796        .join("\n");
797
798        assert!(Engine::Chrome.lost_its_port(&lost));
799        assert!(Engine::Chrome.lost_its_port("IPv6 port not available. Exiting..."));
800        assert!(!Engine::Firefox.lost_its_port(&lost));
801
802        for said in [
803            "",
804            "Starting ChromeDriver 154.0.8037.92 (abcdef) on port 0",
805            "ChromeDriver was started successfully on port 52725.",
806            "error while loading shared libraries: libnss3.so",
807        ] {
808            assert!(!Engine::Chrome.lost_its_port(said), "{said:?}");
809        }
810    }
811
812    /// **Both are told to pick a port, which is what makes starting several at
813    /// once safe** — and the two spellings are not interchangeable.
814    /// chromedriver answers a separated `--port 0` with its usage and an exit.
815    #[test]
816    fn each_driver_is_told_to_pick_its_own_port() {
817        for engine in Engine::ALL {
818            let args = engine.port_args();
819
820            assert!(
821                args.iter().any(|arg| arg.contains('0')),
822                "{engine} is not asking for a port of the driver's choosing"
823            );
824        }
825
826        assert_eq!(Engine::Firefox.port_args(), ["--port", "0"]);
827        assert_eq!(Engine::Chrome.port_args(), ["--port=0"]);
828    }
829
830    /// The suite asks the machine what it can drive before it tries to drive
831    /// anything, so a machine with neither driver is told what to install
832    /// instead of being handed a spawn error naming one binary.
833    #[test]
834    fn a_machine_with_no_driver_is_told_what_would_have_worked() {
835        if Engine::detect().is_some() {
836            assert!(Engine::require().is_ok());
837            return;
838        }
839
840        let error = Engine::require().unwrap_err().to_string();
841
842        for engine in Engine::ALL {
843            assert!(
844                error.contains(engine.driver()),
845                "{error} does not name a driver"
846            );
847        }
848    }
849}
850
851#[cfg(all(test, unix))]
852pub(crate) mod lifecycle_tests {
853    use super::*;
854    use tokio::process::Command;
855
856    pub(crate) async fn fake(address: SocketAddr) -> (Driver, i32) {
857        let mut command = Command::new("sh");
858        command.args([
859            "-c",
860            &format!("echo 'Listening on {address}'; exec sleep 60"),
861        ]);
862        let driver = Driver::start(
863            Engine::Firefox,
864            &mut command,
865            Instant::now() + STARTUP_TIMEOUT,
866        )
867        .await
868        .unwrap();
869        let pid = driver.process.child.id().unwrap() as i32;
870        (driver, pid)
871    }
872
873    pub(crate) async fn gone(pid: i32) {
874        timeout(Duration::from_secs(2), async {
875            loop {
876                let result = unsafe { libc::kill(pid, 0) };
877                if result != 0
878                    && std::io::Error::last_os_error().raw_os_error() == Some(libc::ESRCH)
879                {
880                    break;
881                }
882                tokio::task::yield_now().await;
883            }
884        })
885        .await
886        .expect("the owned driver must be reaped");
887    }
888
889    #[tokio::test]
890    async fn readiness_timeout_keeps_stderr_and_reaps_its_process() {
891        let mut command = Command::new("sh");
892        command.args([
893            "-c",
894            "echo owned-pid=$$ >&2; echo boot-stalled >&2; exec sleep 60",
895        ]);
896        let error = Driver::start(
897            Engine::Firefox,
898            &mut command,
899            Instant::now() + Duration::from_millis(250),
900        )
901        .await
902        .err()
903        .unwrap();
904        let message = format!("{error:#}");
905        assert!(message.contains("boot-stalled"), "{message}");
906        assert!(message.contains("startup timed out"), "{message}");
907        let pid = message
908            .lines()
909            .find_map(|line| line.strip_prefix("owned-pid="))
910            .unwrap()
911            .parse()
912            .unwrap();
913        gone(pid).await;
914    }
915
916    #[tokio::test]
917    async fn early_driver_exit_reports_its_original_error_and_output() {
918        let mut command = Command::new("sh");
919        command.args(["-c", "echo fatal-startup-marker >&2; exit 7"]);
920        let error = Driver::start(
921            Engine::Firefox,
922            &mut command,
923            Instant::now() + STARTUP_TIMEOUT,
924        )
925        .await
926        .err()
927        .unwrap();
928        let message = format!("{error:#}");
929        assert!(message.contains("fatal-startup-marker"), "{message}");
930        assert!(message.contains("stopped before announcing"), "{message}");
931    }
932
933    /// A fake chromedriver that loses its port on its first `losses` starts,
934    /// and on the start after that announces port 12345, recording each start
935    /// in `starts`.
936    fn losing(losses: usize, starts: &std::path::Path) -> Command {
937        let mut command = Command::new("sh");
938        command.args([
939            "-c",
940            r#"echo start >> "$1"
941            if [ "$(wc -l < "$1")" -le "$2" ]; then
942                echo '[SEVERE]: bind() failed: Address already in use (98)' >&2
943                echo 'IPv4 port not available. Exiting...' >&2
944                exit 1
945            fi
946            echo 'ChromeDriver was started successfully on port 12345.'
947            exec sleep 60"#,
948            "fake-chromedriver",
949        ]);
950        command.arg(starts).arg(losses.to_string());
951        command
952    }
953
954    fn starts(path: &std::path::Path) -> usize {
955        std::fs::read_to_string(path).unwrap().lines().count()
956    }
957
958    #[tokio::test]
959    async fn a_driver_that_lost_its_port_is_started_again() {
960        let file = tempfile::NamedTempFile::new().unwrap();
961        let mut command = losing(PORT_RETRIES, file.path());
962        let mut driver = Driver::start_until_it_keeps_a_port(
963            Engine::Chrome,
964            &mut command,
965            Instant::now() + STARTUP_TIMEOUT,
966        )
967        .await
968        .unwrap();
969        assert_eq!(driver.address.port(), 12345);
970        assert_eq!(starts(file.path()), PORT_RETRIES + 1);
971        driver.terminate().await.unwrap();
972    }
973
974    #[tokio::test]
975    async fn a_driver_that_keeps_losing_its_port_fails_saying_so() {
976        let file = tempfile::NamedTempFile::new().unwrap();
977        let mut command = losing(usize::MAX >> 1, file.path());
978        let error = Driver::start_until_it_keeps_a_port(
979            Engine::Chrome,
980            &mut command,
981            Instant::now() + STARTUP_TIMEOUT,
982        )
983        .await
984        .err()
985        .unwrap();
986        let message = format!("{error:#}");
987        assert_eq!(starts(file.path()), PORT_RETRIES + 1);
988        assert!(
989            message.contains("lost the port it picked 4 times"),
990            "{message}"
991        );
992        assert!(message.contains("IPv4 port not available"), "{message}");
993        assert!(message.contains("stopped before announcing"), "{message}");
994    }
995
996    #[tokio::test]
997    async fn a_driver_that_stopped_for_another_reason_is_not_started_again() {
998        let file = tempfile::NamedTempFile::new().unwrap();
999        let mut command = Command::new("sh");
1000        command.args([
1001            "-c",
1002            r#"echo start >> "$1"; echo 'cannot open display' >&2; exit 1"#,
1003            "fake-chromedriver",
1004        ]);
1005        command.arg(file.path());
1006        let error = Driver::start_until_it_keeps_a_port(
1007            Engine::Chrome,
1008            &mut command,
1009            Instant::now() + STARTUP_TIMEOUT,
1010        )
1011        .await
1012        .err()
1013        .unwrap();
1014        let message = format!("{error:#}");
1015        assert_eq!(starts(file.path()), 1);
1016        assert!(message.contains("cannot open display"), "{message}");
1017        assert!(!message.contains("lost the port"), "{message}");
1018    }
1019
1020    #[tokio::test]
1021    async fn closing_one_log_pipe_does_not_hide_the_other_pipes_greeting() {
1022        let mut command = Command::new("sh");
1023        command.args([
1024            "-c",
1025            "exec 1>&-; echo 'Listening on 127.0.0.1:12345' >&2; exec sleep 60",
1026        ]);
1027        let mut driver = Driver::start(
1028            Engine::Firefox,
1029            &mut command,
1030            Instant::now() + STARTUP_TIMEOUT,
1031        )
1032        .await
1033        .unwrap();
1034        assert_eq!(driver.address.port(), 12345);
1035        assert!(driver.diagnostics().contains("Listening on"));
1036        driver.terminate().await.unwrap();
1037    }
1038
1039    #[tokio::test]
1040    async fn cancelling_before_the_driver_announces_its_address_reaps_it() {
1041        let pid_file = tempfile::NamedTempFile::new().unwrap();
1042        let path = pid_file.path().to_owned();
1043        let mut command = Command::new("sh");
1044        command.args([
1045            "-c",
1046            "printf '%s' \"$$\" > \"$1\"; exec sleep 60",
1047            "test-driver",
1048        ]);
1049        command.arg(&path);
1050        let starting = tokio::spawn(async move {
1051            Driver::start(
1052                Engine::Firefox,
1053                &mut command,
1054                Instant::now() + STARTUP_TIMEOUT,
1055            )
1056            .await
1057        });
1058        let pid = timeout(STARTUP_TIMEOUT, async {
1059            loop {
1060                if let Ok(pid) = tokio::fs::read_to_string(&path)
1061                    .await
1062                    .unwrap()
1063                    .parse::<i32>()
1064                {
1065                    break pid;
1066                }
1067                tokio::task::yield_now().await;
1068            }
1069        })
1070        .await
1071        .unwrap();
1072        starting.abort();
1073        assert!(matches!(starting.await, Err(error) if error.is_cancelled()));
1074        gone(pid).await;
1075    }
1076
1077    #[tokio::test]
1078    async fn killing_an_owned_group_does_not_kill_an_unrelated_child() {
1079        use tokio::io::AsyncBufReadExt;
1080        let mut unrelated = Command::new("sleep")
1081            .arg("60")
1082            .kill_on_drop(true)
1083            .spawn()
1084            .unwrap();
1085        let mut command = Command::new("sh");
1086        command.args(["-c", "sleep 60 & echo $!; wait"]);
1087        command.stdout(std::process::Stdio::piped());
1088        let mut owned = OwnedProcess::spawn(&mut command).unwrap();
1089        let leader = owned.child.id().unwrap() as i32;
1090        let mut child_line = String::new();
1091        tokio::io::BufReader::new(owned.child.stdout.take().unwrap())
1092            .read_line(&mut child_line)
1093            .await
1094            .unwrap();
1095        let descendant: i32 = child_line.trim().parse().unwrap();
1096        assert_ne!(leader, descendant);
1097        assert_eq!(unsafe { libc::getpgid(leader) }, leader);
1098        assert_eq!(unsafe { libc::getpgid(descendant) }, leader);
1099        assert_ne!(
1100            unsafe { libc::getpgid(unrelated.id().unwrap() as i32) },
1101            leader
1102        );
1103        owned.reap().await.unwrap();
1104        gone(leader).await;
1105        // Grandchildren are reaped by their new parent, not this harness. A
1106        // zombie has stopped running even if init has not collected it yet.
1107        timeout(Duration::from_secs(2), async {
1108            loop {
1109                let dead = unsafe { libc::kill(descendant, 0) } != 0;
1110                #[cfg(target_os = "linux")]
1111                let dead = dead
1112                    || std::fs::read_to_string(format!("/proc/{descendant}/stat")).is_ok_and(
1113                        |stat| {
1114                            stat.rsplit_once(") ")
1115                                .is_some_and(|(_, fields)| fields.starts_with('Z'))
1116                        },
1117                    );
1118                if dead {
1119                    break;
1120                }
1121                tokio::task::yield_now().await;
1122            }
1123        })
1124        .await
1125        .unwrap();
1126        assert!(unrelated.try_wait().unwrap().is_none());
1127        unrelated.kill().await.unwrap();
1128    }
1129
1130    #[test]
1131    fn cleanup_failure_keeps_the_original_failure_chain() {
1132        let error = with_cleanup(
1133            anyhow!("original assertion failed"),
1134            Err(TimedOut("quit".to_owned()).into()),
1135        );
1136        let message = format!("{error:#}");
1137        assert!(message.contains("original assertion failed"));
1138        assert!(message.contains("quit timed out"));
1139    }
1140
1141    #[test]
1142    fn a_timeout_stays_recognisable_under_its_context() {
1143        let error = anyhow::Error::from(TimedOut("quit".to_owned()))
1144            .context("browser quit: geckodriver It printed nothing.");
1145        assert!(error.downcast_ref::<TimedOut>().is_some());
1146        assert!(format!("{error:#}").contains("test browser quit timed out"));
1147        assert!(
1148            anyhow!("quit timed out")
1149                .downcast_ref::<TimedOut>()
1150                .is_none()
1151        );
1152    }
1153}