@lobehub/lobehub 2.0.0-next.352 → 2.0.0-next.354

package/.cursor/rules/testing-guide/testing-guide.mdc

@@ -1,534 +0,0 @@
----
-globs: *.test.ts,*.test.tsx
-alwaysApply: false
----
-
-# LobeChat Testing Guide
-
-## Test Overview
-
-LobeChat testing consists of **E2E tests** and **Unit tests**. This guide focuses on **Unit tests**.
-
-Unit tests are organized into three main categories:
-
-```plaintext
-+---------------------+---------------------------+-----------------------------+
-| Category            | Location                  | Config File                 |
-+---------------------+---------------------------+-----------------------------+
-| Next.js Webapp      | src/**/*.test.ts(x)       | vitest.config.ts            |
-| Packages            | packages/*/**/*.test.ts   | packages/*/vitest.config.ts |
-| Desktop App         | apps/desktop/**/*.test.ts | apps/desktop/vitest.config.ts |
-+---------------------+---------------------------+-----------------------------+
-```
-
-### Next.js Webapp Tests
-
-- **Config File**: `vitest.config.ts`
-- **Environment**: Happy DOM (browser environment simulation)
-- **Database**: PGLite (PostgreSQL for browser environments)
-- **Setup File**: `tests/setup.ts`
-- **Purpose**: Testing React components, hooks, stores, utilities, and client-side logic
-
-### Packages Tests
-
-Most packages use standard Vitest configuration. However, the `database` package is special:
-
-#### Database Package (Special Case)
-
-The database package supports **dual-environment testing**:
-
-| Environment      | Database        | Config                                | Use Case                          |
-|------------------|-----------------|---------------------------------------|-----------------------------------|
-| Client (Default) | PGLite          | `packages/database/vitest.config.mts` | Fast local development            |
-| Server           | Real PostgreSQL | Set `TEST_SERVER_DB=1`                | CI/CD, compatibility verification |
-
-Server environment details:
-
-- **Concurrency**: Single-threaded (`singleFork: true`)
-- **Setup File**: `packages/database/tests/setup-db.ts`
-- **Requirement**: `DATABASE_TEST_URL` environment variable must be set
-
-### Desktop App Tests
-
-- **Config File**: `apps/desktop/vitest.config.ts`
-- **Environment**: Node.js
-- **Purpose**: Testing Electron main process controllers, IPC handlers, and desktop-specific logic
-
-## Test Commands
-
-**Performance Warning**: The project contains 3000+ test cases. A full run takes approximately 10 minutes. Always use file filtering or test name filtering.
-
-### Recommended Command Format
-
-```bash
-# Run all client/server tests
-bunx vitest run --silent='passed-only'                                          # Client tests
-cd packages/database && TEST_SERVER_DB=1 bunx vitest run --silent='passed-only' # Server tests
-
-# Run specific test file (supports fuzzy matching)
-bunx vitest run --silent='passed-only' user.test.ts
-
-# Run specific test case by name (using -t flag)
-bunx vitest run --silent='passed-only' -t "test case name"
-
-# Combine file and test name filtering
-bunx vitest run --silent='passed-only' filename.test.ts -t "specific test"
-
-# Generate coverage report (using --coverage flag)
-bunx vitest run --silent='passed-only' --coverage
-```
-
-### Commands to Avoid
-
-```bash
-# ❌ These commands run all 3000+ test cases, taking ~10 minutes!
-npm test
-npm test some-file.test.ts
-
-# ❌ Don't use bare vitest (enters watch mode)
-vitest test-file.test.ts
-```
-
-## Test Fixing Principles
-
-### Core Principles
-
-1. **Gather Sufficient Context**
-   Before fixing tests, ensure you:
-   - Fully understand the test's intent and implementation
-   - Strongly recommended: review the current git diff and PR diff
-
-2. **Prioritize Test Fixes**
-   If the test itself is incorrect, fix the test first rather than the implementation code.
-
-3. **Focus on a Single Issue**
-   Only fix the specified test; don't add extra tests along the way.
-
-4. **Don't Act Unilaterally**
-   When discovering other issues, don't modify them directly—raise and discuss first.
-
-### Testing Collaboration Best Practices
-
-Important collaboration principles based on real development experience:
-
-#### 1. Failure Handling Strategy
-
-**Core Principle**: Avoid blind retries; quickly identify problems and seek help.
-
-- **Failure Threshold**: After 1-2 consecutive failed fix attempts, stop immediately
-- **Problem Summary**: Analyze failure reasons and document attempted solutions with their failure causes
-- **Seek Help**: Approach the team with a clear problem summary and attempt history
-- **Avoid the Trap**: Don't fall into the loop of repeatedly trying the same or similar approaches
-
-```typescript
-// ❌ Wrong approach: Keep blindly trying after consecutive failures
-// 3rd, 4th attempts still using similar methods to fix the same problem
-
-// ✅ Correct approach: Summarize after 1-2 failures
-/*
-Problem Summary:
-1. Attempted method: Modified mock data structure
-2. Failure reason: Still getting type mismatch error
-3. Specific error: Expected 'UserData' but received 'UserProfile'
-4. Help needed: Unsure about the latest UserData interface definition
-*/
-```
-
-#### 2. Test Case Naming Conventions
-
-**Core Principle**: Tests should focus on "behavior," not "implementation details."
-
-- **Describe Business Scenarios**: `describe` and `it` titles should describe specific business scenarios and expected behaviors
-- **Avoid Implementation Binding**: Don't mention specific line numbers, coverage goals, or implementation details in test names
-- **Maintain Stability**: Test names should remain meaningful after code refactoring
-
-```typescript
-// ❌ Poor test naming
-describe('User component coverage', () => {
-  it('covers line 45-50 in getUserData', () => {
-    // Test written just to cover lines 45-50
-  });
-
-  it('tests the else branch', () => {
-    // Exists only to test a specific branch
-  });
-});
-
-// ✅ Good test naming
-describe('<UserAvatar />', () => {
-  it('should render fallback icon when image url is not provided', () => {
-    // Tests a specific business scenario, naturally covering relevant code branches
-  });
-
-  it('should display user initials when avatar image fails to load', () => {
-    // Describes user behavior and expected outcome
-  });
-});
-```
-
-**The Right Approach to Improving Coverage**:
-
-- Naturally improve coverage by designing various business scenarios (happy paths, edge cases, error handling)
-- Don't write tests just to hit coverage numbers, and never comment "to cover line xxx" in tests
-
-#### 3. Test Organization Structure
-
-**Core Principle**: Maintain a clear test hierarchy; avoid redundant top-level test blocks.
-
-- **Reuse Existing Structure**: When adding new tests, first look for an appropriate place in existing `describe` blocks
-- **Logical Grouping**: Related test cases should be organized within the same `describe` block
-- **Avoid Fragmentation**: Don't create a new top-level `describe` block for a single test case
-
-```typescript
-// ❌ Poor organization: Too many top-level blocks
-describe('<UserProfile />', () => {
-  it('should render user name', () => {});
-});
-
-describe('UserProfile new prop test', () => {
-  // Unnecessary new block
-  it('should handle email display', () => {});
-});
-
-describe('UserProfile edge cases', () => {
-  // Unnecessary new block
-  it('should handle missing avatar', () => {});
-});
-
-// ✅ Good organization: Merge related tests
-describe('<UserProfile />', () => {
-  it('should render user name', () => {});
-
-  it('should handle email display', () => {});
-
-  it('should handle missing avatar', () => {});
-
-  describe('when user data is incomplete', () => {
-    // Only create sub-groups when there are multiple related sub-scenarios
-    it('should show placeholder for missing name', () => {});
-    it('should hide email section when email is undefined', () => {});
-  });
-});
-```
-
-**Organization Decision Flow**:
-
-1. Is there a logically related existing `describe` block? → If yes, add to it
-2. Are there multiple (3+) related test cases? → If yes, consider creating a new sub-`describe`
-3. Is it an independent, unrelated feature module? → Only then consider creating a new top-level `describe`
-
-### Test Fixing Workflow
-
-1. **Reproduce the Issue**: Locate and run the failing test; confirm it can be reproduced locally
-2. **Analyze the Cause**: Read test code, error logs, and Git history of related files
-3. **Form a Hypothesis**: Determine if the problem is in test logic, implementation code, or environment configuration
-4. **Fix and Verify**: Apply the fix based on your hypothesis; rerun the test to confirm it passes
-5. **Expand Verification**: Run all tests in the current file to ensure no new issues were introduced
-6. **Write a Summary**: Document the error cause and fix method
-
-### Post-Fix Summary
-
-After completing a test fix, provide a brief explanation including:
-
-1. **Root Cause Analysis**: Explain the fundamental reason for the test failure
-   - Test logic error
-   - Implementation bug
-   - Environment configuration issue
-   - Dependency change
-
-2. **Fix Description**: Briefly describe the fix approach
-   - Which files were modified
-   - What solution was applied
-   - Why this fix approach was chosen
-
-**Example Format**:
-
-```markdown
-## Test Fix Summary
-
-**Root Cause**: The mock data format in the test didn't match the actual API response format, causing assertion failures.
-
-**Fix**: Updated the mock data structure in the test file to match the latest API response format. Specifically modified the `mockUserData` object structure in `user.test.ts`.
-```
-
-## Test Writing Best Practices
-
-### Mock Data Strategy: Aim for "Low-Cost Authenticity"
-
-**Core Principle**: Test data should default to authenticity; only simplify when it introduces "high testing costs."
-
-#### What Are "High Testing Costs"?
-
-"High cost" refers to introducing external dependencies in tests that make them slow, unstable, or complex:
-
-- **File I/O Operations**: Reading/writing disk files
-- **Network Requests**: HTTP calls, database connections
-- **System Calls**: Getting system time, environment variables, etc.
-
-#### Recommended Approach: Mock Dependencies, Keep Real Data
-
-```typescript
-// ✅ Good approach: Mock I/O operations but use real file content formats
-describe('parseContentType', () => {
-  beforeEach(() => {
-    // Mock file read operation (avoid real I/O)
-    vi.spyOn(fs, 'readFileSync').mockImplementation((path) => {
-      // But return real file content formats
-      if (path.includes('.pdf')) return '%PDF-1.4\n%âãÏÓ'; // Real PDF header
-      if (path.includes('.png')) return '\x89PNG\r\n\x1a\n'; // Real PNG header
-      return '';
-    });
-  });
-
-  it('should detect PDF content type correctly', () => {
-    const result = parseContentType('/path/to/file.pdf');
-    expect(result).toBe('application/pdf');
-  });
-});
-
-// ❌ Over-simplified: Using unrealistic data
-describe('parseContentType', () => {
-  it('should detect PDF content type correctly', () => {
-    // This simplified data has no test value
-    const result = parseContentType('fake-pdf-content');
-    expect(result).toBe('application/pdf');
-  });
-});
-```
-
-#### The Value of Real Identifiers
-
-```typescript
-// ✅ Use real identifiers
-const result = parseModelString('openai', '+gpt-4,+gpt-3.5-turbo');
-
-// ❌ Use placeholders (lower value)
-const result = parseModelString('test-provider', '+model1,+model2');
-```
-
-### Modern Mocking Techniques: Environment Setup and Mock Methods
-
-When testing client-side code, use environment annotations with modern mock methods:
-
-```typescript
-/**
- * @vitest-environment happy-dom  // Provides browser APIs
- */
-import { beforeEach, vi } from 'vitest';
-
-beforeEach(() => {
-  // Modern method 1: Use vi.stubGlobal instead of global.xxx = ...
-  const mockImage = vi.fn().mockImplementation(() => ({
-    addEventListener: vi.fn(),
-    naturalHeight: 600,
-    naturalWidth: 800,
-  }));
-  vi.stubGlobal('Image', mockImage);
-
-  // Modern method 2: Use vi.spyOn to preserve original functionality, only mock specific methods
-  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock-url');
-  vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {});
-});
-```
-
-#### Environment Selection Priority
-
-1. **@vitest-environment happy-dom** (Recommended) - Lightweight, fast, already installed in the project
-2. **@vitest-environment jsdom** - Full-featured, but requires additional jsdom package installation
-3. **No environment set** - Node.js environment, requires manually mocking all browser APIs
-
-#### Mock Method Comparison
-
-```typescript
-// ❌ Old method: Directly manipulating global object (type issues)
-global.Image = mockImage;
-global.URL = { ...global.URL, createObjectURL: mockFn };
-
-// ✅ Modern method: Type-safe vi API
-vi.stubGlobal('Image', mockImage); // Completely replace global object
-vi.spyOn(URL, 'createObjectURL'); // Partial mock, preserve other functionality
-```
-
-### Test Coverage Principles: Code Branches Over Test Quantity
-
-**Core Principle**: Prioritize covering all code branches rather than writing many repetitive test cases.
-
-```typescript
-// ❌ Over-testing: 29 test cases all validating the same branch
-describe('getImageDimensions', () => {
-  it('should reject .txt files');
-  it('should reject .pdf files');
-  // ... 25 similar tests, all hitting the same validation branch
-});
-
-// ✅ Lean testing: 4 core cases covering all branches
-describe('getImageDimensions', () => {
-  it('should return dimensions for valid File object'); // Success path - File
-  it('should return dimensions for valid data URI'); // Success path - String
-  it('should return undefined for invalid inputs'); // Input validation branch
-  it('should return undefined when image fails to load'); // Error handling branch
-});
-```
-
-#### Branch Coverage Strategy
-
-1. **Success Paths** - One test per input type is sufficient
-2. **Boundary Conditions** - Consolidate similar scenarios into a single test
-3. **Error Handling** - Test representative errors only
-4. **Business Logic** - Cover all if/else branches
-
-#### Reasonable Test Counts
-
-- Simple utility functions: 2-5 tests
-- Complex business logic: 5-10 tests
-- Core security features: Add more as needed, but avoid duplicate paths
-
-### Error Handling Tests: Test "Behavior" Not "Text"
-
-**Core Principle**: Tests should verify that program behavior is predictable when errors occur, not verify error message text that may change.
-
-#### Recommended Error Testing Approach
-
-```typescript
-// ✅ Test error types and properties
-expect(() => validateUser({})).toThrow(ValidationError);
-expect(() => processPayment({})).toThrow(
-  expect.objectContaining({
-    code: 'INVALID_PAYMENT_DATA',
-    statusCode: 400,
-  }),
-);
-
-// ❌ Avoid testing specific error text
-expect(() => processUser({})).toThrow('User data cannot be empty, please check input parameters');
-```
-
-### Troubleshooting: Beware of Module Pollution
-
-**Warning Signs**: When your tests exhibit these "mysterious" behaviors, suspect module pollution first:
-
-- A test passes when run alone but fails when run with other tests
-- Test execution order affects results
-- Mock setup appears correct but actually uses an old mock version
-
-#### Typical Scenario: Dynamic Mocking of the Same Module
-
-```typescript
-// ❌ Problem: Dynamic mocking of the same module
-it('dev mode', async () => {
-  vi.doMock('./config', () => ({ isDev: true }));
-  const { getSettings } = await import('./service'); // May use cache
-});
-
-// ✅ Solution: Clear module cache
-beforeEach(() => {
-  vi.resetModules(); // Ensure each test has a clean environment
-});
-```
-
-**Remember**: `vi.resetModules()` is the ultimate weapon for resolving "mysterious" test failures.
-
-## Test File Organization
-
-### File Naming Convention
-
-`*.test.ts`, `*.test.tsx` (any location)
-
-### Test File Organization Style
-
-The project uses a **co-located test files** organization style:
-
-- Test files are placed in the same directory as the corresponding source files
-- Naming format: `originalFileName.test.ts` or `originalFileName.test.tsx`
-
-Example:
-
-```plaintext
-src/components/Button/
-├── index.tsx           # Source file
-└── index.test.tsx      # Test file
-```
-
-- In some cases, tests are consolidated in a `__tests__` folder, e.g., `packages/database/src/models/__tests__`
-- Test helper files are placed in a fixtures folder
-
-## Test Debugging Tips
-
-### Test Debugging Steps
-
-1. **Determine Test Environment**: Select the correct config file based on file path
-2. **Isolate the Problem**: Use the `-t` flag to run only the failing test case
-3. **Analyze the Error**: Carefully read error messages, stack traces, and recent file modification history
-4. **Add Debugging**: Add `console.log` statements in tests to understand execution flow
-
-### TypeScript Type Handling
-
-In tests, you can relax TypeScript type checking to improve writing efficiency and readability:
-
-#### Recommended Type Relaxation Strategies
-
-```typescript
-// Use non-null assertion to access properties you're certain exist in tests
-const result = await someFunction();
-expect(result!.data).toBeDefined();
-expect(result!.status).toBe('success');
-
-// Use any type to simplify complex mock setups
-const mockStream = new ReadableStream() as any;
-mockStream.toReadableStream = () => mockStream;
-
-// Access private members
-await instance['getFromCache']('key'); // Bracket notation recommended
-await (instance as any).getFromCache('key'); // Avoid as any
-```
-
-#### Applicable Scenarios
-
-- **Mock Objects**: Use `as any` for test mock data to avoid complex type definitions
-- **Third-Party Libraries**: Use `any` appropriately when handling complex third-party library types
-- **Test Assertions**: Use `!` non-null assertion in test scenarios where you're certain the object exists
-- **Private Member Access**: Prefer bracket notation `instance['privateMethod']()` over `(instance as any).privateMethod()`
-- **Temporary Debugging**: When quickly writing tests, use `any` first to ensure functionality, then optionally optimize types later
-
-#### Important Notes
-
-- **Use Moderately**: Don't over-rely on `any`; core business logic types should remain strict
-- **Private Member Access Priority**: Bracket notation > `as any` casting for better type safety
-- **Documentation**: Add comments explaining the reason for complex `any` usage scenarios
-- **Test Coverage**: Ensure tests still effectively verify correctness even when using `any`
-
-### Checking Recent Modifications
-
-**Core Principle**: When tests suddenly fail, first check recent code changes.
-
-#### Quick Check Methods
-
-```bash
-git status                  # View current modification status
-git diff HEAD -- '*.test.*' # Check test file changes
-git diff main...HEAD        # Compare with main branch
-gh pr diff                  # View all changes in the PR
-```
-
-#### Common Causes and Solutions
-
-- **Latest commit introduced a bug** → Check and fix the implementation code
-- **Branch code is outdated** → `git rebase main` to sync with main branch
-
-## Special Testing Scenarios
-
-For special testing scenarios, refer to the related rules:
-
-- `electron-ipc-test.mdc` - Electron IPC Interface Testing Strategy
-- `db-model-test.mdc` - Database Model Testing Guide
-
-## Key Takeaways
-
-- **Command Format**: Use `bunx vitest run --silent='passed-only'` with file filtering
-- **Fix Principles**: Seek help after 1-2 failures; focus test naming on behavior, not implementation details
-- **Debug Workflow**: Reproduce → Analyze → Hypothesize → Fix → Verify → Summarize
-- **File Organization**: Prefer adding tests to existing `describe` blocks; avoid creating redundant top-level blocks
-- **Data Strategy**: Default to authenticity; only simplify for high-cost scenarios (I/O, network, etc.)
-- **Error Testing**: Test error types and behavior; avoid depending on specific error message text
-- **Module Pollution**: When tests fail "mysteriously," suspect module pollution first; use `vi.resetModules()` to resolve
-- **Security Requirements**: Model tests must include permission checks and pass in both environments