test(scanner): use fixtures

Author: caugner

package.json

@@ -12,6 +12,7 @@
     "start": "NODE_EXTRA_CA_CERTS=node_modules/node_extra_ca_certs_mozilla_bundle/ca_bundle/ca_intermediate_root_bundle.pem node src/api/index.js",
     "dev": "NODE_EXTRA_CA_CERTS=node_modules/node_extra_ca_certs_mozilla_bundle/ca_bundle/ca_intermediate_root_bundle.pem nodemon src/api/index.js",
     "test": "CONFIG_FILE=conf/config-test.json mocha",
+    "capture-fixtures": "node scripts/capture-fixtures.js",
     "tsc": "tsc -p jsconfig.json",
     "updateHsts": "node src/retrieve-hsts.js",
     "updateTldList": "node src/retrieve-tld-list.js",

scripts/capture-fixtures.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { retrieve } from "../src/retriever/retriever.js";
+import { scan } from "../src/scanner/index.js";
+import { Site } from "../src/site.js";
+
+/**
+ * Serializes an axios response object to a plain JSON-serializable object
+ * @param {import("../src/types.js").Response|null} response
+ * @returns {object|null}
+ */
+function serializeResponse(response) {
+  if (!response) {
+    return null;
+  }
+
+  return {
+    headers: Object.fromEntries(response.headers || {}),
+    status: response.status,
+    statusText: response.statusText,
+    verified: response.verified,
+    data: response.data || "",
+    httpEquiv: response.httpEquiv ? Object.fromEntries(response.httpEquiv) : {},
+  };
+}
+
+/**
+ * Serializes redirect chain to plain objects
+ * @param {Array<{url: URL, status: number}>} redirects
+ * @returns {Array<{url: string, status: number}>}
+ */
+function serializeRedirects(redirects) {
+  if (!redirects || !Array.isArray(redirects)) {
+    return [];
+  }
+  return redirects.map((r) => ({
+    url: r.url.href,
+    status: r.status,
+  }));
+}
+
+/**
+ * Captures HTTP responses for a domain and saves as fixture
+ * @param {string} domain
+ */
+async function captureFixture(domain) {
+  console.log(`\nCapturing fixture for ${domain}...`);
+
+  const site = Site.fromSiteString(domain);
+
+  // Retrieve full HTTP response data
+  console.log(`  Retrieving HTTP responses...`);
+  const requests = await retrieve(site);
+
+  // Run scan to get results (for metadata/documentation)
+  console.log(`  Running security scan...`);
+  const scanResult = await scan(site);
+
+  // Build fixture object
+  const fixture = {
+    capturedAt: new Date().toISOString(),
+    site: {
+      hostname: site.hostname,
+      port: site.port || null,
+      path: site.path || null,
+    },
+    responses: {
+      auto: serializeResponse(requests.responses.auto),
+      http: serializeResponse(requests.responses.http),
+      https: serializeResponse(requests.responses.https),
+      cors: serializeResponse(requests.responses.cors),
+      httpRedirects: serializeRedirects(requests.responses.httpRedirects),
+      httpsRedirects: serializeRedirects(requests.responses.httpsRedirects),
+    },
+    resources: {
+      path: requests.resources.path || "",
+    },
+    session: {
+      url: requests.session?.url.href,
+    },
+    metadata: {
+      scanResult: {
+        grade: scanResult.scan.grade,
+        score: scanResult.scan.score,
+        testsPassed: scanResult.scan.testsPassed,
+        testsFailed: scanResult.scan.testsFailed,
+      },
+    },
+  };
+
+  // Write to fixture file
+  const fixtureName = domain.replace(/\./g, "-");
+  const fixturePath = path.join("test", "fixtures", `${fixtureName}.json`);
+
+  console.log(`  Writing to ${fixturePath}...`);
+  fs.writeFileSync(fixturePath, JSON.stringify(fixture, null, 2), "utf8");
+
+  console.log(
+    `  ✓ Captured: Grade ${scanResult.scan.grade}, Score ${scanResult.scan.score}`
+  );
+}
+
+/**
+ * Main capture script
+ */
+async function main() {
+  console.log("=== Capturing HTTP Observatory Test Fixtures ===");
+
+  const domains = ["mozilla.org", "observatory.mozilla.org"];
+
+  for (const domain of domains) {
+    try {
+      await captureFixture(domain);
+    } catch (error) {
+      console.error(
+        `  ✗ Error capturing ${domain}:`,
+        Error.isError(error) ? error.message : error
+      );
+      process.exit(1);
+    }
+  }
+
+  console.log("\n✓ All fixtures captured successfully!");
+  console.log(
+    "\nNext steps:\n  1. Review changes: git diff test/fixtures/\n  2. Update test assertions if needed\n  3. Run tests: npm test test/scanner.test.js"
+  );
+}
+
+main();

src/scanner/index.js

@@ -18,19 +18,18 @@ import { ALL_TESTS } from "../constants.js";
  */
 
 /**
- * @param {Site} site
- * @param {import("../types.js").ScanOptions} [options]
- * @returns {Promise<ScanResult>}
+ * Analyzes a Requests object and returns scan results
+ * @param {import("../types.js").Requests} requests
+ * @returns {ScanResult}
  */
-export async function scan(site, options) {
-  let r = await retrieve(site, options);
-  if (!r.responses.auto) {
+export function analyzeScan(requests) {
+  if (!requests.responses.auto) {
     // We cannot connect at all, abort the test.
     throw new Error("The site seems to be down.");
   }
 
   // We allow 2xx, 3xx, 401 and 403 status codes
-  const { status } = r.responses.auto;
+  const { status } = requests.responses.auto;
   if (status < 200 || (status >= 400 && ![401, 403].includes(status))) {
     throw new Error(
       `Site did respond with an unexpected HTTP status code ${status}.`
@@ -40,18 +39,17 @@ export async function scan(site, options) {
   // Run all the tests on the result
   /**  @type {Output[]} */
   const results = ALL_TESTS.map((test) => {
-    return test(r);
+    return test(requests);
   });
 
   /** @type {StringMap} */
-  const responseHeaders = Object.entries(r.responses.auto.headers).reduce(
-    (acc, [key, value]) => {
-      acc[key] = value;
-      return acc;
-    },
-    /** @type {StringMap} */ ({})
-  );
-  const statusCode = r.responses.auto.status;
+  const responseHeaders = Object.entries(
+    requests.responses.auto.headers
+  ).reduce((acc, [key, value]) => {
+    acc[key] = value;
+    return acc;
+  }, /** @type {StringMap} */ ({}));
+  const statusCode = requests.responses.auto.status;
 
   let testsPassed = 0;
   let scoreWithExtraCredit = 100;
@@ -98,3 +96,13 @@ export async function scan(site, options) {
     tests,
   };
 }
+
+/**
+ * @param {Site} site
+ * @param {import("../types.js").ScanOptions} [options]
+ * @returns {Promise<ScanResult>}
+ */
+export async function scan(site, options) {
+  const r = await retrieve(site, options);
+  return analyzeScan(r);
+}

test/fixtures/README.md

@@ -0,0 +1,63 @@
+# Test Fixtures
+
+These fixtures contain captured HTTP responses for scanner integration tests. Using fixtures prevents test breakage when external websites change their security configuration.
+
+## Purpose
+
+The scanner tests validate that our security analysis correctly evaluates real-world websites. However, these websites can change their security headers at any time, causing tests to fail even though our code is working correctly. Fixtures solve this by capturing a snapshot of HTTP responses that we can test against consistently.
+
+## Updating Fixtures
+
+When you want to update test expectations to reflect current website configurations:
+
+1. Run the capture script:
+
+   ```bash
+   npm run capture-fixtures
+   ```
+
+   (This runs `scripts/capture-fixtures.js`)
+
+2. Review the changes:
+
+   ```bash
+   git diff test/fixtures/
+   ```
+
+3. Update corresponding test assertions in [test/scanner.test.js](../scanner.test.js) if needed
+
+4. Commit both fixture changes and test assertion changes together:
+
+   ```bash
+   git add test/fixtures/ test/scanner.test.js
+   git commit -m "test: update scanner fixtures and expectations"
+   ```
+
+## Files
+
+- `mozilla-org.json` - Response data for mozilla.org scanner tests
+- `observatory-mozilla-org.json` - Response data for observatory.mozilla.org scanner tests
+
+## Fixture Contents
+
+Each fixture file contains:
+
+- **Site information**: hostname, port, path
+- **HTTP responses**: Headers, status codes, body content for HTTP and HTTPS requests
+- **Redirect chains**: Complete redirect history for both protocols
+- **CORS preflight**: OPTIONS request response
+- **TLS verification**: Whether certificates were successfully verified
+- **Session URL**: Base URL used for the scanning session
+- **Metadata**: Timestamp and scan results at time of capture (for reference)
+
+## When to Update
+
+Update fixtures when:
+
+- Intentionally updating test expectations to match current site behavior
+- Adding new test cases that require different response scenarios
+- Upgrading dependencies (like axios) that change response structure
+
+## History
+
+Fixtures are versioned in git, so you can see the history of website security configuration changes over time using `git log -- test/fixtures/`.

test/fixtures/mozilla-org.json

@@ -1,12 +1,13 @@
 import fs from "node:fs";
+import path from "node:path";
 
 import { AxiosHeaders } from "axios";
 
 import { Requests } from "../src/types.js";
 import { Session } from "../src/retriever/session.js";
-import path from "node:path";
 import { parseHttpEquivHeaders } from "../src/retriever/utils.js";
 import { Site } from "../src/site.js";
+import { analyzeScan } from "../src/scanner/index.js";
 
 /**
  *
@@ -111,3 +112,79 @@ export function emptyRequests(httpEquivFile = null) {
   }
   return req;
 }
+
+/**
+ * Reconstructs an axios response from serialized fixture data
+ * @param {object} data - Serialized response data
+ * @returns {import("../src/types.js").Response | null}
+ */
+function reconstructResponse(data) {
+  if (!data) {
+    return null;
+  }
+
+  return {
+    headers: new AxiosHeaders(data.headers),
+    status: data.status,
+    statusText: data.statusText,
+    verified: data.verified,
+    data: data.data || "",
+    config: { headers: new AxiosHeaders() },
+    request: { headers: new AxiosHeaders() },
+    httpEquiv: data.httpEquiv
+      ? new Map(Object.entries(data.httpEquiv))
+      : new Map(),
+  };
+}
+
+/**
+ * Loads a fixture and creates a Requests object from it
+ * @param {string} fixtureName - Name of fixture file (without .json extension)
+ * @returns {Requests}
+ */
+export function fixtureRequests(fixtureName) {
+  const fixturePath = path.join("test", "fixtures", `${fixtureName}.json`);
+  const fixtureData = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+
+  const site = Site.fromSiteString(fixtureData.site.hostname);
+  if (fixtureData.site.port) {
+    site.port = fixtureData.site.port;
+  }
+  if (fixtureData.site.path) {
+    site.path = fixtureData.site.path;
+  }
+
+  const req = new Requests(site);
+
+  // Reconstruct responses from fixture data
+  req.responses.auto = reconstructResponse(fixtureData.responses.auto);
+  req.responses.http = reconstructResponse(fixtureData.responses.http);
+  req.responses.https = reconstructResponse(fixtureData.responses.https);
+  req.responses.cors = reconstructResponse(fixtureData.responses.cors);
+
+  // Reconstruct redirect chains
+  req.responses.httpRedirects = (fixtureData.responses.httpRedirects || []).map(
+    (r) => ({ url: new URL(r.url), status: r.status })
+  );
+  req.responses.httpsRedirects = (
+    fixtureData.responses.httpsRedirects || []
+  ).map((r) => ({ url: new URL(r.url), status: r.status }));
+
+  // Set resources
+  req.resources.path = fixtureData.resources.path || "";
+
+  // Create session
+  req.session = new Session(new URL(fixtureData.session.url));
+
+  return req;
+}
+
+/**
+ * Runs scan logic on a pre-loaded Requests object (for fixture-based testing)
+ * This is a simple wrapper around analyzeScan() from the scanner module
+ * @param {Requests} requests - Pre-loaded requests object (e.g., from fixtureRequests)
+ * @returns {import("../src/types.js").ScanResult}
+ */
+export function scanWithRequests(requests) {
+  return analyzeScan(requests);
+}