Snapshot Testing Pattern | Bootspring Docs

Use snapshot testing effectively for UI components, data structures, and generated output with Vitest inline and file snapshots.

Overview#

Snapshot testing captures the output of code and compares it against a stored reference. It's useful for detecting unintended changes to UI components and data transformations.

When to use:

Testing component render output
Verifying serialized data structures
Testing generated code or configurations
Catching unintended UI changes

Key features:

Automatic snapshot creation
Inline and file-based snapshots
Property matchers for dynamic values
Easy snapshot updates

Code Example#

Basic Snapshot#

// tests/components/Button.test.tsx
import { render } from '@testing-library/react'
import { expect, it } from 'vitest'
import { Button } from '@/components/ui/Button'

it('renders correctly', () => {
  const { container } = render(<Button>Click me</Button>)
  expect(container).toMatchSnapshot()
})

it('renders loading state', () => {
  const { container } = render(<Button loading>Submit</Button>)
  expect(container).toMatchSnapshot()
})

it('renders disabled state', () => {
  const { container } = render(<Button disabled>Disabled</Button>)
  expect(container).toMatchSnapshot()
})

Inline Snapshots#

// More readable for small outputs
import { expect, it } from 'vitest'
import { formatCurrency, formatDate, getDisplayName } from '@/lib/utils'

it('formats currency', () => {
  expect(formatCurrency(1234.56)).toMatchInlineSnapshot(`"$1,234.56"`)
})

it('formats date', () => {
  expect(formatDate(new Date('2024-01-15'))).toMatchInlineSnapshot(
    `"January 15, 2024"`
  )
})

it('generates user display name', () => {
  expect(getDisplayName({ firstName: 'John', lastName: 'Doe' }))
    .toMatchInlineSnapshot(`"John Doe"`)
})

Object Snapshots#

// Snapshot complex objects
import { expect, it } from 'vitest'
import { transformResponse, buildConfig } from '@/lib/api'

it('transforms API response', () => {
  const response = {
    id: '123',
    created_at: '2024-01-01T00:00:00Z',
    user_name: 'johndoe',
    is_active: true
  }

  expect(transformResponse(response)).toMatchInlineSnapshot(`
    {
      "id": "123",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "userName": "johndoe",
      "isActive": true
    }
  `)
})

it('builds configuration object', () => {
  const config = buildConfig({
    name: 'my-app',
    features: ['auth', 'api']
  })

  expect(config).toMatchInlineSnapshot(`
    {
      "name": "my-app",
      "features": [
        "auth",
        "api"
      ],
      "version": "1.0.0",
      "debug": false
    }
  `)
})

Property Matchers#

// Ignore dynamic values
import { expect, it } from 'vitest'

it('creates user with generated id', async () => {
  const user = await createUser({ email: 'test@example.com' })

  expect(user).toMatchSnapshot({
    id: expect.any(String),
    createdAt: expect.any(Date)
  })
})

it('generates order with timestamp', () => {
  const order = createOrder({ items: [{ id: '1', quantity: 2 }] })

  expect(order).toMatchSnapshot({
    id: expect.stringMatching(/^order_/),
    createdAt: expect.any(Date),
    updatedAt: expect.any(Date),
    items: [
      {
        id: '1',
        quantity: 2,
        addedAt: expect.any(Date)
      }
    ]
  })
})

// Snapshot with asymmetric matchers
it('returns paginated response', async () => {
  const response = await fetchUsers({ page: 1, limit: 10 })

  expect(response).toMatchSnapshot({
    data: expect.arrayContaining([
      expect.objectContaining({
        id: expect.any(String),
        email: expect.stringMatching(/@/),
        createdAt: expect.any(String)
      })
    ]),
    pagination: {
      page: 1,
      limit: 10,
      total: expect.any(Number),
      totalPages: expect.any(Number)
    }
  })
})

File Snapshots#

// Large output to separate files
import { expect, it } from 'vitest'

it('generates config file', () => {
  const config = generateConfig({
    name: 'my-app',
    features: ['auth', 'api', 'db']
  })

  expect(config).toMatchFileSnapshot('./snapshots/config.json')
})

it('generates schema', () => {
  const schema = generateSchema(models)
  expect(schema).toMatchFileSnapshot('./snapshots/schema.graphql')
})

Custom Serializers#

// vitest.config.ts
export default defineConfig({
  test: {
    snapshotSerializers: ['./tests/serializers/date.ts']
  }
})

// tests/serializers/date.ts
export const serialize = (val: Date) => `Date<${val.toISOString()}>`
export const test = (val: unknown) => val instanceof Date

// Output in snapshots:
// Date<2024-01-01T00:00:00.000Z>

// Custom component serializer
// tests/serializers/component.ts
export const serialize = (val: React.ReactElement) => {
  // Custom serialization logic
  return prettyPrint(val)
}

export const test = (val: unknown) => {
  return val && typeof val === 'object' && '$$typeof' in val
}

Component Variant Snapshots#

// Snapshot multiple variants
import { render } from '@testing-library/react'
import { describe, it, expect } from 'vitest'
import { Button } from '@/components/ui/Button'

describe('Button', () => {
  const variants = ['primary', 'secondary', 'danger', 'ghost'] as const
  const sizes = ['sm', 'md', 'lg'] as const

  // Test all variant and size combinations
  variants.forEach(variant => {
    sizes.forEach(size => {
      it(`renders ${variant} ${size}`, () => {
        const { container } = render(
          <Button variant={variant} size={size}>
            Button
          </Button>
        )
        expect(container.firstChild).toMatchSnapshot()
      })
    })
  })

  // Test with different states
  const states = [
    { disabled: true },
    { loading: true },
    { disabled: false, loading: false }
  ]

  states.forEach(state => {
    it(`renders with state ${JSON.stringify(state)}`, () => {
      const { container } = render(
        <Button {...state}>Button</Button>
      )
      expect(container.firstChild).toMatchSnapshot()
    })
  })
})

Update Snapshots#

# Update all snapshots
npm test -- --update

# Update specific test file snapshots
npm test -- Button.test.tsx --update

# Interactive update (choose which to update)
npm test -- --watch
# Then press 'u' to update

# Update only failing snapshots
npm test -- --update --reporter=verbose

Snapshot Best Practices Examples#

// DON'T: Snapshot too much
it('renders page', () => {
  const { container } = render(<ComplexPage />)
  expect(container).toMatchSnapshot() // Too large, hard to review
})

// DO: Snapshot specific elements
it('renders header correctly', () => {
  render(<ComplexPage />)
  expect(screen.getByRole('banner')).toMatchSnapshot()
})

// DO: Use inline snapshots for small outputs
it('formats date', () => {
  expect(formatDate(new Date('2024-01-15')))
    .toMatchInlineSnapshot(`"January 15, 2024"`)
})

// DON'T: Include dynamic data
it('renders user', () => {
  const { container } = render(<User id={Math.random()} />)
  expect(container).toMatchSnapshot() // Will always fail
})

// DO: Use stable test data
it('renders user', () => {
  const { container } = render(
    <User
      id="test-id"
      createdAt={new Date('2024-01-01')}
    />
  )
  expect(container).toMatchSnapshot()
})

// DON'T: Snapshot implementation details
it('has correct state', () => {
  const { result } = renderHook(() => useCounter())
  expect(result.current).toMatchSnapshot() // Internal state
})

// DO: Snapshot observable behavior
it('renders correct count', () => {
  render(<Counter initialCount={5} />)
  expect(screen.getByRole('spinbutton')).toMatchSnapshot()
})

Snapshot Testing Strategy#

// Use snapshots for UI regression
describe('Card component', () => {
  it('matches snapshot', () => {
    const { container } = render(
      <Card
        title="Test Card"
        description="Test description"
        image="/test.jpg"
      />
    )
    expect(container).toMatchSnapshot()
  })
})

// Use regular assertions for behavior
describe('Card component behavior', () => {
  it('calls onClick when clicked', () => {
    const onClick = vi.fn()
    render(<Card onClick={onClick} />)

    fireEvent.click(screen.getByRole('article'))
    expect(onClick).toHaveBeenCalled()
  })

  it('renders image with alt text', () => {
    render(<Card image="/test.jpg" imageAlt="Test image" />)
    expect(screen.getByAltText('Test image')).toBeInTheDocument()
  })
})

Usage Instructions#

Write test with toMatchSnapshot(): Vitest creates snapshot on first run
Review snapshot files: Verify the captured output is correct
Commit snapshots: Include snapshot files in version control
Update when needed: Run with --update flag after intentional changes
Review in PRs: Check snapshot changes carefully during code review

Best Practices#

Keep snapshots small - Snapshot specific elements, not entire pages
Use inline for small outputs - More readable in the test file
Use property matchers - Handle dynamic values like IDs and dates
Review snapshot changes - Don't blindly update failing snapshots
Complement with assertions - Use snapshots alongside behavior tests
Avoid snapshots for logic - Test business logic with assertions
Commit snapshots - They're part of your test suite

Vitest - Test runner setup
Component Testing - Component testing
Unit Testing - Unit testing patterns
Coverage - Code coverage setup