LobeHub Testing Guide

Quick Reference

Commands:

bash
1# Run specific test file
2bunx vitest run --silent='passed-only' '[file-path]'
3
4# Database package (client)
5cd packages/database && bunx vitest run --silent='passed-only' '[file]'
6
7# Database package (server)
8cd 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

Core Principles

1. Prefer vi.spyOn over vi.mock - More targeted, easier to maintain
2. Tests must pass type check - Run bun run type-check after writing tests
3. After 1-2 failed fix attempts, stop and ask for help
4. Test behavior, not implementation details

Basic Test Structure

typescript
1import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
2
3beforeEach(() => {
4  vi.clearAllMocks();
5});
6
7afterEach(() => {
8  vi.restoreAllMocks();
9});
10
11describe('ModuleName', () => {
12  describe('functionName', () => {
13    it('should handle normal case', () => {
14      // Arrange → Act → Assert
15    });
16  });
17});

Mock Patterns

typescript
1// ✅ Spy on direct dependencies
2vi.spyOn(messageService, 'createMessage').mockResolvedValue('id');
3
4// ✅ Use vi.stubGlobal for browser APIs
5vi.stubGlobal('Image', mockImage);
6vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock');
7
8// ❌ Avoid mocking entire modules globally
9vi.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

Common Issues

1. Module pollution: Use vi.resetModules() when tests fail mysteriously
2. Mock not working: Check setup position and use vi.clearAllMocks() in beforeEach
3. Test data pollution: Clean database state in beforeEach/afterEach
4. Async issues: Wrap state changes in act() for React hooks