bugsink mcp and claude subagents - documentation and test fixes
This commit is contained in:
223
docs/development/DESIGN_TOKENS.md
Normal file
223
docs/development/DESIGN_TOKENS.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# Design Tokens
|
||||
|
||||
This document defines the design tokens used throughout the Flyer Crawler application, including color palettes, usage guidelines, and semantic mappings.
|
||||
|
||||
## Color Palette
|
||||
|
||||
### Brand Colors
|
||||
|
||||
The Flyer Crawler brand uses a **teal** color palette that evokes freshness, value, and the grocery shopping experience.
|
||||
|
||||
| Token | Value | Tailwind | RGB | Usage |
|
||||
| --------------------- | --------- | -------- | ------------- | ---------------------------------------- |
|
||||
| `brand-primary` | `#0d9488` | teal-600 | 13, 148, 136 | Main brand color, primary call-to-action |
|
||||
| `brand-secondary` | `#14b8a6` | teal-500 | 20, 184, 166 | Supporting actions, primary buttons |
|
||||
| `brand-light` | `#ccfbf1` | teal-100 | 204, 251, 241 | Backgrounds, highlights (light mode) |
|
||||
| `brand-dark` | `#115e59` | teal-800 | 17, 94, 89 | Hover states, backgrounds (dark mode) |
|
||||
| `brand-primary-light` | `#99f6e4` | teal-200 | 153, 246, 228 | Subtle backgrounds, light accents |
|
||||
| `brand-primary-dark` | `#134e4a` | teal-900 | 19, 78, 74 | Deep backgrounds, strong emphasis (dark) |
|
||||
|
||||
### Color Usage Examples
|
||||
|
||||
```jsx
|
||||
// Primary color for icons and emphasis
|
||||
<TagIcon className="text-brand-primary" />
|
||||
|
||||
// Secondary color for primary action buttons
|
||||
<button className="bg-brand-secondary hover:bg-brand-dark">
|
||||
Add to List
|
||||
</button>
|
||||
|
||||
// Light backgrounds for selected/highlighted items
|
||||
<div className="bg-brand-light dark:bg-brand-dark/30">
|
||||
Selected Flyer
|
||||
</div>
|
||||
|
||||
// Focus rings on form inputs
|
||||
<input className="focus:ring-brand-primary focus:border-brand-primary" />
|
||||
```
|
||||
|
||||
## Semantic Color Mappings
|
||||
|
||||
### Primary (`brand-primary`)
|
||||
|
||||
**Purpose**: Main brand color for visual identity and key interactive elements
|
||||
|
||||
**Use Cases**:
|
||||
|
||||
- Icons representing key features (shopping cart, tags, deals)
|
||||
- Hover states on links and interactive text
|
||||
- Focus indicators on form elements
|
||||
- Progress bars and loading indicators
|
||||
- Selected state indicators
|
||||
|
||||
**Example Usage**:
|
||||
|
||||
```jsx
|
||||
className = 'text-brand-primary hover:text-brand-dark';
|
||||
```
|
||||
|
||||
### Secondary (`brand-secondary`)
|
||||
|
||||
**Purpose**: Supporting actions and primary buttons that drive user engagement
|
||||
|
||||
**Use Cases**:
|
||||
|
||||
- Primary action buttons (Add, Submit, Save)
|
||||
- Call-to-action elements that require user attention
|
||||
- Active state for toggles and switches
|
||||
|
||||
**Example Usage**:
|
||||
|
||||
```jsx
|
||||
className = 'bg-brand-secondary hover:bg-brand-dark';
|
||||
```
|
||||
|
||||
### Light (`brand-light`)
|
||||
|
||||
**Purpose**: Subtle backgrounds and highlights in light mode
|
||||
|
||||
**Use Cases**:
|
||||
|
||||
- Selected item backgrounds
|
||||
- Highlighted sections
|
||||
- Drag-and-drop target areas
|
||||
- Subtle emphasis backgrounds
|
||||
|
||||
**Example Usage**:
|
||||
|
||||
```jsx
|
||||
className = 'bg-brand-light dark:bg-brand-dark/20';
|
||||
```
|
||||
|
||||
### Dark (`brand-dark`)
|
||||
|
||||
**Purpose**: Hover states and backgrounds in dark mode
|
||||
|
||||
**Use Cases**:
|
||||
|
||||
- Button hover states
|
||||
- Dark mode backgrounds for highlighted sections
|
||||
- Strong emphasis in dark theme
|
||||
|
||||
**Example Usage**:
|
||||
|
||||
```jsx
|
||||
className = 'hover:bg-brand-dark dark:bg-brand-dark/30';
|
||||
```
|
||||
|
||||
## Dark Mode Variants
|
||||
|
||||
All brand colors have dark mode variants defined using Tailwind's `dark:` prefix.
|
||||
|
||||
### Dark Mode Mapping Table
|
||||
|
||||
| Light Mode Class | Dark Mode Class | Purpose |
|
||||
| ----------------------- | ----------------------------- | ------------------------------------ |
|
||||
| `text-brand-primary` | `dark:text-brand-light` | Text readability on dark backgrounds |
|
||||
| `bg-brand-light` | `dark:bg-brand-dark/20` | Subtle backgrounds |
|
||||
| `bg-brand-primary` | `dark:bg-brand-primary` | Brand color maintained in both modes |
|
||||
| `hover:text-brand-dark` | `dark:hover:text-brand-light` | Interactive text hover |
|
||||
| `border-brand-primary` | `dark:border-brand-primary` | Borders maintained in both modes |
|
||||
|
||||
### Dark Mode Best Practices
|
||||
|
||||
1. **Contrast**: Ensure sufficient contrast (WCAG AA: 4.5:1 for text, 3:1 for UI)
|
||||
2. **Consistency**: Use `brand-primary` for icons in both modes (it works well on both backgrounds)
|
||||
3. **Backgrounds**: Use lighter opacity variants for dark mode backgrounds (e.g., `/20`, `/30`)
|
||||
4. **Text**: Swap `brand-dark` ↔ `brand-light` for text elements between modes
|
||||
|
||||
## Accessibility
|
||||
|
||||
### Color Contrast Ratios
|
||||
|
||||
All color combinations meet WCAG 2.1 Level AA standards:
|
||||
|
||||
| Foreground | Background | Contrast Ratio | Pass Level |
|
||||
| --------------- | ----------------- | -------------- | ---------- |
|
||||
| `brand-primary` | white | 4.51:1 | AA |
|
||||
| `brand-dark` | white | 7.82:1 | AAA |
|
||||
| white | `brand-primary` | 4.51:1 | AA |
|
||||
| white | `brand-secondary` | 3.98:1 | AA Large |
|
||||
| white | `brand-dark` | 7.82:1 | AAA |
|
||||
| `brand-light` | `brand-dark` | 13.4:1 | AAA |
|
||||
|
||||
### Focus Indicators
|
||||
|
||||
All interactive elements MUST have visible focus indicators using `focus:ring-2`:
|
||||
|
||||
```jsx
|
||||
className = 'focus:ring-2 focus:ring-brand-primary focus:ring-offset-2';
|
||||
```
|
||||
|
||||
### Color Blindness Considerations
|
||||
|
||||
The teal color palette is accessible for most forms of color blindness:
|
||||
|
||||
- **Deuteranopia** (green-weak): Teal appears as blue/cyan
|
||||
- **Protanopia** (red-weak): Teal appears as blue
|
||||
- **Tritanopia** (blue-weak): Teal appears as green
|
||||
|
||||
The brand colors are always used alongside text labels and icons, never relying solely on color to convey information.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Tailwind Config
|
||||
|
||||
Brand colors are defined in `tailwind.config.js`:
|
||||
|
||||
```javascript
|
||||
theme: {
|
||||
extend: {
|
||||
colors: {
|
||||
brand: {
|
||||
primary: '#0d9488',
|
||||
secondary: '#14b8a6',
|
||||
light: '#ccfbf1',
|
||||
dark: '#115e59',
|
||||
'primary-light': '#99f6e4',
|
||||
'primary-dark': '#134e4a',
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Usage in Components
|
||||
|
||||
Import and use brand colors with Tailwind utility classes:
|
||||
|
||||
```jsx
|
||||
// Text colors
|
||||
<span className="text-brand-primary dark:text-brand-light">Price</span>
|
||||
|
||||
// Background colors
|
||||
<div className="bg-brand-secondary hover:bg-brand-dark">Button</div>
|
||||
|
||||
// Border colors
|
||||
<div className="border-2 border-brand-primary">Card</div>
|
||||
|
||||
// Opacity variants
|
||||
<div className="bg-brand-light/50 dark:bg-brand-dark/20">Overlay</div>
|
||||
```
|
||||
|
||||
## Future Considerations
|
||||
|
||||
### Potential Extensions
|
||||
|
||||
- **Success**: Consider adding semantic success color (green) for completed actions
|
||||
- **Warning**: Consider adding semantic warning color (amber) for alerts
|
||||
- **Error**: Consider adding semantic error color (red) for errors (already using red-\* palette)
|
||||
|
||||
### Color Palette Expansion
|
||||
|
||||
If the brand evolves, consider these complementary colors:
|
||||
|
||||
- **Accent**: Warm coral/orange for limited-time deals
|
||||
- **Neutral**: Gray scale for backgrounds and borders (already using Tailwind's gray palette)
|
||||
|
||||
## References
|
||||
|
||||
- [Tailwind CSS Color Palette](https://tailwindcss.com/docs/customizing-colors)
|
||||
- [WCAG 2.1 Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)
|
||||
- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
|
||||
252
docs/development/TESTING.md
Normal file
252
docs/development/TESTING.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# Testing Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This project has comprehensive test coverage including unit tests, integration tests, and E2E tests. All tests must be run in the **Linux dev container environment** for reliable results.
|
||||
|
||||
## Test Execution Environment
|
||||
|
||||
**CRITICAL**: All tests and type-checking MUST be executed inside the dev container (Linux environment).
|
||||
|
||||
### Why Linux Only?
|
||||
|
||||
- Path separators: Code uses POSIX-style paths (`/`) which may break on Windows
|
||||
- TypeScript compilation works differently on Windows vs Linux
|
||||
- Shell scripts and external dependencies assume Linux
|
||||
- Test results from Windows are **unreliable and should be ignored**
|
||||
|
||||
### Running Tests Correctly
|
||||
|
||||
#### Option 1: Inside Dev Container (Recommended)
|
||||
|
||||
Open VS Code and use "Reopen in Container", then:
|
||||
|
||||
```bash
|
||||
npm test # Run all tests
|
||||
npm run test:unit # Run unit tests only
|
||||
npm run test:integration # Run integration tests
|
||||
npm run type-check # Run TypeScript type checking
|
||||
```
|
||||
|
||||
#### Option 2: Via Podman from Windows Host
|
||||
|
||||
From the Windows host, execute commands in the container:
|
||||
|
||||
```bash
|
||||
# Run unit tests (2900+ tests - pipe to file for AI processing)
|
||||
podman exec -it flyer-crawler-dev npm run test:unit 2>&1 | tee test-results.txt
|
||||
|
||||
# Run integration tests
|
||||
podman exec -it flyer-crawler-dev npm run test:integration
|
||||
|
||||
# Run type checking
|
||||
podman exec -it flyer-crawler-dev npm run type-check
|
||||
|
||||
# Run specific test file
|
||||
podman exec -it flyer-crawler-dev npm test -- --run src/hooks/useAuth.test.tsx
|
||||
```
|
||||
|
||||
## Type Checking
|
||||
|
||||
TypeScript type checking is performed using `tsc --noEmit`.
|
||||
|
||||
### Type Check Command
|
||||
|
||||
```bash
|
||||
npm run type-check
|
||||
```
|
||||
|
||||
### Type Check Validation
|
||||
|
||||
The type-check command will:
|
||||
|
||||
- Exit with code 0 if no errors are found
|
||||
- Exit with non-zero code and print errors if type errors exist
|
||||
- Check all files in the `src/` directory as defined in `tsconfig.json`
|
||||
|
||||
**IMPORTANT**: Type-check on Windows may not show errors reliably. Always verify type-check results by running in the dev container.
|
||||
|
||||
### Verifying Type Check Works
|
||||
|
||||
To verify type-check is working correctly:
|
||||
|
||||
1. Run type-check in dev container: `podman exec -it flyer-crawler-dev npm run type-check`
|
||||
2. Check for output - errors will be displayed with file paths and line numbers
|
||||
3. No output + exit code 0 = no type errors
|
||||
|
||||
Example error output:
|
||||
|
||||
```
|
||||
src/pages/MyDealsPage.tsx:68:31 - error TS2339: Property 'store_name' does not exist on type 'WatchedItemDeal'.
|
||||
|
||||
68 <span>{deal.store_name}</span>
|
||||
~~~~~~~~~~
|
||||
```
|
||||
|
||||
## Pre-Commit Hooks
|
||||
|
||||
The project uses Husky and lint-staged for pre-commit validation:
|
||||
|
||||
```bash
|
||||
# .husky/pre-commit
|
||||
npx lint-staged
|
||||
```
|
||||
|
||||
Lint-staged configuration (`.lintstagedrc.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"*.{js,jsx,ts,tsx}": ["eslint --fix --no-color", "prettier --write"],
|
||||
"*.{json,md,css,html,yml,yaml}": ["prettier --write"]
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: The `--no-color` flag prevents ANSI color codes from breaking file path links in git output.
|
||||
|
||||
## Test Suite Structure
|
||||
|
||||
### Unit Tests (~2900 tests)
|
||||
|
||||
Located throughout `src/` directory alongside source files with `.test.ts` or `.test.tsx` extensions.
|
||||
|
||||
```bash
|
||||
npm run test:unit
|
||||
```
|
||||
|
||||
### Integration Tests (5 test files)
|
||||
|
||||
Located in `src/tests/integration/`:
|
||||
|
||||
- `admin.integration.test.ts`
|
||||
- `flyer.integration.test.ts`
|
||||
- `price.integration.test.ts`
|
||||
- `public.routes.integration.test.ts`
|
||||
- `receipt.integration.test.ts`
|
||||
|
||||
Requires PostgreSQL and Redis services running.
|
||||
|
||||
```bash
|
||||
npm run test:integration
|
||||
```
|
||||
|
||||
### E2E Tests (3 test files)
|
||||
|
||||
Located in `src/tests/e2e/`:
|
||||
|
||||
- `deals-journey.e2e.test.ts`
|
||||
- `budget-journey.e2e.test.ts`
|
||||
- `receipt-journey.e2e.test.ts`
|
||||
|
||||
Requires all services (PostgreSQL, Redis, BullMQ workers) running.
|
||||
|
||||
```bash
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
## Test Result Interpretation
|
||||
|
||||
- Tests that **pass on Windows but fail on Linux** = **BROKEN tests** (must be fixed)
|
||||
- Tests that **fail on Windows but pass on Linux** = **PASSING tests** (acceptable)
|
||||
- Always use **Linux (dev container) results** as the source of truth
|
||||
|
||||
## Test Helpers
|
||||
|
||||
### Store Test Helpers
|
||||
|
||||
Located in `src/tests/utils/storeHelpers.ts`:
|
||||
|
||||
```typescript
|
||||
// Create a store with a location in one call
|
||||
const store = await createStoreWithLocation({
|
||||
storeName: 'Test Store',
|
||||
address: {
|
||||
address_line_1: '123 Main St',
|
||||
city: 'Toronto',
|
||||
province_state: 'ON',
|
||||
postal_code: 'M1M 1M1',
|
||||
},
|
||||
pool,
|
||||
log,
|
||||
});
|
||||
|
||||
// Cleanup stores and their locations
|
||||
await cleanupStoreLocations([storeId1, storeId2], pool, log);
|
||||
```
|
||||
|
||||
### Mock Factories
|
||||
|
||||
Located in `src/tests/utils/mockFactories.ts`:
|
||||
|
||||
```typescript
|
||||
// Create mock data for tests
|
||||
const mockStore = createMockStore({ name: 'Test Store' });
|
||||
const mockAddress = createMockAddress({ city: 'Toronto' });
|
||||
const mockStoreLocation = createMockStoreLocationWithAddress();
|
||||
const mockStoreWithLocations = createMockStoreWithLocations({
|
||||
locations: [{ address: { city: 'Toronto' } }],
|
||||
});
|
||||
```
|
||||
|
||||
## Known Integration Test Issues
|
||||
|
||||
See `CLAUDE.md` for documentation of common integration test issues and their solutions, including:
|
||||
|
||||
1. Vitest globalSetup context isolation
|
||||
2. BullMQ cleanup queue timing issues
|
||||
3. Cache invalidation after direct database inserts
|
||||
4. Unique filename requirements for file uploads
|
||||
5. Response format mismatches
|
||||
6. External service availability
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
Tests run automatically on:
|
||||
|
||||
- Pre-commit (via Husky hooks)
|
||||
- Pull request creation/update (via Gitea CI/CD)
|
||||
- Merge to main branch (via Gitea CI/CD)
|
||||
|
||||
CI/CD configuration:
|
||||
|
||||
- `.gitea/workflows/deploy-to-prod.yml`
|
||||
- `.gitea/workflows/deploy-to-test.yml`
|
||||
|
||||
## Coverage Reports
|
||||
|
||||
Test coverage is tracked using Vitest's built-in coverage tools.
|
||||
|
||||
```bash
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
Coverage reports are generated in the `coverage/` directory.
|
||||
|
||||
## Debugging Tests
|
||||
|
||||
### Enable Verbose Logging
|
||||
|
||||
```bash
|
||||
# Run tests with verbose output
|
||||
npm test -- --reporter=verbose
|
||||
|
||||
# Run specific test with logging
|
||||
DEBUG=* npm test -- --run src/path/to/test.test.ts
|
||||
```
|
||||
|
||||
### Using Vitest UI
|
||||
|
||||
```bash
|
||||
npm run test:ui
|
||||
```
|
||||
|
||||
Opens a browser-based test runner with filtering and debugging capabilities.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always run tests in dev container** - never trust Windows test results
|
||||
2. **Run type-check before committing** - catches TypeScript errors early
|
||||
3. **Use test helpers** - `createStoreWithLocation()`, mock factories, etc.
|
||||
4. **Clean up test data** - use cleanup helpers in `afterEach`/`afterAll`
|
||||
5. **Verify cache invalidation** - tests that insert data directly must invalidate cache
|
||||
6. **Use unique filenames** - file upload tests need timestamp-based filenames
|
||||
7. **Check exit codes** - `npm run type-check` returns 0 on success, non-zero on error
|
||||
Reference in New Issue
Block a user