Add new rustdoc-gui test suite

Author: GuillaumeGomez

src/bootstrap/builder.rs

@@ -440,6 +440,7 @@ impl<'a> Builder<'a> {
                 test::CompiletestTest,
                 test::RustdocJSStd,
                 test::RustdocJSNotStd,
+                test::RustdocGUI,
                 test::RustdocTheme,
                 test::RustdocUi,
                 test::RustdocJson,

src/bootstrap/config.rs

@@ -174,6 +174,7 @@ pub struct Config {
     pub mandir: Option<PathBuf>,
     pub codegen_tests: bool,
     pub nodejs: Option<PathBuf>,
+    pub npm: Option<PathBuf>,
     pub gdb: Option<PathBuf>,
     pub python: Option<PathBuf>,
     pub cargo_native_static: bool,
@@ -364,6 +365,7 @@ struct Build {
     fast_submodules: Option<bool>,
     gdb: Option<String>,
     nodejs: Option<String>,
+    npm: Option<String>,
     python: Option<String>,
     locked_deps: Option<bool>,
     vendor: Option<bool>,
@@ -654,6 +656,7 @@ impl Config {
         };
 
         config.nodejs = build.nodejs.map(PathBuf::from);
+        config.npm = build.npm.map(PathBuf::from);
         config.gdb = build.gdb.map(PathBuf::from);
         config.python = build.python.map(PathBuf::from);
         set(&mut config.low_priority, build.low_priority);

src/bootstrap/lib.rs

@@ -637,6 +637,10 @@ impl Build {
         self.out.join(&*target.triple).join("doc")
     }
 
+    fn test_out(&self, target: TargetSelection) -> PathBuf {
+        self.out.join(&*target.triple).join("test")
+    }
+
     /// Output directory for all documentation for a target
     fn compiler_doc_out(&self, target: TargetSelection) -> PathBuf {
         self.out.join(&*target.triple).join("compiler-doc")

src/bootstrap/sanity.rs

@@ -113,6 +113,13 @@ pub fn check(build: &mut Build) {
         .or_else(|| cmd_finder.maybe_have("node"))
         .or_else(|| cmd_finder.maybe_have("nodejs"));
 
+    build.config.npm = build
+        .config
+        .npm
+        .take()
+        .map(|p| cmd_finder.must_have(p))
+        .or_else(|| cmd_finder.maybe_have("npm"));
+
     build.config.gdb = build
         .config
         .gdb

src/bootstrap/test.rs

@@ -688,6 +688,78 @@ impl Step for RustdocJSNotStd {
     }
 }
 
+#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
+pub struct RustdocGUI {
+    pub target: TargetSelection,
+    pub compiler: Compiler,
+}
+
+impl Step for RustdocGUI {
+    type Output = ();
+    const DEFAULT: bool = true;
+    const ONLY_HOSTS: bool = true;
+
+    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
+        run.path("src/test/rustdoc-gui")
+    }
+
+    fn make_run(run: RunConfig<'_>) {
+        let compiler = run.builder.compiler(run.builder.top_stage, run.build_triple());
+        run.builder.ensure(RustdocGUI { target: run.target, compiler });
+    }
+
+    fn run(self, builder: &Builder<'_>) {
+        if let (Some(nodejs), Some(npm)) = (&builder.config.nodejs, &builder.config.npm) {
+            builder.ensure(compile::Std { compiler: self.compiler, target: self.target });
+
+            // The goal here is to check if the necessary packages are installed, and if not, we
+            // display a warning and move on.
+            let mut command = Command::new(&npm);
+            command.arg("list").arg("--depth=0");
+            let lines = command
+                .output()
+                .map(|output| String::from_utf8_lossy(&output.stdout).to_string())
+                .unwrap_or(String::new());
+            if !lines.contains(&" browser-ui-test@") {
+                println!(
+                    "warning: rustdoc-gui test suite cannot be run because npm `browser-ui-test` \
+                     dependency is missing",
+                );
+                println!(
+                    "If you want to install the `{0}` dependency, run `npm install {0}`",
+                    "browser-ui-test",
+                );
+                return;
+            }
+
+            let out_dir = builder.test_out(self.target).join("rustdoc-gui");
+            let mut command = builder.rustdoc_cmd(self.compiler);
+            command.arg("src/test/rustdoc-gui/lib.rs").arg("-o").arg(&out_dir);
+            builder.run(&mut command);
+
+            for file in fs::read_dir("src/test/rustdoc-gui").unwrap() {
+                let file = file.unwrap();
+                let file_path = file.path();
+                let file_name = file.file_name();
+
+                if !file_name.to_str().unwrap().ends_with(".goml") {
+                    continue;
+                }
+                let mut command = Command::new(&nodejs);
+                command
+                    .arg("src/tools/rustdoc-gui/tester.js")
+                    .arg("--doc-folder")
+                    .arg(out_dir.join("test_docs"))
+                    .arg("--test-file")
+                    .arg(file_path);
+                builder.run(&mut command);
+            }
+        } else {
+            builder.info("No nodejs found, skipping \"src/test/rustdoc-gui\" tests");
+        }
+    }
+}
+
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub struct Tidy;
 
@@ -1048,6 +1120,9 @@ note: if you're sure you want to do this, please open an issue as to why. In the
         if let Some(ref nodejs) = builder.config.nodejs {
             cmd.arg("--nodejs").arg(nodejs);
         }
+        if let Some(ref npm) = builder.config.npm {
+            cmd.arg("--npm").arg(npm);
+        }
 
         let mut flags = if is_rustdoc { Vec::new() } else { vec!["-Crpath".to_string()] };
         if !is_rustdoc {

src/tools/compiletest/src/common.rs

@@ -344,6 +344,8 @@ pub struct Config {
 
     /// Path to a NodeJS executable. Used for JS doctests, emscripten and WASM tests
     pub nodejs: Option<String>,
+    /// Path to a npm executable. Used for rustdoc GUI tests
+    pub npm: Option<String>,
 }
 
 #[derive(Debug, Clone)]

src/tools/compiletest/src/main.rs

@@ -126,6 +126,7 @@ pub fn parse_config(args: Vec<String>) -> Config {
         .reqopt("", "llvm-components", "list of LLVM components built in", "LIST")
         .optopt("", "llvm-bin-dir", "Path to LLVM's `bin` directory", "PATH")
         .optopt("", "nodejs", "the name of nodejs", "PATH")
+        .optopt("", "npm", "the name of npm", "PATH")
         .optopt("", "remote-test-client", "path to the remote test client", "PATH")
         .optopt(
             "",
@@ -264,6 +265,7 @@ pub fn parse_config(args: Vec<String>) -> Config {
         linker: matches.opt_str("linker"),
         llvm_components: matches.opt_str("llvm-components").unwrap(),
         nodejs: matches.opt_str("nodejs"),
+        npm: matches.opt_str("npm"),
     }
 }
 

src/tools/compiletest/src/runtest.rs

@@ -1585,7 +1585,7 @@ impl<'test> TestCx<'test> {
 
         let aux_dir = self.aux_output_dir_name();
 
-        let rustdoc_path = self.config.rustdoc_path.as_ref().expect("--rustdoc-path passed");
+        let rustdoc_path = self.config.rustdoc_path.as_ref().expect("--rustdoc-path not passed");
         let mut rustdoc = Command::new(rustdoc_path);
 
         rustdoc

src/tools/rustdoc-gui/tester.js

@@ -0,0 +1,89 @@
+// This package needs to be install:
+//
+// ```
+// npm install browser-ui-test
+// ```
+const path = require('path');
+const {Options, runTest} = require('browser-ui-test');
+
+function showHelp() {
+    console.log("rustdoc-js options:");
+    console.log("  --doc-folder [PATH]        : location of the generated doc folder");
+    console.log("  --help                     : show this message then quit");
+    console.log("  --test-file [PATH]         : location of the JS test file");
+}
+
+function parseOptions(args) {
+    var opts = {
+        "doc_folder": "",
+        "test_file": "",
+    };
+    var correspondances = {
+        "--doc-folder": "doc_folder",
+        "--test-file": "test_file",
+    };
+
+    for (var i = 0; i < args.length; ++i) {
+        if (args[i] === "--doc-folder"
+            || args[i] === "--test-file") {
+            i += 1;
+            if (i >= args.length) {
+                console.log("Missing argument after `" + args[i - 1] + "` option.");
+                return null;
+            }
+            opts[correspondances[args[i - 1]]] = args[i];
+        } else if (args[i] === "--help") {
+            showHelp();
+            process.exit(0);
+        } else {
+            console.log("Unknown option `" + args[i] + "`.");
+            console.log("Use `--help` to see the list of options");
+            return null;
+        }
+    }
+    if (opts["test_file"].length < 1) {
+        console.log("Missing `--test-file` option.");
+    } else if (opts["doc_folder"].length < 1) {
+        console.log("Missing `--doc-folder` option.");
+    } else {
+        return opts;
+    }
+    return null;
+}
+
+function checkFile(test_file, opts, loaded, index) {
+    const test_name = path.basename(test_file, ".js");
+
+    process.stdout.write('Checking "' + test_name + '" ... ');
+    return runChecks(test_file, loaded, index);
+}
+
+function main(argv) {
+    var opts = parseOptions(argv.slice(2));
+    if (opts === null) {
+        process.exit(1);
+    }
+
+    const options = new Options();
+    try {
+        // This is more convenient that setting fields one by one.
+        options.parseArguments([
+            '--no-screenshot',
+            "--variable", "DOC_PATH", opts["doc_folder"],
+        ]);
+    } catch (error) {
+        console.error(`invalid argument: ${error}`);
+        process.exit(1);
+    }
+
+    runTest(opts["test_file"], options).then(out => {
+        const [output, nb_failures] = out;
+        console.log(output);
+        process.exit(nb_failures);
+    }).catch(err => {
+        console.error(err);
+        process.exit(1);
+    });
+}
+
+main(process.argv);