customSnapshotIdentifier option is defined in types but not implemented in plugin

[reergymerej]

customSnapshotIdentifier option is defined in types but not implemented in plugin

Summary

The TypeScript definitions for cypress-image-snapshot include a customSnapshotIdentifier option that appears to allow customization of snapshot naming/path generation, but this option is completely ignored by the actual plugin implementation. This creates a misleading API where developers can configure an option that has no effect.

Expected Behavior

Based on the TypeScript definitions in @types/cypress-image-snapshot/index.d.ts, the customSnapshotIdentifier option should allow customization of snapshot paths:

/**
 * A custom name to give this snapshot. If not provided, one is computed automatically. When a function is provided
 * it is called with an object containing testPath, currentTestName, counter and defaultIdentifier as its first
 * argument. The function must return an identifier to use for the snapshot.
 */
customSnapshotIdentifier?:
    | ((parameters: {
        testPath: string;
        currentTestName: string;
        counter: number;
        defaultIdentifier: string;
    }) => string)
    | string
    | undefined;

Actual Behavior

The option is completely ignored. In plugin.js, the snapshotIdentifier is hardcoded as:

// remove the cypress v5+ native retries suffix from the file name
const snapshotIdentifier = name.replace(/ \(attempt [0-9]+\)/, '');

There is no code anywhere in the plugin that checks for or uses a customSnapshotIdentifier option.

Steps to Reproduce

1. Configure customSnapshotIdentifier in cypress.config.ts:

addMatchImageSnapshotPlugin(on, {
  ...config,
  customSnapshotIdentifier: ({ defaultIdentifier }) => {
    console.log('customSnapshotIdentifier called');
    return 'custom-name';
  }
});

2. Run a test with cy.matchImageSnapshot()
3. Observe that:
   • The console.log never fires
   • Snapshot paths are generated using the default logic, ignoring the custom function

Root Cause

The TypeScript definitions appear to be copied from jest-image-snapshot or another library that does implement this feature, but cypress-image-snapshot never implemented it. The only options that are actually used are:

• failureThreshold
• failureThresholdType
• customSnapshotsDir
• customDiffDir

Impact

This creates a particularly problematic inconsistency between Cypress CLI and GUI modes:

• CLI mode creates snapshots in nested directories: ./cypress/snapshots/SpecFile.cy.tsx/snapshot-name.snap.png
• GUI mode creates flat snapshots: ./cypress/snapshots/snapshot-name.snap.png

Developers cannot resolve this path inconsistency because the API that should allow path customization doesn't actually work.

Suggested Solution

Either:

1. Implement the feature - Add support for customSnapshotIdentifier in the plugin to match the TypeScript definitions
2. Fix the types - Remove customSnapshotIdentifier from the TypeScript definitions and document the actual supported options
3. Document the limitation - Clearly state in the README that path customization is not supported and explain the CLI/GUI inconsistency

Environment

• cypress-image-snapshot: 4.0.1
• @types/cypress-image-snapshot: (latest)
• Cypress: 13.17.0

Additional Context

This issue makes visual regression testing unreliable in CI/CD pipelines where both CLI and GUI modes might be used, as the snapshot paths don't match between execution modes.