Documentation lints and helpers

test-harness/src/internal.rs

@@ -30,13 +30,13 @@ thread_local! {
 
 /// Wraps an asynchronous test with startup/cleanup code.
 ///
-/// Before the user test code, we set the [`GHC_VERSION`] thread-local variable so that when
+/// Before the user test code, we set the `GHC_VERSION` thread-local variable so that when
 /// we construct a [`super::GhciWatch`] it can use the correct GHC version.
 ///
 /// Then we run the user test code. If it errors, we save the logs to `CARGO_TARGET_TMPDIR`.
 ///
-/// Finally, we wait for the [`GHCIWATCH_PROCESS`] to exit and clean up the temporary directory `GhciWatch`
-/// created.
+/// Finally, we wait for the process set by [`set_ghciwatch_process`] to exit and clean up the
+/// temporary directory `GhciWatch` created.
 pub async fn wrap_test(
     test: impl Future<Output = ()> + Send + 'static,
     ghc_version: &'static str,
@@ -100,7 +100,7 @@ fn save_test_logs(test_name: String, cargo_target_tmpdir: PathBuf) {
 
 /// Perform end-of-test cleanup.
 ///
-/// 1. Kill the [`GHCIWATCH_PROCESS`].
+/// 1. Kill the process set by [`set_ghciwatch_process`].
 /// 2. Remove the [`TEMPDIR`] from the filesystem.
 async fn cleanup() {
     let child = GHCIWATCH_PROCESS.with(|child| child.take());
@@ -156,7 +156,7 @@ async fn cleanup() {
     }
 }
 
-/// Get the GHC version as given by [`GHC_VERSION`].
+/// Get the GHC version for this thread as given by `GHC_VERSION`.
 pub(crate) fn get_ghc_version() -> miette::Result<String> {
     let ghc_version = GHC_VERSION.with(|version| version.borrow().to_owned());
     if ghc_version.is_empty() {
@@ -190,9 +190,9 @@ pub(crate) fn set_tempdir() -> miette::Result<PathBuf> {
     Ok(tempdir.into_path())
 }
 
-/// Set [`GHCIWATCH_PROCESS`] to the given [`Child`].
+/// Set the `GHCIWATCH_PROCESS` for the current thread to the given [`Child`].
 ///
-/// Fails if [`GHCIWATCH_PROCESS`] is already set.
+/// Fails if the `GHCIWATCH_PROCESS` is already set.
 pub(crate) fn set_ghciwatch_process(child: Child) -> miette::Result<()> {
     GHCIWATCH_PROCESS.with(|maybe_child| {
         if maybe_child.borrow().is_some() {

test-harness/src/matcher/base_matcher.rs

@@ -35,12 +35,59 @@ impl BaseMatcher {
 
     /// Construct a query for new span events, denoted by a `new` message.
     pub fn span_new() -> Self {
-        Self::message("new")
+        Self::message("^new$")
     }
 
     /// Construct a query for span close events, denoted by a `close` message.
     pub fn span_close() -> Self {
-        Self::message("close")
+        Self::message("^close$")
+    }
+
+    /// Utility for constructing a matcher that waits until the inner `ghci` finishes compilation
+    /// successfully.
+    pub fn compilation_succeeded() -> Self {
+        Self::message("^Compilation succeeded$").in_span("reload")
+    }
+
+    /// Utility for constructing a matcher that waits until the inner `ghci` finishes compilation
+    /// unsuccessfully.
+    pub fn compilation_failed() -> Self {
+        Self::message("^Compilation failed$").in_span("reload")
+    }
+
+    /// Utility for constructing a matcher that waits until the inner `ghci` compiles the given
+    /// module.
+    ///
+    /// The module is given by name (`My.Module`), not path (`src/My/Module.hs`).
+    pub fn module_compiling(module: &str) -> Self {
+        Self::message("^Compiling$")
+            .in_span("reload")
+            .with_field("module", &regex::escape(module))
+    }
+
+    /// Utility for constructing a matcher that waits until the inner `ghci` session is reloaded.
+    pub fn reload() -> Self {
+        Self::message("^Reloading ghci:\n")
+    }
+
+    /// Utility for constructing a matcher that waits until the inner `ghci` session finishes
+    /// responding to changed file events. This may or may not include reloading, restarting, or
+    /// adding modules. (E.g., if all the changed files are ignored, a 'reload' may be a no-op.)
+    pub fn reload_completes() -> Self {
+        Self::span_close()
+            .in_span("reload")
+            .in_module("ghciwatch::ghci")
+    }
+
+    /// Utility for constructing a matcher that waits until a module is added to the inner `ghci`
+    /// session.
+    pub fn module_add() -> Self {
+        Self::message("^Adding modules to ghci:\n")
+    }
+
+    /// Utility for constructing a matcher that waits until the inner `ghci` session is restarted.
+    pub fn restart() -> Self {
+        Self::message("^Restarting ghci:\n")
     }
 
     /// Require that matching events be in a span with the given name.
@@ -138,11 +185,11 @@ impl Display for BaseMatcher {
         write!(f, "{:?}", self.message.as_str())?;
 
         if let Some(target) = &self.target {
-            write!(f, " in module {target}")?;
+            write!(f, " in module {target:?}")?;
         }
 
         if !self.spans.is_empty() {
-            write!(f, " in spans {}", self.spans.join(", "))?;
+            write!(f, " in spans {:?}", self.spans.join(", "))?;
         }
 
         if !self.fields.is_empty() {

tests/restart.rs

@@ -4,6 +4,7 @@ use test_harness::fs;
 use test_harness::test;
 use test_harness::BaseMatcher;
 use test_harness::GhciWatch;
+use test_harness::GhciWatchBuilder;
 
 /// Test that `ghciwatch` can restart `ghci` after a module is moved.
 #[test]