Merge pull request #226 from haim-io/feat/screenshot-name-format

feat: screenshot name format

src/command.js

@@ -1,6 +1,7 @@
 import merge from 'lodash/merge'
 import { recurse } from 'cypress-recurse';
 import DEFAULT_CONFIG from './config.default'
+import { getFileName } from './utils.browser'
 
 const compareSnapshotCommand = () => {
   const userConfig = Cypress.env('cypressImageDiff') || DEFAULT_CONFIG
@@ -16,19 +17,34 @@ const compareSnapshotCommand = () => {
     'compareSnapshot',
     { prevSubject: 'optional' },
     (
-      subject, 
-      orignalOptions, 
+      subject,
+      orignalOptions,
     ) => {
       const {
-        name, 
+        name,
         testThreshold = userConfig.FAILURE_THRESHOLD,
         retryOptions = userConfig.RETRY_OPTIONS,
         exactName = false,
-        cypressScreenshotOptions
+        cypressScreenshotOptions,
+        nameTemplate = userConfig.NAME_TEMPLATE
       } = typeof orignalOptions === 'string' ? { name: orignalOptions } : orignalOptions
 
-      const specName = Cypress.spec.name
-      const testName = exactName ? name : `${specName.replace('.js', '')}${/^\//.test(name) ? '' : '-'}${name}`
+      // IN-QUEUE-FOR-BREAKING-CHANGE: Ternary condition here is to avoid a breaking change with the new option nameTemplate, will be simplified once we remove the exactName option
+      // eslint-disable-next-line no-nested-ternary
+      const testName = nameTemplate
+        ? getFileName({
+            nameTemplate,
+            givenName: name,
+            specName: Cypress.spec.name,
+            browserName: Cypress.browser.name,
+            width: Cypress.config('viewportWidth'),
+            height: Cypress.config('viewportHeight'),
+          })
+        : exactName
+        ? name
+        : `${Cypress.spec.name.replace('.js', '')}${
+            /^\//.test(name) ? '' : '-'
+          }${name}`
 
       const defaultRetryOptions = {
         limit: 1,
@@ -65,7 +81,7 @@ const compareSnapshotCommand = () => {
             specPath: Cypress.spec.relative,
             inlineAssets: userConfig.INLINE_ASSETS
           }
-          
+
           return cy.task('compareSnapshotsPlugin', options)
         },
         (percentage) => percentage <= testThreshold,

src/config.default.js

@@ -11,5 +11,7 @@ export default {
     OVERWRITE: true,
   },
   CYPRESS_SCREENSHOT_OPTIONS: {},
-  INLINE_ASSETS: false
-}
+  INLINE_ASSETS: false,
+  // IN-QUEUE-FOR-BREAKING-CHANGE: default NAME_TEMPLATE can be set until the next breaking change
+  // NAME_TEMPLATE: '[specName]-[givenName]'
+}

src/utils.browser.js

@@ -0,0 +1,22 @@
+/* eslint-disable import/prefer-default-export */
+const getFileName = ({
+    nameTemplate,
+    givenName,
+    specName,
+    browserName,
+    width,
+    height,
+  }) => {
+    return (
+      nameTemplate
+        .replace(/\[givenName\]/, givenName)
+        .replace(/\[specName\]/, specName.replace(/\.(js|jsx|ts|tsx)$/, ''))
+        .replace(/\[browserName\]/, browserName)
+        .replace(/\[width\]/, width)
+        .replace(/\[height\]/, height)
+        .replace(/[^a-z0-9_\-/.]/gi, '')
+    ) // remove anything that's not a letter, a number, a dash, an underscore or a dot.
+  }
+
+  export { getFileName }
+

src/utils.test.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, emptyDirSync, readdirSync, moveSync, copySync, writeFile } from 'fs-extra'
 import { createDir, cleanDir, renameAndMoveFile, renameAndCopyFile, getRelativePathFromCwd, getCleanDate, writeFileIncrement } from './utils'
+import { getFileName } from './utils.browser'
 
 jest.mock('fs-extra', () => ({
   ...jest.requireActual('fs-extra'),
@@ -131,4 +132,32 @@ describe('Utils', () => {
       expect(writeFile).toBeCalledWith(filenameIncremented, fakeData)
     })
   })
+
+  describe('getFileName', () => {
+    it('should replace placeholders correctly', () => {
+      const template = '[browserName]/[givenName]-[specName]-[width]x[height].js';
+      const result = getFileName({
+        nameTemplate: template,
+        givenName: 'test',
+        specName: 'example.spec.js',
+        browserName: 'chrome',
+        width: 1280,
+        height: 720
+      });
+      expect(result).toBe('chrome/test-example.spec-1280x720.js');
+    });
+
+    it('should remove special characters correctly', () => {
+      const template = '[givenName]-[specName]-[browserName]-[width]x[height].js';
+      const result = getFileName({
+        nameTemplate: template,
+        givenName: 'test$123',
+        specName: 'spec file.js',
+        browserName: 'safari',
+        width: 800,
+        height: 600
+      });
+      expect(result).toBe('test123-specfile-safari-800x600.js');
+    });
+  });
 })

types/options.d.ts

@@ -7,6 +7,14 @@ export interface CompareSnapshotOptions {
      * The name of the snapshots that will be generated
      */
     name: string
+    /**
+     * The snapshot naming pattern using replaceable labels. All possible labels are: specName, givenName, browserName, width and height. 
+     * All labels in square brackets are replaced with actual values during runtime.
+     * giveName is the name property above. 
+     * @default undefined
+     * @example '[browserName]/[specName]-[givenName].[width]x[height]'
+     */
+    nameTemplate?: string
     /**
      * A number between 0 and 1 that represents the allowed percentage of pixels that can be different between the two snapshots
      * @default 0