Implementing and Updating Vitest Snapshot Tests

Desired Outcome

Run a Vitest test that asserts a component's rendered output matches a stored snapshot, and be able to update the snapshot safely when intentional changes occur.

Prerequisites

• Node.js ≥18 installed.
• Project with Vite and Vitest configured (e.g., npm init vite@latest my-app -- --template react-ts or similar).
• A UI component or function whose output you want to snapshot (e.g., a React component MyButton).

Procedure

1. Install Vitest if not present (run in project root):

   npm install --save-dev vitest
   

2. Add a test file next to the component, e.g., src/components/MyButton.test.tsx:

   import { render, screen } from '@testing-library/react';
   import MyButton from './MyButton';
   import { expect, test } from 'vitest';
   
   test('renders MyButton with default props', () => {
     render();
     const button = screen.getByRole('button');
     expect(button).toMatchSnapshot();
   });
   

3. Run Vitest in watch mode to generate the initial snapshot:

   npx vitest
   

   The command creates a __snapshots__ folder beside the test file and writes MyButton.test.tsx.snap containing the serialized button markup.
4. Verify the snapshot: open the generated .snap file and confirm the markup matches what you expect (e.g., includes the button text and any default classes).
5. Introduce an intentional change (e.g., add a new CSS class to the button in MyButton.tsx).
6. Run the test again:

   npx vitest
   

   You will see a failure indicating a snapshot mismatch, with a diff shown in the terminal.
7. Review the diff: ensure the change is only the added class and nothing else.
8. Update the snapshot (choose one):
   • Interactive: press u when Vitest prompts in watch mode.
   • Command line: run npx vitest --update (or npx vitest -u) to overwrite all stale snapshots.
9. Confirm the test passes after the update.
10. Optional: Add a custom serializer to trim whitespace or format complex objects. In vitest.config.ts:

    import { defineConfig } from 'vitest/config';
    
    export default defineConfig({
      test: {
        snapshotFormat: {
          // Example serializer that removes trailing spaces
          printBasicValue: value => String(value).replace(/\s+$/g, ''),
        },
      },
    });
    

    Then restart Vitest; new snapshots will use the formatter.

Expected Checks

• Test passes after initial snapshot creation.
• After a deliberate component change, the test fails and shows a clear diff.
• Running vitest --update resolves the failure and the test passes again.
• The __snapshots__ folder is tracked by your VCS (e.g., Git) and snapshots evolve with intentional changes.

Maintenance and CI Considerations

Snapshot files grow as tests evolve. Periodically run:

npx vitest --clean-snapshots

This removes snapshot files that no longer have a corresponding test. Verify the output list before committing.
In CI, execute Vitest in non‑interactive mode to treat snapshot mismatches as failures:
npx vitest --run

Ensure the __snapshots__ directory is checked into your repository so that all agents compare against the same baseline.
If you use parallel test execution (default in Vitest), each worker gets its own temporary snapshot cache; the final comparison is still serialized, so no extra configuration is required. Check the Vitest logs for lines like “snapshot: worker 1” to confirm isolation.

Recovery Options
If you accidentally update a snapshot that should not have changed:

Revert the snapshot file to its previous version using your VCS (e.g., git checkout HEAD -- src/components/__snapshots__/MyButton.test.tsx.snap).
Or run npx vitest --restore-snapshots if you have a backup copy.
Re‑run the test to confirm it now fails as expected, then re‑apply the intended component change and update the snapshot again.