Add SnapshotTester utility for karma unit tests

Provides textual snapshot testing, similar to jest snapshot tests. Uses
the `--on-diff` CLI test parameter.

Updated `PerformanceInsightFormatter.test.ts` to use this.

Bug: 434252192
Change-Id: I2d3e90f78e73a75e78273518660f92f60dd820d0
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6789018
Auto-Submit: Connor Clark <[email protected]>
Commit-Queue: Paul Irish <[email protected]>
Reviewed-by: Paul Irish <[email protected]>

Author: Connor Clark

front_end/models/ai_assistance/BUILD.gn

@@ -98,3 +98,7 @@ ts_library("unittests") {
     "../trace:bundle",
   ]
 }
+
+copy_to_gen("snapshots") {
+  sources = [ "data_formatters/PerformanceInsightFormatter.snapshot.txt" ]
+}

front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.snapshot.txt

@@ -2,6 +2,7 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
+import("../../scripts/build/ninja/copy.gni")
 import("../../scripts/build/typescript/typescript.gni")
 
 ts_library("testing") {
@@ -34,6 +35,8 @@ ts_library("testing") {
     "PersistenceHelpers.ts",
     "PropertyParser.ts",
     "ResourceTreeHelpers.ts",
+    "SnapshotTester.test.ts",
+    "SnapshotTester.ts",
     "SourceMapEncoder.test.ts",
     "SourceMapEncoder.ts",
     "SourceMapHelpers.ts",
@@ -82,3 +85,7 @@ ts_library("testing") {
     "../ui/visual_logging:testing",
   ]
 }
+
+copy_to_gen("snapshots") {
+  sources = [ "SnapshotTester.snapshot.txt" ]
+}

front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.test.ts

@@ -87,3 +87,37 @@ it('does not mutate the DOM when we scroll the component', async () => {
 ```
 
 The above test will fail if any DOM mutations are detected.
+
+## SnapshotTester
+
+For Karma unit tests, you can add regression tests for string output (similar to Jest snapshots) via SnapshotTester.
+
+> Note: Prefer unit tests that test behavior more directly when possible. Some good candidates for snapshot tests is code the formats long strings. A bad candidate would be a `JSON.stringify` of a complex object structure (prefer explicit asserts instead).
+
+Results for all snapshots for a test file `MyFile.test.ts` are written to `MyFile.snapshot.txt`.
+
+To add snapshot tests to a new test file, add a before and after hook to the describe test suite:
+
+```
+let snapshotTester: SnapshotTester;
+before(async () => {
+  snapshotTester = new SnapshotTester(import.meta);
+  await snapshotTester.load();
+});
+
+after(async () => {
+  await snapshotTester.finish();
+});
+```
+
+Then add the `.snapshot.txt` file to the appropriate BUILD.gn:
+
+```
+copy_to_gen("snapshots") {
+  sources = [ "myfile.snapshot.txt" ]
+}
+```
+
+Then inside a test, call `snapshotTester.assert(this, output)`. For an example, see SnapshotTester.test.ts.
+
+To update snapshots, run `npm run test -- --on-diff=update ...`

front_end/testing/BUILD.gn

@@ -0,0 +1,9 @@
+Title: SnapshotTester example snapshot
+Content:
+hello world
+=== end content
+
+Title: SnapshotTester only one snapshot assert allowed
+Content:
+hello world 1
+=== end content

front_end/testing/README.md

@@ -0,0 +1,32 @@
+// Copyright 2025 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import {SnapshotTester} from './SnapshotTester.js';
+
+describe('SnapshotTester', () => {
+  let snapshotTester: SnapshotTester;
+  before(async () => {
+    snapshotTester = new SnapshotTester(import.meta);
+    await snapshotTester.load();
+  });
+
+  after(async () => {
+    await snapshotTester.finish();
+  });
+
+  it('example snapshot', function() {
+    snapshotTester.assert(this, 'hello world');
+  });
+
+  it('only one snapshot assert allowed', function() {
+    snapshotTester.assert(this, 'hello world 1');
+
+    try {
+      snapshotTester.assert(this, 'hello world 2');
+      assert.fail('Expected `snapshotTester.assert` to throw');
+    } catch (err) {
+      assert.strictEqual(err.message, 'sorry, currently only support 1 snapshot assertion per test');
+    }
+  });
+});

front_end/testing/SnapshotTester.snapshot.txt

@@ -0,0 +1,150 @@
+// Copyright 2025 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/**
+ * Asserts two strings are equal, and logs the first differing line if not equal.
+ */
+function assertSnapshotContent(actual: string, expected: string): void {
+  if (actual !== expected) {
+    const actualLines = actual.split('\n');
+    const expectedLines = expected.split('\n');
+    for (let i = 0; i < Math.max(actualLines.length, expectedLines.length); i++) {
+      const actualLine = actualLines.at(i);
+      const expectedLine = expectedLines.at(i);
+      if (actualLine !== expectedLine) {
+        const firstDifference = `First differing line:\nexpected: ${expectedLine}\nactual:   ${actualLine}`;
+        throw new Error(
+            `snapshot assertion failed! to update snapshot, run \`npm run test -- --on-diff=update ...\`\n\n${
+                firstDifference}`);
+      }
+    }
+  }
+}
+
+/**
+ * Provides snapshot testing for karma unit tests.
+ * See README.md for more.
+ *
+ * Note: karma.conf.ts implements the server logic (see snapshotTesterFactory).
+ */
+export class SnapshotTester {
+  static #updateMode: boolean|null = null;
+
+  #snapshotUrl: string;
+  #expected = new Map<string, string>();
+  #actual = new Map<string, string>();
+  #anyFailures = false;
+  #newTests = false;
+
+  constructor(meta: ImportMeta) {
+    this.#snapshotUrl = meta.url.replace('.test.js', '.snapshot.txt').split('?')[0];
+  }
+
+  async load() {
+    if (SnapshotTester.#updateMode === null) {
+      SnapshotTester.#updateMode = await this.#checkIfUpdateMode();
+    }
+
+    const url = new URL(this.#snapshotUrl, import.meta.url);
+    const response = await fetch(url);
+    if (response.status === 404) {
+      console.warn(`Snapshot file not found: ${url.href}. Will create it for you.`);
+      return;
+    }
+    if (response.status !== 200) {
+      throw new Error('failed to load snapshot');
+    }
+
+    this.#parseSnapshotFileContent(await response.text());
+  }
+
+  assert(context: Mocha.Context, actual: string) {
+    const title = context.test?.fullTitle() ?? '';
+
+    if (this.#actual.has(title)) {
+      throw new Error('sorry, currently only support 1 snapshot assertion per test');
+    }
+
+    if (actual.includes('=== end content')) {
+      throw new Error('invalid content');
+    }
+
+    actual = actual.trim();
+    this.#actual.set(title, actual);
+
+    const expected = this.#expected.get(title);
+    if (!expected) {
+      // New tests always pass on the first run.
+      this.#newTests = true;
+      return;
+    }
+
+    if (!SnapshotTester.#updateMode && actual !== expected) {
+      this.#anyFailures = true;
+      assertSnapshotContent(actual, expected);
+    }
+  }
+
+  async finish() {
+    let didAnyTestNotRun = false;
+    for (const title of this.#expected.keys()) {
+      if (!this.#actual.has(title)) {
+        didAnyTestNotRun = true;
+        break;
+      }
+    }
+
+    let shouldPostUpdate = SnapshotTester.#updateMode;
+    if (!this.#anyFailures && (didAnyTestNotRun || this.#newTests)) {
+      shouldPostUpdate = true;
+    }
+
+    if (!shouldPostUpdate) {
+      return;
+    }
+
+    const url = new URL('/update-snapshot', import.meta.url);
+    url.searchParams.set('snapshotUrl', this.#snapshotUrl);
+    const content = this.#serializeSnapshotFileContent();
+    const response = await fetch(url, {method: 'POST', body: content});
+    if (response.status !== 200) {
+      throw new Error(`Unable to update snapshot ${url}`);
+    }
+  }
+
+  #serializeSnapshotFileContent(): string {
+    if (!this.#actual.size) {
+      return '';
+    }
+
+    const lines = [];
+    for (const [title, result] of this.#actual) {
+      lines.push(`Title: ${title}`);
+      lines.push(`Content:\n${result}`);
+      lines.push('=== end content\n');
+    }
+    lines.push('');
+
+    return lines.join('\n').trim() + '\n';
+  }
+
+  #parseSnapshotFileContent(content: string): void {
+    const sections = content.split('=== end content').map(s => s.trim()).filter(Boolean);
+    for (const section of sections) {
+      const [titleField, contentField, ...contentLines] = section.split('\n');
+      const title = titleField.replace('Title:', '').trim();
+      if (contentField !== 'Content:') {
+        throw new Error('unexpected snapshot file');
+      }
+      const content = contentLines.join('\n').trim();
+      this.#expected.set(title, content);
+    }
+  }
+
+  async #checkIfUpdateMode(): Promise<boolean> {
+    const response = await fetch('/snapshot-update-mode');
+    const data = await response.json();
+    return data.updateMode === true;
+  }
+}

front_end/testing/SnapshotTester.test.ts

@@ -77,7 +77,6 @@ export class TraceLoader {
     if (cached) {
       return cached;
     }
-    // Required URLs differ across the component server and the unit tests, so try both.
     const urlForTest = new URL(`../panels/timeline/fixtures/traces/${name}`, import.meta.url);
 
     const contents = await TraceLoader.loadTraceFileFromURL(urlForTest);

front_end/testing/SnapshotTester.ts

@@ -4,9 +4,11 @@
 
 /* eslint @typescript-eslint/no-explicit-any: 0 */
 
+import * as fs from 'fs';
 import * as path from 'path';
 import type {Page, ScreenshotOptions, Target} from 'puppeteer-core';
 import puppeteer from 'puppeteer-core';
+import * as url from 'url';
 
 import {formatAsPatch, resultAssertionsDiff, ResultsDBReporter} from '../../test/conductor/karma-resultsdb-reporter.js';
 import {CHECKOUT_ROOT, GEN_DIR, SOURCE_ROOT} from '../../test/conductor/paths.js';
@@ -195,6 +197,7 @@ module.exports = function(config: any) {
       {pattern: path.join(GEN_DIR, 'inspector_overlay/**/*.js'), served: true, included: false},
       {pattern: path.join(GEN_DIR, 'inspector_overlay/**/*.js.map'), served: true, included: false},
       {pattern: path.join(GEN_DIR, 'front_end/**/fixtures/**/*'), served: true, included: false},
+      {pattern: path.join(GEN_DIR, 'front_end/**/*.snapshot.txt'), served: true, included: false},
       {pattern: path.join(GEN_DIR, 'front_end/ui/components/docs/**/*'), served: true, included: false},
     ],
 
@@ -230,6 +233,7 @@ module.exports = function(config: any) {
       require('karma-coverage'),
       {'reporter:resultsdb': ['type', ResultsDBReporter]},
       {'reporter:progress-diff': ['type', ProgressWithDiffReporter]},
+      {'middleware:snapshotTester': ['factory', snapshotTesterFactory]},
     ],
 
     preprocessors: {
@@ -244,6 +248,8 @@ module.exports = function(config: any) {
       '/front_end': `/base/${targetDir}/front_end`,
     },
 
+    middleware: ['snapshotTester'],
+
     coverageReporter: {
       dir: path.join(TestConfig.artifactsDir, COVERAGE_OUTPUT_DIRECTORY),
       subdir: '.',
@@ -266,3 +272,45 @@ module.exports = function(config: any) {
 
   config.set(options);
 };
+
+function snapshotTesterFactory() {
+  return (req: any, res: any, next: any) => {
+    if (req.url.startsWith('/snapshot-update-mode')) {
+      res.writeHead(200, {'Content-Type': 'application/json'});
+      const updateMode = TestConfig.onDiff.update === true;
+      res.end(JSON.stringify({updateMode}));
+      return res.end();
+    }
+
+    if (req.url.startsWith('/update-snapshot')) {
+      const parsedUrl = url.parse(req.url, true);
+      if (typeof parsedUrl.query.snapshotUrl !== 'string') {
+        throw new Error('invalid snapshotUrl');
+      }
+
+      const snapshotUrl = parsedUrl.query.snapshotUrl;
+      const snapshotPath = path.join(SOURCE_ROOT, url.parse(snapshotUrl, false).pathname?.split('gen')[1] ?? '');
+
+      let body = '';
+      req.on('data', (chunk: any) => {
+        body += chunk.toString();
+      });
+      req.on('end', () => {
+        // eslint-disable-next-line no-console
+        console.info(`updating snapshot: ${snapshotPath}`);
+        if (body) {
+          fs.writeFileSync(snapshotPath, body);
+        } else {
+          fs.rmSync(snapshotPath, {force: true});
+        }
+
+        res.writeHead(200);
+        res.end();
+      });
+
+      return;
+    }
+
+    next();
+  };
+}