Testing Guide
LobeHub's testing strategy includes unit testing with Vitest and end-to-end (E2E) testing with Playwright + Cucumber. This guide covers how to write and run tests effectively.
Overview
Our testing strategy includes:
- Unit Tests — Vitest for functions, components, and stores
- E2E Tests — Playwright + Cucumber for user flows
- Type Checking — TypeScript compiler (
bun run type-check) - Linting — ESLint, Stylelint
Quick Reference
Commands
Never run the full test suite with bun run test — it runs all tests and takes ~10 minutes.
Always target a specific file with bunx vitest run --silent='passed-only' '[file-path]'.
Unit Testing with Vitest
Test File Structure
Create test files alongside the code being tested, named <filename>.test.ts:
Writing Test Cases
Use describe and it to organize test cases. Use beforeEach/afterEach to manage setup and teardown:
Testing React Components
Use @testing-library/react to test component behavior:
Testing Zustand Stores
Reset store state in beforeEach to keep tests independent:
Mocking
Prefer vi.spyOn Over vi.mock
Mock Browser APIs
Mock Modules
Testing Async Code
Testing Database Code
For database and ORM tests in packages:
E2E Testing with Playwright
Running E2E Tests
E2E Test Structure
E2E tests live in the e2e/ directory:
Writing E2E Tests
Feature file (e2e/features/chat.feature):
Step definitions (e2e/step-definitions/chat.steps.ts):
Best Practices
1. Test Behavior, Not Implementation
2. Use Semantic Queries
3. Clean Up After Each Test
4. Test Edge Cases
5. Keep Tests Independent
Common Patterns
Testing Hooks
Testing Context Providers
Coverage
Generate Coverage Report
bun run test-app:coverageThen open coverage/index.html to view the report.
Coverage Goals
| Area | Target |
|---|---|
| Critical paths | 80%+ |
| Utilities | 90%+ |
| UI components | 70%+ |
Debugging Tests
VS Code Debugging
Add to .vscode/launch.json:
Vitest UI
bunx vitest --uiOpens an interactive test explorer in the browser.
Console Logging
CI/CD Integration
GitHub Actions automatically runs on every PR:
- Linting (ESLint, Stylelint)
- Type checking
- Unit tests
- E2E tests
- Build verification
All checks must pass before a PR can merge.