gosling-lang · etowahadams · Aug 17, 2023 · Aug 17, 2023 · Aug 17, 2023 · Aug 17, 2023
diff --git a/.gitignore b/.gitignore
@@ -20,4 +20,4 @@ yarn-error.log*
 report.*
 *.swp
 *.swo
-*~
+*~
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -61,6 +61,18 @@ yarn build-editor
 yarn preview
 ```
 
+## Visual Regression
+
+To test if your changes make a difference visually across a large number of specifications, you can use the `yarn screenshot` command. 
+``` bash
+yarn build      # needed to get the latest gosling build
+yarn screenshot # takes screenshots of all of the example specs and puts them in img/visual-regression/new-screenshots
+yarn update-ref-screenshots # update the reference screenshots with your new screenshots 
+```
+This command will use `dist/gosling.js` in a headless browser (using puppeteer) and take a screenshot of the visualization that is included in the editor. 
+It will save these screenshots in `img/visual-regression/new-screenshots`. If there is a difference compared to the screenshots in `img/visual-regression/reference-screenshots`
+it will show the differences in an image in `img/visual-regression/diffs`. 
+
 ## Editing `gosling.js/embed`
 
 This repo also contains the source code for `gosling.js/embed`, an ES Module intended to be

diff --git a/img/visual-regression/diffs/.gitignore b/img/visual-regression/diffs/.gitignore
@@ -0,0 +1,4 @@
+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore
diff --git a/img/visual-regression/new-screenshots/.gitignore b/img/visual-regression/new-screenshots/.gitignore
@@ -0,0 +1,4 @@
+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore
diff --git a/img/visual-regression/screenshots/ALIGNMENT.png b/img/visual-regression/screenshots/ALIGNMENT.png
diff --git a/img/visual-regression/screenshots/BAM_PILEUP.png b/img/visual-regression/screenshots/BAM_PILEUP.png
diff --git a/img/visual-regression/screenshots/BAND.png b/img/visual-regression/screenshots/BAND.png
diff --git a/img/visual-regression/screenshots/BASIC_SEMANTIC_ZOOM.png b/img/visual-regression/screenshots/BASIC_SEMANTIC_ZOOM.png
diff --git a/img/visual-regression/screenshots/CANCER_VARIANT.png b/img/visual-regression/screenshots/CANCER_VARIANT.png
diff --git a/img/visual-regression/screenshots/CIRCOS.png b/img/visual-regression/screenshots/CIRCOS.png
diff --git a/img/visual-regression/screenshots/CIRCULAR_BETWEEN_BANDS.png b/img/visual-regression/screenshots/CIRCULAR_BETWEEN_BANDS.png
diff --git a/img/visual-regression/screenshots/CIRCULAR_OVERVIEW_LINEAR_DETAIL.png b/img/visual-regression/screenshots/CIRCULAR_OVERVIEW_LINEAR_DETAIL.png
diff --git a/img/visual-regression/screenshots/CORCES_ET_AL.png b/img/visual-regression/screenshots/CORCES_ET_AL.png
diff --git a/img/visual-regression/screenshots/CYTOBANDS.png b/img/visual-regression/screenshots/CYTOBANDS.png
diff --git a/img/visual-regression/screenshots/Circular Range.png b/img/visual-regression/screenshots/Circular Range.png
diff --git a/img/visual-regression/screenshots/DEBUG.png b/img/visual-regression/screenshots/DEBUG.png
diff --git a/img/visual-regression/screenshots/GENE_ANNOTATION.png b/img/visual-regression/screenshots/GENE_ANNOTATION.png
diff --git a/img/visual-regression/screenshots/GIVE.png b/img/visual-regression/screenshots/GIVE.png
diff --git a/img/visual-regression/screenshots/GREMLIN.png b/img/visual-regression/screenshots/GREMLIN.png
diff --git a/img/visual-regression/screenshots/ISLANDVIEWER.png b/img/visual-regression/screenshots/ISLANDVIEWER.png
diff --git a/img/visual-regression/screenshots/LAYOUT_AND_ARRANGEMENT_1.png b/img/visual-regression/screenshots/LAYOUT_AND_ARRANGEMENT_1.png
diff --git a/img/visual-regression/screenshots/LAYOUT_AND_ARRANGEMENT_2.png b/img/visual-regression/screenshots/LAYOUT_AND_ARRANGEMENT_2.png
diff --git a/img/visual-regression/screenshots/LINKING.png b/img/visual-regression/screenshots/LINKING.png
diff --git a/img/visual-regression/screenshots/MARK_DISPLACEMENT.png b/img/visual-regression/screenshots/MARK_DISPLACEMENT.png
diff --git a/img/visual-regression/screenshots/MATRIX.png b/img/visual-regression/screenshots/MATRIX.png
diff --git a/img/visual-regression/screenshots/MATRIX_HFFC6.png b/img/visual-regression/screenshots/MATRIX_HFFC6.png
diff --git a/img/visual-regression/screenshots/MOUSE_EVENT.png b/img/visual-regression/screenshots/MOUSE_EVENT.png
diff --git a/img/visual-regression/screenshots/RESPONSIVE_ALIGNMENT.png b/img/visual-regression/screenshots/RESPONSIVE_ALIGNMENT.png
diff --git a/img/visual-regression/screenshots/RESPONSIVE_COMPARATIVE_MATRICES.png b/img/visual-regression/screenshots/RESPONSIVE_COMPARATIVE_MATRICES.png
diff --git a/img/visual-regression/screenshots/RESPONSIVE_COMPARATIVE_VIEWS.png b/img/visual-regression/screenshots/RESPONSIVE_COMPARATIVE_VIEWS.png
diff --git a/img/visual-regression/screenshots/RESPONSIVE_IDEOGRAM.png b/img/visual-regression/screenshots/RESPONSIVE_IDEOGRAM.png
diff --git a/img/visual-regression/screenshots/RESPONSIVE_MULTIVEC.png b/img/visual-regression/screenshots/RESPONSIVE_MULTIVEC.png
diff --git a/img/visual-regression/screenshots/RESPONSIVE_MULTIVEC_CIRCULAR.png b/img/visual-regression/screenshots/RESPONSIVE_MULTIVEC_CIRCULAR.png
diff --git a/img/visual-regression/screenshots/RESPONSIVE_TRACK_WISE_COMPARISON.png b/img/visual-regression/screenshots/RESPONSIVE_TRACK_WISE_COMPARISON.png
diff --git a/img/visual-regression/screenshots/RULE.png b/img/visual-regression/screenshots/RULE.png
diff --git a/img/visual-regression/screenshots/SARS_COV_2.png b/img/visual-regression/screenshots/SARS_COV_2.png
diff --git a/img/visual-regression/screenshots/SASHIMI_PLOT.png b/img/visual-regression/screenshots/SASHIMI_PLOT.png
diff --git a/img/visual-regression/screenshots/SEMANTIC_ZOOM.png b/img/visual-regression/screenshots/SEMANTIC_ZOOM.png
diff --git a/img/visual-regression/screenshots/SEQUENCE.png b/img/visual-regression/screenshots/SEQUENCE.png
diff --git a/img/visual-regression/screenshots/TEMPLATE.png b/img/visual-regression/screenshots/TEMPLATE.png
diff --git a/img/visual-regression/screenshots/VISUAL_ENCODING.png b/img/visual-regression/screenshots/VISUAL_ENCODING.png
diff --git a/img/visual-regression/screenshots/VISUAL_ENCODING_CIRCULAR.png b/img/visual-regression/screenshots/VISUAL_ENCODING_CIRCULAR.png
diff --git a/img/visual-regression/screenshots/doc_area.png b/img/visual-regression/screenshots/doc_area.png
diff --git a/img/visual-regression/screenshots/doc_bar.png b/img/visual-regression/screenshots/doc_bar.png
diff --git a/img/visual-regression/screenshots/doc_bed.png b/img/visual-regression/screenshots/doc_bed.png
diff --git a/img/visual-regression/screenshots/doc_brush.png b/img/visual-regression/screenshots/doc_brush.png
diff --git a/img/visual-regression/screenshots/doc_dummy_track.png b/img/visual-regression/screenshots/doc_dummy_track.png
diff --git a/img/visual-regression/screenshots/doc_gff.png b/img/visual-regression/screenshots/doc_gff.png
diff --git a/img/visual-regression/screenshots/doc_line.png b/img/visual-regression/screenshots/doc_line.png
diff --git a/img/visual-regression/screenshots/doc_link.png b/img/visual-regression/screenshots/doc_link.png
diff --git a/img/visual-regression/screenshots/doc_linking_tracks.png b/img/visual-regression/screenshots/doc_linking_tracks.png
diff --git a/img/visual-regression/screenshots/doc_overlay_bar_point.png b/img/visual-regression/screenshots/doc_overlay_bar_point.png
diff --git a/img/visual-regression/screenshots/doc_overlay_line_point.png b/img/visual-regression/screenshots/doc_overlay_line_point.png
diff --git a/img/visual-regression/screenshots/doc_overlay_rect_text.png b/img/visual-regression/screenshots/doc_overlay_rect_text.png
diff --git a/img/visual-regression/screenshots/doc_point.png b/img/visual-regression/screenshots/doc_point.png
diff --git a/img/visual-regression/screenshots/doc_rect.png b/img/visual-regression/screenshots/doc_rect.png
diff --git a/img/visual-regression/screenshots/doc_semantic_zoom_cyto.png b/img/visual-regression/screenshots/doc_semantic_zoom_cyto.png
diff --git a/img/visual-regression/screenshots/doc_semantic_zoom_sequence.png b/img/visual-regression/screenshots/doc_semantic_zoom_sequence.png
diff --git a/img/visual-regression/screenshots/doc_text.png b/img/visual-regression/screenshots/doc_text.png
diff --git a/img/visual-regression/screenshots/doc_triangle.png b/img/visual-regression/screenshots/doc_triangle.png
diff --git a/img/visual-regression/screenshots/doc_vcf_indels.png b/img/visual-regression/screenshots/doc_vcf_indels.png
diff --git a/img/visual-regression/screenshots/doc_vcf_point_mutations.png b/img/visual-regression/screenshots/doc_vcf_point_mutations.png
diff --git a/img/visual-regression/visual-regression.test.ts b/img/visual-regression/visual-regression.test.ts
@@ -0,0 +1,116 @@
+import puppeteer, { Page, Browser } from 'puppeteer';
+import { examples } from '../../editor/example';
+import * as fs from 'fs';
+import { beforeAll } from 'vitest';
+
+import { PNG } from 'pngjs';
+import pixelmatch from 'pixelmatch';
+
+function delay(time: number) {
+    return new Promise(resolve => {
+        setTimeout(resolve, time);
+    });
+}
+// Based on https://github.com/hms-dbmi/chromoscope/blob/master/src/script/gosling-screenshot.js
+function html(
+    spec: string,
+    gosling: string,
+    { reactVersion = '16', pixijsVersion = '6', higlassVersion = '1.11' } = {}
+) {
+    const baseUrl = 'https://unpkg.com';
+    return `\
+<!DOCTYPE html>
+<html>
+	<link rel="stylesheet" href="${baseUrl}/higlass@${higlassVersion}/dist/hglib.css">
+	<script src="${baseUrl}/react@${reactVersion}/umd/react.production.min.js"></script>
+	<script src="${baseUrl}/react-dom@${reactVersion}/umd/react-dom.production.min.js"></script>
+	<script src="${baseUrl}/pixi.js@${pixijsVersion}/dist/browser/pixi.min.js"></script>
+	<script src="${baseUrl}/higlass@${higlassVersion}/dist/hglib.js"></script>
+    <script type="text/javascript">${gosling}</script>
+<body>
+	<div id="vis"></div>
+	<script>
+		gosling.embed(document.getElementById("vis"), JSON.parse(\`${spec}\`))
+	</script>
+</body>
+</html>`;
+}
+
+function readFile(filePath: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+        fs.readFile(filePath, 'utf8', (err, data) => {
+            if (err) {
+                reject(err);
+            } else {
+                resolve(data);
+            }
+        });
+    });
+}
+
+/**
+ * Compares two PNG files and writes the difference to a third file if a difference is found
+ */
+function comparePNG(path1: string, path2: string, diffPath: string) {
+    const img1 = PNG.sync.read(fs.readFileSync(path1));
+    const img2 = PNG.sync.read(fs.readFileSync(path2));
+    const { width, height } = img1;
+    const diff = new PNG({ width, height });
+    const pixeldifference = pixelmatch(img1.data, img2.data, diff.data, width, height, { threshold: 0.1 });
+    // only write to file if there is a difference in the images
+    if (pixeldifference > 0) {
+        fs.writeFileSync(diffPath, PNG.sync.write(diff));
+    }
+}
+
+let browser: Browser;
+let page: Page;
+let currentGosling: string;
+
+/**
+ * Setup the browser and page
+ */
+
+beforeAll(async () => {
+    currentGosling = await readFile('./dist/gosling.js');
+    browser = await puppeteer.launch({
+        headless: true,
+        devtools: true,
+        args: ['--use-gl=swiftshader'] // necessary for canvas to not be blank in the screenshot
+    });
+    page = await browser.newPage();
+    await page.goto('http://gosling-lang.org/docs/'); // must first go to a page with a URL for workers to work properly
+});
+
+console.warn('Expect this to take about 10 minutes to run, depending on your internet speed');
+
+/**
+ * Loop over all examples and take a screenshot
+ */
+Object.entries(examples)
+    // .filter(([name]) => name === 'doc_text') // we only want to see the broken example now
+    .forEach(([name, example]) => {
+        test(
+            name,
+            async () => {
+                let spec = JSON.stringify(example.spec);
+                spec = spec.replaceAll('\\', '\\\\');
+                await page.setContent(html(spec, currentGosling), { waitUntil: 'networkidle0' });
+                await page.addScriptTag({ path: './dist/gosling.js' });
+                const component = await page.waitForSelector('.gosling-component');
+                await page.waitForNetworkIdle({ idleTime: 2000 });
+                await delay(2000); // wait extra 2 seconds. Should be enough time for any rendering to finish
+                await component!.screenshot({ path: `./img/visual-regression/new-screenshots/${name}.png` });
+                comparePNG(
+                    `img/visual-regression/reference-screenshots/${name}.png`,
+                    `img/visual-regression/new-screenshots/${name}.png`,
+                    `img/visual-regression/diffs/${name}.png`
+                );
+            },
+            20000
+        );
+    });
+
+afterAll(async () => {
+    await browser.close();
+});
diff --git a/package.json b/package.json
@@ -29,6 +29,8 @@
         "preview": "vite preview",
         "check": "tsc --noEmit",
         "test": "vitest",
+        "screenshot": "vitest --mode screenshot",
+        "update-ref-screenshots": "rm ./img/visual-regression/reference-screenshots/*.png; mv ./img/visual-regression/new-screenshots/*.png ./img/visual-regression/reference-screenshots/",
         "coverage": "vitest run --coverage",
         "format": "eslint src/ editor/ --fix && prettier 'editor/**/*.css' --write",
         "schema": "node scripts/generate-schemas.mjs",
@@ -93,6 +95,8 @@
         "@types/d3-request": "^1.0.6",
         "@types/d3-selection": "^2.0.0",
         "@types/lodash-es": "^4.17.5",
+        "@types/pixelmatch": "^5.2.4",
+        "@types/pngjs": "^6.0.2",
         "@types/pubsub-js": "^1.8.2",
         "@types/react": "^18.2.0",
         "@types/react-dom": "^18.2.0",
@@ -121,8 +125,11 @@
         "jsdom": "^19.0.0",
         "jsoncrush": "^1.1.6",
         "npm-run-all": "^4.1.5",
+        "pixelmatch": "^5.3.0",
         "pixi.js": "^6.3.0",
+        "pngjs": "^7.0.0",
         "prettier": "^2.0.5",
+        "puppeteer": "^13.5.2",
         "react": "^18.2.0",
         "react-dom": "^18.2.0",
         "react-markdown": "^5.0.3",

diff --git a/tsconfig.json b/tsconfig.json
@@ -42,7 +42,7 @@
     "editor/index.tsx",
     "embed/index.ts"
   ],
-  "include": ["src", "src/**/*.d.ts", "editor"],
+  "include": ["src", "src/**/*.d.ts", "editor", "img"],
   "exclude": [
     "node_modules",
     "public",

diff --git a/vite.config.js b/vite.config.js
@@ -73,6 +73,9 @@ const external = [...Object.keys(pkg.dependencies), ...Object.keys(pkg.peerDepen
     dep => !skipExt.has(dep)
 );
 
+/**
+ * Used when yarn build-lib is run
+ */
 const esm = defineConfig({
     build: {
         emptyOutDir: false,
@@ -101,9 +104,13 @@ const dev = defineConfig({
     plugins: [bundleWebWorker, manualInlineWorker]
 });
 
+/**
+ * This config is used when vitest is run
+ */
 const testing = defineConfig({
     resolve: { alias },
     test: {
+        exclude: ['./node_modules/**', './dist/**', './img/**'], // img is excluded because it is used for visual regression testing
         globals: true,
         setupFiles: [path.resolve(__dirname, './scripts/setup-vitest.js')],
         environment: 'jsdom',
@@ -121,9 +128,27 @@ const testing = defineConfig({
     }
 });
 
+/**
+ * This config is used to take screenshots of every example Gosling spec using a headless browser (puppeteer)
+ */
+const screenshot = defineConfig({
+    test: {
+        include: ['./img/visual-regression/*'],
+        globals: true,
+        environment: 'jsdom',
+        threads: false,
+        environmentOptions: {
+            jsdom: {
+                resources: 'usable'
+            }
+        }
+    }
+});
+
 export default ({ command, mode }) => {
     if (command === 'build' && mode === 'lib') return esm;
     if (mode == 'test') return testing;
+    if (mode == 'screenshot') return screenshot;
     if (mode === 'editor') {
         dev.plugins.push(reactRefresh());
     }
-Original file line number
+Diff line change
@@ Expand Up / @@ -20,4 +20,4 @@ yarn-error.log* @@
     report.*
     *.swp
     *.swo
-    *~
+    *~