cypress-snapshot-per-file-by-nikitin

Cypress snapshot plugin with automatic per-file snapshot organization

This package is a fork of @cypress/snapshot with enhanced functionality to automatically create separate snapshot files for each test file.

Features

• ✅ Automatic per-file snapshots: Each test file gets its own snapshot file automatically
• ✅ Organized in snapshots/ folder: All snapshot files are stored in a dedicated snapshots/ directory
• ✅ Auto-creation: Snapshot files are automatically created if they don't exist
• ✅ Backward compatible: Can be used like the original @cypress/snapshot package

Install

npm install --save-dev cypress-snapshot-per-file-by-nikitin

Setup

1. Add plugin task (required, one-time setup)

⚠️ Important: You need to manually add the readFileMaybe task to your cypress/plugins/index.js file. This is a one-time setup required for the package to work.

The package uses cy.task('readFileMaybe', ...) to read snapshot files. This task runs in Node.js context and can handle file system operations that Cypress commands cannot do directly.

If you don't have any tasks yet:

Add this to your cypress/plugins/index.js:

const fs = require('fs');
const path = require('path');

module.exports = (on, config) => {
  // ... your existing config code ...
  
  on('task', {
    readFileMaybe(filePath) {
      try {
        const fullPath = path.resolve(filePath);
        if (fs.existsSync(fullPath)) {
          return fs.readFileSync(fullPath, 'utf-8');
        }
        // File doesn't exist - create directory and file automatically
        const dir = path.dirname(fullPath);
        if (!fs.existsSync(dir)) {
          fs.mkdirSync(dir, { recursive: true });
        }
        fs.writeFileSync(fullPath, '{}\n', 'utf-8');
        return '{}\n';
      } catch (err) {
        return null;
      }
    }
  });
  
  return config;
};

If you already have tasks:

Add readFileMaybe to your existing on('task', {...}) object:

module.exports = (on, config) => {
  // ... your existing code ...
  
  on('task', {
    // ... your existing tasks ...
    
    readFileMaybe(filePath) {
      const fs = require('fs');
      const path = require('path');
      try {
        const fullPath = path.resolve(filePath);
        if (fs.existsSync(fullPath)) {
          return fs.readFileSync(fullPath, 'utf-8');
        }
        // File doesn't exist - create directory and file automatically
        const dir = path.dirname(fullPath);
        if (!fs.existsSync(dir)) {
          fs.mkdirSync(dir, { recursive: true });
        }
        fs.writeFileSync(fullPath, '{}\n', 'utf-8');
        return '{}\n';
      } catch (err) {
        return null;
      }
    }
  });
  
  return config;
};

Note: The task automatically creates the snapshot file and directory if they don't exist, so you don't need to create them manually.

2. Register the plugin

In your test files, register the plugin:

require('cypress-snapshot-per-file').register()

Or in cypress/support/commands.js:

require('cypress-snapshot-per-file').register()

Usage

describe('my tests', () => {
  it('works', () => {
    cy.wrap({ foo: 42 }).snapshot()
    cy.wrap({ bar: 101 }).snapshot()
  })
})

Configuration

You can configure the plugin via Cypress config:

// cypress.config.js
module.exports = defineConfig({
  // ... other config
  autoPerFile: true,        // Enable automatic per-file snapshots (default: true)
  snapshotsDir: 'snapshots', // Directory for snapshot files (default: 'snapshots')
  snapshotFileName: 'snapshots.js' // Only used if autoPerFile is false
})

How it works

• When autoPerFile: true (default), the plugin automatically:

  1. Detects the current test file name (e.g., 03_all_share_order_statuses_snapshot.cy.js)
  2. Creates a snapshot file named snapshots/03_all_share_order_statuses_snapshot.snap.js
  3. Automatically creates the file if it doesn't exist

• Each test file gets its own snapshot file, making it easy to:

  • Find snapshots for a specific test
  • Delete and regenerate snapshots for a single test
  • Organize and manage snapshots

License

MIT