Add codebase mapping documents

2026-03-13 01:08:16 +08:00
commit afe1603bbe
7 changed files with 1349 additions and 0 deletions
--- a/.planning/codebase/TESTING.md
+++ b/.planning/codebase/TESTING.md
@@ -0,0 +1,249 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-03-13
+
+## Test Infrastructure
+
+**Status: NO TESTING INFRASTRUCTURE DETECTED**
+
+The codebase currently lacks automated testing configuration and test files.
+
+## Test Framework
+
+**Runner:** Not configured
+- No Jest configuration detected
+- No Vitest configuration detected  
+- No Playwright/Cypress configuration detected
+
+**Assertion Library:** Not configured
+- No testing libraries in dependencies
+
+**Run Commands:** Not available
+- `package.json` only defines: `"build": "vite build"`
+- No test scripts present
+
+## Test File Organization
+
+**Current State:**
+- No test files in source code (`*.test.ts`, `*.spec.ts`, `*.test.tsx`, `*.spec.tsx`)
+- All test file matches were from `node_modules/` (zod library tests)
+
+**File Pattern:** Not established
+
+**Test Directory Structure:** Not implemented
+
+## Code Quality Indicators
+
+### TODO/FIXME Comments
+Minimal technical debt markers found:
+- `MobileSettingView.tsx` line 31: `placeholder="+63 XXX XXX XXXX"` (placeholder text, not TODO)
+
+### Code Complexity
+View component line counts (reasonable for view components):
+```
+FlashMemoryView.tsx    112 lines
+ADCSettingView.tsx      83 lines
+LevelSettingView.tsx    78 lines
+MobileSettingView.tsx   70 lines
+RainfallSettingView.tsx 69 lines
+NetworkSetupView.tsx    69 lines
+DateTimeSettingView.tsx 65 lines
+CalibrationView.tsx     63 lines
+RainfallView.tsx        63 lines
+SettingView.tsx         76 lines
+LoginView.tsx           61 lines
+GraphView.tsx           51 lines
+EVAPSettingView.tsx     54 lines
+SirenSettingView.tsx    71 lines
+GPRSSettingView.tsx     68 lines
+StationInfoView.tsx     40 lines
+```
+
+**Total view code:** ~1,092 lines across 16 view files
+
+### Component Complexity
+UI components (`src/app/components/ui/`):
+- Range: 6 lines (`utils.ts`) to 168 lines (`form.tsx`)
+- Most components: 20-90 lines
+- Pattern: Small, focused components following shadcn/ui conventions
+
+## Missing Testing Infrastructure
+
+### Critical Gaps
+1. **No unit test framework** - Components cannot be unit tested
+2. **No integration tests** - Route integration untested
+3. **No E2E tests** - User flows untested
+4. **No test scripts** - No CI/CD integration possible
+5. **No mocking strategy** - External dependencies not mockable
+
+### Testing Dependencies to Add
+For comprehensive testing, the following would be needed:
+
+```json
+{
+  "devDependencies": {
+    "vitest": "^2.x",
+    "@testing-library/react": "^14.x",
+    "@testing-library/jest-dom": "^6.x",
+    "@testing-library/user-event": "^14.x",
+    "jsdom": "^24.x"
+  }
+}
+```
+
+Or alternatively with Jest:
+
+```json
+{
+  "devDependencies": {
+    "jest": "^29.x",
+    "@testing-library/react": "^14.x",
+    "@testing-library/jest-dom": "^6.x",
+    "ts-jest": "^29.x",
+    "jest-environment-jsdom": "^29.x"
+  }
+}
+```
+
+## Recommended Testing Strategy
+
+### Priority 1: Unit Tests for UI Components
+Test critical UI primitives in `src/app/components/ui/`:
+- `button.tsx` - Variant rendering, click handling
+- `card.tsx` - Composition pattern
+- `input.tsx` - Value handling, focus states
+- `switch.tsx` - Toggle behavior
+
+### Priority 2: View Component Tests
+Test user interactions in views:
+- Form submissions
+- State changes
+- Navigation triggers
+
+### Priority 3: Integration Tests
+Test route configuration:
+- Route rendering
+- Navigation flow
+- Layout composition
+
+## Testing Conventions to Establish
+
+### Test File Naming
+Recommended pattern (when tests are added):
+- Co-located: `[Component].test.tsx` next to `[Component].tsx`
+- Or separate: `__tests__/[Component].test.tsx`
+
+### Test Structure (Recommended)
+```typescript
+// button.test.tsx - Example pattern to follow
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { Button } from './button';
+
+describe('Button', () => {
+  it('renders with default variant', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByText('Click me')).toBeInTheDocument();
+  });
+
+  it('handles click events', () => {
+    const handleClick = vi.fn();
+    render(<Button onClick={handleClick}>Click me</Button>);
+    fireEvent.click(screen.getByText('Click me'));
+    expect(handleClick).toHaveBeenCalled();
+  });
+
+  it('renders different variants', () => {
+    const { rerender } = render(<Button variant="destructive">Delete</Button>);
+    // Assert destructive styling
+    
+    rerender(<Button variant="outline">Cancel</Button>);
+    // Assert outline styling
+  });
+});
+```
+
+### Mocking Strategy (Recommended)
+
+**External Libraries:**
+- Mock `lucide-react` icons for snapshot stability
+- Mock `@radix-ui` components at boundary
+
+**Browser APIs:**
+- Mock `document.getElementById()` for scroll tests
+- Mock `window` events if needed
+
+**Example Mock Pattern:**
+```typescript
+// Mock scroll behavior
+const scrollByMock = vi.fn();
+Object.defineProperty(document, 'getElementById', {
+  value: vi.fn(() => ({ scrollBy: scrollByMock })),
+});
+```
+
+## Coverage Recommendations
+
+### Minimum Targets
+- **UI Components:** 80% coverage (small, critical components)
+- **View Components:** 60% coverage (user interaction paths)
+- **Utility Functions:** 90% coverage (business logic)
+- **Routes:** Integration tests for all paths
+
+### Critical Paths to Test
+1. Login form submission
+2. Sidebar navigation
+3. File selection in FlashMemoryView
+4. Settings toggle switches
+5. Navigation button scrolling
+
+## CI/CD Integration
+
+### GitHub Actions (Recommended)
+When tests are added, include in workflow:
+
+```yaml
+name: Test
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+      - run: pnpm install
+      - run: pnpm test
+      - run: pnpm test:coverage
+```
+
+## Testing Documentation Gap
+
+**Issue:** No testing guidelines in existing documentation
+
+The `Guidelines.md` file (458 lines) covers:
+- Design patterns
+- Color palettes
+- Component naming
+- Touchscreen guidelines
+
+But does NOT cover:
+- Testing conventions
+- Test file organization
+- Mocking patterns
+- Coverage requirements
+
+## Action Items for Testing
+
+1. **Add testing dependencies** (Vitest + React Testing Library recommended)
+2. **Create `vitest.config.ts`** with jsdom environment
+3. **Add test scripts** to `package.json`
+4. **Write initial tests** for critical UI components
+5. **Document testing patterns** in Guidelines.md
+6. **Set up CI/CD** to run tests on PR
+7. **Establish coverage thresholds**
+
+---
+
+*Testing analysis: 2026-03-13*
+
+**Summary:** This codebase currently has no testing infrastructure. All testing patterns documented above are recommendations for implementation rather than observed conventions.