Percy and jest-puppeteer environment setup for visual testing

.eslintrc.js

@@ -20,4 +20,19 @@ esLintConfig.settings['import/resolver'].nuxt = {
   nuxtSrcDir: 'docs',
 };
 
+// Remove linting errors for the globals defined in the jest-puppeteer package
+esLintConfig.env = {
+  ...esLintConfig.env,
+  'jest': true,
+};
+
+esLintConfig.globals = {
+  ...esLintConfig.globals,
+  page: true,
+  browser: true,
+  context: true,
+  puppeteerConfig: true,
+  jestPuppeteer: true,
+};
+
 module.exports = esLintConfig;

.percy.yml

@@ -0,0 +1,19 @@
+version: 2
+snapshot:
+  widths:
+    - 375
+    - 1280
+  minHeight: 1024
+  percyCSS: ""
+  enableJavaScript: false #disable Javascript by default to capture initial page state without JS-driven changes
+  cliEnableJavaScript: true #enable Javascript when running Percy through CLI, for dynamic content
+  disableShadowDOM: false
+discovery:
+  allowedHostnames: []
+  disallowedHostnames: []
+  networkIdleTimeout: 100
+  captureMockedServiceWorker: false
+upload:
+  files: "**/*.{png,jpg,jpeg}"
+  ignore: ""
+  stripExtensions: false

docs/pages/testing-playground.vue

@@ -0,0 +1,67 @@
+<template>
+
+  <!--
+    Testing Playground: A dedicated page for component visual testing
+    *****************************************************
+
+    Please do not modify the contents of this file.
+  -->
+  <div id="testing-playground" style="padding: 24px">
+    <component :is="component" v-bind="componentProps" />
+  </div>
+
+</template>
+
+
+<script>
+
+  /**
+   * Renders the components for visual testing
+   * to ensure expected visual behavior under
+   * various conditions.
+   */
+  export default {
+    name: 'VisualTestingPlayground',
+    data() {
+      return {
+        /**
+         * @type {string|null} The name of the component to be dynamically rendered.
+         */
+        component: null,
+        /**
+         * @type {Object} The props to be passed to the dynamically rendered component.
+         */
+        componentProps: {},
+      };
+    },
+
+    /**
+     * Adds an event listener for messages from the test runner.
+     * This listener will trigger the `handleMessage` method.
+     */
+    mounted() {
+      window.addEventListener('message', this.handleMessage);
+    },
+
+    /**
+     * Removes the event listener for messages from the test runner.
+     */
+    beforeDestroy() {
+      window.removeEventListener('message', this.handleMessage);
+    },
+
+    methods: {
+      /**
+       * Handles messages received from the test runner to render a specified component.
+       * @param {MessageEvent} event - The message event containing the component and its props.
+       */
+      handleMessage(event) {
+        if (event.data.type === 'RENDER_COMPONENT') {
+          this.component = event.data.component;
+          this.componentProps = event.data.props;
+        }
+      },
+    },
+  };
+
+</script>

jest-puppeteer.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  launch: {
+    headless: true,
+    timeout: 180000,
+  },
+  browserContext: 'default',
+};

jest.conf/setup.js

@@ -38,7 +38,9 @@ Vue.config.silent = true;
 Vue.config.devtools = false;
 Vue.config.productionTip = false;
 
-Object.defineProperty(window, 'scrollTo', { value: () => {}, writable: true });
+if (process.env.TEST_TYPE !== 'visual' && typeof window !== 'undefined') {
+  Object.defineProperty(window, 'scrollTo', { value: () => {}, writable: true });
+}
 
 // Shows better NodeJS unhandled promise rejection errors
 process.on('unhandledRejection', (reason, p) => {

jest.conf/testUtils.js

@@ -10,6 +10,17 @@ export const resizeWindow = (width, height = 768) => {
   });
 };
 
+export function canTakeScreenshot() {
+  const percyToken = process.env.PERCY_TOKEN;
+  const runVisualTests = process.env.TEST_TYPE === 'visual';
+  if (runVisualTests && !percyToken) {
+    throw new Error(
+      'Error: Visual tests cannot be run because PERCY_TOKEN environment variable is not set.'
+    );
+  }
+  return runVisualTests && percyToken;
+}
+
 export const testAfterResize = testFunction => {
   let animationFrameId;
   const assertAfterResize = () => {

jest.conf/visual.index.js

@@ -0,0 +1,30 @@
+const path = require('node:path');
+
+const moduleNameMapper = {
+  '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga|css)$': path.resolve(
+    __dirname,
+    './fileMock.js'
+  ),
+};
+
+module.exports = {
+  rootDir: path.resolve(__dirname, '..'),
+  preset: 'jest-puppeteer',
+  testTimeout: 50000,
+  moduleFileExtensions: ['js', 'json', 'vue'],
+  moduleNameMapper,
+  transform: {
+    '^.+\\.js$': require.resolve('babel-jest'),
+    '^.+\\.vue$': require.resolve('vue-jest'),
+  },
+  snapshotSerializers: ['jest-serializer-vue'],
+  globals: {
+    HOST: 'http://localhost:4000/',
+    'vue-jest': {
+      hideStyleWarn: true,
+      experimentalCSSCompile: true,
+    },
+  },
+  setupFilesAfterEnv: [path.resolve(__dirname, './visual.setup')],
+  verbose: true,
+};

jest.conf/visual.setup.js

@@ -0,0 +1,7 @@
+import './setup';
+import { percySnapshot } from '@percy/puppeteer';
+
+// Set the test type to visual
+process.env.TEST_TYPE = 'visual';
+
+global.percySnapshot = percySnapshot;

lib/KImg/__tests__/KImg.spec.js

@@ -1,20 +1,17 @@
 import { shallowMount } from '@vue/test-utils';
 import KImg from '../';
 
-function makeWrapper(opts) {
-  return shallowMount(KImg, opts);
+function makeWrapper({ propsData = {} } = {}) {
+  return shallowMount(KImg, { propsData });
 }
 
 describe('KImg', () => {
   it(`renders without any errors when a valid 'src' and 'altText' are provided`, () => {
-    const error = jest.fn();
     const wrapper = makeWrapper({
       propsData: { src: '/le-logo.svg', altText: 'LE logo' },
-      listeners: { error },
     });
 
     expect(wrapper.exists()).toBe(true);
-    expect(error).not.toHaveBeenCalled();
 
     const img = wrapper.find('img');
     expect(img.exists()).toBe(true);
@@ -23,26 +20,20 @@ describe('KImg', () => {
   });
 
   it(`throws an error when no 'altText' is provided`, () => {
-    const error = jest.fn();
-    makeWrapper({
-      propsData: { src: '/le-logo.svg', altText: undefined },
-      listeners: { error },
-    });
-    expect(error).toHaveBeenCalled();
-    expect(error.mock.calls[0][0]).toBeInstanceOf(Error);
-    expect(error.mock.calls[0][0].message).toBe(
-      'Missing required prop - provide altText or indicate isDecorative'
-    );
+    expect(() =>
+      makeWrapper({
+        propsData: { src: '/le-logo.svg', altText: undefined },
+      })
+    ).toThrow();
   });
 
   describe(`when no 'altText' is provided and it is a decorative image`, () => {
     it(`does not throw an error`, () => {
-      const error = jest.fn();
-      makeWrapper({
-        propsData: { src: '/le-logo.svg', altText: undefined, isDecorative: true },
-        listeners: { error },
-      });
-      expect(error).not.toHaveBeenCalled();
+      expect(() =>
+        makeWrapper({
+          propsData: { src: '/le-logo.svg', altText: undefined, isDecorative: true },
+        })
+      ).not.toThrow();
     });
 
     it(`sets 'alt' attribute to an empty string`, () => {
@@ -55,38 +46,32 @@ describe('KImg', () => {
   });
 
   it(`throws an error when 'aspectRatio' has an invalid format`, () => {
-    const error = jest.fn();
-    makeWrapper({
-      propsData: { src: '/le-logo.svg', altText: 'LE logo', aspectRatio: '16/9' },
-      listeners: { error },
-    });
-    expect(error).toHaveBeenCalled();
-    expect(error.mock.calls[0][0]).toBeInstanceOf(Error);
-    expect(error.mock.calls[0][0].message).toBe('Invalid aspect ratio provided: 16/9');
+    expect(() =>
+      makeWrapper({
+        propsData: { src: '/le-logo.svg', altText: 'LE logo', aspectRatio: '16/9' },
+      })
+    ).toThrow();
   });
 
   it(`doesn't throw an error when 'aspectRatio' has a valid format`, () => {
-    const error = jest.fn();
-    makeWrapper({
-      propsData: { src: '/le-logo.svg', altText: 'LE logo', aspectRatio: '16:9' },
-      listeners: { error },
-    });
-    expect(error).not.toHaveBeenCalled();
+    expect(() =>
+      makeWrapper({
+        propsData: { src: '/le-logo.svg', altText: 'LE logo', aspectRatio: '16:9' },
+      })
+    ).not.toThrow();
   });
 
-  it(`emits an 'error' event when there is an error in loading the image`, async () => {
-    const error = jest.fn();
+  it(`emits an 'error' event when there is an error in loading the image`, () => {
     const wrapper = makeWrapper({
       propsData: { src: '/le-logo.svg', altText: 'LE logo' },
-      listeners: { error },
     });
 
     // Manually trigger the onError method to simulate the image load failure
-    const e = new Event('error');
-    wrapper.vm.onError(e);
+    wrapper.vm.onError(new Event('error'));
 
-    expect(error).toHaveBeenCalled();
-    expect(error.mock.calls[0][0]).toBeInstanceOf(Event);
-    expect(error.mock.calls[0][0]).toEqual(e);
+    // Check if the "error" event has been emitted with the DOM event payload
+    const emittedEvent = wrapper.emitted().error;
+    expect(emittedEvent).toBeTruthy();
+    expect(emittedEvent[0][0]).toBeInstanceOf(Event);
   });
 });