Add some dox

crates/cli/src/bin/wasm-bindgen-test-runner/headless.rs

@@ -16,6 +16,11 @@ use shell::Shell;
 
 /// Execute a headless browser tests against a server running on `server`
 /// address.
+///
+/// This function will take care of everything from spawning the WebDriver
+/// binary, controlling it, running tests, scraping output, displaying output,
+/// etc. It will return `Ok` if all tests finish successfully, and otherwise it
+/// will return an error if some tests failed.
 pub fn run(server: &SocketAddr, shell: &Shell) -> Result<(), Error> {
     let (driver, args) = Driver::find()?;
     println!("Running headless tests in {} with `{}`",
@@ -155,6 +160,10 @@ pub fn run(server: &SocketAddr, shell: &Shell) -> Result<(), Error> {
         println!("console.log div contained:\n{}", tab(&errors));
     }
 
+    if !output.contains("test result: ok") {
+        bail!("some tests failed")
+    }
+
     Ok(())
 }
 
@@ -165,6 +174,15 @@ enum Driver {
 }
 
 impl Driver {
+    /// Attempts to find an appropriate WebDriver server binary to execute tests
+    /// with. Performs a number of heuristics to find one available, including:
+    ///
+    /// * Env vars like `GECKODRIVER` point to the path to a binary to execute.
+    /// * Otherwise, `PATH` is searched for an appropriate binary.
+    ///
+    /// In both cases a list of auxiliary arguments is also returned which is
+    /// configured through env vars like `GECKODRIVER_ARGS` to support extra
+    /// arguments to the driver's invocation.
     fn find() -> Result<(Driver, Vec<String>), Error> {
         let env_args = |name: &str| {
             env::var(format!("{}_ARGS", name.to_uppercase()))
@@ -243,6 +261,10 @@ enum Method<'a> {
     Delete,
 }
 
+// Below here is a bunch of details of the WebDriver protocol implementation.
+// I'm not too too familiar with them myself, but these seem to work! I mostly
+// copied the `webdriver-client` crate when writing the below bindings.
+
 impl Client {
     fn new_session(&self, driver: &Driver) -> Result<String, Error> {
         match driver {

crates/cli/src/bin/wasm-bindgen-test-runner/main.rs

@@ -1,3 +1,16 @@
+//! A "wrapper binary" used to execute wasm files as tests
+//!
+//! This binary is intended to be used as a "test runner" for wasm binaries,
+//! being compatible with `cargo test` for the wasm target. It will
+//! automatically execute `wasm-bindgen` (or the equivalent thereof) and then
+//! execute either Node.js over the tests or start a server which a browser can
+//! be used to run against to execute tests. In a browser mode if `CI` is in the
+//! environment then it'll also attempt headless testing, spawning the server in
+//! the background and then using the WebDriver protocol to execute tests.
+//!
+//! For more documentation about this see the `wasm-bindgen-test` crate README
+//! and source code.
+
 extern crate curl;
 extern crate env_logger;
 #[macro_use]

crates/cli/src/bin/wasm-bindgen-test-runner/node.rs

@@ -38,11 +38,6 @@ pub fn execute(module: &str, tmpdir: &Path, args: &[OsString], tests: &[String])
             const support = require("./{0}");
             const wasm = require("./{0}_bg");
 
-            // Hack for now to support 0 tests in a binary. This should be done
-            // better...
-            if (support.Context === undefined)
-                process.exit(0);
-
             cx = new support.Context();
 
             // Forward runtime arguments. These arguments are also arguments to the
@@ -75,6 +70,9 @@ pub fn execute(module: &str, tmpdir: &Path, args: &[OsString], tests: &[String])
     fs::write(&js_path, js_to_execute)
         .context("failed to write JS file")?;
 
+    // Augment `NODE_PATH` so things like `require("tests/my-custom.js")` work
+    // and Rust code can import from custom JS shims. This is a bit of a hack
+    // and should probably be removed at some point.
     let path = env::var("NODE_PATH").unwrap_or_default();
     let mut path = env::split_paths(&path).collect::<Vec<_>>();
     path.push(env::current_dir().unwrap());

crates/cli/src/bin/wasm-bindgen-test-runner/server.rs

@@ -19,10 +19,16 @@ pub fn spawn(
         import {{ Context }} from './{0}';
         import * as wasm from './{0}_bg';
 
+        // Now that we've gotten to the point where JS is executing, update our
+        // status text as at this point we should be asynchronously fetching the
+        // wasm module.
         document.getElementById('output').innerHTML = "Loading wasm module...";
 
         async function main(test) {{
+            // this is a facet of using wasm2es6js, a hack until browsers have
+            // native ESM support for wasm modules.
             await wasm.booted;
+
             const cx = Context.new();
             window.global_cx = cx;
 
@@ -51,6 +57,11 @@ pub fn spawn(
     // No browser today supports a wasm file as ES modules natively, so we need
     // to shim it. Use `wasm2es6js` here to fetch an appropriate URL and look
     // like an ES module with the wasm module under the hood.
+    //
+    // TODO: don't reparse the wasm module here, should pass the
+    //       `parity_wasm::Module struct` directly from the output of
+    //       `wasm-bindgen` previously here and avoid unnecessary
+    //       parsing.
     let wasm_name = format!("{}_bg.wasm", module);
     let wasm = fs::read(tmpdir.join(&wasm_name))?;
     let output = Config::new()
@@ -63,7 +74,10 @@ pub fn spawn(
     // For now, always run forever on this port. We may update this later!
     let tmpdir = tmpdir.to_path_buf();
     let srv = Server::new(addr, move |request| {
-        // The root path gets our canned `index.html`
+        // The root path gets our canned `index.html`. The two templates here
+        // differ slightly in the default routing of `console.log`, going to an
+        // HTML element during headless testing so we can try to scrape its
+        // output.
         if request.url() == "/" {
             let s = if headless {
                 include_str!("index-headless.html")