1use 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
19struct 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 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 }
82}
83
84#[derive(Debug, Clone, Copy, PartialEq, Eq)]
86pub enum Engine {
87 Firefox,
89 Chrome,
92}
93
94fn 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
130fn 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 pub const ALL: [Engine; 2] = [Engine::Firefox, Engine::Chrome];
152
153 pub fn driver(self) -> &'static str {
155 match self {
156 Engine::Firefox => "geckodriver",
157 Engine::Chrome => "chromedriver",
158 }
159 }
160
161 pub fn name(self) -> &'static str {
163 match self {
164 Engine::Firefox => "firefox",
165 Engine::Chrome => "chrome",
166 }
167 }
168
169 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 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 pub fn available(self) -> bool {
243 self.installed().is_some()
244 }
245
246 pub fn browser_present(self) -> bool {
248 match self {
249 Engine::Firefox => false,
250 Engine::Chrome => crate::fetch::chrome_present(),
251 }
252 }
253
254 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 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 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
325fn 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
353pub(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 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 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 #[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 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 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 }
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#[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#[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
589const READY_LINES: usize = 16;
593
594const PORT_RETRIES: usize = 3;
598
599impl Engine {
600 fn port_args(self) -> &'static [&'static str] {
602 match self {
603 Engine::Firefox => &["--port", "0"],
604 Engine::Chrome => &["--port=0"],
605 }
606 }
607
608 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 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
642fn 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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 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 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}