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