LobeHub Testing Guide
Quick Reference
Commands:
# Run specific test file
bunx vitest run --silent='passed-only' '[file-path]'
# Database package (client)
cd packages/database && bunx vitest run --silent='passed-only' '[file]'
# Database package (server)
cd packages/database && TEST_SERVER_DB=1 bunx vitest run --silent='passed-only' '[file]'
Never run bun run test - it runs all 3000+ tests (~10 minutes).
Test Categories
| Category |
Location |
Config |
| Webapp |
src/**/*.test.ts(x) |
vitest.config.ts |
| Packages |
packages/*/**/*.test.ts |
packages/*/vitest.config.ts |
| Desktop |
apps/desktop/**/*.test.ts |
apps/desktop/vitest.config.ts |
Core Principles
- Prefer
vi.spyOn over vi.mock - More targeted, easier to maintain
- Tests must pass type check - Run
bun run type-check after writing tests
- After 1-2 failed fix attempts, stop and ask for help
- Test behavior, not implementation details
Basic Test Structure
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
beforeEach(() => {
vi.clearAllMocks();
});
afterEach(() => {
vi.restoreAllMocks();
});
describe('ModuleName', () => {
describe('functionName', () => {
it('should handle normal case', () => {
// Arrange → Act → Assert
});
});
});
Mock Patterns
// ✅ Spy on direct dependencies
vi.spyOn(messageService, 'createMessage').mockResolvedValue('id');
// ✅ Use vi.stubGlobal for browser APIs
vi.stubGlobal('Image', mockImage);
vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock');
// ❌ Avoid mocking entire modules globally
vi.mock('@/services/chat'); // Too broad
Detailed Guides
See references/ for specific testing scenarios:
- Database Model testing:
references/db-model-test.md
- Electron IPC testing:
references/electron-ipc-test.md
- Zustand Store Action testing:
references/zustand-store-action-test.md
- Agent Runtime E2E testing:
references/agent-runtime-e2e.md
- Desktop Controller testing:
references/desktop-controller-test.md
Fixing Failing Tests — Optimize or Delete?
When tests fail due to implementation changes (not bugs), evaluate before blindly fixing:
Keep & Fix (update test data/assertions)
- Behavior tests: Tests that verify what the code does (output, side effects, user-visible behavior). Just update mock data formats or expected values.
- Example: Tool data structure changed from
{ name } to { function: { name } } → update mock data
- Example: Output format changed from
Current date: YYYY-MM-DD to Current date: YYYY-MM-DD (TZ) → update expected string
Delete (over-specified, low value)
- Param-forwarding tests: Tests that assert exact internal function call arguments (e.g.,
expect(internalFn).toHaveBeenCalledWith(expect.objectContaining({ exact params }))) — these break on every refactor and duplicate what behavior tests already cover.
- Implementation-coupled tests: Tests that verify how the code works internally rather than what it produces. If a higher-level test already covers the same behavior, the low-level test adds maintenance cost without coverage gain.
Decision Checklist
- Does the test verify externally observable behavior (API response, DB write, rendered output)? → Keep
- Does the test only verify internal wiring (which function receives which params)? → Check if a behavior test already covers it. If yes → Delete
- Is the same behavior already tested at a higher integration level? → Delete the lower-level duplicate
- Would the test break again on the next routine refactor? → Consider raising to integration level or deleting
When Writing New Tests
- Prefer integration-level assertions (verify final output) over white-box assertions (verify internal calls)
- Use
expect.objectContaining only for stable, public-facing contracts — not for internal param shapes that change with refactors
- Mock at boundaries (DB, network, external services), not between internal modules
Common Issues
- Module pollution: Use
vi.resetModules() when tests fail mysteriously
- Mock not working: Check setup position and use
vi.clearAllMocks() in beforeEach
- Test data pollution: Clean database state in beforeEach/afterEach
- Async issues: Wrap state changes in
act() for React hooks
Converted and distributed by TomeVault | Claim this content
1---2name: testing-23description: Testing guide using Vitest. Use when writing tests (.test.ts, .test.tsx), fixing failing tests, improving test coverage, or debugging test issues. Triggers on test creation, test debugging, mock setup, or test-related questions.4metadata:5 source: https://skillmd.com/skills/mahabdalla/testing-26---78# LobeHub Testing Guide910## Quick Reference1112**Commands:**1314```bash15# Run specific test file16bunx vitest run --silent='passed-only' '[file-path]'1718# Database package (client)19cd packages/database && bunx vitest run --silent='passed-only' '[file]'2021# Database package (server)22cd packages/database && TEST_SERVER_DB=1 bunx vitest run --silent='passed-only' '[file]'23```2425**Never run** `bun run test` - it runs all 3000+ tests (\~10 minutes).2627## Test Categories2829| Category | Location | Config |30| -------- | --------------------------- | ------------------------------- |31| Webapp | `src/**/*.test.ts(x)` | `vitest.config.ts` |32| Packages | `packages/*/**/*.test.ts` | `packages/*/vitest.config.ts` |33| Desktop | `apps/desktop/**/*.test.ts` | `apps/desktop/vitest.config.ts` |3435## Core Principles36371. **Prefer `vi.spyOn` over `vi.mock`** - More targeted, easier to maintain382. **Tests must pass type check** - Run `bun run type-check` after writing tests393. **After 1-2 failed fix attempts, stop and ask for help**404. **Test behavior, not implementation details**4142## Basic Test Structure4344```typescript45import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';4647beforeEach(() => {48 vi.clearAllMocks();49});5051afterEach(() => {52 vi.restoreAllMocks();53});5455describe('ModuleName', () => {56 describe('functionName', () => {57 it('should handle normal case', () => {58 // Arrange → Act → Assert59 });60 });61});62```6364## Mock Patterns6566```typescript67// ✅ Spy on direct dependencies68vi.spyOn(messageService, 'createMessage').mockResolvedValue('id');6970// ✅ Use vi.stubGlobal for browser APIs71vi.stubGlobal('Image', mockImage);72vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock');7374// ❌ Avoid mocking entire modules globally75vi.mock('@/services/chat'); // Too broad76```7778## Detailed Guides7980See `references/` for specific testing scenarios:8182- **Database Model testing**: `references/db-model-test.md`83- **Electron IPC testing**: `references/electron-ipc-test.md`84- **Zustand Store Action testing**: `references/zustand-store-action-test.md`85- **Agent Runtime E2E testing**: `references/agent-runtime-e2e.md`86- **Desktop Controller testing**: `references/desktop-controller-test.md`8788## Fixing Failing Tests — Optimize or Delete?8990When tests fail due to implementation changes (not bugs), evaluate before blindly fixing:9192### Keep & Fix (update test data/assertions)9394- **Behavior tests**: Tests that verify _what_ the code does (output, side effects, user-visible behavior). Just update mock data formats or expected values.95 - Example: Tool data structure changed from `{ name }` to `{ function: { name } }` → update mock data96 - Example: Output format changed from `Current date: YYYY-MM-DD` to `Current date: YYYY-MM-DD (TZ)` → update expected string9798### Delete (over-specified, low value)99100- **Param-forwarding tests**: Tests that assert exact internal function call arguments (e.g., `expect(internalFn).toHaveBeenCalledWith(expect.objectContaining({ exact params }))`) — these break on every refactor and duplicate what behavior tests already cover.101- **Implementation-coupled tests**: Tests that verify _how_ the code works internally rather than _what_ it produces. If a higher-level test already covers the same behavior, the low-level test adds maintenance cost without coverage gain.102103### Decision Checklist1041051. Does the test verify **externally observable behavior** (API response, DB write, rendered output)? → **Keep**1062. Does the test only verify **internal wiring** (which function receives which params)? → Check if a behavior test already covers it. If yes → **Delete**1073. Is the same behavior already tested at a **higher integration level**? → Delete the lower-level duplicate1084. Would the test break again on the **next routine refactor**? → Consider raising to integration level or deleting109110### When Writing New Tests111112- Prefer **integration-level assertions** (verify final output) over **white-box assertions** (verify internal calls)113- Use `expect.objectContaining` only for stable, public-facing contracts — not for internal param shapes that change with refactors114- Mock at boundaries (DB, network, external services), not between internal modules115116## Common Issues1171181. **Module pollution**: Use `vi.resetModules()` when tests fail mysteriously1192. **Mock not working**: Check setup position and use `vi.clearAllMocks()` in beforeEach1203. **Test data pollution**: Clean database state in beforeEach/afterEach1214. **Async issues**: Wrap state changes in `act()` for React hooks122123---124> Converted and distributed by [TomeVault](https://tomevault.io) | [Claim this content](https://tomevault.io/claim/lobehub/lobehub)125<!-- tomevault:2.0:skill_md:2026-04-05 -->