Merge pull request #21598 from calixteman/use_per_test

Download the per-test coverage index

Author: calixteman

README.md

@@ -136,14 +136,31 @@ browsable HTML report instead, or pass several formats at once, e.g.
 
 ### Finding which tests cover a given line
 
-Run a browser test task with `--coverage-per-test` to build an index
-(`per-test-index.json`) in the coverage directory, then query it to list the
-tests that exercised a specific source line or function:
+`coverage_search` lists the ref tests that exercised a specific source line or
+function. It uses the per-test index (`per-test-index.json`) that is rebuilt on
+every push to `master` and published to the
+[`pdf.js.refs`](https://github.com/mozilla/pdf.js.refs/tree/gh-pages)
+repository. The index is downloaded on demand, cached locally, and only
+re-downloaded when it has changed, so no local coverage build is required:
 
-    $ npx gulp botbrowsertest --coverage-per-test
     $ npx gulp coverage_search --code="canvas.js::205"
     $ npx gulp coverage_search --code="canvas.js::drawImageAtIntegerCoords"
 
+To run — or regenerate the reference images for — only the ref tests that touch
+a given line or function, pass the same `--code` option to a browser test or
+`makeref` task:
+
+    $ npx gulp browsertest --code="canvas.js::205"
+    $ npx gulp makeref --code="canvas.js::205"
+
+Pass `--no-download` to reuse the locally cached index without contacting the
+network. The index can also be built and queried locally (the CI job that
+publishes it builds it the same way):
+
+    $ npx gulp botbrowsertest --coverage-per-test
+    $ npx gulp coverage_search --code="canvas.js::205" \
+        --index=build/coverage/per-test-index.json --no-download
+
 ### Continuous integration
 
 On every push and pull request three GitHub Actions workflows collect coverage

external/ccov/coverage_search.mjs

@@ -20,26 +20,46 @@ import path from "path";
 const __dirname = import.meta.dirname;
 const PROJECT_ROOT = path.join(__dirname, "../..");
 
-const { values } = parseArgs({
-  args: process.argv.slice(2),
-  options: {
-    code: { type: "string" },
-    "coverage-dir": { type: "string", default: "build/coverage" },
-    help: { type: "boolean", short: "h", default: false },
-  },
-});
+// The per-test coverage index (which ref test exercises which source
+// line/function) is rebuilt on every push to master and published to the
+// gh-pages branch of the pdf.js.refs repository.
+const PER_TEST_INDEX_URL =
+  "https://raw.githubusercontent.com/mozilla/pdf.js.refs/gh-pages/per-test-index.json";
+
+let values;
+try {
+  ({ values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      code: { type: "string" },
+      index: { type: "string", default: "build/per-test-index.json" },
+      "no-download": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  }));
+} catch (error) {
+  // parseArgs is strict, so an unknown/renamed option (e.g. the removed
+  // --coverage-dir) would otherwise abort with an uncaught stack trace.
+  console.error(`Error: ${error.message}`);
+  console.error("Run with --help to see the available options.");
+  process.exit(1);
+}
 
 if (values.help || !values.code) {
   console.log(
-    "Usage: coverage_search.mjs --code=<file>::<line|function> [--coverage-dir=<path>]\n\n" +
+    "Usage: coverage_search.mjs --code=<file>::<line|function> [--index=<path>] [--no-download]\n\n" +
       "  --code          Source file and line number or function name to search for.\n" +
       "                  Examples:\n" +
       "                    --code=canvas.js::205\n" +
       "                    --code=canvas.js::drawImageAtIntegerCoords\n" +
-      "  --coverage-dir  Coverage directory containing per-test-index.json [build/coverage]\n\n" +
+      "  --index         Where to cache or read the per-test index.\n" +
+      "                  [build/per-test-index.json]\n" +
+      "  --no-download   Don't contact the network; use the cached index as-is.\n\n" +
       "Prints to stdout the IDs of tests whose coverage includes the given line or\n" +
-      "function (one ID per line).\n" +
-      "Run browsertest with --coverage-per-test first to generate the index."
+      "function (one ID per line).\n\n" +
+      "The index is downloaded from the pdf.js.refs repository and cached locally;\n" +
+      "it is only re-downloaded when the published file has changed.\n" +
+      `Source: ${PER_TEST_INDEX_URL}`
   );
   process.exit(values.help ? 0 : 1);
 }
@@ -58,18 +78,129 @@ const isLine = /^\d+$/.test(location);
 const lineNum = isLine ? parseInt(location, 10) : null;
 const funcName = isLine ? null : location;
 
-const coverageDir = path.isAbsolute(values["coverage-dir"])
-  ? values["coverage-dir"]
-  : path.join(PROJECT_ROOT, values["coverage-dir"]);
+const indexPath = path.isAbsolute(values.index)
+  ? values.index
+  : path.join(PROJECT_ROOT, values.index);
+// The ETag of the cached copy is stored alongside it, so the next run can ask
+// the server (via If-None-Match) to only re-send the file when it has changed.
+const etagPath = `${indexPath}.etag`;
+
+// Refreshes the locally cached index from the published copy, downloading it
+// only when it has changed since the last run. When the network is unavailable
+// a previously cached copy is reused if present.
+async function refreshIndex() {
+  if (values["no-download"]) {
+    return; // Freshness check disabled; the read below validates existence.
+  }
+
+  const hasCached = fs.existsSync(indexPath);
+
+  // On any download failure, fall back to a previously cached copy when one
+  // exists; otherwise there's nothing to search, so fail.
+  const fallbackOrFail = reason => {
+    if (hasCached) {
+      console.error(
+        `Warning: couldn't refresh per-test index (${reason}); using the cached copy.`
+      );
+      return;
+    }
+    console.error(`Error: couldn't download per-test index (${reason}).`);
+    process.exit(1);
+  };
+
+  const headers = {};
+  if (hasCached && fs.existsSync(etagPath)) {
+    const etag = fs.readFileSync(etagPath, "utf8").trim();
+    // Only forward a syntactically valid HTTP ETag (RFC 7232), so the cached
+    // file's contents can't be used to inject arbitrary data into the request.
+    if (/^(?:W\/)?"[\x21\x23-\x7e]*"$/.test(etag)) {
+      headers["If-None-Match"] = etag;
+    }
+  }
+
+  let response;
+  try {
+    console.error(`Fetching per-test index from ${PER_TEST_INDEX_URL} ...`);
+    response = await fetch(PER_TEST_INDEX_URL, { headers });
+  } catch (error) {
+    fallbackOrFail(error.message);
+    return;
+  }
+
+  if (response.status === 304) {
+    console.error("Per-test index is up to date.");
+    return;
+  }
+  if (!response.ok) {
+    fallbackOrFail(`HTTP ${response.status}`);
+    return;
+  }
+
+  let text;
+  try {
+    text = await response.text();
+  } catch (error) {
+    fallbackOrFail(error.message);
+    return;
+  }
+
+  // Parse the payload before caching it, and cache the re-serialized result
+  // rather than the raw response body: only well-formed JSON produced by our
+  // own JSON.stringify is ever written to disk.
+  let serialized;
+  try {
+    serialized = JSON.stringify(JSON.parse(text));
+  } catch {
+    fallbackOrFail("the downloaded index is not valid JSON");
+    return;
+  }
+
+  // Write to a temporary file and rename it into place.
+  try {
+    fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+    const tmpPath = `${indexPath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmpPath, serialized);
+    fs.renameSync(tmpPath, indexPath);
+
+    const etag = response.headers.get("etag");
+    if (etag) {
+      fs.writeFileSync(etagPath, etag);
+    } else {
+      fs.rmSync(etagPath, { force: true });
+    }
+  } catch (error) {
+    // A write failure (disk full, read-only dir, ...) shouldn't be fatal when
+    // a usable cached copy already exists.
+    fallbackOrFail(error.message);
+    return;
+  }
+  console.error(`Per-test index updated (${serialized.length} bytes).`);
+}
+
+await refreshIndex();
 
-const indexPath = path.join(coverageDir, "per-test-index.json");
 if (!fs.existsSync(indexPath)) {
-  console.error(`Error: index file not found: ${indexPath}`);
-  console.error("Run browsertest with --coverage-per-test first.");
+  console.error(`Error: per-test index not found: ${indexPath}`);
+  console.error(
+    "Build it locally (gulp botbrowsertest --coverage-per-test) or omit " +
+      "--no-download to fetch it from the pdf.js.refs repository."
+  );
   process.exit(1);
 }
 
-const { ids, files } = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+let ids, files;
+try {
+  ({ ids, files } = JSON.parse(fs.readFileSync(indexPath, "utf8")));
+} catch (error) {
+  console.error(
+    `Error: couldn't read per-test index at ${indexPath}: ${error.message}`
+  );
+  console.error(
+    "The cached index may be corrupt; delete it and re-run without " +
+      "--no-download to refetch it."
+  );
+  process.exit(1);
+}
 
 // Find the file entry whose path matches fileName.
 let fileEntry = null;