Unit Testing Pattern | Bootspring Docs

Write effective unit tests for utility functions, services, and business logic with Vitest, including edge cases and error handling.

Overview#

Unit tests verify individual functions and modules in isolation. They're the foundation of a testing strategy, providing fast feedback and ensuring code correctness at the smallest level.

When to use:

Testing pure utility functions
Validating business logic
Testing data transformations
Verifying error handling

Key features:

Fast execution
Isolated from dependencies
Easy to write and maintain
High coverage potential

Code Example#

Testing Pure Functions#

// lib/utils.test.ts
import { describe, it, expect } from 'vitest'
import {
  formatCurrency,
  slugify,
  truncate,
  calculateTax,
  parseQueryString
} from './utils'

describe('formatCurrency', () => {
  it('formats positive amounts', () => {
    expect(formatCurrency(1234.56)).toBe('$1,234.56')
    expect(formatCurrency(0.99)).toBe('$0.99')
  })

  it('handles zero', () => {
    expect(formatCurrency(0)).toBe('$0.00')
  })

  it('formats negative amounts', () => {
    expect(formatCurrency(-50)).toBe('-$50.00')
  })

  it('handles different currencies', () => {
    expect(formatCurrency(100, 'EUR')).toBe('100.00 EUR')
    expect(formatCurrency(100, 'GBP')).toBe('100.00 GBP')
  })

  it('rounds to 2 decimal places', () => {
    expect(formatCurrency(10.999)).toBe('$11.00')
    expect(formatCurrency(10.994)).toBe('$10.99')
  })
})

describe('slugify', () => {
  it('converts to lowercase', () => {
    expect(slugify('Hello World')).toBe('hello-world')
  })

  it('replaces spaces with hyphens', () => {
    expect(slugify('foo bar baz')).toBe('foo-bar-baz')
  })

  it('removes special characters', () => {
    expect(slugify('Hello! World?')).toBe('hello-world')
  })

  it('handles multiple spaces', () => {
    expect(slugify('hello   world')).toBe('hello-world')
  })

  it('handles empty strings', () => {
    expect(slugify('')).toBe('')
  })

  it('handles unicode characters', () => {
    expect(slugify('caf\u00e9')).toBe('cafe')
  })
})

describe('truncate', () => {
  it('truncates long strings', () => {
    expect(truncate('hello world', 5)).toBe('hello...')
  })

  it('does not truncate short strings', () => {
    expect(truncate('hello', 10)).toBe('hello')
  })

  it('uses custom suffix', () => {
    expect(truncate('hello world', 5, '>')).toBe('hello>')
  })

  it('handles exact length', () => {
    expect(truncate('hello', 5)).toBe('hello')
  })
})

Testing Validation Functions#

// lib/validation.test.ts
import { describe, it, expect } from 'vitest'
import {
  isValidEmail,
  isValidPassword,
  isValidUrl,
  isValidPhone
} from './validation'

describe('isValidEmail', () => {
  const validEmails = [
    'user@example.com',
    'user.name@example.com',
    'user+tag@example.co.uk',
    'user@subdomain.example.com'
  ]

  const invalidEmails = [
    'invalid',
    '@example.com',
    'user@',
    'user@.com',
    'user@example',
    '',
    null,
    undefined
  ]

  it.each(validEmails)('accepts valid email: %s', (email) => {
    expect(isValidEmail(email)).toBe(true)
  })

  it.each(invalidEmails)('rejects invalid email: %s', (email) => {
    expect(isValidEmail(email as string)).toBe(false)
  })
})

describe('isValidPassword', () => {
  it('requires minimum length', () => {
    expect(isValidPassword('short')).toBe(false)
    expect(isValidPassword('longenough123')).toBe(true)
  })

  it('requires at least one number', () => {
    expect(isValidPassword('NoNumbers!')).toBe(false)
    expect(isValidPassword('HasNumber1')).toBe(true)
  })

  it('requires at least one uppercase', () => {
    expect(isValidPassword('alllowercase1')).toBe(false)
    expect(isValidPassword('HasUppercase1')).toBe(true)
  })

  it('returns validation errors', () => {
    const result = isValidPassword('weak', { returnErrors: true })
    expect(result.valid).toBe(false)
    expect(result.errors).toContain('Password must be at least 8 characters')
  })
})

Testing Business Logic#

// lib/pricing.test.ts
import { describe, it, expect } from 'vitest'
import {
  calculateSubtotal,
  calculateDiscount,
  calculateTax,
  calculateTotal
} from './pricing'

describe('calculateSubtotal', () => {
  it('sums item prices', () => {
    const items = [
      { price: 10, quantity: 2 },
      { price: 5, quantity: 3 }
    ]
    expect(calculateSubtotal(items)).toBe(35)
  })

  it('handles empty cart', () => {
    expect(calculateSubtotal([])).toBe(0)
  })

  it('handles single item', () => {
    expect(calculateSubtotal([{ price: 25, quantity: 1 }])).toBe(25)
  })
})

describe('calculateDiscount', () => {
  it('applies percentage discount', () => {
    expect(calculateDiscount(100, { type: 'percentage', value: 10 })).toBe(10)
  })

  it('applies fixed discount', () => {
    expect(calculateDiscount(100, { type: 'fixed', value: 15 })).toBe(15)
  })

  it('caps discount at subtotal', () => {
    expect(calculateDiscount(50, { type: 'fixed', value: 100 })).toBe(50)
  })

  it('handles zero discount', () => {
    expect(calculateDiscount(100, { type: 'percentage', value: 0 })).toBe(0)
  })
})

describe('calculateTax', () => {
  it('calculates tax rate', () => {
    expect(calculateTax(100, 0.08)).toBe(8)
  })

  it('rounds to 2 decimal places', () => {
    expect(calculateTax(10.5, 0.07)).toBe(0.74) // 0.735 rounded
  })

  it('handles tax-exempt items', () => {
    expect(calculateTax(100, 0)).toBe(0)
  })
})

describe('calculateTotal', () => {
  it('combines subtotal, discount, and tax', () => {
    const result = calculateTotal({
      items: [{ price: 100, quantity: 1 }],
      discount: { type: 'percentage', value: 10 },
      taxRate: 0.08
    })

    expect(result.subtotal).toBe(100)
    expect(result.discount).toBe(10)
    expect(result.tax).toBe(7.2) // (100 - 10) * 0.08
    expect(result.total).toBe(97.2) // 100 - 10 + 7.2
  })
})

Testing Error Handling#

// lib/api-client.test.ts
import { describe, it, expect, vi } from 'vitest'
import { fetchData, parseResponse, handleApiError } from './api-client'

describe('fetchData', () => {
  it('throws on network error', async () => {
    global.fetch = vi.fn().mockRejectedValue(new Error('Network error'))

    await expect(fetchData('/api/data')).rejects.toThrow('Network error')
  })

  it('throws on non-ok response', async () => {
    global.fetch = vi.fn().mockResolvedValue({
      ok: false,
      status: 404,
      json: () => Promise.resolve({ error: 'Not found' })
    })

    await expect(fetchData('/api/data')).rejects.toThrow('Not found')
  })
})

describe('parseResponse', () => {
  it('parses valid JSON', () => {
    expect(parseResponse('{"name":"test"}')).toEqual({ name: 'test' })
  })

  it('throws on invalid JSON', () => {
    expect(() => parseResponse('invalid')).toThrow('Invalid JSON response')
  })

  it('handles empty response', () => {
    expect(parseResponse('')).toBeNull()
  })
})

describe('handleApiError', () => {
  it('extracts error message from response', () => {
    const error = handleApiError({
      status: 400,
      body: { error: { message: 'Bad request' } }
    })
    expect(error.message).toBe('Bad request')
    expect(error.code).toBe('BAD_REQUEST')
  })

  it('provides default message for unknown errors', () => {
    const error = handleApiError({ status: 500, body: {} })
    expect(error.message).toBe('An unexpected error occurred')
  })
})

Testing with Test Data#

// lib/user.test.ts
import { describe, it, expect } from 'vitest'
import { formatUserName, getUserInitials, isAdmin } from './user'

// Test fixtures
const users = {
  standard: {
    id: '1',
    firstName: 'John',
    lastName: 'Doe',
    email: 'john@example.com',
    role: 'user'
  },
  admin: {
    id: '2',
    firstName: 'Jane',
    lastName: 'Smith',
    email: 'jane@example.com',
    role: 'admin'
  },
  noLastName: {
    id: '3',
    firstName: 'Alice',
    lastName: '',
    email: 'alice@example.com',
    role: 'user'
  }
}

describe('formatUserName', () => {
  it('formats full name', () => {
    expect(formatUserName(users.standard)).toBe('John Doe')
  })

  it('handles missing last name', () => {
    expect(formatUserName(users.noLastName)).toBe('Alice')
  })

  it('formats with reversed order', () => {
    expect(formatUserName(users.standard, { reverse: true })).toBe('Doe, John')
  })
})

describe('getUserInitials', () => {
  it('returns initials from full name', () => {
    expect(getUserInitials(users.standard)).toBe('JD')
  })

  it('handles single name', () => {
    expect(getUserInitials(users.noLastName)).toBe('A')
  })
})

describe('isAdmin', () => {
  it('returns true for admin users', () => {
    expect(isAdmin(users.admin)).toBe(true)
  })

  it('returns false for regular users', () => {
    expect(isAdmin(users.standard)).toBe(false)
  })
})

Usage Instructions#

Identify testable units: Find pure functions and isolated logic
Write descriptive tests: Use clear test names that describe behavior
Cover edge cases: Test boundaries, null values, and errors
Use test fixtures: Create reusable test data
Group related tests: Organize with describe blocks

Best Practices#

Test one thing per test - Each test should verify a single behavior
Use descriptive names - Test names should describe expected behavior
Arrange-Act-Assert - Structure tests clearly with setup, action, verification
Test edge cases - Empty arrays, null values, boundaries
Keep tests independent - Tests should not depend on each other
Avoid testing implementation - Test behavior, not internal details
Use parameterized tests - Use it.each for multiple inputs

Vitest - Vitest configuration
Mocking - Mocking dependencies
Fixtures - Test data management
Coverage - Code coverage setup