Local Testing Workflow

This guide covers the local development testing workflow for fast iteration and debugging.

Quick Start

# Terminal 1: Start your main app
npm run dev

# Terminal 2: Start Storybook
npm run storybook

# Terminal 3: Start unit tests in watch mode
npm run test:dev

# Optional: Install Playwright browsers (only needed for Storybook testing)
npx playwright install

# Terminal 4: Test Storybook against running server (requires Playwright)
npm run test:storybook:running

Testing Scripts Overview

Unit Tests (Fast)

Command	Description	Use Case
npm run test:unit:watch	Watch mode for unit tests	Development
npm run test:unit	Run unit tests once	CI/verification
npm run test:ui	Interactive test UI	Debugging
npm run test:coverage	Run with coverage	Local verification
npm run test	Run all tests once	Quick verification

Storybook Tests (Comprehensive)

Command	Description	Use Case
npm run test:storybook	Interactive mode with Storybook UI	Development
npm run test-storybook	Run once (headless)	CI/verification
npm run test:storybook:watch	Watch mode for stories	Storybook development
npm run test:storybook:running	Test against live server	Manual testing

Combined Workflows

Command	Description	Use Case
npm run test:all	Unit + Storybook tests	Full verification
npm run test:dev	Alias for unit watch mode	Development

Development Workflows

1. Component Development Flow

# Terminal 1: Start your main app
npm run dev

# Terminal 2: Start Storybook
npm run storybook

# Terminal 3: Start tests in watch mode
npm run test:dev

# Terminal 4: Run Storybook tests (when needed)
npm run test:storybook:running

2. Test-Driven Development

# Run specific test file while developing
npm run test:file src/components/tooltip/tooltip.spec.tsx

# Or test by pattern
npm run test -- --testNamePattern="tooltip"

3. Pre-Commit Workflow

# Quick verification before committing
npm run test:unit && npm run lint

# Full test suite
npm run test:all

4. Debugging Failing Tests

# Use the interactive UI for debugging
npm run test:ui

# Run with verbose output
npm run test:file src/path/to/failing.spec.ts

Local vs CI Testing

Local Development (Fast Iteration)

• Unit Tests: Run in Node.js with jsdom (fast)
• Storybook: Build static + serve locally
• Focus: Quick feedback, debugging, component development

CI Testing (Production-Like)

• Unit Tests: Docker Alpine container
• Storybook: Docker Playwright container
• Focus: Production environment simulation, comprehensive coverage

File Structure

src/
├── components/
│   └── tooltip/
│       ├── tooltip.tsx           # Component
│       ├── tooltip.spec.tsx      # Unit tests
│       └── tooltip.stories.tsx   # Storybook tests
├── utils/
│   └── format/
│       ├── formatDate.ts         # Utility
│       └── formatDate.spec.ts    # Unit tests
└── test/
    └── test-utils.tsx            # Shared test utilities

Test Types & When to Use

Unit Tests (.spec.ts/.spec.tsx)

✅ Use for:

• Pure functions
• Component logic
• Data transformations
• Edge cases
• Fast feedback loops

# Watch specific component tests
npm run test -- src/components/tooltip

Storybook Tests (.stories.tsx)

✅ Use for:

• Visual regression
• Accessibility testing
• Component interactions
• Integration scenarios
• Cross-browser testing

# Test specific story
npm run test:storybook -- --testNamePattern="Tooltip"

Debugging Tips

Unit Test Debugging

// Add debug info to failing tests
import { screen, debug } from '@testing-library/solid';

it('should render correctly', () => {
  render(() => <Tooltip content="Test" />);

  // Debug the DOM when tests fail
  debug();

  expect(screen.getByText('Test')).toBeInTheDocument();
});

Storybook Test Debugging

# Run Storybook tests with browser visible
npm run test:storybook -- --no-headless

# Debug specific accessibility failures
npm run test:storybook -- --testNamePattern="a11y" --verbose

VS Code Integration

Add to your .vscode/launch.json:

{
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Unit Tests",
      "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
      "args": ["run", "--reporter=verbose"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

Performance Optimization

Speed Up Unit Tests

# Skip coverage for faster feedback
npm run test:dev

# Run only changed files
npm run test:changed

# Test specific patterns
npm run test -- --testNamePattern="utils"

Speed Up Storybook Tests

# Keep Storybook dev server running
# Terminal 1:
npm run storybook

# Terminal 2:
npm run test:storybook:watch

Common Issues & Solutions

”Playwright not found” (Only for Storybook testing)

npx playwright install

Note: This is only needed if you want to run Storybook accessibility tests locally. Unit tests don’t require Playwright.

”Port 6006 already in use"

# Kill existing Storybook
pkill -f "storybook"
# Or use different port
npm run storybook -- --port 6007

"Tests timing out"

# Increase timeout for slow tests
npm run test -- --testTimeout=10000

"Coverage reports not generated”

# Clean and regenerate
rm -rf coverage/
npm run test:coverage

Integration with Git Hooks

Add to .husky/pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Run quick tests before commit
npm run test:unit && npm run lint

Best Practices

1. Use watch mode during development for instant feedback
2. Start with unit tests for component logic
3. Add Storybook tests for interactions and accessibility
4. Run full test suite before pushing
5. Debug with test UI when tests fail
6. Keep tests close to code for easy maintenance