Compare commits
18 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
5bc8f6a42b | ||
| 4fd5e900af | |||
|
|
39ab773b82 | ||
| 75406cd924 | |||
|
|
8fb0a57f02 | ||
| c78323275b | |||
|
|
5fe537b93d | ||
| 61f24305fb | |||
|
|
de3f0cf26e | ||
| 45ac4fccf5 | |||
|
|
b6c3ca9abe | ||
| 4f06698dfd | |||
|
|
e548d1b0cc | ||
| 771f59d009 | |||
|
|
0979a074ad | ||
| 0d4b028a66 | |||
|
|
4baed53713 | ||
| f10c6c0cd6 |
32
.env.example
32
.env.example
@@ -128,3 +128,35 @@ GENERATE_SOURCE_MAPS=true
|
||||
SENTRY_AUTH_TOKEN=
|
||||
# URL of your Bugsink instance (for source map uploads)
|
||||
SENTRY_URL=https://bugsink.projectium.com
|
||||
|
||||
# ===================
|
||||
# Feature Flags (ADR-024)
|
||||
# ===================
|
||||
# Feature flags control the availability of features at runtime.
|
||||
# All flags default to disabled (false) when not set or set to any value other than 'true'.
|
||||
# Set to 'true' to enable a feature.
|
||||
#
|
||||
# Backend flags use: FEATURE_SNAKE_CASE
|
||||
# Frontend flags use: VITE_FEATURE_SNAKE_CASE (VITE_ prefix required for client-side access)
|
||||
#
|
||||
# Lifecycle:
|
||||
# 1. Add flag with default false
|
||||
# 2. Enable via env var when ready for testing/rollout
|
||||
# 3. Remove conditional code when feature is fully rolled out
|
||||
# 4. Remove flag from config within 3 months of full rollout
|
||||
#
|
||||
# See: docs/adr/0024-feature-flagging-strategy.md
|
||||
|
||||
# Backend Feature Flags
|
||||
# FEATURE_BUGSINK_SYNC=false # Enable Bugsink error sync integration
|
||||
# FEATURE_ADVANCED_RBAC=false # Enable advanced RBAC features
|
||||
# FEATURE_NEW_DASHBOARD=false # Enable new dashboard experience
|
||||
# FEATURE_BETA_RECIPES=false # Enable beta recipe features
|
||||
# FEATURE_EXPERIMENTAL_AI=false # Enable experimental AI features
|
||||
# FEATURE_DEBUG_MODE=false # Enable debug mode for development
|
||||
|
||||
# Frontend Feature Flags (VITE_ prefix required)
|
||||
# VITE_FEATURE_NEW_DASHBOARD=false # Enable new dashboard experience
|
||||
# VITE_FEATURE_BETA_RECIPES=false # Enable beta recipe features
|
||||
# VITE_FEATURE_EXPERIMENTAL_AI=false # Enable experimental AI features
|
||||
# VITE_FEATURE_DEBUG_MODE=false # Enable debug mode for development
|
||||
|
||||
4
.gitignore
vendored
4
.gitignore
vendored
@@ -38,3 +38,7 @@ Thumbs.db
|
||||
.claude/settings.local.json
|
||||
nul
|
||||
tmpclaude*
|
||||
|
||||
|
||||
|
||||
test.tmp
|
||||
147
CLAUDE.md
147
CLAUDE.md
@@ -27,6 +27,24 @@ podman exec -it flyer-crawler-dev npm run type-check
|
||||
|
||||
Out-of-sync = test failures.
|
||||
|
||||
### Server Access: READ-ONLY (Production/Test Servers)
|
||||
|
||||
**CRITICAL**: The `claude-win10` user has **READ-ONLY** access to production and test servers.
|
||||
|
||||
| Capability | Status |
|
||||
| ---------------------- | ---------------------- |
|
||||
| Root/sudo access | NO |
|
||||
| Write permissions | NO |
|
||||
| PM2 restart, systemctl | NO - User must execute |
|
||||
|
||||
**Server Operations Workflow**: Diagnose → User executes → Analyze → Fix (1-3 commands) → User executes → Verify
|
||||
|
||||
**Rules**:
|
||||
|
||||
- Provide diagnostic commands first, wait for user to report results
|
||||
- Maximum 3 fix commands at a time (errors may cascade)
|
||||
- Always verify after fixes complete
|
||||
|
||||
### Communication Style
|
||||
|
||||
Ask before assuming. Never assume:
|
||||
@@ -60,25 +78,27 @@ Ask before assuming. Never assume:
|
||||
|
||||
### Key Patterns (with file locations)
|
||||
|
||||
| Pattern | ADR | Implementation | File |
|
||||
| ------------------ | ------- | ------------------------------------------------- | ----------------------------------- |
|
||||
| Error Handling | ADR-001 | `handleDbError()`, throw `NotFoundError` | `src/services/db/errors.db.ts` |
|
||||
| Repository Methods | ADR-034 | `get*` (throws), `find*` (null), `list*` (array) | `src/services/db/*.db.ts` |
|
||||
| API Responses | ADR-028 | `sendSuccess()`, `sendPaginated()`, `sendError()` | `src/utils/apiResponse.ts` |
|
||||
| Transactions | ADR-002 | `withTransaction(async (client) => {...})` | `src/services/db/transaction.db.ts` |
|
||||
| Pattern | ADR | Implementation | File |
|
||||
| ------------------ | ------- | ------------------------------------------------- | ------------------------------------- |
|
||||
| Error Handling | ADR-001 | `handleDbError()`, throw `NotFoundError` | `src/services/db/errors.db.ts` |
|
||||
| Repository Methods | ADR-034 | `get*` (throws), `find*` (null), `list*` (array) | `src/services/db/*.db.ts` |
|
||||
| API Responses | ADR-028 | `sendSuccess()`, `sendPaginated()`, `sendError()` | `src/utils/apiResponse.ts` |
|
||||
| Transactions | ADR-002 | `withTransaction(async (client) => {...})` | `src/services/db/connection.db.ts` |
|
||||
| Feature Flags | ADR-024 | `isFeatureEnabled()`, `useFeatureFlag()` | `src/services/featureFlags.server.ts` |
|
||||
|
||||
### Key Files Quick Access
|
||||
|
||||
| Purpose | File |
|
||||
| ----------------- | -------------------------------- |
|
||||
| Express app | `server.ts` |
|
||||
| Environment | `src/config/env.ts` |
|
||||
| Routes | `src/routes/*.routes.ts` |
|
||||
| Repositories | `src/services/db/*.db.ts` |
|
||||
| Workers | `src/services/workers.server.ts` |
|
||||
| Queues | `src/services/queues.server.ts` |
|
||||
| PM2 Config (Dev) | `ecosystem.dev.config.cjs` |
|
||||
| PM2 Config (Prod) | `ecosystem.config.cjs` |
|
||||
| Purpose | File |
|
||||
| ----------------- | ------------------------------------- |
|
||||
| Express app | `server.ts` |
|
||||
| Environment | `src/config/env.ts` |
|
||||
| Routes | `src/routes/*.routes.ts` |
|
||||
| Repositories | `src/services/db/*.db.ts` |
|
||||
| Workers | `src/services/workers.server.ts` |
|
||||
| Queues | `src/services/queues.server.ts` |
|
||||
| Feature Flags | `src/services/featureFlags.server.ts` |
|
||||
| PM2 Config (Dev) | `ecosystem.dev.config.cjs` |
|
||||
| PM2 Config (Prod) | `ecosystem.config.cjs` |
|
||||
|
||||
---
|
||||
|
||||
@@ -121,7 +141,7 @@ The dev container now matches production by using PM2 for process management.
|
||||
- `flyer-crawler-worker-dev` - Background job worker
|
||||
- `flyer-crawler-vite-dev` - Vite frontend dev server (port 5173)
|
||||
|
||||
### Log Aggregation (ADR-050)
|
||||
### Log Aggregation (ADR-015)
|
||||
|
||||
All logs flow to Bugsink via Logstash with 3-project routing:
|
||||
|
||||
@@ -204,7 +224,7 @@ All logs flow to Bugsink via Logstash with 3-project routing:
|
||||
|
||||
**Launch Pattern**:
|
||||
|
||||
```
|
||||
```text
|
||||
Use Task tool with subagent_type: "coder", "db-dev", "tester", etc.
|
||||
```
|
||||
|
||||
@@ -285,8 +305,8 @@ podman cp "d:/path/file" container:/tmp/file
|
||||
|
||||
**Quick Access**:
|
||||
|
||||
- **Dev**: https://localhost:8443 (`admin@localhost`/`admin`)
|
||||
- **Prod**: https://bugsink.projectium.com
|
||||
- **Dev**: <https://localhost:8443> (`admin@localhost`/`admin`)
|
||||
- **Prod**: <https://bugsink.projectium.com>
|
||||
|
||||
**Token Creation** (required for MCP):
|
||||
|
||||
@@ -294,15 +314,15 @@ podman cp "d:/path/file" container:/tmp/file
|
||||
# Dev container
|
||||
MSYS_NO_PATHCONV=1 podman exec -e DATABASE_URL=postgresql://bugsink:bugsink_dev_password@postgres:5432/bugsink -e SECRET_KEY=dev-bugsink-secret-key-minimum-50-characters-for-security flyer-crawler-dev sh -c 'cd /opt/bugsink/conf && DJANGO_SETTINGS_MODULE=bugsink_conf PYTHONPATH=/opt/bugsink/conf:/opt/bugsink/lib/python3.10/site-packages /opt/bugsink/bin/python -m django create_auth_token'
|
||||
|
||||
# Production (via SSH)
|
||||
ssh root@projectium.com "cd /opt/bugsink && bugsink-manage create_auth_token"
|
||||
# Production (user executes on server)
|
||||
cd /opt/bugsink && bugsink-manage create_auth_token
|
||||
```
|
||||
|
||||
### Logstash
|
||||
|
||||
**See**: [docs/operations/LOGSTASH-QUICK-REF.md](docs/operations/LOGSTASH-QUICK-REF.md)
|
||||
|
||||
Log aggregation: PostgreSQL + PM2 + Redis + NGINX → Bugsink (ADR-050)
|
||||
Log aggregation: PostgreSQL + PM2 + Redis + NGINX → Bugsink (ADR-015)
|
||||
|
||||
---
|
||||
|
||||
@@ -322,84 +342,3 @@ Log aggregation: PostgreSQL + PM2 + Redis + NGINX → Bugsink (ADR-050)
|
||||
| **Logstash** | [LOGSTASH-QUICK-REF.md](docs/operations/LOGSTASH-QUICK-REF.md) |
|
||||
| **ADRs** | [docs/adr/index.md](docs/adr/index.md) |
|
||||
| **All Docs** | [docs/README.md](docs/README.md) |
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Integration Test Issues (Full Details)
|
||||
|
||||
### 1. Vitest globalSetup Context Isolation
|
||||
|
||||
Vitest's `globalSetup` runs in separate Node.js context. Singletons, spies, mocks do NOT share instances with test files.
|
||||
|
||||
**Affected**: BullMQ worker service mocks (AI/DB failure tests)
|
||||
|
||||
**Solutions**: Mark `.todo()`, create test-only API endpoints, use Redis-based mock flags
|
||||
|
||||
```typescript
|
||||
// DOES NOT WORK - different instances
|
||||
const { flyerProcessingService } = await import('../../services/workers.server');
|
||||
flyerProcessingService._getAiProcessor()._setExtractAndValidateData(mockFn);
|
||||
```
|
||||
|
||||
### 2. Cleanup Queue Deletes Before Verification
|
||||
|
||||
Cleanup worker processes jobs in globalSetup context, ignoring test spies.
|
||||
|
||||
**Solution**: Drain and pause queue:
|
||||
|
||||
```typescript
|
||||
const { cleanupQueue } = await import('../../services/queues.server');
|
||||
await cleanupQueue.drain();
|
||||
await cleanupQueue.pause();
|
||||
// ... test ...
|
||||
await cleanupQueue.resume();
|
||||
```
|
||||
|
||||
### 3. Cache Stale After Direct SQL
|
||||
|
||||
Direct `pool.query()` inserts bypass cache invalidation.
|
||||
|
||||
**Solution**: `await cacheService.invalidateFlyers();` after inserts
|
||||
|
||||
### 4. Test Filename Collisions
|
||||
|
||||
Multer predictable filenames cause race conditions.
|
||||
|
||||
**Solution**: Use unique suffix: `${Date.now()}-${Math.round(Math.random() * 1e9)}`
|
||||
|
||||
### 5. Response Format Mismatches
|
||||
|
||||
API formats change: `data.jobId` vs `data.job.id`, nested vs flat, string vs number IDs.
|
||||
|
||||
**Solution**: Log response bodies, update assertions
|
||||
|
||||
### 6. External Service Availability
|
||||
|
||||
PM2/Redis health checks fail when unavailable.
|
||||
|
||||
**Solution**: try/catch with graceful degradation or mock
|
||||
|
||||
### 7. TZ Environment Variable Breaking Async Hooks
|
||||
|
||||
**Problem**: When `TZ=America/Los_Angeles` (or other timezone values) is set in the environment, Node.js async_hooks module can produce `RangeError: Invalid triggerAsyncId value: NaN`. This breaks React Testing Library's `render()` function which uses async hooks internally.
|
||||
|
||||
**Root Cause**: Setting `TZ` to certain timezone values interferes with Node.js's internal async tracking mechanism, causing invalid async IDs to be generated.
|
||||
|
||||
**Symptoms**:
|
||||
|
||||
```text
|
||||
RangeError: Invalid triggerAsyncId value: NaN
|
||||
❯ process.env.NODE_ENV.queueSeveralMicrotasks node_modules/react/cjs/react.development.js:751:15
|
||||
❯ process.env.NODE_ENV.exports.act node_modules/react/cjs/react.development.js:886:11
|
||||
❯ node_modules/@testing-library/react/dist/act-compat.js:46:25
|
||||
❯ renderRoot node_modules/@testing-library/react/dist/pure.js:189:26
|
||||
```
|
||||
|
||||
**Solution**: Explicitly unset `TZ` in all test scripts by adding `TZ=` (empty value) to cross-env:
|
||||
|
||||
```json
|
||||
"test:unit": "cross-env NODE_ENV=test TZ= tsx ..."
|
||||
"test:integration": "cross-env NODE_ENV=test TZ= tsx ..."
|
||||
```
|
||||
|
||||
**Context**: This issue was introduced in commit `d03900c` which added `TZ: 'America/Los_Angeles'` to PM2 ecosystem configs for consistent log timestamps in production/dev environments. Tests must explicitly override this to prevent the async hooks error.
|
||||
|
||||
393
docs/AI-DOCUMENTATION-INDEX.md
Normal file
393
docs/AI-DOCUMENTATION-INDEX.md
Normal file
@@ -0,0 +1,393 @@
|
||||
# AI Documentation Index
|
||||
|
||||
Machine-optimized navigation for AI agents. Structured for vector retrieval and semantic search.
|
||||
|
||||
---
|
||||
|
||||
## Quick Lookup Table
|
||||
|
||||
| Task/Question | Primary Doc | Section/ADR |
|
||||
| ----------------------- | --------------------------------------------------- | --------------------------------------- |
|
||||
| Add new API endpoint | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) | API Response Patterns, Input Validation |
|
||||
| Add repository method | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) | Repository Patterns (get*/find*/list\*) |
|
||||
| Fix failing test | [TESTING.md](development/TESTING.md) | Known Integration Test Issues |
|
||||
| Run tests correctly | [TESTING.md](development/TESTING.md) | Test Execution Environment |
|
||||
| Add database column | [DATABASE-GUIDE.md](subagents/DATABASE-GUIDE.md) | Schema sync required |
|
||||
| Deploy to production | [DEPLOYMENT.md](operations/DEPLOYMENT.md) | Application Deployment |
|
||||
| Debug container issue | [DEBUGGING.md](development/DEBUGGING.md) | Container Issues |
|
||||
| Configure environment | [ENVIRONMENT.md](getting-started/ENVIRONMENT.md) | Configuration by Environment |
|
||||
| Add background job | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) | Background Jobs |
|
||||
| Handle errors correctly | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) | Error Handling |
|
||||
| Use transactions | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) | Transaction Management |
|
||||
| Add authentication | [AUTHENTICATION.md](architecture/AUTHENTICATION.md) | JWT Token Architecture |
|
||||
| Cache data | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) | Caching |
|
||||
| Check PM2 status | [DEV-CONTAINER.md](development/DEV-CONTAINER.md) | PM2 Process Management |
|
||||
| View logs | [DEBUGGING.md](development/DEBUGGING.md) | PM2 Log Access |
|
||||
| Understand architecture | [OVERVIEW.md](architecture/OVERVIEW.md) | System Architecture Diagram |
|
||||
| Check ADR for decision | [adr/index.md](adr/index.md) | ADR by category |
|
||||
| Use subagent | [subagents/OVERVIEW.md](subagents/OVERVIEW.md) | Available Subagents |
|
||||
| API versioning | [API-VERSIONING.md](development/API-VERSIONING.md) | Phase 2 infrastructure |
|
||||
|
||||
---
|
||||
|
||||
## Documentation Tree
|
||||
|
||||
```
|
||||
docs/
|
||||
+-- AI-DOCUMENTATION-INDEX.md # THIS FILE - AI navigation index
|
||||
+-- README.md # Human-readable doc hub
|
||||
|
|
||||
+-- adr/ # Architecture Decision Records (57 ADRs)
|
||||
| +-- index.md # ADR index by category
|
||||
| +-- 0001-*.md # Standardized error handling
|
||||
| +-- 0002-*.md # Transaction management (withTransaction)
|
||||
| +-- 0003-*.md # Input validation (Zod middleware)
|
||||
| +-- 0008-*.md # API versioning (/api/v1/)
|
||||
| +-- 0014-*.md # Platform: Linux only (CRITICAL)
|
||||
| +-- 0028-*.md # API response (sendSuccess/sendError)
|
||||
| +-- 0034-*.md # Repository pattern (get*/find*/list*)
|
||||
| +-- 0035-*.md # Service layer architecture
|
||||
| +-- 0050-*.md # PostgreSQL observability + Logstash
|
||||
| +-- 0057-*.md # Test remediation post-API versioning
|
||||
| +-- adr-implementation-tracker.md # Implementation status
|
||||
|
|
||||
+-- architecture/
|
||||
| +-- OVERVIEW.md # System architecture, data flows, entities
|
||||
| +-- DATABASE.md # Schema design, extensions, setup
|
||||
| +-- AUTHENTICATION.md # OAuth, JWT, security features
|
||||
| +-- WEBSOCKET_USAGE.md # Real-time communication patterns
|
||||
| +-- api-versioning-infrastructure.md # Phase 2 versioning details
|
||||
|
|
||||
+-- development/
|
||||
| +-- CODE-PATTERNS.md # Error handling, repos, API responses
|
||||
| +-- TESTING.md # Unit/integration/E2E, known issues
|
||||
| +-- DEBUGGING.md # Container, DB, API, PM2 debugging
|
||||
| +-- DEV-CONTAINER.md # PM2, Logstash, container services
|
||||
| +-- API-VERSIONING.md # API versioning workflows
|
||||
| +-- DESIGN_TOKENS.md # Neo-Brutalism design system
|
||||
| +-- ERROR-LOGGING-PATHS.md # req.originalUrl pattern
|
||||
| +-- test-path-migration.md # Test file reorganization
|
||||
|
|
||||
+-- getting-started/
|
||||
| +-- QUICKSTART.md # Quick setup instructions
|
||||
| +-- INSTALL.md # Full installation guide
|
||||
| +-- ENVIRONMENT.md # Environment variables reference
|
||||
|
|
||||
+-- operations/
|
||||
| +-- DEPLOYMENT.md # Production deployment guide
|
||||
| +-- BARE-METAL-SETUP.md # Server provisioning
|
||||
| +-- MONITORING.md # Bugsink, health checks
|
||||
| +-- LOGSTASH-QUICK-REF.md # Log aggregation reference
|
||||
| +-- LOGSTASH-TROUBLESHOOTING.md # Logstash debugging
|
||||
|
|
||||
+-- subagents/
|
||||
| +-- OVERVIEW.md # Subagent system introduction
|
||||
| +-- CODER-GUIDE.md # Code development patterns
|
||||
| +-- TESTER-GUIDE.md # Testing strategies
|
||||
| +-- DATABASE-GUIDE.md # Database workflows
|
||||
| +-- DEVOPS-GUIDE.md # Deployment/infrastructure
|
||||
| +-- FRONTEND-GUIDE.md # UI/UX development
|
||||
| +-- AI-USAGE-GUIDE.md # Gemini integration
|
||||
| +-- DOCUMENTATION-GUIDE.md # Writing docs
|
||||
| +-- SECURITY-DEBUG-GUIDE.md # Security and debugging
|
||||
|
|
||||
+-- tools/
|
||||
| +-- MCP-CONFIGURATION.md # MCP servers setup
|
||||
| +-- BUGSINK-SETUP.md # Error tracking setup
|
||||
| +-- VSCODE-SETUP.md # Editor configuration
|
||||
|
|
||||
+-- archive/ # Historical docs, session notes
|
||||
+-- sessions/ # Development session logs
|
||||
+-- plans/ # Feature implementation plans
|
||||
+-- research/ # Investigation notes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Problem-to-Document Mapping
|
||||
|
||||
### Database Issues
|
||||
|
||||
| Problem | Documents |
|
||||
| -------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| Schema out of sync | [DATABASE-GUIDE.md](subagents/DATABASE-GUIDE.md), [CLAUDE.md](../CLAUDE.md) schema sync section |
|
||||
| Migration needed | [DATABASE.md](architecture/DATABASE.md), ADR-013, ADR-023 |
|
||||
| Query performance | [DEBUGGING.md](development/DEBUGGING.md) Query Performance Issues |
|
||||
| Connection errors | [DEBUGGING.md](development/DEBUGGING.md) Database Issues |
|
||||
| Transaction patterns | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) Transaction Management, ADR-002 |
|
||||
| Repository methods | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) Repository Patterns, ADR-034 |
|
||||
|
||||
### Test Failures
|
||||
|
||||
| Problem | Documents |
|
||||
| ---------------------------- | --------------------------------------------------------------------- |
|
||||
| Tests fail in container | [TESTING.md](development/TESTING.md), ADR-014 |
|
||||
| Vitest globalSetup isolation | [CLAUDE.md](../CLAUDE.md) Integration Test Issues #1 |
|
||||
| Cache stale after insert | [CLAUDE.md](../CLAUDE.md) Integration Test Issues #3 |
|
||||
| Queue interference | [CLAUDE.md](../CLAUDE.md) Integration Test Issues #2 |
|
||||
| API path mismatches | [TESTING.md](development/TESTING.md) API Versioning in Tests, ADR-057 |
|
||||
| Type check failures | [DEBUGGING.md](development/DEBUGGING.md) Type Check Failures |
|
||||
| TZ environment breaks async | [CLAUDE.md](../CLAUDE.md) Integration Test Issues #7 |
|
||||
|
||||
### Deployment Issues
|
||||
|
||||
| Problem | Documents |
|
||||
| --------------------- | ------------------------------------------------------------------------------------- |
|
||||
| PM2 not starting | [DEBUGGING.md](development/DEBUGGING.md) PM2 Process Issues |
|
||||
| NGINX configuration | [DEPLOYMENT.md](operations/DEPLOYMENT.md) NGINX Configuration |
|
||||
| SSL certificates | [DEBUGGING.md](development/DEBUGGING.md) SSL Certificate Issues |
|
||||
| CI/CD failures | [DEPLOYMENT.md](operations/DEPLOYMENT.md) CI/CD Pipeline, ADR-017 |
|
||||
| Container won't start | [DEBUGGING.md](development/DEBUGGING.md) Container Issues |
|
||||
| Bugsink not receiving | [BUGSINK-SETUP.md](tools/BUGSINK-SETUP.md), [MONITORING.md](operations/MONITORING.md) |
|
||||
|
||||
### Frontend/UI Changes
|
||||
|
||||
| Problem | Documents |
|
||||
| ------------------ | --------------------------------------------------------------- |
|
||||
| Component patterns | [FRONTEND-GUIDE.md](subagents/FRONTEND-GUIDE.md), ADR-044 |
|
||||
| Design tokens | [DESIGN_TOKENS.md](development/DESIGN_TOKENS.md), ADR-012 |
|
||||
| State management | ADR-005, [OVERVIEW.md](architecture/OVERVIEW.md) Frontend Stack |
|
||||
| Hot reload broken | [DEBUGGING.md](development/DEBUGGING.md) Frontend Issues |
|
||||
| CORS errors | [DEBUGGING.md](development/DEBUGGING.md) API Calls Failing |
|
||||
|
||||
### API Development
|
||||
|
||||
| Problem | Documents |
|
||||
| ---------------- | ------------------------------------------------------------------------------- |
|
||||
| Response format | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) API Response Patterns, ADR-028 |
|
||||
| Input validation | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) Input Validation, ADR-003 |
|
||||
| Error handling | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) Error Handling, ADR-001 |
|
||||
| Rate limiting | ADR-032, [OVERVIEW.md](architecture/OVERVIEW.md) |
|
||||
| API versioning | [API-VERSIONING.md](development/API-VERSIONING.md), ADR-008 |
|
||||
| Authentication | [AUTHENTICATION.md](architecture/AUTHENTICATION.md), ADR-048 |
|
||||
|
||||
### Background Jobs
|
||||
|
||||
| Problem | Documents |
|
||||
| ------------------- | ------------------------------------------------------------------------- |
|
||||
| Jobs not processing | [DEBUGGING.md](development/DEBUGGING.md) Background Job Issues |
|
||||
| Queue configuration | [CODE-PATTERNS.md](development/CODE-PATTERNS.md) Background Jobs, ADR-006 |
|
||||
| Worker crashes | [DEBUGGING.md](development/DEBUGGING.md), ADR-053 |
|
||||
| Scheduled jobs | ADR-037, [OVERVIEW.md](architecture/OVERVIEW.md) Scheduled Jobs |
|
||||
|
||||
---
|
||||
|
||||
## Document Priority Matrix
|
||||
|
||||
### CRITICAL (Read First)
|
||||
|
||||
| Document | Purpose | Key Content |
|
||||
| --------------------------------------------------------------- | ----------------------- | ----------------------------- |
|
||||
| [CLAUDE.md](../CLAUDE.md) | AI agent instructions | Rules, patterns, known issues |
|
||||
| [ADR-014](adr/0014-containerization-and-deployment-strategy.md) | Platform requirement | Tests MUST run in container |
|
||||
| [DEV-CONTAINER.md](development/DEV-CONTAINER.md) | Development environment | PM2, Logstash, services |
|
||||
|
||||
### HIGH (Core Development)
|
||||
|
||||
| Document | Purpose | Key Content |
|
||||
| --------------------------------------------------- | ----------------- | ---------------------------- |
|
||||
| [CODE-PATTERNS.md](development/CODE-PATTERNS.md) | Code templates | Error handling, repos, APIs |
|
||||
| [TESTING.md](development/TESTING.md) | Test execution | Commands, known issues |
|
||||
| [DATABASE.md](architecture/DATABASE.md) | Schema reference | Setup, extensions, users |
|
||||
| [ADR-034](adr/0034-repository-pattern-standards.md) | Repository naming | get*/find*/list\* |
|
||||
| [ADR-028](adr/0028-api-response-standardization.md) | API responses | sendSuccess/sendError |
|
||||
| [ADR-001](adr/0001-standardized-error-handling.md) | Error handling | handleDbError, NotFoundError |
|
||||
|
||||
### MEDIUM (Specialized Tasks)
|
||||
|
||||
| Document | Purpose | Key Content |
|
||||
| --------------------------------------------------- | --------------------- | ------------------------ |
|
||||
| [subagents/OVERVIEW.md](subagents/OVERVIEW.md) | Subagent selection | When to delegate |
|
||||
| [DEPLOYMENT.md](operations/DEPLOYMENT.md) | Production deployment | PM2, NGINX, CI/CD |
|
||||
| [DEBUGGING.md](development/DEBUGGING.md) | Troubleshooting | Common issues, solutions |
|
||||
| [ENVIRONMENT.md](getting-started/ENVIRONMENT.md) | Config reference | Variables by environment |
|
||||
| [AUTHENTICATION.md](architecture/AUTHENTICATION.md) | Auth patterns | OAuth, JWT, security |
|
||||
| [API-VERSIONING.md](development/API-VERSIONING.md) | Versioning | /api/v1/ prefix |
|
||||
|
||||
### LOW (Reference/Historical)
|
||||
|
||||
| Document | Purpose | Key Content |
|
||||
| -------------------- | ------------------ | ------------------------- |
|
||||
| [archive/](archive/) | Historical docs | Session notes, old plans |
|
||||
| ADR-013, ADR-023 | Migration strategy | Proposed, not implemented |
|
||||
| ADR-024 | Feature flags | Proposed |
|
||||
| ADR-025 | i18n/l10n | Proposed |
|
||||
|
||||
---
|
||||
|
||||
## Cross-Reference Matrix
|
||||
|
||||
| Document | References | Referenced By |
|
||||
| -------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| **CLAUDE.md** | ADR-001, ADR-002, ADR-008, ADR-014, ADR-028, ADR-034, ADR-035, ADR-050, ADR-057 | All development docs |
|
||||
| **ADR-008** | ADR-028 | API-VERSIONING.md, TESTING.md, ADR-057 |
|
||||
| **ADR-014** | - | CLAUDE.md, TESTING.md, DEPLOYMENT.md, DEV-CONTAINER.md |
|
||||
| **ADR-028** | ADR-001 | CODE-PATTERNS.md, OVERVIEW.md |
|
||||
| **ADR-034** | ADR-001 | CODE-PATTERNS.md, DATABASE-GUIDE.md |
|
||||
| **ADR-057** | ADR-008, ADR-028 | TESTING.md |
|
||||
| **CODE-PATTERNS.md** | ADR-001, ADR-002, ADR-003, ADR-028, ADR-034, ADR-036, ADR-048 | CODER-GUIDE.md |
|
||||
| **TESTING.md** | ADR-014, ADR-057, CLAUDE.md | TESTER-GUIDE.md, DEBUGGING.md |
|
||||
| **DEBUGGING.md** | DEV-CONTAINER.md, TESTING.md, MONITORING.md | DEVOPS-GUIDE.md |
|
||||
| **DEV-CONTAINER.md** | ADR-014, ADR-050, ecosystem.dev.config.cjs | DEBUGGING.md, CLAUDE.md |
|
||||
| **OVERVIEW.md** | ADR-001 through ADR-050+ | All architecture docs |
|
||||
| **DATABASE.md** | ADR-002, ADR-013, ADR-055 | DATABASE-GUIDE.md |
|
||||
|
||||
---
|
||||
|
||||
## Navigation Patterns
|
||||
|
||||
### Adding a Feature
|
||||
|
||||
```
|
||||
1. CLAUDE.md -> Project rules, patterns
|
||||
2. CODE-PATTERNS.md -> Implementation templates
|
||||
3. Relevant subagent guide -> Domain-specific patterns
|
||||
4. Related ADRs -> Design decisions
|
||||
5. TESTING.md -> Test requirements
|
||||
```
|
||||
|
||||
### Fixing a Bug
|
||||
|
||||
```
|
||||
1. DEBUGGING.md -> Common issues checklist
|
||||
2. TESTING.md -> Run tests in container
|
||||
3. Error logs (pm2/bugsink) -> Identify root cause
|
||||
4. CODE-PATTERNS.md -> Correct pattern reference
|
||||
5. Related ADR -> Architectural context
|
||||
```
|
||||
|
||||
### Deploying
|
||||
|
||||
```
|
||||
1. DEPLOYMENT.md -> Deployment procedures
|
||||
2. ENVIRONMENT.md -> Required variables
|
||||
3. MONITORING.md -> Health check verification
|
||||
4. LOGSTASH-QUICK-REF.md -> Log aggregation check
|
||||
```
|
||||
|
||||
### Database Changes
|
||||
|
||||
```
|
||||
1. DATABASE-GUIDE.md -> Schema sync requirements (CRITICAL)
|
||||
2. DATABASE.md -> Schema design patterns
|
||||
3. ADR-002 -> Transaction patterns
|
||||
4. ADR-034 -> Repository methods
|
||||
5. ADR-055 -> Normalization rules
|
||||
```
|
||||
|
||||
### Subagent Selection
|
||||
|
||||
| Task Type | Subagent | Guide |
|
||||
| --------------------- | ------------------------- | ------------------------------------------------------------ |
|
||||
| Write production code | `coder` | [CODER-GUIDE.md](subagents/CODER-GUIDE.md) |
|
||||
| Database changes | `db-dev` | [DATABASE-GUIDE.md](subagents/DATABASE-GUIDE.md) |
|
||||
| Create tests | `testwriter` | [TESTER-GUIDE.md](subagents/TESTER-GUIDE.md) |
|
||||
| Fix failing tests | `tester` | [TESTER-GUIDE.md](subagents/TESTER-GUIDE.md) |
|
||||
| Container/deployment | `devops` | [DEVOPS-GUIDE.md](subagents/DEVOPS-GUIDE.md) |
|
||||
| UI components | `frontend-specialist` | [FRONTEND-GUIDE.md](subagents/FRONTEND-GUIDE.md) |
|
||||
| External APIs | `integrations-specialist` | - |
|
||||
| Security review | `security-engineer` | [SECURITY-DEBUG-GUIDE.md](subagents/SECURITY-DEBUG-GUIDE.md) |
|
||||
| Production errors | `log-debug` | [SECURITY-DEBUG-GUIDE.md](subagents/SECURITY-DEBUG-GUIDE.md) |
|
||||
| AI/Gemini issues | `ai-usage` | [AI-USAGE-GUIDE.md](subagents/AI-USAGE-GUIDE.md) |
|
||||
|
||||
---
|
||||
|
||||
## Key File Quick Reference
|
||||
|
||||
### Configuration
|
||||
|
||||
| File | Purpose |
|
||||
| -------------------------- | ---------------------------- |
|
||||
| `server.ts` | Express app setup |
|
||||
| `src/config/env.ts` | Environment validation (Zod) |
|
||||
| `ecosystem.dev.config.cjs` | PM2 dev config |
|
||||
| `ecosystem.config.cjs` | PM2 prod config |
|
||||
| `vite.config.ts` | Vite build config |
|
||||
|
||||
### Core Implementation
|
||||
|
||||
| File | Purpose |
|
||||
| ----------------------------------- | ----------------------------------- |
|
||||
| `src/routes/*.routes.ts` | API route handlers |
|
||||
| `src/services/db/*.db.ts` | Repository layer |
|
||||
| `src/services/*.server.ts` | Server-only services |
|
||||
| `src/services/queues.server.ts` | BullMQ queue definitions |
|
||||
| `src/services/workers.server.ts` | BullMQ workers |
|
||||
| `src/utils/apiResponse.ts` | sendSuccess/sendError/sendPaginated |
|
||||
| `src/services/db/errors.db.ts` | handleDbError, NotFoundError |
|
||||
| `src/services/db/transaction.db.ts` | withTransaction |
|
||||
|
||||
### Database Schema
|
||||
|
||||
| File | Purpose |
|
||||
| ------------------------------ | ----------------------------------- |
|
||||
| `sql/master_schema_rollup.sql` | Test DB, complete reference |
|
||||
| `sql/initial_schema.sql` | Fresh install (identical to rollup) |
|
||||
| `sql/migrations/*.sql` | Production ALTER statements |
|
||||
|
||||
### Testing
|
||||
|
||||
| File | Purpose |
|
||||
| ---------------------------------- | ----------------------- |
|
||||
| `vitest.config.ts` | Unit test config |
|
||||
| `vitest.config.integration.ts` | Integration test config |
|
||||
| `vitest.config.e2e.ts` | E2E test config |
|
||||
| `src/tests/utils/mockFactories.ts` | Mock data factories |
|
||||
| `src/tests/utils/storeHelpers.ts` | Store test helpers |
|
||||
|
||||
---
|
||||
|
||||
## ADR Quick Reference
|
||||
|
||||
### By Implementation Status
|
||||
|
||||
**Implemented**: 001, 002, 003, 004, 006, 008, 009, 010, 016, 017, 020, 021, 028, 032, 033, 034, 035, 036, 037, 038, 040, 041, 043, 044, 045, 046, 050, 051, 052, 055, 057
|
||||
|
||||
**Partially Implemented**: 012, 014, 015, 048
|
||||
|
||||
**Proposed**: 011, 013, 022, 023, 024, 025, 029, 030, 031, 039, 047, 053, 054, 056
|
||||
|
||||
### By Category
|
||||
|
||||
| Category | ADRs |
|
||||
| --------------------- | ------------------------------------------- |
|
||||
| Core Infrastructure | 002, 007, 020, 030 |
|
||||
| Data Management | 009, 013, 019, 023, 031, 055 |
|
||||
| API & Integration | 003, 008, 018, 022, 028 |
|
||||
| Security | 001, 011, 016, 029, 032, 033, 048 |
|
||||
| Observability | 004, 015, 050, 051, 052, 056 |
|
||||
| Deployment & Ops | 006, 014, 017, 024, 037, 038, 053, 054 |
|
||||
| Frontend/UI | 005, 012, 025, 026, 044 |
|
||||
| Dev Workflow | 010, 021, 027, 040, 045, 047, 057 |
|
||||
| Architecture Patterns | 034, 035, 036, 039, 041, 042, 043, 046, 049 |
|
||||
|
||||
---
|
||||
|
||||
## Essential Commands
|
||||
|
||||
```bash
|
||||
# Run all tests (MUST use container)
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
|
||||
# Run unit tests
|
||||
podman exec -it flyer-crawler-dev npm run test:unit
|
||||
|
||||
# Run type check
|
||||
podman exec -it flyer-crawler-dev npm run type-check
|
||||
|
||||
# Run integration tests
|
||||
podman exec -it flyer-crawler-dev npm run test:integration
|
||||
|
||||
# PM2 status
|
||||
podman exec -it flyer-crawler-dev pm2 status
|
||||
|
||||
# PM2 logs
|
||||
podman exec -it flyer-crawler-dev pm2 logs
|
||||
|
||||
# Restart all processes
|
||||
podman exec -it flyer-crawler-dev pm2 restart all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
_This index is optimized for AI agent consumption. Updated: 2026-01-28_
|
||||
@@ -32,8 +32,10 @@ Day-to-day development guides:
|
||||
|
||||
- [Testing Guide](development/TESTING.md) - Unit, integration, and E2E testing
|
||||
- [Code Patterns](development/CODE-PATTERNS.md) - Common code patterns and ADR examples
|
||||
- [API Versioning](development/API-VERSIONING.md) - API versioning infrastructure and workflows
|
||||
- [Design Tokens](development/DESIGN_TOKENS.md) - UI design system and Neo-Brutalism
|
||||
- [Debugging Guide](development/DEBUGGING.md) - Common debugging patterns
|
||||
- [Dev Container](development/DEV-CONTAINER.md) - Development container setup and PM2
|
||||
|
||||
### 🔧 Operations
|
||||
|
||||
|
||||
@@ -1,5 +1,21 @@
|
||||
# DevOps Subagent Reference
|
||||
|
||||
## Critical Rule: Server Access is READ-ONLY
|
||||
|
||||
**Claude Code has READ-ONLY access to production/test servers.** The `claude-win10` user cannot execute write operations directly.
|
||||
|
||||
When working with production/test servers:
|
||||
|
||||
1. **Provide commands** for the user to execute (do not attempt SSH)
|
||||
2. **Wait for user** to report command output
|
||||
3. **Provide fix commands** 1-3 at a time (errors may cascade)
|
||||
4. **Verify success** with read-only commands after user executes fixes
|
||||
5. **Document findings** in relevant documentation
|
||||
|
||||
Commands in this reference are for the **user to run on the server**, not for Claude to execute.
|
||||
|
||||
---
|
||||
|
||||
## Critical Rule: Git Bash Path Conversion
|
||||
|
||||
Git Bash on Windows auto-converts Unix paths, breaking container commands.
|
||||
@@ -69,12 +85,11 @@ MSYS_NO_PATHCONV=1 podman exec -it flyer-crawler-dev psql -U postgres -d flyer_c
|
||||
|
||||
## PM2 Commands
|
||||
|
||||
### Production Server (via SSH)
|
||||
### Production Server
|
||||
|
||||
> **Note**: These commands are for the **user to execute on the server**. Claude Code provides commands but cannot run them directly. See [Server Access is READ-ONLY](#critical-rule-server-access-is-read-only) above.
|
||||
|
||||
```bash
|
||||
# SSH to server
|
||||
ssh root@projectium.com
|
||||
|
||||
# List all apps
|
||||
pm2 list
|
||||
|
||||
@@ -210,9 +225,10 @@ INFO
|
||||
|
||||
### Production
|
||||
|
||||
> **Note**: User executes these commands on the server.
|
||||
|
||||
```bash
|
||||
# Via SSH
|
||||
ssh root@projectium.com
|
||||
# Access Redis CLI
|
||||
redis-cli -a $REDIS_PASSWORD
|
||||
|
||||
# Flush cache (use with caution)
|
||||
@@ -278,10 +294,9 @@ Trigger `manual-db-backup.yml` from Gitea Actions UI.
|
||||
|
||||
### Manual Backup
|
||||
|
||||
```bash
|
||||
# SSH to server
|
||||
ssh root@projectium.com
|
||||
> **Note**: User executes these commands on the server.
|
||||
|
||||
```bash
|
||||
# Backup
|
||||
PGPASSWORD=$DB_PASSWORD pg_dump -h $DB_HOST -U $DB_USER $DB_NAME > backup_$(date +%Y%m%d).sql
|
||||
|
||||
@@ -301,8 +316,10 @@ MSYS_NO_PATHCONV=1 podman exec -e DATABASE_URL=postgresql://bugsink:bugsink_dev_
|
||||
|
||||
### Production Token Generation
|
||||
|
||||
> **Note**: User executes this command on the server.
|
||||
|
||||
```bash
|
||||
ssh root@projectium.com "cd /opt/bugsink && bugsink-manage create_auth_token"
|
||||
cd /opt/bugsink && bugsink-manage create_auth_token
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -2,9 +2,11 @@
|
||||
|
||||
**Date**: 2025-12-12
|
||||
|
||||
**Status**: Accepted (Phase 1 Complete)
|
||||
**Status**: Accepted (Phase 2 Complete - All Tasks Done)
|
||||
|
||||
**Updated**: 2026-01-26
|
||||
**Updated**: 2026-01-27
|
||||
|
||||
**Completion Note**: Phase 2 fully complete including test path migration. All 23 integration test files updated to use `/api/v1/` paths. Test suite improved from 274/348 to 345/348 passing (3 remain as todo/skipped for known issues unrelated to versioning).
|
||||
|
||||
## Context
|
||||
|
||||
@@ -43,19 +45,19 @@ We will adopt a URI-based versioning strategy for the API using a phased rollout
|
||||
|
||||
The following changes require a new API version:
|
||||
|
||||
| Change Type | Breaking? | Example |
|
||||
| ----------------------------- | --------- | -------------------------------------------- |
|
||||
| Remove endpoint | Yes | DELETE `/api/v1/legacy-feature` |
|
||||
| Remove response field | Yes | Remove `user.email` from response |
|
||||
| Change response field type | Yes | `id: number` to `id: string` |
|
||||
| Change required request field | Yes | Make `email` required when it was optional |
|
||||
| Rename endpoint | Yes | `/users` to `/accounts` |
|
||||
| Add optional response field | No | Add `user.avatar_url` |
|
||||
| Add optional request field | No | Add optional `page` parameter |
|
||||
| Add new endpoint | No | Add `/api/v1/new-feature` |
|
||||
| Fix bug in behavior | No* | Correct calculation error |
|
||||
| Change Type | Breaking? | Example |
|
||||
| ----------------------------- | --------- | ------------------------------------------ |
|
||||
| Remove endpoint | Yes | DELETE `/api/v1/legacy-feature` |
|
||||
| Remove response field | Yes | Remove `user.email` from response |
|
||||
| Change response field type | Yes | `id: number` to `id: string` |
|
||||
| Change required request field | Yes | Make `email` required when it was optional |
|
||||
| Rename endpoint | Yes | `/users` to `/accounts` |
|
||||
| Add optional response field | No | Add `user.avatar_url` |
|
||||
| Add optional request field | No | Add optional `page` parameter |
|
||||
| Add new endpoint | No | Add `/api/v1/new-feature` |
|
||||
| Fix bug in behavior | No\* | Correct calculation error |
|
||||
|
||||
*Bug fixes may warrant version increment if clients depend on the buggy behavior.
|
||||
\*Bug fixes may warrant version increment if clients depend on the buggy behavior.
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
@@ -109,6 +111,7 @@ The following changes require a new API version:
|
||||
```
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- All existing functionality works at `/api/v1/*`
|
||||
- Frontend makes requests to `/api/v1/*`
|
||||
- OpenAPI documentation reflects `/api/v1/*` paths
|
||||
@@ -246,11 +249,14 @@ export function versionRedirectMiddleware(req: Request, res: Response, next: Nex
|
||||
}
|
||||
|
||||
// Log deprecation warning
|
||||
logger.warn({
|
||||
path: req.originalUrl,
|
||||
method: req.method,
|
||||
ip: req.ip,
|
||||
}, 'Unversioned API request - redirecting to v1');
|
||||
logger.warn(
|
||||
{
|
||||
path: req.originalUrl,
|
||||
method: req.method,
|
||||
ip: req.ip,
|
||||
},
|
||||
'Unversioned API request - redirecting to v1',
|
||||
);
|
||||
|
||||
// Use 307 to preserve HTTP method
|
||||
const redirectUrl = `/api/v1${path}${req.url.includes('?') ? req.url.substring(req.url.indexOf('?')) : ''}`;
|
||||
@@ -296,13 +302,13 @@ app.use('/api/v1', (req, res, next) => {
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
| ----------------------------------- | --------------------------------------------- |
|
||||
| `server.ts` | Route registration with version prefixes |
|
||||
| `src/services/apiClient.ts` | Frontend API base URL configuration |
|
||||
| `src/config/swagger.ts` | OpenAPI server URL and version info |
|
||||
| `src/routes/*.routes.ts` | Individual route handlers |
|
||||
| `src/middleware/versionRedirect.ts` | Backwards compatibility redirects (Phase 1) |
|
||||
| File | Purpose |
|
||||
| ----------------------------------- | ------------------------------------------- |
|
||||
| `server.ts` | Route registration with version prefixes |
|
||||
| `src/services/apiClient.ts` | Frontend API base URL configuration |
|
||||
| `src/config/swagger.ts` | OpenAPI server URL and version info |
|
||||
| `src/routes/*.routes.ts` | Individual route handlers |
|
||||
| `src/middleware/versionRedirect.ts` | Backwards compatibility redirects (Phase 1) |
|
||||
|
||||
## Related ADRs
|
||||
|
||||
@@ -310,6 +316,7 @@ app.use('/api/v1', (req, res, next) => {
|
||||
- [ADR-018](./0018-api-documentation-strategy.md) - API Documentation Strategy (versioned OpenAPI specs)
|
||||
- [ADR-028](./0028-api-response-standardization.md) - Response Standardization (envelope pattern applies to all versions)
|
||||
- [ADR-016](./0016-api-security-hardening.md) - Security Hardening (applies to all versions)
|
||||
- [ADR-057](./0057-test-remediation-post-api-versioning.md) - Test Remediation Post-API Versioning (documents test migration)
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
@@ -323,12 +330,76 @@ app.use('/api/v1', (req, res, next) => {
|
||||
- [x] Update API documentation examples (Swagger server URL updated)
|
||||
- [x] Verify all health checks work at `/api/v1/health/*`
|
||||
|
||||
### Phase 2 Tasks (Future)
|
||||
### Phase 2 Tasks
|
||||
|
||||
- [ ] Create version router factory
|
||||
- [ ] Implement deprecation header middleware
|
||||
- [ ] Add version detection to request context
|
||||
- [ ] Document versioning patterns for developers
|
||||
**Implementation Guide**: [API Versioning Infrastructure](../architecture/api-versioning-infrastructure.md)
|
||||
**Developer Guide**: [API Versioning Developer Guide](../development/API-VERSIONING.md)
|
||||
|
||||
- [x] Create version router factory (`src/routes/versioned.ts`)
|
||||
- [x] Implement deprecation header middleware (`src/middleware/deprecation.middleware.ts`)
|
||||
- [x] Add version detection to request context (`src/middleware/apiVersion.middleware.ts`)
|
||||
- [x] Add version types to Express Request (`src/types/express.d.ts`)
|
||||
- [x] Create version constants configuration (`src/config/apiVersions.ts`)
|
||||
- [x] Update server.ts to use version router factory
|
||||
- [x] Update swagger.ts for multi-server documentation
|
||||
- [x] Add unit tests for version middleware
|
||||
- [x] Add integration tests for versioned router
|
||||
- [x] Document versioning patterns for developers
|
||||
- [x] Migrate all test files to use `/api/v1/` paths (23 files, ~70 occurrences)
|
||||
|
||||
### Test Path Migration Summary (2026-01-27)
|
||||
|
||||
The final cleanup task for Phase 2 was completed by updating all integration test files to use versioned API paths:
|
||||
|
||||
| Metric | Value |
|
||||
| ---------------------------- | ---------------------------------------- |
|
||||
| Test files updated | 23 |
|
||||
| Path occurrences changed | ~70 |
|
||||
| Test failures resolved | 71 (274 -> 345 passing) |
|
||||
| Tests remaining todo/skipped | 3 (known issues, not versioning-related) |
|
||||
| Type check | Passing |
|
||||
| Versioning-specific tests | 82/82 passing |
|
||||
|
||||
**Test Results After Migration**:
|
||||
|
||||
- Integration tests: 345/348 passing
|
||||
- Unit tests: 3,375/3,391 passing (16 pre-existing failures unrelated to versioning)
|
||||
|
||||
### Unit Test Path Fix (2026-01-27)
|
||||
|
||||
Following the test path migration, 16 unit test failures were discovered and fixed. These failures were caused by error log messages using hardcoded `/api/` paths instead of versioned `/api/v1/` paths.
|
||||
|
||||
**Root Cause**: Error log messages in route handlers used hardcoded path strings like:
|
||||
|
||||
```typescript
|
||||
// INCORRECT - hardcoded path doesn't reflect actual request URL
|
||||
req.log.error({ error }, 'Error in /api/flyers/:id:');
|
||||
```
|
||||
|
||||
**Solution**: Updated to use `req.originalUrl` for dynamic path logging:
|
||||
|
||||
```typescript
|
||||
// CORRECT - uses actual request URL including version prefix
|
||||
req.log.error({ error }, `Error in ${req.originalUrl.split('?')[0]}:`);
|
||||
```
|
||||
|
||||
**Files Modified**:
|
||||
|
||||
| File | Changes |
|
||||
| -------------------------------------- | ---------------------------------- |
|
||||
| `src/routes/recipe.routes.ts` | 3 error log statements updated |
|
||||
| `src/routes/stats.routes.ts` | 1 error log statement updated |
|
||||
| `src/routes/flyer.routes.ts` | 2 error logs + 2 test expectations |
|
||||
| `src/routes/personalization.routes.ts` | 3 error log statements updated |
|
||||
|
||||
**Test Results After Fix**:
|
||||
|
||||
- Unit tests: 3,382/3,391 passing (0 failures in fixed files)
|
||||
- Remaining 9 failures are pre-existing, unrelated issues (CSS/mocking)
|
||||
|
||||
**Best Practice**: See [Error Logging Path Patterns](../development/ERROR-LOGGING-PATHS.md) for guidance on logging request paths in error handlers.
|
||||
|
||||
**Migration Documentation**: [Test Path Migration Guide](../development/test-path-migration.md)
|
||||
|
||||
### Phase 3 Tasks (Future)
|
||||
|
||||
|
||||
@@ -363,6 +363,13 @@ The following files contain acknowledged code smell violations that are deferred
|
||||
- `src/tests/utils/mockFactories.ts` - Mock factories (1553 lines)
|
||||
- `src/tests/utils/testHelpers.ts` - Test utilities
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-014](./0014-containerization-and-deployment-strategy.md) - Containerization (tests must run in dev container)
|
||||
- [ADR-040](./0040-testing-economics-and-priorities.md) - Testing Economics and Priorities
|
||||
- [ADR-045](./0045-test-data-factories-and-fixtures.md) - Test Data Factories and Fixtures
|
||||
- [ADR-057](./0057-test-remediation-post-api-versioning.md) - Test Remediation Post-API Versioning
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Browser E2E Tests**: Consider adding Playwright for actual browser testing
|
||||
|
||||
@@ -2,7 +2,9 @@
|
||||
|
||||
**Date**: 2025-12-12
|
||||
|
||||
**Status**: Proposed
|
||||
**Status**: Superseded by [ADR-023](./0023-database-schema-migration-strategy.md)
|
||||
|
||||
**Note**: This ADR was an early draft. ADR-023 provides a more detailed specification for the same topic.
|
||||
|
||||
## Context
|
||||
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
**Status**: Proposed
|
||||
|
||||
**Supersedes**: [ADR-013](./0013-database-schema-migration-strategy.md)
|
||||
|
||||
## Context
|
||||
|
||||
The `README.md` indicates that the database schema is managed by manually running a large `schema.sql.txt` file. This approach is highly error-prone, makes tracking changes difficult, and is not feasible for updating a live production database without downtime or data loss.
|
||||
|
||||
@@ -1,18 +1,333 @@
|
||||
# ADR-024: Feature Flagging Strategy
|
||||
|
||||
**Date**: 2025-12-12
|
||||
**Status**: Accepted
|
||||
**Implemented**: 2026-01-28
|
||||
**Implementation Plan**: [2026-01-28-adr-024-feature-flags-implementation.md](../plans/2026-01-28-adr-024-feature-flags-implementation.md)
|
||||
|
||||
**Status**: Proposed
|
||||
## Implementation Summary
|
||||
|
||||
Feature flag infrastructure fully implemented with 89 new tests (all passing). Total test suite: 3,616 tests passing.
|
||||
|
||||
**Backend**:
|
||||
|
||||
- Zod-validated schema in `src/config/env.ts` with 6 feature flags
|
||||
- Service module `src/services/featureFlags.server.ts` with `isFeatureEnabled()`, `getFeatureFlags()`, `getEnabledFeatureFlags()`
|
||||
- Admin endpoint `GET /api/v1/admin/feature-flags` (requires admin authentication)
|
||||
- Convenience exports for direct boolean access
|
||||
|
||||
**Frontend**:
|
||||
|
||||
- Config section in `src/config.ts` with `VITE_FEATURE_*` environment variables
|
||||
- Type declarations in `src/vite-env.d.ts`
|
||||
- React hook `useFeatureFlag()` and `useAllFeatureFlags()` in `src/hooks/useFeatureFlag.ts`
|
||||
- Declarative component `<FeatureFlag>` in `src/components/FeatureFlag.tsx`
|
||||
|
||||
**Current Flags**: `bugsinkSync`, `advancedRbac`, `newDashboard`, `betaRecipes`, `experimentalAi`, `debugMode`
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
As the application grows, there is no way to roll out new features to a subset of users (e.g., for beta testing) or to quickly disable a problematic feature in production without a full redeployment.
|
||||
Application lacks controlled feature rollout capability. No mechanism for beta testing, quick production disablement, or gradual rollouts without full redeployment. Need type-safe, configuration-based system integrating with ADR-007 Zod validation.
|
||||
|
||||
## Decision
|
||||
|
||||
We will implement a feature flagging system. This could start with a simple configuration-based approach (defined in `ADR-007`) and evolve to use a dedicated service like **Flagsmith** or **LaunchDarkly**. This ADR will define how feature flags are created, managed, and checked in both the backend and frontend code.
|
||||
Implement environment-variable-based feature flag system. Backend: Zod-validated schema in `src/config/env.ts` + dedicated service. Frontend: Vite env vars + React hook + declarative component. All flags default `false` (opt-in model). Future migration path to Flagsmith/LaunchDarkly preserved via abstraction layer.
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive**: Decouples feature releases from code deployments, reducing risk and allowing for more controlled, gradual rollouts and A/B testing. Enables easier experimentation and faster iteration.
|
||||
**Negative**: Adds complexity to the codebase with conditional logic around features. Requires careful management of feature flag states to avoid technical debt.
|
||||
- **Positive**: Decouples releases from deployments → reduced risk, gradual rollouts, A/B testing capability
|
||||
- **Negative**: Conditional logic complexity → requires sunset policy (3-month max after full rollout)
|
||||
- **Neutral**: Restart required for flag changes (acceptable for current scale, external service removes this constraint)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Architecture Overview
|
||||
|
||||
```text
|
||||
Environment Variables (FEATURE_*, VITE_FEATURE_*)
|
||||
│
|
||||
├── Backend ──► src/config/env.ts (Zod) ──► src/services/featureFlags.server.ts
|
||||
│ │
|
||||
│ ┌──────────┴──────────┐
|
||||
│ │ │
|
||||
│ isFeatureEnabled() getAllFeatureFlags()
|
||||
│ │
|
||||
│ Routes/Services
|
||||
│
|
||||
└── Frontend ─► src/config.ts ──► src/hooks/useFeatureFlag.ts
|
||||
│
|
||||
┌──────────────┼──────────────┐
|
||||
│ │ │
|
||||
useFeatureFlag() useAllFeatureFlags() <FeatureFlag>
|
||||
│ Component
|
||||
Components
|
||||
```
|
||||
|
||||
### File Structure
|
||||
|
||||
| File | Purpose | Layer |
|
||||
| ------------------------------------- | ------------------------ | ---------------- |
|
||||
| `src/config/env.ts` | Zod schema + env loading | Backend config |
|
||||
| `src/services/featureFlags.server.ts` | Flag access service | Backend runtime |
|
||||
| `src/config.ts` | Vite env parsing | Frontend config |
|
||||
| `src/vite-env.d.ts` | TypeScript declarations | Frontend types |
|
||||
| `src/hooks/useFeatureFlag.ts` | React hook | Frontend runtime |
|
||||
| `src/components/FeatureFlag.tsx` | Declarative wrapper | Frontend UI |
|
||||
|
||||
### Naming Convention
|
||||
|
||||
| Context | Pattern | Example |
|
||||
| ------------------- | ------------------------- | ---------------------------------- |
|
||||
| Backend env var | `FEATURE_SNAKE_CASE` | `FEATURE_NEW_DASHBOARD` |
|
||||
| Frontend env var | `VITE_FEATURE_SNAKE_CASE` | `VITE_FEATURE_NEW_DASHBOARD` |
|
||||
| Config property | `camelCase` | `config.featureFlags.newDashboard` |
|
||||
| Hook/function param | `camelCase` literal | `isFeatureEnabled('newDashboard')` |
|
||||
|
||||
### Backend Implementation
|
||||
|
||||
#### Schema Definition (`src/config/env.ts`)
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Feature flags schema (ADR-024).
|
||||
* All flags default false (disabled) for safety.
|
||||
*/
|
||||
const featureFlagsSchema = z.object({
|
||||
newDashboard: booleanString(false), // FEATURE_NEW_DASHBOARD
|
||||
betaRecipes: booleanString(false), // FEATURE_BETA_RECIPES
|
||||
experimentalAi: booleanString(false), // FEATURE_EXPERIMENTAL_AI
|
||||
debugMode: booleanString(false), // FEATURE_DEBUG_MODE
|
||||
});
|
||||
|
||||
// In loadEnvVars():
|
||||
featureFlags: {
|
||||
newDashboard: process.env.FEATURE_NEW_DASHBOARD,
|
||||
betaRecipes: process.env.FEATURE_BETA_RECIPES,
|
||||
experimentalAi: process.env.FEATURE_EXPERIMENTAL_AI,
|
||||
debugMode: process.env.FEATURE_DEBUG_MODE,
|
||||
},
|
||||
```
|
||||
|
||||
#### Service Module (`src/services/featureFlags.server.ts`)
|
||||
|
||||
```typescript
|
||||
import { config, isDevelopment } from '../config/env';
|
||||
import { logger } from './logger.server';
|
||||
|
||||
export type FeatureFlagName = keyof typeof config.featureFlags;
|
||||
|
||||
/**
|
||||
* Check feature flag state. Logs in development mode.
|
||||
*/
|
||||
export function isFeatureEnabled(flagName: FeatureFlagName): boolean {
|
||||
const enabled = config.featureFlags[flagName];
|
||||
if (isDevelopment) {
|
||||
logger.debug({ flag: flagName, enabled }, 'Feature flag checked');
|
||||
}
|
||||
return enabled;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all flags (admin/debug endpoints).
|
||||
*/
|
||||
export function getAllFeatureFlags(): Record<FeatureFlagName, boolean> {
|
||||
return { ...config.featureFlags };
|
||||
}
|
||||
|
||||
// Convenience exports (evaluated once at startup)
|
||||
export const isNewDashboardEnabled = config.featureFlags.newDashboard;
|
||||
export const isBetaRecipesEnabled = config.featureFlags.betaRecipes;
|
||||
```
|
||||
|
||||
#### Usage in Routes
|
||||
|
||||
```typescript
|
||||
import { isFeatureEnabled } from '../services/featureFlags.server';
|
||||
|
||||
router.get('/dashboard', async (req, res) => {
|
||||
if (isFeatureEnabled('newDashboard')) {
|
||||
return sendSuccess(res, { version: 'v2', data: await getNewDashboardData() });
|
||||
}
|
||||
return sendSuccess(res, { version: 'v1', data: await getLegacyDashboardData() });
|
||||
});
|
||||
```
|
||||
|
||||
### Frontend Implementation
|
||||
|
||||
#### Config (`src/config.ts`)
|
||||
|
||||
```typescript
|
||||
const config = {
|
||||
// ... existing sections ...
|
||||
|
||||
featureFlags: {
|
||||
newDashboard: import.meta.env.VITE_FEATURE_NEW_DASHBOARD === 'true',
|
||||
betaRecipes: import.meta.env.VITE_FEATURE_BETA_RECIPES === 'true',
|
||||
experimentalAi: import.meta.env.VITE_FEATURE_EXPERIMENTAL_AI === 'true',
|
||||
debugMode: import.meta.env.VITE_FEATURE_DEBUG_MODE === 'true',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### Type Declarations (`src/vite-env.d.ts`)
|
||||
|
||||
```typescript
|
||||
interface ImportMetaEnv {
|
||||
readonly VITE_FEATURE_NEW_DASHBOARD?: string;
|
||||
readonly VITE_FEATURE_BETA_RECIPES?: string;
|
||||
readonly VITE_FEATURE_EXPERIMENTAL_AI?: string;
|
||||
readonly VITE_FEATURE_DEBUG_MODE?: string;
|
||||
}
|
||||
```
|
||||
|
||||
#### React Hook (`src/hooks/useFeatureFlag.ts`)
|
||||
|
||||
```typescript
|
||||
import { useMemo } from 'react';
|
||||
import config from '../config';
|
||||
|
||||
export type FeatureFlagName = keyof typeof config.featureFlags;
|
||||
|
||||
export function useFeatureFlag(flagName: FeatureFlagName): boolean {
|
||||
return useMemo(() => config.featureFlags[flagName], [flagName]);
|
||||
}
|
||||
|
||||
export function useAllFeatureFlags(): Record<FeatureFlagName, boolean> {
|
||||
return useMemo(() => ({ ...config.featureFlags }), []);
|
||||
}
|
||||
```
|
||||
|
||||
#### Declarative Component (`src/components/FeatureFlag.tsx`)
|
||||
|
||||
```typescript
|
||||
import { ReactNode } from 'react';
|
||||
import { useFeatureFlag, FeatureFlagName } from '../hooks/useFeatureFlag';
|
||||
|
||||
interface FeatureFlagProps {
|
||||
name: FeatureFlagName;
|
||||
children: ReactNode;
|
||||
fallback?: ReactNode;
|
||||
}
|
||||
|
||||
export function FeatureFlag({ name, children, fallback = null }: FeatureFlagProps) {
|
||||
const isEnabled = useFeatureFlag(name);
|
||||
return <>{isEnabled ? children : fallback}</>;
|
||||
}
|
||||
```
|
||||
|
||||
#### Usage in Components
|
||||
|
||||
```tsx
|
||||
// Declarative approach
|
||||
<FeatureFlag name="newDashboard" fallback={<LegacyDashboard />}>
|
||||
<NewDashboard />
|
||||
</FeatureFlag>;
|
||||
|
||||
// Hook approach (for logic beyond rendering)
|
||||
const isNewDashboard = useFeatureFlag('newDashboard');
|
||||
useEffect(() => {
|
||||
if (isNewDashboard) analytics.track('new_dashboard_viewed');
|
||||
}, [isNewDashboard]);
|
||||
```
|
||||
|
||||
### Testing Patterns
|
||||
|
||||
#### Backend Test Setup
|
||||
|
||||
```typescript
|
||||
// Reset modules to test different flag states
|
||||
beforeEach(() => {
|
||||
vi.resetModules();
|
||||
process.env.FEATURE_NEW_DASHBOARD = 'true';
|
||||
});
|
||||
|
||||
// src/services/featureFlags.server.test.ts
|
||||
describe('isFeatureEnabled', () => {
|
||||
it('returns false for disabled flags', () => {
|
||||
expect(isFeatureEnabled('newDashboard')).toBe(false);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
#### Frontend Test Setup
|
||||
|
||||
```typescript
|
||||
// Mock config module
|
||||
vi.mock('../config', () => ({
|
||||
default: {
|
||||
featureFlags: {
|
||||
newDashboard: true,
|
||||
betaRecipes: false,
|
||||
},
|
||||
},
|
||||
}));
|
||||
|
||||
// Component test
|
||||
describe('FeatureFlag', () => {
|
||||
it('renders fallback when disabled', () => {
|
||||
render(
|
||||
<FeatureFlag name="betaRecipes" fallback={<div>Old</div>}>
|
||||
<div>New</div>
|
||||
</FeatureFlag>
|
||||
);
|
||||
expect(screen.getByText('Old')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Flag Lifecycle
|
||||
|
||||
| Phase | Actions |
|
||||
| ---------- | -------------------------------------------------------------------------------------------- |
|
||||
| **Add** | 1. Add to both schemas (backend + frontend) 2. Default `false` 3. Document in `.env.example` |
|
||||
| **Enable** | Set env var `='true'` → restart application |
|
||||
| **Remove** | 1. Remove conditional code 2. Remove from schemas 3. Remove env vars |
|
||||
| **Sunset** | Max 3 months after full rollout → remove flag |
|
||||
|
||||
### Admin Endpoint (Optional)
|
||||
|
||||
```typescript
|
||||
// GET /api/v1/admin/feature-flags (admin-only)
|
||||
router.get('/feature-flags', requireAdmin, async (req, res) => {
|
||||
sendSuccess(res, { flags: getAllFeatureFlags() });
|
||||
});
|
||||
```
|
||||
|
||||
### Integration with ADR-007
|
||||
|
||||
Feature flags extend existing Zod configuration pattern:
|
||||
|
||||
- **Validation**: Same `booleanString()` transform used by other config
|
||||
- **Loading**: Same `loadEnvVars()` function loads `FEATURE_*` vars
|
||||
- **Type Safety**: `FeatureFlagName` type derived from config schema
|
||||
- **Fail-Fast**: Invalid flag values fail at startup (Zod validation)
|
||||
|
||||
### Future Migration Path
|
||||
|
||||
Current implementation abstracts flag access via `isFeatureEnabled()` function and `useFeatureFlag()` hook. External service migration requires:
|
||||
|
||||
1. Replace implementation internals of these functions
|
||||
2. Add API client for Flagsmith/LaunchDarkly
|
||||
3. No changes to consuming code (routes/components)
|
||||
|
||||
### Explicitly Out of Scope
|
||||
|
||||
- External service integration (Flagsmith/LaunchDarkly)
|
||||
- Database-stored flags
|
||||
- Real-time flag updates (WebSocket/SSE)
|
||||
- User-specific flags (A/B testing percentages)
|
||||
- Flag inheritance/hierarchy
|
||||
- Flag audit logging
|
||||
|
||||
### Key Files Reference
|
||||
|
||||
| Action | Files |
|
||||
| --------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| Add new flag | `src/config/env.ts`, `src/config.ts`, `src/vite-env.d.ts`, `.env.example` |
|
||||
| Check flag (backend) | Import from `src/services/featureFlags.server.ts` |
|
||||
| Check flag (frontend) | Import hook from `src/hooks/useFeatureFlag.ts` or component from `src/components/FeatureFlag.tsx` |
|
||||
| Test flag behavior | Mock via `vi.resetModules()` (backend) or `vi.mock('../config')` (frontend) |
|
||||
|
||||
@@ -195,6 +195,12 @@ Do NOT add tests:
|
||||
- Coverage percentages may not satisfy external audits
|
||||
- Requires judgment calls that may be inconsistent
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-010](./0010-testing-strategy-and-standards.md) - Testing Strategy and Standards (this ADR extends ADR-010)
|
||||
- [ADR-045](./0045-test-data-factories-and-fixtures.md) - Test Data Factories and Fixtures
|
||||
- [ADR-057](./0057-test-remediation-post-api-versioning.md) - Test Remediation Post-API Versioning
|
||||
|
||||
## Key Files
|
||||
|
||||
- `docs/adr/0010-testing-strategy-and-standards.md` - Testing mechanics
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**Status**: Accepted (Fully Implemented)
|
||||
|
||||
**Related**: [ADR-015](0015-application-performance-monitoring-and-error-tracking.md), [ADR-004](0004-standardized-application-wide-structured-logging.md)
|
||||
**Related**: [ADR-015](0015-error-tracking-and-observability.md), [ADR-004](0004-standardized-application-wide-structured-logging.md)
|
||||
|
||||
## Context
|
||||
|
||||
@@ -335,7 +335,7 @@ SELECT award_achievement('user-uuid', 'Nonexistent Badge');
|
||||
|
||||
## References
|
||||
|
||||
- [ADR-015: Application Performance Monitoring](0015-application-performance-monitoring-and-error-tracking.md)
|
||||
- [ADR-015: Error Tracking and Observability](0015-error-tracking-and-observability.md)
|
||||
- [ADR-004: Standardized Structured Logging](0004-standardized-application-wide-structured-logging.md)
|
||||
- [PostgreSQL RAISE Documentation](https://www.postgresql.org/docs/current/plpgsql-errors-and-messages.html)
|
||||
- [PostgreSQL Logging Configuration](https://www.postgresql.org/docs/current/runtime-config-logging.html)
|
||||
|
||||
@@ -332,6 +332,6 @@ Response:
|
||||
## References
|
||||
|
||||
- [ADR-006: Background Job Processing](./0006-background-job-processing-and-task-queues.md)
|
||||
- [ADR-015: Application Performance Monitoring](./0015-application-performance-monitoring-and-error-tracking.md)
|
||||
- [ADR-015: Error Tracking and Observability](./0015-error-tracking-and-observability.md)
|
||||
- [Bugsink API Documentation](https://bugsink.com/docs/api/)
|
||||
- [Gitea API Documentation](https://docs.gitea.io/en-us/api-usage/)
|
||||
|
||||
367
docs/adr/0057-test-remediation-post-api-versioning.md
Normal file
367
docs/adr/0057-test-remediation-post-api-versioning.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# ADR-057: Test Remediation Post-API Versioning and Frontend Rework
|
||||
|
||||
**Date**: 2026-01-28
|
||||
|
||||
**Status**: Accepted
|
||||
|
||||
**Context**: Major test remediation effort completed after ADR-008 API versioning implementation and frontend style rework
|
||||
|
||||
## Context
|
||||
|
||||
Following the completion of ADR-008 Phase 2 (API Versioning Strategy) and a concurrent frontend style/design rework, the test suite experienced 105 test failures across unit tests and E2E tests. This ADR documents the systematic remediation effort, root cause analysis, and lessons learned to prevent similar issues in future migrations.
|
||||
|
||||
### Scope of Failures
|
||||
|
||||
| Test Type | Failures | Total Tests | Pass Rate After Fix |
|
||||
| ---------- | -------- | ----------- | ------------------- |
|
||||
| Unit Tests | 69 | 3,392 | 100% |
|
||||
| E2E Tests | 36 | 36 | 100% |
|
||||
| **Total** | **105** | **3,428** | **100%** |
|
||||
|
||||
### Root Causes Identified
|
||||
|
||||
The failures were categorized into six distinct categories:
|
||||
|
||||
1. **API Versioning Path Mismatches** (71 failures)
|
||||
- Test files using `/api/` instead of `/api/v1/`
|
||||
- Environment variables not set for API base URL
|
||||
- Integration and E2E tests calling unversioned endpoints
|
||||
|
||||
2. **Dark Mode Class Assertion Failures** (8 failures)
|
||||
- Frontend rework changed Tailwind dark mode utility classes
|
||||
- Test assertions checking for outdated class names
|
||||
|
||||
3. **Selected Item Styling Changes** (6 failures)
|
||||
- Component styling refactored to new design tokens
|
||||
- Test assertions expecting old CSS class combinations
|
||||
|
||||
4. **Admin-Only Component Visibility** (12 failures)
|
||||
- MainLayout tests not properly mocking admin role
|
||||
- ActivityLog component visibility tied to role-based access
|
||||
|
||||
5. **Mock Hoisting Issues** (5 failures)
|
||||
- Queue mocks not available during module initialization
|
||||
- Vitest's module hoisting order causing mock setup failures
|
||||
|
||||
6. **Error Log Path Hardcoding** (3 failures)
|
||||
- Route handlers logging hardcoded paths like `/api/flyers`
|
||||
- Test assertions expecting versioned paths `/api/v1/flyers`
|
||||
|
||||
## Decision
|
||||
|
||||
We implemented a systematic remediation approach addressing each failure category with targeted fixes while establishing patterns to prevent regression.
|
||||
|
||||
### 1. API Versioning Configuration Updates
|
||||
|
||||
**Files Modified**:
|
||||
|
||||
- `vite.config.ts`
|
||||
- `vitest.config.e2e.ts`
|
||||
- `vitest.config.integration.ts`
|
||||
|
||||
**Pattern Applied**: Centralize API base URL in Vitest environment variables
|
||||
|
||||
```typescript
|
||||
// vite.config.ts - Unit test configuration
|
||||
test: {
|
||||
env: {
|
||||
// ADR-008: Ensure API versioning is correctly set for unit tests
|
||||
VITE_API_BASE_URL: '/api/v1',
|
||||
},
|
||||
// ...
|
||||
}
|
||||
|
||||
// vitest.config.e2e.ts - E2E test configuration
|
||||
test: {
|
||||
env: {
|
||||
// ADR-008: API versioning - all routes use /api/v1 prefix
|
||||
VITE_API_BASE_URL: 'http://localhost:3098/api/v1',
|
||||
},
|
||||
// ...
|
||||
}
|
||||
|
||||
// vitest.config.integration.ts - Integration test configuration
|
||||
test: {
|
||||
env: {
|
||||
// ADR-008: API versioning - all routes use /api/v1 prefix
|
||||
VITE_API_BASE_URL: 'http://localhost:3099/api/v1',
|
||||
},
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 2. E2E Test URL Path Updates
|
||||
|
||||
**Files Modified** (7 files, 31 URL occurrences):
|
||||
|
||||
- `src/tests/e2e/budget-journey.e2e.test.ts`
|
||||
- `src/tests/e2e/deals-journey.e2e.test.ts`
|
||||
- `src/tests/e2e/flyer-upload.e2e.test.ts`
|
||||
- `src/tests/e2e/inventory-journey.e2e.test.ts`
|
||||
- `src/tests/e2e/receipt-journey.e2e.test.ts`
|
||||
- `src/tests/e2e/upc-journey.e2e.test.ts`
|
||||
- `src/tests/e2e/user-journey.e2e.test.ts`
|
||||
|
||||
**Pattern Applied**: Update all hardcoded API paths to versioned endpoints
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
const response = await getRequest().post('/api/auth/register').send({...});
|
||||
|
||||
// After
|
||||
const response = await getRequest().post('/api/v1/auth/register').send({...});
|
||||
```
|
||||
|
||||
### 3. Unit Test Assertion Updates for UI Changes
|
||||
|
||||
**Files Modified**:
|
||||
|
||||
- `src/features/flyer/FlyerDisplay.test.tsx`
|
||||
- `src/features/flyer/FlyerList.test.tsx`
|
||||
|
||||
**Pattern Applied**: Update CSS class assertions to match new design system
|
||||
|
||||
```typescript
|
||||
// FlyerDisplay.test.tsx - Dark mode class update
|
||||
// Before
|
||||
expect(image).toHaveClass('dark:brightness-75');
|
||||
// After
|
||||
expect(image).toHaveClass('dark:brightness-90');
|
||||
|
||||
// FlyerList.test.tsx - Selected item styling update
|
||||
// Before
|
||||
expect(selectedItem).toHaveClass('ring-2', 'ring-brand-primary');
|
||||
// After
|
||||
expect(selectedItem).toHaveClass('border-brand-primary', 'bg-teal-50/50', 'dark:bg-teal-900/10');
|
||||
```
|
||||
|
||||
### 4. Admin-Only Component Test Separation
|
||||
|
||||
**File Modified**: `src/layouts/MainLayout.test.tsx`
|
||||
|
||||
**Pattern Applied**: Separate test cases for admin vs. regular user visibility
|
||||
|
||||
```typescript
|
||||
describe('for authenticated users', () => {
|
||||
beforeEach(() => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
...defaultUseAuthReturn,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
userProfile: createMockUserProfile({ user: mockUser }),
|
||||
});
|
||||
});
|
||||
|
||||
it('renders auth-gated components for regular users (PriceHistoryChart, Leaderboard)', () => {
|
||||
renderWithRouter(<MainLayout {...defaultProps} />);
|
||||
expect(screen.getByTestId('price-history-chart')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('leaderboard')).toBeInTheDocument();
|
||||
// ActivityLog is admin-only, should NOT be present for regular users
|
||||
expect(screen.queryByTestId('activity-log')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('renders ActivityLog for admin users', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
...defaultUseAuthReturn,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
userProfile: createMockUserProfile({ user: mockUser, role: 'admin' }),
|
||||
});
|
||||
renderWithRouter(<MainLayout {...defaultProps} />);
|
||||
expect(screen.getByTestId('activity-log')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 5. vi.hoisted() Pattern for Queue Mocks
|
||||
|
||||
**File Modified**: `src/routes/health.routes.test.ts`
|
||||
|
||||
**Pattern Applied**: Use `vi.hoisted()` to ensure mocks are available during module hoisting
|
||||
|
||||
```typescript
|
||||
// Use vi.hoisted to create mock queue objects that are available during vi.mock hoisting.
|
||||
// This ensures the mock objects exist when the factory function runs.
|
||||
const { mockQueuesModule } = vi.hoisted(() => {
|
||||
// Helper function to create a mock queue object with vi.fn()
|
||||
const createMockQueue = () => ({
|
||||
getJobCounts: vi.fn().mockResolvedValue({
|
||||
waiting: 0,
|
||||
active: 0,
|
||||
failed: 0,
|
||||
delayed: 0,
|
||||
}),
|
||||
});
|
||||
|
||||
return {
|
||||
mockQueuesModule: {
|
||||
flyerQueue: createMockQueue(),
|
||||
emailQueue: createMockQueue(),
|
||||
// ... additional queues
|
||||
},
|
||||
};
|
||||
});
|
||||
|
||||
// Mock the queues.server module BEFORE the health router imports it.
|
||||
vi.mock('../services/queues.server', () => mockQueuesModule);
|
||||
|
||||
// Import the router AFTER all mocks are defined.
|
||||
import healthRouter from './health.routes';
|
||||
```
|
||||
|
||||
### 6. Dynamic Error Log Paths
|
||||
|
||||
**Pattern Applied**: Use `req.originalUrl` instead of hardcoded paths in error handlers
|
||||
|
||||
```typescript
|
||||
// Before (INCORRECT - hardcoded path)
|
||||
req.log.error({ error }, 'Error in /api/flyers/:id:');
|
||||
|
||||
// After (CORRECT - dynamic path)
|
||||
req.log.error({ error }, `Error in ${req.originalUrl.split('?')[0]}:`);
|
||||
```
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
### Files Modified (14 total)
|
||||
|
||||
| Category | Files | Changes |
|
||||
| -------------------- | ----- | ------------------------------------------------- |
|
||||
| Vitest Configuration | 3 | Added `VITE_API_BASE_URL` environment variables |
|
||||
| E2E Tests | 7 | Updated 31 API endpoint URLs |
|
||||
| Unit Tests | 4 | Updated assertions for UI, mocks, and admin roles |
|
||||
|
||||
### Verification Results
|
||||
|
||||
After remediation, all tests pass in the dev container environment:
|
||||
|
||||
```text
|
||||
Unit Tests: 3,392 passing
|
||||
E2E Tests: 36 passing
|
||||
Integration: 345/348 passing (3 known issues, unrelated)
|
||||
Type Check: Passing
|
||||
```
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
1. **Test Suite Stability**: All tests now pass consistently in the dev container
|
||||
2. **API Versioning Compliance**: Tests enforce the `/api/v1/` path requirement
|
||||
3. **Pattern Documentation**: Clear patterns established for future test maintenance
|
||||
4. **Separation of Concerns**: Admin vs. user test cases properly separated
|
||||
5. **Mock Reliability**: `vi.hoisted()` pattern prevents mock timing issues
|
||||
|
||||
### Negative
|
||||
|
||||
1. **Maintenance Overhead**: Future API version changes will require test updates
|
||||
2. **Manual Migration**: No automated tool to update test paths during versioning
|
||||
|
||||
### Neutral
|
||||
|
||||
1. **Test Execution Time**: No significant impact on test execution duration
|
||||
2. **Coverage Metrics**: Coverage percentages unchanged
|
||||
|
||||
## Best Practices Established
|
||||
|
||||
### 1. API Versioning in Tests
|
||||
|
||||
**Always use versioned API paths in tests**:
|
||||
|
||||
```typescript
|
||||
// Good
|
||||
const response = await request.get('/api/v1/users/profile');
|
||||
|
||||
// Bad
|
||||
const response = await request.get('/api/users/profile');
|
||||
```
|
||||
|
||||
**Configure environment variables centrally in Vitest configs** rather than in individual test files.
|
||||
|
||||
### 2. vi.hoisted() for Module-Level Mocks
|
||||
|
||||
When mocking modules that are imported at the top level of other modules:
|
||||
|
||||
```typescript
|
||||
// Pattern: Define mocks with vi.hoisted() BEFORE vi.mock() calls
|
||||
const { mockModule } = vi.hoisted(() => ({
|
||||
mockModule: {
|
||||
someFunction: vi.fn(),
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock('./some-module', () => mockModule);
|
||||
|
||||
// Import AFTER mocks
|
||||
import { something } from './module-that-imports-some-module';
|
||||
```
|
||||
|
||||
### 3. Testing Conditional Component Rendering
|
||||
|
||||
When testing components that render differently based on user role:
|
||||
|
||||
1. Create separate `describe` blocks for each role
|
||||
2. Set up role-specific mocks in `beforeEach`
|
||||
3. Explicitly test both presence AND absence of role-gated components
|
||||
|
||||
### 4. CSS Class Assertions After UI Refactors
|
||||
|
||||
After frontend style changes:
|
||||
|
||||
1. Review component implementation for new class names
|
||||
2. Update test assertions to match actual CSS classes
|
||||
3. Consider using partial matching for complex class combinations:
|
||||
|
||||
```typescript
|
||||
// Flexible matching for Tailwind classes
|
||||
expect(element).toHaveClass('border-brand-primary');
|
||||
// vs exact matching
|
||||
expect(element).toHaveClass('border-brand-primary', 'bg-teal-50/50', 'dark:bg-teal-900/10');
|
||||
```
|
||||
|
||||
### 5. Error Logging Paths
|
||||
|
||||
**Always use dynamic paths in error logs**:
|
||||
|
||||
```typescript
|
||||
// Pattern: Use req.originalUrl for request path logging
|
||||
req.log.error({ error }, `Error in ${req.originalUrl.split('?')[0]}:`);
|
||||
```
|
||||
|
||||
This ensures error logs reflect the actual request URL including version prefixes.
|
||||
|
||||
## Migration Checklist for Future API Version Changes
|
||||
|
||||
When implementing a new API version (e.g., v2), follow this checklist:
|
||||
|
||||
- [ ] Update `vite.config.ts` test environment `VITE_API_BASE_URL`
|
||||
- [ ] Update `vitest.config.e2e.ts` test environment `VITE_API_BASE_URL`
|
||||
- [ ] Update `vitest.config.integration.ts` test environment `VITE_API_BASE_URL`
|
||||
- [ ] Search and replace `/api/v1/` with `/api/v2/` in E2E test files
|
||||
- [ ] Search and replace `/api/v1/` with `/api/v2/` in integration test files
|
||||
- [ ] Verify route handler error logs use `req.originalUrl`
|
||||
- [ ] Run full test suite in dev container to verify
|
||||
|
||||
**Search command for finding hardcoded paths**:
|
||||
|
||||
```bash
|
||||
grep -r "/api/v1/" src/tests/
|
||||
grep -r "'/api/" src/routes/*.ts
|
||||
```
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-008](./0008-api-versioning-strategy.md) - API Versioning Strategy
|
||||
- [ADR-010](./0010-testing-strategy-and-standards.md) - Testing Strategy and Standards
|
||||
- [ADR-014](./0014-containerization-and-deployment-strategy.md) - Platform: Linux Only
|
||||
- [ADR-040](./0040-testing-economics-and-priorities.md) - Testing Economics and Priorities
|
||||
- [ADR-012](./0012-frontend-component-library-and-design-system.md) - Frontend Component Library
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
| ------------------------------ | -------------------------------------------- |
|
||||
| `vite.config.ts` | Unit test environment configuration |
|
||||
| `vitest.config.e2e.ts` | E2E test environment configuration |
|
||||
| `vitest.config.integration.ts` | Integration test environment configuration |
|
||||
| `src/tests/e2e/*.e2e.test.ts` | E2E test files with versioned API paths |
|
||||
| `src/routes/*.routes.test.ts` | Route test files with `vi.hoisted()` pattern |
|
||||
| `docs/development/TESTING.md` | Testing guide with best practices |
|
||||
@@ -15,9 +15,10 @@ This document tracks the implementation status and estimated effort for all Arch
|
||||
|
||||
| Status | Count |
|
||||
| ---------------------------- | ----- |
|
||||
| Accepted (Fully Implemented) | 39 |
|
||||
| Accepted (Fully Implemented) | 42 |
|
||||
| Partially Implemented | 2 |
|
||||
| Proposed (Not Started) | 15 |
|
||||
| Proposed (Not Started) | 12 |
|
||||
| Superseded | 1 |
|
||||
|
||||
---
|
||||
|
||||
@@ -34,23 +35,23 @@ This document tracks the implementation status and estimated effort for all Arch
|
||||
|
||||
### Category 2: Data Management
|
||||
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| --------------------------------------------------------------- | ------------------------ | -------- | ------ | ------------------------------ |
|
||||
| [ADR-009](./0009-caching-strategy-for-read-heavy-operations.md) | Caching Strategy | Accepted | - | Fully implemented |
|
||||
| [ADR-013](./0013-database-schema-migration-strategy.md) | Schema Migrations v1 | Proposed | M | Superseded by ADR-023 |
|
||||
| [ADR-019](./0019-data-backup-and-recovery-strategy.md) | Backup & Recovery | Accepted | - | Fully implemented |
|
||||
| [ADR-023](./0023-database-schema-migration-strategy.md) | Schema Migrations v2 | Proposed | L | Requires tooling setup |
|
||||
| [ADR-031](./0031-data-retention-and-privacy-compliance.md) | Data Retention & Privacy | Proposed | XL | Legal/compliance review needed |
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| --------------------------------------------------------------- | ------------------------ | ---------- | ------ | ------------------------------ |
|
||||
| [ADR-009](./0009-caching-strategy-for-read-heavy-operations.md) | Caching Strategy | Accepted | - | Fully implemented |
|
||||
| [ADR-013](./0013-database-schema-migration-strategy.md) | Schema Migrations v1 | Superseded | - | Superseded by ADR-023 |
|
||||
| [ADR-019](./0019-data-backup-and-recovery-strategy.md) | Backup & Recovery | Accepted | - | Fully implemented |
|
||||
| [ADR-023](./0023-database-schema-migration-strategy.md) | Schema Migrations v2 | Proposed | L | Requires tooling setup |
|
||||
| [ADR-031](./0031-data-retention-and-privacy-compliance.md) | Data Retention & Privacy | Proposed | XL | Legal/compliance review needed |
|
||||
|
||||
### Category 3: API & Integration
|
||||
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| ------------------------------------------------------------------- | ------------------------ | ----------- | ------ | ------------------------------------- |
|
||||
| [ADR-003](./0003-standardized-input-validation-using-middleware.md) | Input Validation | Accepted | - | Fully implemented |
|
||||
| [ADR-008](./0008-api-versioning-strategy.md) | API Versioning | Proposed | L | Major URL/routing changes |
|
||||
| [ADR-018](./0018-api-documentation-strategy.md) | API Documentation | Accepted | - | OpenAPI/Swagger implemented |
|
||||
| [ADR-022](./0022-real-time-notification-system.md) | Real-time Notifications | Accepted | - | Fully implemented |
|
||||
| [ADR-028](./0028-api-response-standardization.md) | Response Standardization | Implemented | L | Completed (routes, middleware, tests) |
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| ------------------------------------------------------------------- | ------------------------ | -------- | ------ | ------------------------------------- |
|
||||
| [ADR-003](./0003-standardized-input-validation-using-middleware.md) | Input Validation | Accepted | - | Fully implemented |
|
||||
| [ADR-008](./0008-api-versioning-strategy.md) | API Versioning | Accepted | - | Phase 2 complete, tests migrated |
|
||||
| [ADR-018](./0018-api-documentation-strategy.md) | API Documentation | Accepted | - | OpenAPI/Swagger implemented |
|
||||
| [ADR-022](./0022-real-time-notification-system.md) | Real-time Notifications | Accepted | - | Fully implemented |
|
||||
| [ADR-028](./0028-api-response-standardization.md) | Response Standardization | Accepted | - | Completed (routes, middleware, tests) |
|
||||
|
||||
### Category 4: Security & Compliance
|
||||
|
||||
@@ -77,16 +78,16 @@ This document tracks the implementation status and estimated effort for all Arch
|
||||
|
||||
### Category 6: Deployment & Operations
|
||||
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| -------------------------------------------------------------- | ------------------ | -------- | ------ | -------------------------- |
|
||||
| [ADR-006](./0006-background-job-processing-and-task-queues.md) | Background Jobs | Accepted | - | Fully implemented |
|
||||
| [ADR-014](./0014-containerization-and-deployment-strategy.md) | Containerization | Partial | M | Docker done, K8s pending |
|
||||
| [ADR-017](./0017-ci-cd-and-branching-strategy.md) | CI/CD & Branching | Accepted | - | Fully implemented |
|
||||
| [ADR-024](./0024-feature-flagging-strategy.md) | Feature Flags | Proposed | M | New service/library needed |
|
||||
| [ADR-037](./0037-scheduled-jobs-and-cron-pattern.md) | Scheduled Jobs | Accepted | - | Fully implemented |
|
||||
| [ADR-038](./0038-graceful-shutdown-pattern.md) | Graceful Shutdown | Accepted | - | Fully implemented |
|
||||
| [ADR-053](./0053-worker-health-checks.md) | Worker Health | Accepted | - | Fully implemented |
|
||||
| [ADR-054](./0054-bugsink-gitea-issue-sync.md) | Bugsink-Gitea Sync | Proposed | L | Automated issue creation |
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| -------------------------------------------------------------- | ------------------ | -------- | ------ | ------------------------ |
|
||||
| [ADR-006](./0006-background-job-processing-and-task-queues.md) | Background Jobs | Accepted | - | Fully implemented |
|
||||
| [ADR-014](./0014-containerization-and-deployment-strategy.md) | Containerization | Partial | M | Docker done, K8s pending |
|
||||
| [ADR-017](./0017-ci-cd-and-branching-strategy.md) | CI/CD & Branching | Accepted | - | Fully implemented |
|
||||
| [ADR-024](./0024-feature-flagging-strategy.md) | Feature Flags | Accepted | - | Fully implemented |
|
||||
| [ADR-037](./0037-scheduled-jobs-and-cron-pattern.md) | Scheduled Jobs | Accepted | - | Fully implemented |
|
||||
| [ADR-038](./0038-graceful-shutdown-pattern.md) | Graceful Shutdown | Accepted | - | Fully implemented |
|
||||
| [ADR-053](./0053-worker-health-checks.md) | Worker Health | Accepted | - | Fully implemented |
|
||||
| [ADR-054](./0054-bugsink-gitea-issue-sync.md) | Bugsink-Gitea Sync | Proposed | L | Automated issue creation |
|
||||
|
||||
### Category 7: Frontend / User Interface
|
||||
|
||||
@@ -108,6 +109,7 @@ This document tracks the implementation status and estimated effort for all Arch
|
||||
| [ADR-040](./0040-testing-economics-and-priorities.md) | Testing Economics | Accepted | - | Fully implemented |
|
||||
| [ADR-045](./0045-test-data-factories-and-fixtures.md) | Test Data Factories | Accepted | - | Fully implemented |
|
||||
| [ADR-047](./0047-project-file-and-folder-organization.md) | Project Organization | Proposed | XL | Major reorganization |
|
||||
| [ADR-057](./0057-test-remediation-post-api-versioning.md) | Test Remediation | Accepted | - | Fully implemented |
|
||||
|
||||
### Category 9: Architecture Patterns
|
||||
|
||||
@@ -132,51 +134,54 @@ These ADRs are proposed or partially implemented, ordered by suggested implement
|
||||
|
||||
| Priority | ADR | Title | Status | Effort | Rationale |
|
||||
| -------- | ------- | ------------------------ | -------- | ------ | ------------------------------------ |
|
||||
| 1 | ADR-024 | Feature Flags | Proposed | M | Safer deployments, A/B testing |
|
||||
| 2 | ADR-054 | Bugsink-Gitea Sync | Proposed | L | Automated issue tracking from errors |
|
||||
| 3 | ADR-023 | Schema Migrations v2 | Proposed | L | Database evolution support |
|
||||
| 4 | ADR-029 | Secret Rotation | Proposed | L | Security improvement |
|
||||
| 5 | ADR-008 | API Versioning | Proposed | L | Future API evolution |
|
||||
| 6 | ADR-030 | Circuit Breaker | Proposed | L | Resilience improvement |
|
||||
| 7 | ADR-056 | APM (Performance) | Proposed | M | Enable when performance issues arise |
|
||||
| 8 | ADR-011 | Authorization & RBAC | Proposed | XL | Advanced permission system |
|
||||
| 9 | ADR-025 | i18n & l10n | Proposed | XL | Multi-language support |
|
||||
| 10 | ADR-031 | Data Retention & Privacy | Proposed | XL | Compliance requirements |
|
||||
| 1 | ADR-054 | Bugsink-Gitea Sync | Proposed | L | Automated issue tracking from errors |
|
||||
| 2 | ADR-023 | Schema Migrations v2 | Proposed | L | Database evolution support |
|
||||
| 3 | ADR-029 | Secret Rotation | Proposed | L | Security improvement |
|
||||
| 4 | ADR-030 | Circuit Breaker | Proposed | L | Resilience improvement |
|
||||
| 5 | ADR-056 | APM (Performance) | Proposed | M | Enable when performance issues arise |
|
||||
| 6 | ADR-011 | Authorization & RBAC | Proposed | XL | Advanced permission system |
|
||||
| 7 | ADR-025 | i18n & l10n | Proposed | XL | Multi-language support |
|
||||
| 8 | ADR-031 | Data Retention & Privacy | Proposed | XL | Compliance requirements |
|
||||
|
||||
---
|
||||
|
||||
## Recent Implementation History
|
||||
|
||||
| Date | ADR | Change |
|
||||
| ---------- | ------- | ---------------------------------------------------------------------------- |
|
||||
| 2026-01-26 | ADR-015 | Completed - Added Sentry user context in AuthProvider, now fully implemented |
|
||||
| 2026-01-26 | ADR-056 | Created - APM split from ADR-015, status Proposed (tracesSampleRate=0) |
|
||||
| 2026-01-26 | ADR-015 | Refactored to focus on error tracking only, temporarily status Partial |
|
||||
| 2026-01-26 | ADR-048 | Verified as fully implemented - JWT + OAuth authentication complete |
|
||||
| 2026-01-26 | ADR-022 | Verified as fully implemented - WebSocket notifications complete |
|
||||
| 2026-01-26 | ADR-052 | Marked as fully implemented - createScopedLogger complete |
|
||||
| 2026-01-26 | ADR-053 | Marked as fully implemented - /health/queues endpoint complete |
|
||||
| 2026-01-26 | ADR-050 | Marked as fully implemented - PostgreSQL function observability |
|
||||
| 2026-01-26 | ADR-055 | Created (renumbered from duplicate ADR-023) - DB normalization |
|
||||
| 2026-01-26 | ADR-054 | Added to tracker - Bugsink to Gitea issue synchronization |
|
||||
| 2026-01-26 | ADR-053 | Added to tracker - Worker health checks and monitoring |
|
||||
| 2026-01-26 | ADR-052 | Added to tracker - Granular debug logging strategy |
|
||||
| 2026-01-26 | ADR-051 | Added to tracker - Asynchronous context propagation |
|
||||
| 2026-01-26 | ADR-048 | Added to tracker - Authentication strategy |
|
||||
| 2026-01-26 | ADR-040 | Added to tracker - Testing economics and priorities |
|
||||
| 2026-01-17 | ADR-054 | Created - Bugsink-Gitea sync worker proposal |
|
||||
| 2026-01-11 | ADR-050 | Created - PostgreSQL function observability with fn_log() |
|
||||
| 2026-01-11 | ADR-018 | Implemented - OpenAPI/Swagger documentation at /docs/api-docs |
|
||||
| 2026-01-11 | ADR-049 | Created - Gamification system, achievements, and testing |
|
||||
| 2026-01-09 | ADR-047 | Created - Project file/folder organization with migration plan |
|
||||
| 2026-01-09 | ADR-041 | Created - AI/Gemini integration with model fallback |
|
||||
| 2026-01-09 | ADR-042 | Created - Email and notification architecture with BullMQ |
|
||||
| 2026-01-09 | ADR-043 | Created - Express middleware pipeline ordering and patterns |
|
||||
| 2026-01-09 | ADR-044 | Created - Frontend feature-based folder organization |
|
||||
| 2026-01-09 | ADR-045 | Created - Test data factory pattern for mock generation |
|
||||
| 2026-01-09 | ADR-046 | Created - Image processing pipeline with Sharp and EXIF stripping |
|
||||
| 2026-01-09 | ADR-026 | Fully implemented - client-side structured logger |
|
||||
| 2026-01-09 | ADR-028 | Fully implemented - all routes, middleware, and tests updated |
|
||||
| Date | ADR | Change |
|
||||
| ---------- | ------- | ----------------------------------------------------------------------------------- |
|
||||
| 2026-01-28 | ADR-024 | Fully implemented - Backend/frontend feature flags, 89 tests, admin endpoint |
|
||||
| 2026-01-28 | ADR-057 | Created - Test remediation documentation for ADR-008 Phase 2 migration |
|
||||
| 2026-01-28 | ADR-013 | Marked as Superseded by ADR-023 |
|
||||
| 2026-01-27 | ADR-008 | Test path migration complete - 23 files, ~70 paths updated, 274->345 tests passing |
|
||||
| 2026-01-27 | ADR-008 | Phase 2 Complete - Version router factory, deprecation headers, 82 versioning tests |
|
||||
| 2026-01-26 | ADR-015 | Completed - Added Sentry user context in AuthProvider, now fully implemented |
|
||||
| 2026-01-26 | ADR-056 | Created - APM split from ADR-015, status Proposed (tracesSampleRate=0) |
|
||||
| 2026-01-26 | ADR-015 | Refactored to focus on error tracking only, temporarily status Partial |
|
||||
| 2026-01-26 | ADR-048 | Verified as fully implemented - JWT + OAuth authentication complete |
|
||||
| 2026-01-26 | ADR-022 | Verified as fully implemented - WebSocket notifications complete |
|
||||
| 2026-01-26 | ADR-052 | Marked as fully implemented - createScopedLogger complete |
|
||||
| 2026-01-26 | ADR-053 | Marked as fully implemented - /health/queues endpoint complete |
|
||||
| 2026-01-26 | ADR-050 | Marked as fully implemented - PostgreSQL function observability |
|
||||
| 2026-01-26 | ADR-055 | Created (renumbered from duplicate ADR-023) - DB normalization |
|
||||
| 2026-01-26 | ADR-054 | Added to tracker - Bugsink to Gitea issue synchronization |
|
||||
| 2026-01-26 | ADR-053 | Added to tracker - Worker health checks and monitoring |
|
||||
| 2026-01-26 | ADR-052 | Added to tracker - Granular debug logging strategy |
|
||||
| 2026-01-26 | ADR-051 | Added to tracker - Asynchronous context propagation |
|
||||
| 2026-01-26 | ADR-048 | Added to tracker - Authentication strategy |
|
||||
| 2026-01-26 | ADR-040 | Added to tracker - Testing economics and priorities |
|
||||
| 2026-01-17 | ADR-054 | Created - Bugsink-Gitea sync worker proposal |
|
||||
| 2026-01-11 | ADR-050 | Created - PostgreSQL function observability with fn_log() |
|
||||
| 2026-01-11 | ADR-018 | Implemented - OpenAPI/Swagger documentation at /docs/api-docs |
|
||||
| 2026-01-11 | ADR-049 | Created - Gamification system, achievements, and testing |
|
||||
| 2026-01-09 | ADR-047 | Created - Project file/folder organization with migration plan |
|
||||
| 2026-01-09 | ADR-041 | Created - AI/Gemini integration with model fallback |
|
||||
| 2026-01-09 | ADR-042 | Created - Email and notification architecture with BullMQ |
|
||||
| 2026-01-09 | ADR-043 | Created - Express middleware pipeline ordering and patterns |
|
||||
| 2026-01-09 | ADR-044 | Created - Frontend feature-based folder organization |
|
||||
| 2026-01-09 | ADR-045 | Created - Test data factory pattern for mock generation |
|
||||
| 2026-01-09 | ADR-046 | Created - Image processing pipeline with Sharp and EXIF stripping |
|
||||
| 2026-01-09 | ADR-026 | Fully implemented - client-side structured logger |
|
||||
| 2026-01-09 | ADR-028 | Fully implemented - all routes, middleware, and tests updated |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
This directory contains a log of the architectural decisions made for the Flyer Crawler project.
|
||||
|
||||
**[Implementation Tracker](./adr-implementation-tracker.md)**: Track implementation status and effort estimates for all ADRs.
|
||||
|
||||
## 1. Foundational / Core Infrastructure
|
||||
|
||||
**[ADR-002](./0002-standardized-transaction-management.md)**: Standardized Transaction Management and Unit of Work Pattern (Accepted)
|
||||
@@ -12,7 +14,7 @@ This directory contains a log of the architectural decisions made for the Flyer
|
||||
## 2. Data Management
|
||||
|
||||
**[ADR-009](./0009-caching-strategy-for-read-heavy-operations.md)**: Caching Strategy for Read-Heavy Operations (Accepted)
|
||||
**[ADR-013](./0013-database-schema-migration-strategy.md)**: Database Schema Migration Strategy (Proposed)
|
||||
**[ADR-013](./0013-database-schema-migration-strategy.md)**: Database Schema Migration Strategy (Superseded by ADR-023)
|
||||
**[ADR-019](./0019-data-backup-and-recovery-strategy.md)**: Data Backup and Recovery Strategy (Accepted)
|
||||
**[ADR-023](./0023-database-schema-migration-strategy.md)**: Database Schema Migration Strategy (Proposed)
|
||||
**[ADR-031](./0031-data-retention-and-privacy-compliance.md)**: Data Retention and Privacy Compliance (Proposed)
|
||||
@@ -20,9 +22,9 @@ This directory contains a log of the architectural decisions made for the Flyer
|
||||
## 3. API & Integration
|
||||
|
||||
**[ADR-003](./0003-standardized-input-validation-using-middleware.md)**: Standardized Input Validation using Middleware (Accepted)
|
||||
**[ADR-008](./0008-api-versioning-strategy.md)**: API Versioning Strategy (Accepted - Phase 1 Complete)
|
||||
**[ADR-008](./0008-api-versioning-strategy.md)**: API Versioning Strategy (Accepted - Phase 2 Complete)
|
||||
**[ADR-018](./0018-api-documentation-strategy.md)**: API Documentation Strategy (Accepted)
|
||||
**[ADR-022](./0022-real-time-notification-system.md)**: Real-time Notification System (Proposed)
|
||||
**[ADR-022](./0022-real-time-notification-system.md)**: Real-time Notification System (Accepted)
|
||||
**[ADR-028](./0028-api-response-standardization.md)**: API Response Standardization and Envelope Pattern (Implemented)
|
||||
|
||||
## 4. Security & Compliance
|
||||
@@ -33,12 +35,12 @@ This directory contains a log of the architectural decisions made for the Flyer
|
||||
**[ADR-029](./0029-secret-rotation-and-key-management.md)**: Secret Rotation and Key Management Strategy (Proposed)
|
||||
**[ADR-032](./0032-rate-limiting-strategy.md)**: Rate Limiting Strategy (Accepted)
|
||||
**[ADR-033](./0033-file-upload-and-storage-strategy.md)**: File Upload and Storage Strategy (Accepted)
|
||||
**[ADR-048](./0048-authentication-strategy.md)**: Authentication Strategy (Partially Implemented)
|
||||
**[ADR-048](./0048-authentication-strategy.md)**: Authentication Strategy (Accepted)
|
||||
|
||||
## 5. Observability & Monitoring
|
||||
|
||||
**[ADR-004](./0004-standardized-application-wide-structured-logging.md)**: Standardized Application-Wide Structured Logging (Accepted)
|
||||
**[ADR-015](./0015-error-tracking-and-observability.md)**: Error Tracking and Observability (Partial)
|
||||
**[ADR-015](./0015-error-tracking-and-observability.md)**: Error Tracking and Observability (Accepted)
|
||||
**[ADR-050](./0050-postgresql-function-observability.md)**: PostgreSQL Function Observability (Accepted)
|
||||
**[ADR-051](./0051-asynchronous-context-propagation.md)**: Asynchronous Context Propagation (Accepted)
|
||||
**[ADR-052](./0052-granular-debug-logging-strategy.md)**: Granular Debug Logging Strategy (Accepted)
|
||||
@@ -52,7 +54,7 @@ This directory contains a log of the architectural decisions made for the Flyer
|
||||
**[ADR-024](./0024-feature-flagging-strategy.md)**: Feature Flagging Strategy (Proposed)
|
||||
**[ADR-037](./0037-scheduled-jobs-and-cron-pattern.md)**: Scheduled Jobs and Cron Pattern (Accepted)
|
||||
**[ADR-038](./0038-graceful-shutdown-pattern.md)**: Graceful Shutdown Pattern (Accepted)
|
||||
**[ADR-053](./0053-worker-health-checks-and-monitoring.md)**: Worker Health Checks and Monitoring (Proposed)
|
||||
**[ADR-053](./0053-worker-health-checks.md)**: Worker Health Checks and Stalled Job Monitoring (Accepted)
|
||||
**[ADR-054](./0054-bugsink-gitea-issue-sync.md)**: Bugsink to Gitea Issue Synchronization (Proposed)
|
||||
|
||||
## 7. Frontend / User Interface
|
||||
@@ -71,6 +73,7 @@ This directory contains a log of the architectural decisions made for the Flyer
|
||||
**[ADR-040](./0040-testing-economics-and-priorities.md)**: Testing Economics and Priorities (Accepted)
|
||||
**[ADR-045](./0045-test-data-factories-and-fixtures.md)**: Test Data Factories and Fixtures (Accepted)
|
||||
**[ADR-047](./0047-project-file-and-folder-organization.md)**: Project File and Folder Organization (Proposed)
|
||||
**[ADR-057](./0057-test-remediation-post-api-versioning.md)**: Test Remediation Post-API Versioning (Accepted)
|
||||
|
||||
## 9. Architecture Patterns
|
||||
|
||||
|
||||
@@ -1,10 +1,168 @@
|
||||
# Database Setup
|
||||
# Database Architecture
|
||||
|
||||
Flyer Crawler uses PostgreSQL with several extensions for full-text search, geographic data, and UUID generation.
|
||||
**Version**: 0.12.20
|
||||
**Last Updated**: 2026-01-28
|
||||
|
||||
Flyer Crawler uses PostgreSQL 16 with PostGIS for geographic data, pg_trgm for fuzzy text search, and uuid-ossp for UUID generation. The database contains 65 tables organized into logical domains.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Schema Overview](#schema-overview)
|
||||
2. [Database Setup](#database-setup)
|
||||
3. [Schema Reference](#schema-reference)
|
||||
4. [Related Documentation](#related-documentation)
|
||||
|
||||
---
|
||||
|
||||
## Required Extensions
|
||||
## Schema Overview
|
||||
|
||||
The database is organized into the following domains:
|
||||
|
||||
### Core Infrastructure (6 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ----------------------- | ----------------------------------------- | ----------------- |
|
||||
| `users` | Authentication credentials and login data | `user_id` (UUID) |
|
||||
| `profiles` | Public user data, preferences, points | `user_id` (UUID) |
|
||||
| `addresses` | Normalized address storage with geocoding | `address_id` |
|
||||
| `activity_log` | User activity audit trail | `activity_log_id` |
|
||||
| `password_reset_tokens` | Temporary tokens for password reset | `token_id` |
|
||||
| `schema_info` | Schema deployment metadata | `environment` |
|
||||
|
||||
### Stores and Locations (4 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ------------------------ | --------------------------------------- | ------------------- |
|
||||
| `stores` | Grocery store chains (Safeway, Kroger) | `store_id` |
|
||||
| `store_locations` | Physical store locations with addresses | `store_location_id` |
|
||||
| `favorite_stores` | User store favorites | `user_id, store_id` |
|
||||
| `store_receipt_patterns` | Receipt text patterns for store ID | `pattern_id` |
|
||||
|
||||
### Flyers and Items (7 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ----------------------- | -------------------------------------- | ------------------------ |
|
||||
| `flyers` | Uploaded flyer metadata and status | `flyer_id` |
|
||||
| `flyer_items` | Individual deals extracted from flyers | `flyer_item_id` |
|
||||
| `flyer_locations` | Flyer-to-location associations | `flyer_location_id` |
|
||||
| `categories` | Item categorization (Produce, Dairy) | `category_id` |
|
||||
| `master_grocery_items` | Canonical grocery item dictionary | `master_grocery_item_id` |
|
||||
| `master_item_aliases` | Alternative names for master items | `alias_id` |
|
||||
| `unmatched_flyer_items` | Items pending master item matching | `unmatched_item_id` |
|
||||
|
||||
### Products and Brands (2 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ---------- | ---------------------------------------------- | ------------ |
|
||||
| `brands` | Brand names (Coca-Cola, Kraft) | `brand_id` |
|
||||
| `products` | Specific products (master item + brand + size) | `product_id` |
|
||||
|
||||
### Price Tracking (3 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ----------------------- | ---------------------------------- | ------------------ |
|
||||
| `item_price_history` | Historical prices for master items | `price_history_id` |
|
||||
| `user_submitted_prices` | User-contributed price reports | `submission_id` |
|
||||
| `suggested_corrections` | Suggested edits to flyer items | `correction_id` |
|
||||
|
||||
### User Features (8 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| -------------------- | ------------------------------------ | --------------------------- |
|
||||
| `user_watched_items` | Items user wants to track prices for | `user_watched_item_id` |
|
||||
| `user_alerts` | Price alert thresholds | `alert_id` |
|
||||
| `notifications` | User notifications | `notification_id` |
|
||||
| `user_item_aliases` | User-defined item name aliases | `alias_id` |
|
||||
| `user_follows` | User-to-user follow relationships | `follower_id, following_id` |
|
||||
| `user_reactions` | Reactions to content (likes, etc.) | `reaction_id` |
|
||||
| `budgets` | User-defined spending budgets | `budget_id` |
|
||||
| `search_queries` | Search history for analytics | `query_id` |
|
||||
|
||||
### Shopping Lists (4 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ----------------------- | ------------------------ | ------------------------- |
|
||||
| `shopping_lists` | User shopping lists | `shopping_list_id` |
|
||||
| `shopping_list_items` | Items on shopping lists | `shopping_list_item_id` |
|
||||
| `shared_shopping_lists` | Shopping list sharing | `shared_shopping_list_id` |
|
||||
| `shopping_trips` | Completed shopping trips | `trip_id` |
|
||||
| `shopping_trip_items` | Items purchased on trips | `trip_item_id` |
|
||||
|
||||
### Recipes (11 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| --------------------------------- | -------------------------------- | ------------------------- |
|
||||
| `recipes` | User recipes with metadata | `recipe_id` |
|
||||
| `recipe_ingredients` | Recipe ingredient list | `recipe_ingredient_id` |
|
||||
| `recipe_ingredient_substitutions` | Ingredient alternatives | `substitution_id` |
|
||||
| `tags` | Recipe tags (vegan, quick, etc.) | `tag_id` |
|
||||
| `recipe_tags` | Recipe-to-tag associations | `recipe_id, tag_id` |
|
||||
| `appliances` | Kitchen appliances | `appliance_id` |
|
||||
| `recipe_appliances` | Appliances needed for recipes | `recipe_id, appliance_id` |
|
||||
| `recipe_ratings` | User ratings for recipes | `rating_id` |
|
||||
| `recipe_comments` | User comments on recipes | `comment_id` |
|
||||
| `favorite_recipes` | User recipe favorites | `user_id, recipe_id` |
|
||||
| `recipe_collections` | User recipe collections | `collection_id` |
|
||||
|
||||
### Meal Planning (3 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ------------------- | -------------------------- | ----------------- |
|
||||
| `menu_plans` | Weekly/monthly meal plans | `menu_plan_id` |
|
||||
| `shared_menu_plans` | Menu plan sharing | `share_id` |
|
||||
| `planned_meals` | Individual meals in a plan | `planned_meal_id` |
|
||||
|
||||
### Pantry and Inventory (4 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| -------------------- | ------------------------------------ | ----------------- |
|
||||
| `pantry_items` | User pantry inventory | `pantry_item_id` |
|
||||
| `pantry_locations` | Storage locations (fridge, freezer) | `location_id` |
|
||||
| `expiry_date_ranges` | Reference shelf life data | `expiry_range_id` |
|
||||
| `expiry_alerts` | User expiry notification preferences | `expiry_alert_id` |
|
||||
| `expiry_alert_log` | Sent expiry notifications | `alert_log_id` |
|
||||
|
||||
### Receipts (4 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ------------------------ | ----------------------------- | ----------------- |
|
||||
| `receipts` | Scanned receipt metadata | `receipt_id` |
|
||||
| `receipt_items` | Items parsed from receipts | `receipt_item_id` |
|
||||
| `receipt_processing_log` | OCR/AI processing audit trail | `log_id` |
|
||||
|
||||
### UPC Scanning (2 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ---------------------- | ------------------------------- | ----------- |
|
||||
| `upc_scan_history` | User barcode scan history | `scan_id` |
|
||||
| `upc_external_lookups` | External UPC API response cache | `lookup_id` |
|
||||
|
||||
### Gamification (2 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ------------------- | ---------------------------- | ------------------------- |
|
||||
| `achievements` | Defined achievements | `achievement_id` |
|
||||
| `user_achievements` | Achievements earned by users | `user_id, achievement_id` |
|
||||
|
||||
### User Preferences (3 tables)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| --------------------------- | ---------------------------- | ------------------------- |
|
||||
| `dietary_restrictions` | Defined dietary restrictions | `restriction_id` |
|
||||
| `user_dietary_restrictions` | User dietary preferences | `user_id, restriction_id` |
|
||||
| `user_appliances` | Appliances user owns | `user_id, appliance_id` |
|
||||
|
||||
### Reference Data (1 table)
|
||||
|
||||
| Table | Purpose | Primary Key |
|
||||
| ------------------ | ----------------------- | --------------- |
|
||||
| `unit_conversions` | Unit conversion factors | `conversion_id` |
|
||||
|
||||
---
|
||||
|
||||
## Database Setup
|
||||
|
||||
### Required Extensions
|
||||
|
||||
| Extension | Purpose |
|
||||
| ----------- | ------------------------------------------- |
|
||||
@@ -14,7 +172,7 @@ Flyer Crawler uses PostgreSQL with several extensions for full-text search, geog
|
||||
|
||||
---
|
||||
|
||||
## Database Users
|
||||
### Database Users
|
||||
|
||||
This project uses **environment-specific database users** to isolate production and test environments:
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Flyer Crawler - System Architecture Overview
|
||||
|
||||
**Version**: 0.12.5
|
||||
**Last Updated**: 2026-01-22
|
||||
**Version**: 0.12.20
|
||||
**Last Updated**: 2026-01-28
|
||||
**Platform**: Linux (Production and Development)
|
||||
|
||||
---
|
||||
@@ -41,7 +41,7 @@
|
||||
|
||||
## System Architecture Diagram
|
||||
|
||||
```
|
||||
```text
|
||||
+-----------------------------------------------------------------------------------+
|
||||
| CLIENT LAYER |
|
||||
+-----------------------------------------------------------------------------------+
|
||||
@@ -153,10 +153,10 @@
|
||||
| Component | Technology | Version | Purpose |
|
||||
| ---------------------- | ---------- | -------- | -------------------------------- |
|
||||
| **Runtime** | Node.js | 22.x LTS | Server-side JavaScript runtime |
|
||||
| **Language** | TypeScript | 5.9.x | Type-safe JavaScript superset |
|
||||
| **Web Framework** | Express.js | 5.1.x | HTTP server and routing |
|
||||
| **Frontend Framework** | React | 19.2.x | UI component library |
|
||||
| **Build Tool** | Vite | 7.2.x | Frontend bundling and dev server |
|
||||
| **Language** | TypeScript | 5.9.3 | Type-safe JavaScript superset |
|
||||
| **Web Framework** | Express.js | 5.1.0 | HTTP server and routing |
|
||||
| **Frontend Framework** | React | 19.2.0 | UI component library |
|
||||
| **Build Tool** | Vite | 7.2.4 | Frontend bundling and dev server |
|
||||
|
||||
### Data Storage
|
||||
|
||||
@@ -176,23 +176,23 @@
|
||||
| **OAuth** | Google, GitHub | Social authentication |
|
||||
| **Email** | Nodemailer (SMTP) | Transactional emails |
|
||||
|
||||
### Background Processing
|
||||
### Background Processing Stack
|
||||
|
||||
| Component | Technology | Version | Purpose |
|
||||
| ------------------- | ---------- | ------- | --------------------------------- |
|
||||
| **Job Queues** | BullMQ | 5.65.x | Reliable async job processing |
|
||||
| **Job Queues** | BullMQ | 5.65.1 | Reliable async job processing |
|
||||
| **Process Manager** | PM2 | Latest | Process management and clustering |
|
||||
| **Scheduler** | node-cron | 4.2.x | Scheduled tasks |
|
||||
| **Scheduler** | node-cron | 4.2.1 | Scheduled tasks |
|
||||
|
||||
### Frontend Stack
|
||||
|
||||
| Component | Technology | Version | Purpose |
|
||||
| -------------------- | -------------- | ------- | ---------------------------------------- |
|
||||
| **State Management** | TanStack Query | 5.90.x | Server state caching and synchronization |
|
||||
| **Routing** | React Router | 7.9.x | Client-side routing |
|
||||
| **Styling** | Tailwind CSS | 4.1.x | Utility-first CSS framework |
|
||||
| **Icons** | Lucide React | 0.555.x | Icon components |
|
||||
| **Charts** | Recharts | 3.4.x | Data visualization |
|
||||
| **State Management** | TanStack Query | 5.90.12 | Server state caching and synchronization |
|
||||
| **Routing** | React Router | 7.9.6 | Client-side routing |
|
||||
| **Styling** | Tailwind CSS | 4.1.17 | Utility-first CSS framework |
|
||||
| **Icons** | Lucide React | 0.555.0 | Icon components |
|
||||
| **Charts** | Recharts | 3.4.1 | Data visualization |
|
||||
|
||||
### Observability and Quality
|
||||
|
||||
@@ -221,7 +221,7 @@ The frontend is a single-page application (SPA) built with React 19 and Vite.
|
||||
|
||||
**Directory Structure**:
|
||||
|
||||
```
|
||||
```text
|
||||
src/
|
||||
+-- components/ # Reusable UI components
|
||||
+-- contexts/ # React context providers
|
||||
@@ -244,17 +244,30 @@ The backend is a RESTful API server built with Express.js 5.
|
||||
- Structured logging with Pino
|
||||
- Standardized error handling (ADR-001)
|
||||
|
||||
**API Route Modules**:
|
||||
| Route | Purpose |
|
||||
|-------|---------|
|
||||
| `/api/auth` | Authentication (login, register, OAuth) |
|
||||
| `/api/users` | User profile management |
|
||||
| `/api/flyers` | Flyer CRUD and processing |
|
||||
| `/api/recipes` | Recipe management |
|
||||
| `/api/deals` | Best prices and deal discovery |
|
||||
| `/api/stores` | Store management |
|
||||
| `/api/admin` | Administrative functions |
|
||||
| `/api/health` | Health checks and monitoring |
|
||||
**API Route Modules** (all versioned under `/api/v1/*`):
|
||||
|
||||
| Route | Purpose |
|
||||
| ------------------------- | ----------------------------------------------- |
|
||||
| `/api/v1/auth` | Authentication (login, register, OAuth) |
|
||||
| `/api/v1/health` | Health checks and monitoring |
|
||||
| `/api/v1/system` | System administration (PM2 status, server info) |
|
||||
| `/api/v1/users` | User profile management |
|
||||
| `/api/v1/ai` | AI-powered features and flyer processing |
|
||||
| `/api/v1/admin` | Administrative functions |
|
||||
| `/api/v1/budgets` | Budget management and spending analysis |
|
||||
| `/api/v1/achievements` | Gamification and achievement system |
|
||||
| `/api/v1/flyers` | Flyer CRUD and processing |
|
||||
| `/api/v1/recipes` | Recipe management and recommendations |
|
||||
| `/api/v1/personalization` | Master items and user preferences |
|
||||
| `/api/v1/price-history` | Price tracking and trend analysis |
|
||||
| `/api/v1/stats` | Public statistics and analytics |
|
||||
| `/api/v1/upc` | UPC barcode scanning and product lookup |
|
||||
| `/api/v1/inventory` | Inventory and expiry tracking |
|
||||
| `/api/v1/receipts` | Receipt scanning and purchase history |
|
||||
| `/api/v1/deals` | Best prices and deal discovery |
|
||||
| `/api/v1/reactions` | Social features (reactions, sharing) |
|
||||
| `/api/v1/stores` | Store management and location services |
|
||||
| `/api/v1/categories` | Category browsing and product categorization |
|
||||
|
||||
### Database (PostgreSQL/PostGIS)
|
||||
|
||||
@@ -331,7 +344,7 @@ BullMQ workers handle asynchronous processing tasks. PM2 manages both the API se
|
||||
|
||||
### Flyer Processing Pipeline
|
||||
|
||||
```
|
||||
```text
|
||||
+-------------+ +----------------+ +------------------+ +---------------+
|
||||
| User | | Express | | BullMQ | | PostgreSQL |
|
||||
| Upload +---->+ Route +---->+ Queue +---->+ Storage |
|
||||
@@ -395,7 +408,7 @@ BullMQ workers handle asynchronous processing tasks. PM2 manages both the API se
|
||||
|
||||
The application follows a strict layered architecture as defined in ADR-035.
|
||||
|
||||
```
|
||||
```text
|
||||
+-----------------------------------------------------------------------+
|
||||
| ROUTES LAYER |
|
||||
| Responsibilities: |
|
||||
@@ -458,7 +471,7 @@ The application follows a strict layered architecture as defined in ADR-035.
|
||||
|
||||
### Entity Relationship Overview
|
||||
|
||||
```
|
||||
```text
|
||||
+------------------+ +------------------+ +------------------+
|
||||
| users | | profiles | | addresses |
|
||||
|------------------| |------------------| |------------------|
|
||||
@@ -537,7 +550,7 @@ The application follows a strict layered architecture as defined in ADR-035.
|
||||
|
||||
### JWT Token Architecture
|
||||
|
||||
```
|
||||
```text
|
||||
+-------------------+ +-------------------+ +-------------------+
|
||||
| Login Request | | Server | | Database |
|
||||
| (email/pass) +---->+ Validates +---->+ Verify User |
|
||||
@@ -576,7 +589,7 @@ The application follows a strict layered architecture as defined in ADR-035.
|
||||
|
||||
### Protected Route Flow
|
||||
|
||||
```
|
||||
```text
|
||||
+-------------------+ +-------------------+ +-------------------+
|
||||
| API Request | | requireAuth | | JWT Strategy |
|
||||
| + Bearer Token +---->+ Middleware +---->+ Validate |
|
||||
@@ -603,7 +616,7 @@ The application follows a strict layered architecture as defined in ADR-035.
|
||||
|
||||
### Worker Architecture
|
||||
|
||||
```
|
||||
```text
|
||||
+-------------------+ +-------------------+ +-------------------+
|
||||
| API Server | | Redis | | Worker Process |
|
||||
| (Queue Producer)| | (Job Storage) | | (Consumer) |
|
||||
@@ -635,7 +648,7 @@ The application follows a strict layered architecture as defined in ADR-035.
|
||||
|
||||
Jobs use exponential backoff for retries:
|
||||
|
||||
```
|
||||
```text
|
||||
Attempt 1: Immediate
|
||||
Attempt 2: Initial delay (e.g., 5 seconds)
|
||||
Attempt 3: 2x delay (e.g., 10 seconds)
|
||||
@@ -658,7 +671,7 @@ Attempt 4: 4x delay (e.g., 20 seconds)
|
||||
|
||||
### Environment Overview
|
||||
|
||||
```
|
||||
```text
|
||||
+-----------------------------------------------------------------------------------+
|
||||
| DEVELOPMENT |
|
||||
+-----------------------------------------------------------------------------------+
|
||||
@@ -710,7 +723,7 @@ Attempt 4: 4x delay (e.g., 20 seconds)
|
||||
|
||||
### Deployment Pipeline (ADR-017)
|
||||
|
||||
```
|
||||
```text
|
||||
+------------+ +------------+ +------------+ +------------+
|
||||
| Push to | | Gitea | | Build & | | Deploy |
|
||||
| main +---->+ Actions +---->+ Test +---->+ to Prod |
|
||||
@@ -762,11 +775,14 @@ The system architecture is governed by Architecture Decision Records (ADRs). Key
|
||||
|
||||
### API and Integration
|
||||
|
||||
| ADR | Title | Status |
|
||||
| ------- | ----------------------------- | ----------- |
|
||||
| ADR-003 | Standardized Input Validation | Accepted |
|
||||
| ADR-022 | Real-time Notification System | Proposed |
|
||||
| ADR-028 | API Response Standardization | Implemented |
|
||||
| ADR | Title | Status |
|
||||
| ------- | ----------------------------- | ---------------- |
|
||||
| ADR-003 | Standardized Input Validation | Accepted |
|
||||
| ADR-008 | API Versioning Strategy | Phase 1 Complete |
|
||||
| ADR-022 | Real-time Notification System | Proposed |
|
||||
| ADR-028 | API Response Standardization | Implemented |
|
||||
|
||||
**Implementation Guide**: [API Versioning Infrastructure](./api-versioning-infrastructure.md) (Phase 2)
|
||||
|
||||
### Security
|
||||
|
||||
@@ -836,22 +852,55 @@ The system architecture is governed by Architecture Decision Records (ADRs). Key
|
||||
| File | Purpose |
|
||||
| ----------------------------------------------- | --------------------------------------- |
|
||||
| `src/services/flyerProcessingService.server.ts` | Flyer processing pipeline orchestration |
|
||||
| `src/services/flyerAiProcessor.server.ts` | AI extraction for flyers |
|
||||
| `src/services/aiService.server.ts` | Google Gemini AI integration |
|
||||
| `src/services/cacheService.server.ts` | Redis caching abstraction |
|
||||
| `src/services/emailService.server.ts` | Email sending |
|
||||
| `src/services/queues.server.ts` | BullMQ queue definitions |
|
||||
| `src/services/queueService.server.ts` | Queue management and scheduling |
|
||||
| `src/services/workers.server.ts` | BullMQ worker definitions |
|
||||
| `src/services/websocketService.server.ts` | Real-time WebSocket notifications |
|
||||
| `src/services/receiptService.server.ts` | Receipt scanning and OCR |
|
||||
| `src/services/upcService.server.ts` | UPC barcode lookup |
|
||||
| `src/services/expiryService.server.ts` | Pantry expiry tracking |
|
||||
| `src/services/geocodingService.server.ts` | Address geocoding |
|
||||
| `src/services/analyticsService.server.ts` | Analytics and reporting |
|
||||
| `src/services/monitoringService.server.ts` | Health monitoring |
|
||||
| `src/services/barcodeService.server.ts` | Barcode detection |
|
||||
| `src/services/logger.server.ts` | Structured logging (Pino) |
|
||||
| `src/services/redis.server.ts` | Redis connection management |
|
||||
| `src/services/sentry.server.ts` | Error tracking (Sentry/Bugsink) |
|
||||
|
||||
### Database Files
|
||||
|
||||
| File | Purpose |
|
||||
| ---------------------------------- | -------------------------------------------- |
|
||||
| `src/services/db/connection.db.ts` | Database pool and transaction management |
|
||||
| `src/services/db/errors.db.ts` | Database error types |
|
||||
| `src/services/db/user.db.ts` | User repository |
|
||||
| `src/services/db/flyer.db.ts` | Flyer repository |
|
||||
| `sql/master_schema_rollup.sql` | Complete database schema (for test DB setup) |
|
||||
| `sql/initial_schema.sql` | Fresh installation schema |
|
||||
| File | Purpose |
|
||||
| --------------------------------------- | -------------------------------------------- |
|
||||
| `src/services/db/connection.db.ts` | Database pool and transaction management |
|
||||
| `src/services/db/errors.db.ts` | Database error types |
|
||||
| `src/services/db/index.db.ts` | Repository exports |
|
||||
| `src/services/db/user.db.ts` | User repository |
|
||||
| `src/services/db/flyer.db.ts` | Flyer repository |
|
||||
| `src/services/db/store.db.ts` | Store repository |
|
||||
| `src/services/db/storeLocation.db.ts` | Store location repository |
|
||||
| `src/services/db/recipe.db.ts` | Recipe repository |
|
||||
| `src/services/db/category.db.ts` | Category repository |
|
||||
| `src/services/db/personalization.db.ts` | Master items and personalization |
|
||||
| `src/services/db/shopping.db.ts` | Shopping lists repository |
|
||||
| `src/services/db/deals.db.ts` | Deals and best prices repository |
|
||||
| `src/services/db/price.db.ts` | Price history repository |
|
||||
| `src/services/db/receipt.db.ts` | Receipt repository |
|
||||
| `src/services/db/upc.db.ts` | UPC scan history repository |
|
||||
| `src/services/db/expiry.db.ts` | Expiry tracking repository |
|
||||
| `src/services/db/gamification.db.ts` | Achievements repository |
|
||||
| `src/services/db/budget.db.ts` | Budget repository |
|
||||
| `src/services/db/reaction.db.ts` | User reactions repository |
|
||||
| `src/services/db/notification.db.ts` | Notifications repository |
|
||||
| `src/services/db/address.db.ts` | Address repository |
|
||||
| `src/services/db/admin.db.ts` | Admin operations repository |
|
||||
| `src/services/db/conversion.db.ts` | Unit conversion repository |
|
||||
| `src/services/db/flyerLocation.db.ts` | Flyer locations repository |
|
||||
| `sql/master_schema_rollup.sql` | Complete database schema (for test DB setup) |
|
||||
| `sql/initial_schema.sql` | Fresh installation schema |
|
||||
|
||||
### Type Definitions
|
||||
|
||||
|
||||
521
docs/architecture/api-versioning-infrastructure.md
Normal file
521
docs/architecture/api-versioning-infrastructure.md
Normal file
@@ -0,0 +1,521 @@
|
||||
# API Versioning Infrastructure (ADR-008 Phase 2)
|
||||
|
||||
**Status**: Complete
|
||||
**Date**: 2026-01-27
|
||||
**Prerequisite**: ADR-008 Phase 1 Complete (all routes at `/api/v1/*`)
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
Phase 2 has been fully implemented with the following results:
|
||||
|
||||
| Metric | Value |
|
||||
| ------------------ | -------------------------------------- |
|
||||
| New Files Created | 5 |
|
||||
| Files Modified | 2 (server.ts, express.d.ts) |
|
||||
| Unit Tests | 82 passing (100%) |
|
||||
| Integration Tests | 48 new versioning tests |
|
||||
| RFC Compliance | RFC 8594 (Sunset), RFC 8288 (Link) |
|
||||
| Supported Versions | v1 (active), v2 (infrastructure ready) |
|
||||
|
||||
**Developer Guide**: [API-VERSIONING.md](../development/API-VERSIONING.md)
|
||||
|
||||
## Purpose
|
||||
|
||||
Build infrastructure to support parallel API versions, version detection, and deprecation workflows. Enables future v2 API without breaking existing clients.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```text
|
||||
Request → Version Router → Version Middleware → Domain Router → Handler
|
||||
↓ ↓
|
||||
createVersionedRouter() attachVersionInfo()
|
||||
↓ ↓
|
||||
/api/v1/* | /api/v2/* req.apiVersion = 'v1'|'v2'
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
| Component | File | Responsibility |
|
||||
| ---------------------- | ------------------------------------------ | ------------------------------------------ |
|
||||
| Version Router Factory | `src/routes/versioned.ts` | Create version-specific Express routers |
|
||||
| Version Middleware | `src/middleware/apiVersion.middleware.ts` | Extract version, attach to request context |
|
||||
| Deprecation Middleware | `src/middleware/deprecation.middleware.ts` | Add RFC 8594 deprecation headers |
|
||||
| Version Types | `src/types/express.d.ts` | Extend Express Request with apiVersion |
|
||||
| Version Constants | `src/config/apiVersions.ts` | Centralized version definitions |
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### Task 1: Version Types (Foundation)
|
||||
|
||||
**File**: `src/types/express.d.ts`
|
||||
|
||||
```typescript
|
||||
declare global {
|
||||
namespace Express {
|
||||
interface Request {
|
||||
apiVersion?: 'v1' | 'v2';
|
||||
versionDeprecated?: boolean;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**: None
|
||||
**Testing**: Type-check only (`npm run type-check`)
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Version Constants
|
||||
|
||||
**File**: `src/config/apiVersions.ts`
|
||||
|
||||
```typescript
|
||||
export const API_VERSIONS = ['v1', 'v2'] as const;
|
||||
export type ApiVersion = (typeof API_VERSIONS)[number];
|
||||
|
||||
export const CURRENT_VERSION: ApiVersion = 'v1';
|
||||
export const DEFAULT_VERSION: ApiVersion = 'v1';
|
||||
|
||||
export interface VersionConfig {
|
||||
version: ApiVersion;
|
||||
status: 'active' | 'deprecated' | 'sunset';
|
||||
sunsetDate?: string; // ISO 8601
|
||||
successorVersion?: ApiVersion;
|
||||
}
|
||||
|
||||
export const VERSION_CONFIG: Record<ApiVersion, VersionConfig> = {
|
||||
v1: { version: 'v1', status: 'active' },
|
||||
v2: { version: 'v2', status: 'active' },
|
||||
};
|
||||
```
|
||||
|
||||
**Dependencies**: None
|
||||
**Testing**: Unit test for version validation
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Version Detection Middleware
|
||||
|
||||
**File**: `src/middleware/apiVersion.middleware.ts`
|
||||
|
||||
```typescript
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import { API_VERSIONS, ApiVersion, DEFAULT_VERSION } from '../config/apiVersions';
|
||||
|
||||
export function extractApiVersion(req: Request, _res: Response, next: NextFunction) {
|
||||
// Extract from URL path: /api/v1/... → 'v1'
|
||||
const pathMatch = req.path.match(/^\/v(\d+)\//);
|
||||
if (pathMatch) {
|
||||
const version = `v${pathMatch[1]}` as ApiVersion;
|
||||
if (API_VERSIONS.includes(version)) {
|
||||
req.apiVersion = version;
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback to default if not detected
|
||||
req.apiVersion = req.apiVersion || DEFAULT_VERSION;
|
||||
next();
|
||||
}
|
||||
```
|
||||
|
||||
**Pattern**: Attach to request before route handlers
|
||||
**Integration Point**: `server.ts` before versioned route mounting
|
||||
**Testing**: Unit tests for path extraction, default fallback
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Deprecation Headers Middleware
|
||||
|
||||
**File**: `src/middleware/deprecation.middleware.ts`
|
||||
|
||||
Implements RFC 8594 (Sunset Header) and draft-ietf-httpapi-deprecation-header.
|
||||
|
||||
```typescript
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import { VERSION_CONFIG, ApiVersion } from '../config/apiVersions';
|
||||
import { logger } from '../services/logger.server';
|
||||
|
||||
export function deprecationHeaders(version: ApiVersion) {
|
||||
const config = VERSION_CONFIG[version];
|
||||
|
||||
return (req: Request, res: Response, next: NextFunction) => {
|
||||
if (config.status === 'deprecated') {
|
||||
res.set('Deprecation', 'true');
|
||||
|
||||
if (config.sunsetDate) {
|
||||
res.set('Sunset', config.sunsetDate);
|
||||
}
|
||||
|
||||
if (config.successorVersion) {
|
||||
res.set('Link', `</api/${config.successorVersion}>; rel="successor-version"`);
|
||||
}
|
||||
|
||||
req.versionDeprecated = true;
|
||||
|
||||
// Log deprecation access for monitoring
|
||||
logger.warn(
|
||||
{
|
||||
apiVersion: version,
|
||||
path: req.path,
|
||||
method: req.method,
|
||||
sunsetDate: config.sunsetDate,
|
||||
},
|
||||
'Deprecated API version accessed',
|
||||
);
|
||||
}
|
||||
|
||||
// Always set version header
|
||||
res.set('X-API-Version', version);
|
||||
next();
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
**RFC Compliance**:
|
||||
|
||||
- `Deprecation: true` (draft-ietf-httpapi-deprecation-header)
|
||||
- `Sunset: <date>` (RFC 8594)
|
||||
- `Link: <url>; rel="successor-version"` (RFC 8288)
|
||||
|
||||
**Testing**: Unit tests for header presence, version status variations
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Version Router Factory
|
||||
|
||||
**File**: `src/routes/versioned.ts`
|
||||
|
||||
```typescript
|
||||
import { Router } from 'express';
|
||||
import { ApiVersion } from '../config/apiVersions';
|
||||
import { extractApiVersion } from '../middleware/apiVersion.middleware';
|
||||
import { deprecationHeaders } from '../middleware/deprecation.middleware';
|
||||
|
||||
// Import domain routers
|
||||
import authRouter from './auth.routes';
|
||||
import userRouter from './user.routes';
|
||||
import flyerRouter from './flyer.routes';
|
||||
// ... all domain routers
|
||||
|
||||
interface VersionedRouters {
|
||||
v1: Record<string, Router>;
|
||||
v2: Record<string, Router>;
|
||||
}
|
||||
|
||||
const ROUTERS: VersionedRouters = {
|
||||
v1: {
|
||||
auth: authRouter,
|
||||
users: userRouter,
|
||||
flyers: flyerRouter,
|
||||
// ... all v1 routers (current implementation)
|
||||
},
|
||||
v2: {
|
||||
// Future: v2-specific routers
|
||||
// auth: authRouterV2,
|
||||
// For now, fallback to v1
|
||||
},
|
||||
};
|
||||
|
||||
export function createVersionedRouter(version: ApiVersion): Router {
|
||||
const router = Router();
|
||||
|
||||
// Apply version middleware
|
||||
router.use(extractApiVersion);
|
||||
router.use(deprecationHeaders(version));
|
||||
|
||||
// Get routers for this version, fallback to v1
|
||||
const versionRouters = ROUTERS[version] || ROUTERS.v1;
|
||||
|
||||
// Mount domain routers
|
||||
Object.entries(versionRouters).forEach(([path, domainRouter]) => {
|
||||
router.use(`/${path}`, domainRouter);
|
||||
});
|
||||
|
||||
return router;
|
||||
}
|
||||
```
|
||||
|
||||
**Pattern**: Factory function returns configured Router
|
||||
**Fallback Strategy**: v2 uses v1 routers until v2-specific handlers exist
|
||||
**Testing**: Integration test verifying route mounting
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Server Integration
|
||||
|
||||
**File**: `server.ts` (modifications)
|
||||
|
||||
```typescript
|
||||
// Before (current implementation - Phase 1):
|
||||
app.use('/api/v1/auth', authRouter);
|
||||
app.use('/api/v1/users', userRouter);
|
||||
// ... individual route mounting
|
||||
|
||||
// After (Phase 2):
|
||||
import { createVersionedRouter } from './src/routes/versioned';
|
||||
|
||||
// Mount versioned API routers
|
||||
app.use('/api/v1', createVersionedRouter('v1'));
|
||||
app.use('/api/v2', createVersionedRouter('v2')); // Placeholder for future
|
||||
|
||||
// Keep redirect middleware for unversioned requests
|
||||
app.use('/api', versionRedirectMiddleware);
|
||||
```
|
||||
|
||||
**Breaking Change Risk**: Low (same routes, different mounting)
|
||||
**Rollback**: Revert to individual `app.use()` calls
|
||||
**Testing**: Full integration test suite must pass
|
||||
|
||||
---
|
||||
|
||||
### Task 7: Request Context Propagation
|
||||
|
||||
**Pattern**: Version flows through request lifecycle for conditional logic.
|
||||
|
||||
```typescript
|
||||
// In any route handler or service:
|
||||
function handler(req: Request, res: Response) {
|
||||
if (req.apiVersion === 'v2') {
|
||||
// v2-specific behavior
|
||||
return sendSuccess(res, transformV2(data));
|
||||
}
|
||||
// v1 behavior (default)
|
||||
return sendSuccess(res, data);
|
||||
}
|
||||
```
|
||||
|
||||
**Use Cases**:
|
||||
|
||||
- Response transformation based on version
|
||||
- Feature flags per version
|
||||
- Metric tagging by version
|
||||
|
||||
---
|
||||
|
||||
### Task 8: Documentation Update
|
||||
|
||||
**File**: `src/config/swagger.ts` (modifications)
|
||||
|
||||
```typescript
|
||||
const swaggerDefinition: OpenAPIV3.Document = {
|
||||
// ...
|
||||
servers: [
|
||||
{
|
||||
url: '/api/v1',
|
||||
description: 'API v1 (Current)',
|
||||
},
|
||||
{
|
||||
url: '/api/v2',
|
||||
description: 'API v2 (Future)',
|
||||
},
|
||||
],
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
**File**: `docs/adr/0008-api-versioning-strategy.md` (update checklist)
|
||||
|
||||
---
|
||||
|
||||
### Task 9: Unit Tests
|
||||
|
||||
**File**: `src/middleware/apiVersion.middleware.test.ts`
|
||||
|
||||
```typescript
|
||||
describe('extractApiVersion', () => {
|
||||
it('extracts v1 from /api/v1/users', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('extracts v2 from /api/v2/users', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('defaults to v1 for unversioned paths', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('ignores invalid version numbers', () => {
|
||||
/* ... */
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**File**: `src/middleware/deprecation.middleware.test.ts`
|
||||
|
||||
```typescript
|
||||
describe('deprecationHeaders', () => {
|
||||
it('adds no headers for active version', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('adds Deprecation header for deprecated version', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('adds Sunset header when sunsetDate configured', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('adds Link header for successor version', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('always sets X-API-Version header', () => {
|
||||
/* ... */
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 10: Integration Tests
|
||||
|
||||
**File**: `src/routes/versioned.test.ts`
|
||||
|
||||
```typescript
|
||||
describe('Versioned Router Integration', () => {
|
||||
it('mounts all v1 routes correctly', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('v2 falls back to v1 handlers', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('sets X-API-Version response header', () => {
|
||||
/* ... */
|
||||
});
|
||||
it('deprecation headers appear when configured', () => {
|
||||
/* ... */
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Run in Container**: `podman exec -it flyer-crawler-dev npm test -- versioned`
|
||||
|
||||
## Implementation Sequence
|
||||
|
||||
```text
|
||||
[Task 1] → [Task 2] → [Task 3] → [Task 4] → [Task 5] → [Task 6]
|
||||
Types Config Middleware Middleware Factory Server
|
||||
↓ ↓ ↓ ↓
|
||||
[Task 7] [Task 9] [Task 10] [Task 8]
|
||||
Context Unit Integ Docs
|
||||
```
|
||||
|
||||
**Critical Path**: 1 → 2 → 3 → 5 → 6 (server integration)
|
||||
|
||||
## File Structure After Implementation
|
||||
|
||||
```text
|
||||
src/
|
||||
├── config/
|
||||
│ ├── apiVersions.ts # NEW: Version constants
|
||||
│ └── swagger.ts # MODIFIED: Multi-server
|
||||
├── middleware/
|
||||
│ ├── apiVersion.middleware.ts # NEW: Version extraction
|
||||
│ ├── apiVersion.middleware.test.ts # NEW: Unit tests
|
||||
│ ├── deprecation.middleware.ts # NEW: RFC 8594 headers
|
||||
│ └── deprecation.middleware.test.ts # NEW: Unit tests
|
||||
├── routes/
|
||||
│ ├── versioned.ts # NEW: Router factory
|
||||
│ ├── versioned.test.ts # NEW: Integration tests
|
||||
│ └── *.routes.ts # UNCHANGED: Domain routers
|
||||
├── types/
|
||||
│ └── express.d.ts # MODIFIED: Add apiVersion
|
||||
server.ts # MODIFIED: Use versioned router
|
||||
```
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
| ------------------------------------ | ---------- | ------ | ----------------------------------- |
|
||||
| Route registration order breaks | Medium | High | Full integration test suite |
|
||||
| Middleware not applied to all routes | Low | Medium | Factory pattern ensures consistency |
|
||||
| Performance impact from middleware | Low | Low | Minimal overhead (path regex) |
|
||||
| Type errors in extended Request | Low | Medium | TypeScript strict mode catches |
|
||||
|
||||
## Rollback Procedure
|
||||
|
||||
1. Revert `server.ts` to individual route mounting
|
||||
2. Remove new middleware files (not breaking)
|
||||
3. Remove version types from `express.d.ts`
|
||||
4. Run `npm run type-check && npm test` to verify
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [x] All existing tests pass (`npm test` in container)
|
||||
- [x] `X-API-Version: v1` header on all `/api/v1/*` responses
|
||||
- [x] TypeScript compiles without errors (`npm run type-check`)
|
||||
- [x] No performance regression (< 5ms added latency)
|
||||
- [x] Deprecation headers work when v1 marked deprecated (manual test)
|
||||
|
||||
## Known Issues and Follow-up Work
|
||||
|
||||
### Integration Tests Using Unversioned Paths
|
||||
|
||||
**Issue**: Some existing integration tests make requests to unversioned paths (e.g., `/api/flyers` instead of `/api/v1/flyers`). These tests now receive 301 redirects due to the backwards compatibility middleware.
|
||||
|
||||
**Impact**: 74 integration tests may need updates to use versioned paths explicitly.
|
||||
|
||||
**Workaround Options**:
|
||||
|
||||
1. Update test paths to use `/api/v1/*` explicitly (recommended)
|
||||
2. Configure supertest to follow redirects automatically
|
||||
3. Accept 301 as valid response in affected tests
|
||||
|
||||
**Resolution**: Phase 3 work item - update integration tests to use versioned endpoints consistently.
|
||||
|
||||
### Phase 3 Prerequisites
|
||||
|
||||
Before marking v1 as deprecated and implementing v2:
|
||||
|
||||
1. Update all integration tests to use versioned paths
|
||||
2. Define breaking changes requiring v2
|
||||
3. Create v2-specific route handlers where needed
|
||||
4. Set deprecation timeline for v1
|
||||
|
||||
## Related ADRs
|
||||
|
||||
| ADR | Relationship |
|
||||
| ------- | ------------------------------------------------- |
|
||||
| ADR-008 | Parent decision (this implements Phase 2) |
|
||||
| ADR-003 | Validation middleware pattern applies per-version |
|
||||
| ADR-028 | Response format consistent across versions |
|
||||
| ADR-018 | OpenAPI docs reflect versioned endpoints |
|
||||
| ADR-043 | Middleware pipeline order considerations |
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Checking Version in Handler
|
||||
|
||||
```typescript
|
||||
// src/routes/flyer.routes.ts
|
||||
router.get('/', async (req, res) => {
|
||||
const flyers = await flyerRepo.getFlyers(req.log);
|
||||
|
||||
// Version-specific response transformation
|
||||
if (req.apiVersion === 'v2') {
|
||||
return sendSuccess(res, flyers.map(transformFlyerV2));
|
||||
}
|
||||
return sendSuccess(res, flyers);
|
||||
});
|
||||
```
|
||||
|
||||
### Marking Version as Deprecated
|
||||
|
||||
```typescript
|
||||
// src/config/apiVersions.ts
|
||||
export const VERSION_CONFIG = {
|
||||
v1: {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
},
|
||||
v2: { version: 'v2', status: 'active' },
|
||||
};
|
||||
```
|
||||
|
||||
### Testing Deprecation Headers
|
||||
|
||||
```bash
|
||||
curl -I https://localhost:3001/api/v1/flyers
|
||||
# When v1 deprecated:
|
||||
# Deprecation: true
|
||||
# Sunset: 2027-01-01T00:00:00Z
|
||||
# Link: </api/v2>; rel="successor-version"
|
||||
# X-API-Version: v1
|
||||
```
|
||||
844
docs/development/API-VERSIONING.md
Normal file
844
docs/development/API-VERSIONING.md
Normal file
@@ -0,0 +1,844 @@
|
||||
# API Versioning Developer Guide
|
||||
|
||||
**Status**: Complete (Phase 2)
|
||||
**Last Updated**: 2026-01-27
|
||||
**Implements**: ADR-008 Phase 2
|
||||
**Architecture**: [api-versioning-infrastructure.md](../architecture/api-versioning-infrastructure.md)
|
||||
|
||||
This guide covers the API versioning infrastructure for the Flyer Crawler application. It explains how versioning works, how to add new versions, and how to deprecate old ones.
|
||||
|
||||
## Implementation Status
|
||||
|
||||
| Component | Status | Tests |
|
||||
| ------------------------------ | -------- | -------------------- |
|
||||
| Version Constants | Complete | Unit tests |
|
||||
| Version Detection Middleware | Complete | 25 unit tests |
|
||||
| Deprecation Headers Middleware | Complete | 30 unit tests |
|
||||
| Version Router Factory | Complete | Integration tests |
|
||||
| Server Integration | Complete | 48 integration tests |
|
||||
| Developer Documentation | Complete | This guide |
|
||||
|
||||
**Total Tests**: 82 versioning-specific tests (100% passing)
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Architecture](#architecture)
|
||||
3. [Key Concepts](#key-concepts)
|
||||
4. [Developer Workflows](#developer-workflows)
|
||||
5. [Version Headers](#version-headers)
|
||||
6. [Testing Versioned Endpoints](#testing-versioned-endpoints)
|
||||
7. [Migration Guide: v1 to v2](#migration-guide-v1-to-v2)
|
||||
8. [Troubleshooting](#troubleshooting)
|
||||
9. [Related Documentation](#related-documentation)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The API uses URI-based versioning with the format `/api/v{MAJOR}/resource`. All endpoints are accessible at versioned paths like `/api/v1/flyers` or `/api/v2/users`.
|
||||
|
||||
### Current Version Status
|
||||
|
||||
| Version | Status | Description |
|
||||
| ------- | ------ | ------------------------------------- |
|
||||
| v1 | Active | Current production version |
|
||||
| v2 | Active | Future version (infrastructure ready) |
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Automatic version detection** from URL path
|
||||
- **RFC 8594 compliant deprecation headers** when versions are deprecated
|
||||
- **Backwards compatibility** via 301 redirects from unversioned paths
|
||||
- **Version-aware request context** for conditional logic in handlers
|
||||
- **Centralized configuration** for version lifecycle management
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Request Flow
|
||||
|
||||
```text
|
||||
Client Request: GET /api/v1/flyers
|
||||
|
|
||||
v
|
||||
+------+-------+
|
||||
| server.ts |
|
||||
| - Redirect |
|
||||
| middleware |
|
||||
+------+-------+
|
||||
|
|
||||
v
|
||||
+------+-------+
|
||||
| createApi |
|
||||
| Router() |
|
||||
+------+-------+
|
||||
|
|
||||
v
|
||||
+------+-------+
|
||||
| detectApi |
|
||||
| Version |
|
||||
| middleware |
|
||||
+------+-------+
|
||||
| req.apiVersion = 'v1'
|
||||
v
|
||||
+------+-------+
|
||||
| Versioned |
|
||||
| Router |
|
||||
| (v1) |
|
||||
+------+-------+
|
||||
|
|
||||
v
|
||||
+------+-------+
|
||||
| addDepreca |
|
||||
| tionHeaders |
|
||||
| middleware |
|
||||
+------+-------+
|
||||
| X-API-Version: v1
|
||||
v
|
||||
+------+-------+
|
||||
| Domain |
|
||||
| Router |
|
||||
| (flyers) |
|
||||
+------+-------+
|
||||
|
|
||||
v
|
||||
Response
|
||||
```
|
||||
|
||||
### Component Overview
|
||||
|
||||
| Component | File | Purpose |
|
||||
| ------------------- | ------------------------------------------ | ----------------------------------------------------- |
|
||||
| Version Constants | `src/config/apiVersions.ts` | Type definitions, version configs, utility functions |
|
||||
| Version Detection | `src/middleware/apiVersion.middleware.ts` | Extract version from URL, validate, attach to request |
|
||||
| Deprecation Headers | `src/middleware/deprecation.middleware.ts` | Add RFC 8594 headers for deprecated versions |
|
||||
| Router Factory | `src/routes/versioned.ts` | Create version-specific Express routers |
|
||||
| Type Extensions | `src/types/express.d.ts` | Add `apiVersion` and `versionDeprecation` to Request |
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### 1. Version Configuration
|
||||
|
||||
All version definitions live in `src/config/apiVersions.ts`:
|
||||
|
||||
```typescript
|
||||
// src/config/apiVersions.ts
|
||||
|
||||
// Supported versions as a const tuple
|
||||
export const API_VERSIONS = ['v1', 'v2'] as const;
|
||||
|
||||
// Union type: 'v1' | 'v2'
|
||||
export type ApiVersion = (typeof API_VERSIONS)[number];
|
||||
|
||||
// Version lifecycle status
|
||||
export type VersionStatus = 'active' | 'deprecated' | 'sunset';
|
||||
|
||||
// Configuration for each version
|
||||
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
|
||||
v1: {
|
||||
version: 'v1',
|
||||
status: 'active',
|
||||
},
|
||||
v2: {
|
||||
version: 'v2',
|
||||
status: 'active',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Version Detection
|
||||
|
||||
The `detectApiVersion` middleware extracts the version from `req.params.version` and validates it:
|
||||
|
||||
```typescript
|
||||
// How it works (src/middleware/apiVersion.middleware.ts)
|
||||
|
||||
// For valid versions:
|
||||
// GET /api/v1/flyers -> req.apiVersion = 'v1'
|
||||
|
||||
// For invalid versions:
|
||||
// GET /api/v99/flyers -> 404 with UNSUPPORTED_VERSION error
|
||||
```
|
||||
|
||||
### 3. Request Context
|
||||
|
||||
After middleware runs, the request object has version information:
|
||||
|
||||
```typescript
|
||||
// In any route handler
|
||||
router.get('/flyers', async (req, res) => {
|
||||
// Access the detected version
|
||||
const version = req.apiVersion; // 'v1' | 'v2'
|
||||
|
||||
// Check deprecation status
|
||||
if (req.versionDeprecation?.deprecated) {
|
||||
req.log.warn(
|
||||
{
|
||||
sunset: req.versionDeprecation.sunsetDate,
|
||||
},
|
||||
'Client using deprecated API',
|
||||
);
|
||||
}
|
||||
|
||||
// Version-specific behavior
|
||||
if (req.apiVersion === 'v2') {
|
||||
return sendSuccess(res, transformV2(data));
|
||||
}
|
||||
|
||||
return sendSuccess(res, data);
|
||||
});
|
||||
```
|
||||
|
||||
### 4. Route Registration
|
||||
|
||||
Routes are registered in `src/routes/versioned.ts` with version availability:
|
||||
|
||||
```typescript
|
||||
// src/routes/versioned.ts
|
||||
|
||||
export const ROUTES: RouteRegistration[] = [
|
||||
{
|
||||
path: 'auth',
|
||||
router: authRouter,
|
||||
description: 'Authentication routes',
|
||||
// Available in all versions (no versions array)
|
||||
},
|
||||
{
|
||||
path: 'flyers',
|
||||
router: flyerRouter,
|
||||
description: 'Flyer management',
|
||||
// Available in all versions
|
||||
},
|
||||
{
|
||||
path: 'new-feature',
|
||||
router: newFeatureRouter,
|
||||
description: 'New feature only in v2',
|
||||
versions: ['v2'], // Only available in v2
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Developer Workflows
|
||||
|
||||
### Adding a New API Version (e.g., v3)
|
||||
|
||||
**Step 1**: Add version to constants (`src/config/apiVersions.ts`)
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
export const API_VERSIONS = ['v1', 'v2'] as const;
|
||||
|
||||
// After
|
||||
export const API_VERSIONS = ['v1', 'v2', 'v3'] as const;
|
||||
|
||||
// Add configuration
|
||||
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
|
||||
v1: { version: 'v1', status: 'active' },
|
||||
v2: { version: 'v2', status: 'active' },
|
||||
v3: { version: 'v3', status: 'active' }, // NEW
|
||||
};
|
||||
```
|
||||
|
||||
**Step 2**: Router cache auto-updates (no changes needed)
|
||||
|
||||
The versioned router cache in `src/routes/versioned.ts` automatically creates routers for all versions defined in `API_VERSIONS`.
|
||||
|
||||
**Step 3**: Update OpenAPI documentation (`src/config/swagger.ts`)
|
||||
|
||||
```typescript
|
||||
servers: [
|
||||
{ url: '/api/v1', description: 'API v1' },
|
||||
{ url: '/api/v2', description: 'API v2' },
|
||||
{ url: '/api/v3', description: 'API v3 (New)' }, // NEW
|
||||
],
|
||||
```
|
||||
|
||||
**Step 4**: Test the new version
|
||||
|
||||
```bash
|
||||
# In dev container
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
|
||||
# Manual verification
|
||||
curl -i http://localhost:3001/api/v3/health
|
||||
# Should return 200 with X-API-Version: v3 header
|
||||
```
|
||||
|
||||
### Marking a Version as Deprecated
|
||||
|
||||
**Step 1**: Update version config (`src/config/apiVersions.ts`)
|
||||
|
||||
```typescript
|
||||
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
|
||||
v1: {
|
||||
version: 'v1',
|
||||
status: 'deprecated', // Changed from 'active'
|
||||
sunsetDate: '2027-01-01T00:00:00Z', // When it will be removed
|
||||
successorVersion: 'v2', // Migration target
|
||||
},
|
||||
v2: {
|
||||
version: 'v2',
|
||||
status: 'active',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
**Step 2**: Verify deprecation headers
|
||||
|
||||
```bash
|
||||
curl -I http://localhost:3001/api/v1/health
|
||||
|
||||
# Expected headers:
|
||||
# X-API-Version: v1
|
||||
# Deprecation: true
|
||||
# Sunset: 2027-01-01T00:00:00Z
|
||||
# Link: </api/v2>; rel="successor-version"
|
||||
# X-API-Deprecation-Notice: API v1 is deprecated and will be sunset...
|
||||
```
|
||||
|
||||
**Step 3**: Monitor deprecation usage
|
||||
|
||||
Check logs for `Deprecated API version accessed` messages with context about which clients are still using deprecated versions.
|
||||
|
||||
### Adding Version-Specific Routes
|
||||
|
||||
**Scenario**: Add a new endpoint only available in v2+
|
||||
|
||||
**Step 1**: Create the route handler (new or existing file)
|
||||
|
||||
```typescript
|
||||
// src/routes/newFeature.routes.ts
|
||||
import { Router } from 'express';
|
||||
import { sendSuccess } from '../utils/apiResponse';
|
||||
|
||||
const router = Router();
|
||||
|
||||
router.get('/', async (req, res) => {
|
||||
// This endpoint only exists in v2+
|
||||
sendSuccess(res, { feature: 'new-feature-data' });
|
||||
});
|
||||
|
||||
export default router;
|
||||
```
|
||||
|
||||
**Step 2**: Register with version restriction (`src/routes/versioned.ts`)
|
||||
|
||||
```typescript
|
||||
import newFeatureRouter from './newFeature.routes';
|
||||
|
||||
export const ROUTES: RouteRegistration[] = [
|
||||
// ... existing routes ...
|
||||
{
|
||||
path: 'new-feature',
|
||||
router: newFeatureRouter,
|
||||
description: 'New feature only available in v2+',
|
||||
versions: ['v2'], // Not available in v1
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
**Step 3**: Verify route availability
|
||||
|
||||
```bash
|
||||
# v1 - should return 404
|
||||
curl -i http://localhost:3001/api/v1/new-feature
|
||||
# HTTP/1.1 404 Not Found
|
||||
|
||||
# v2 - should work
|
||||
curl -i http://localhost:3001/api/v2/new-feature
|
||||
# HTTP/1.1 200 OK
|
||||
# X-API-Version: v2
|
||||
```
|
||||
|
||||
### Adding Version-Specific Behavior in Existing Routes
|
||||
|
||||
For routes that exist in multiple versions but behave differently:
|
||||
|
||||
```typescript
|
||||
// src/routes/flyer.routes.ts
|
||||
router.get('/:id', async (req, res) => {
|
||||
const flyer = await flyerService.getFlyer(req.params.id, req.log);
|
||||
|
||||
// Different response format per version
|
||||
if (req.apiVersion === 'v2') {
|
||||
// v2 returns expanded store data
|
||||
return sendSuccess(res, {
|
||||
...flyer,
|
||||
store: await storeService.getStore(flyer.store_id, req.log),
|
||||
});
|
||||
}
|
||||
|
||||
// v1 returns just the flyer
|
||||
return sendSuccess(res, flyer);
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version Headers
|
||||
|
||||
### Response Headers
|
||||
|
||||
All versioned API responses include these headers:
|
||||
|
||||
| Header | Always Present | Description |
|
||||
| -------------------------- | ------------------ | ------------------------------------------------------- |
|
||||
| `X-API-Version` | Yes | The API version handling the request |
|
||||
| `Deprecation` | Only if deprecated | `true` when version is deprecated |
|
||||
| `Sunset` | Only if configured | ISO 8601 date when version will be removed |
|
||||
| `Link` | Only if configured | URL to successor version with `rel="successor-version"` |
|
||||
| `X-API-Deprecation-Notice` | Only if deprecated | Human-readable deprecation message |
|
||||
|
||||
### Example: Active Version Response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
X-API-Version: v2
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Example: Deprecated Version Response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
X-API-Version: v1
|
||||
Deprecation: true
|
||||
Sunset: 2027-01-01T00:00:00Z
|
||||
Link: </api/v2>; rel="successor-version"
|
||||
X-API-Deprecation-Notice: API v1 is deprecated and will be sunset on 2027-01-01T00:00:00Z. Please migrate to v2.
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### RFC Compliance
|
||||
|
||||
The deprecation headers follow these standards:
|
||||
|
||||
- **RFC 8594**: The "Sunset" HTTP Header Field
|
||||
- **draft-ietf-httpapi-deprecation-header**: The "Deprecation" HTTP Header Field
|
||||
- **RFC 8288**: Web Linking (for `rel="successor-version"`)
|
||||
|
||||
---
|
||||
|
||||
## Testing Versioned Endpoints
|
||||
|
||||
### Unit Testing Middleware
|
||||
|
||||
See test files for patterns:
|
||||
|
||||
- `src/middleware/apiVersion.middleware.test.ts`
|
||||
- `src/middleware/deprecation.middleware.test.ts`
|
||||
|
||||
**Testing version detection**:
|
||||
|
||||
```typescript
|
||||
// src/middleware/apiVersion.middleware.test.ts
|
||||
import { detectApiVersion } from './apiVersion.middleware';
|
||||
import { createMockRequest } from '../tests/utils/createMockRequest';
|
||||
|
||||
describe('detectApiVersion', () => {
|
||||
it('should extract v1 from req.params.version', () => {
|
||||
const mockRequest = createMockRequest({
|
||||
params: { version: 'v1' },
|
||||
});
|
||||
const mockResponse = { status: vi.fn().mockReturnThis(), json: vi.fn() };
|
||||
const mockNext = vi.fn();
|
||||
|
||||
detectApiVersion(mockRequest, mockResponse, mockNext);
|
||||
|
||||
expect(mockRequest.apiVersion).toBe('v1');
|
||||
expect(mockNext).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should return 404 for invalid version', () => {
|
||||
const mockRequest = createMockRequest({
|
||||
params: { version: 'v99' },
|
||||
});
|
||||
const mockResponse = {
|
||||
status: vi.fn().mockReturnThis(),
|
||||
json: vi.fn(),
|
||||
};
|
||||
const mockNext = vi.fn();
|
||||
|
||||
detectApiVersion(mockRequest, mockResponse, mockNext);
|
||||
|
||||
expect(mockNext).not.toHaveBeenCalled();
|
||||
expect(mockResponse.status).toHaveBeenCalledWith(404);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Testing deprecation headers**:
|
||||
|
||||
```typescript
|
||||
// src/middleware/deprecation.middleware.test.ts
|
||||
import { addDeprecationHeaders } from './deprecation.middleware';
|
||||
import { VERSION_CONFIGS } from '../config/apiVersions';
|
||||
|
||||
describe('addDeprecationHeaders', () => {
|
||||
beforeEach(() => {
|
||||
// Mark v1 as deprecated for test
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
});
|
||||
|
||||
it('should add all deprecation headers', () => {
|
||||
const setHeader = vi.fn();
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
middleware(mockRequest, { set: setHeader }, mockNext);
|
||||
|
||||
expect(setHeader).toHaveBeenCalledWith('Deprecation', 'true');
|
||||
expect(setHeader).toHaveBeenCalledWith('Sunset', '2027-01-01T00:00:00Z');
|
||||
expect(setHeader).toHaveBeenCalledWith('Link', '</api/v2>; rel="successor-version"');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
|
||||
**Test versioned endpoints**:
|
||||
|
||||
```typescript
|
||||
import request from 'supertest';
|
||||
import app from '../../server';
|
||||
|
||||
describe('API Versioning Integration', () => {
|
||||
it('should return X-API-Version header for v1', async () => {
|
||||
const response = await request(app).get('/api/v1/health').expect(200);
|
||||
|
||||
expect(response.headers['x-api-version']).toBe('v1');
|
||||
});
|
||||
|
||||
it('should return 404 for unsupported version', async () => {
|
||||
const response = await request(app).get('/api/v99/health').expect(404);
|
||||
|
||||
expect(response.body.error.code).toBe('UNSUPPORTED_VERSION');
|
||||
});
|
||||
|
||||
it('should redirect unversioned paths to v1', async () => {
|
||||
const response = await request(app).get('/api/health').expect(301);
|
||||
|
||||
expect(response.headers.location).toBe('/api/v1/health');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests in container (required)
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
|
||||
# Run only middleware tests
|
||||
podman exec -it flyer-crawler-dev npm test -- apiVersion
|
||||
podman exec -it flyer-crawler-dev npm test -- deprecation
|
||||
|
||||
# Type check
|
||||
podman exec -it flyer-crawler-dev npm run type-check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide: v1 to v2
|
||||
|
||||
When v2 is introduced with breaking changes, follow this migration process.
|
||||
|
||||
### For API Consumers (Frontend/Mobile)
|
||||
|
||||
**Step 1**: Check current API version usage
|
||||
|
||||
```typescript
|
||||
// Frontend apiClient.ts
|
||||
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api/v1';
|
||||
```
|
||||
|
||||
**Step 2**: Monitor deprecation headers
|
||||
|
||||
When v1 is deprecated, responses will include:
|
||||
|
||||
```http
|
||||
Deprecation: true
|
||||
Sunset: 2027-01-01T00:00:00Z
|
||||
Link: </api/v2>; rel="successor-version"
|
||||
```
|
||||
|
||||
**Step 3**: Update to v2
|
||||
|
||||
```typescript
|
||||
// Change API base URL
|
||||
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api/v2';
|
||||
```
|
||||
|
||||
**Step 4**: Handle response format changes
|
||||
|
||||
If v2 changes response formats, update your type definitions and parsing logic:
|
||||
|
||||
```typescript
|
||||
// v1 response
|
||||
interface FlyerResponseV1 {
|
||||
id: number;
|
||||
store_id: number;
|
||||
}
|
||||
|
||||
// v2 response (example: includes embedded store)
|
||||
interface FlyerResponseV2 {
|
||||
id: string; // Changed to UUID
|
||||
store: {
|
||||
id: string;
|
||||
name: string;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### For Backend Developers
|
||||
|
||||
**Step 1**: Create v2-specific handlers (if needed)
|
||||
|
||||
For breaking changes, create version-specific route files:
|
||||
|
||||
```text
|
||||
src/routes/
|
||||
flyer.routes.ts # Shared/v1 handlers
|
||||
flyer.v2.routes.ts # v2-specific handlers (if significantly different)
|
||||
```
|
||||
|
||||
**Step 2**: Register version-specific routes
|
||||
|
||||
```typescript
|
||||
// src/routes/versioned.ts
|
||||
export const ROUTES: RouteRegistration[] = [
|
||||
{
|
||||
path: 'flyers',
|
||||
router: flyerRouter,
|
||||
description: 'Flyer routes (v1)',
|
||||
versions: ['v1'],
|
||||
},
|
||||
{
|
||||
path: 'flyers',
|
||||
router: flyerRouterV2,
|
||||
description: 'Flyer routes (v2 with breaking changes)',
|
||||
versions: ['v2'],
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
**Step 3**: Document changes
|
||||
|
||||
Update OpenAPI documentation to reflect v2 changes and mark v1 as deprecated.
|
||||
|
||||
### Timeline Example
|
||||
|
||||
| Date | Action |
|
||||
| ---------- | ------------------------------------------ |
|
||||
| T+0 | v2 released, v1 marked deprecated |
|
||||
| T+0 | Deprecation headers added to v1 responses |
|
||||
| T+30 days | Sunset warning emails to known integrators |
|
||||
| T+90 days | v1 returns 410 Gone |
|
||||
| T+120 days | v1 code removed |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: "UNSUPPORTED_VERSION" Error
|
||||
|
||||
**Symptom**: Request to `/api/v3/...` returns 404 with `UNSUPPORTED_VERSION`
|
||||
|
||||
**Cause**: Version `v3` is not defined in `API_VERSIONS`
|
||||
|
||||
**Solution**: Add the version to `src/config/apiVersions.ts`:
|
||||
|
||||
```typescript
|
||||
export const API_VERSIONS = ['v1', 'v2', 'v3'] as const;
|
||||
|
||||
export const VERSION_CONFIGS = {
|
||||
// ...
|
||||
v3: { version: 'v3', status: 'active' },
|
||||
};
|
||||
```
|
||||
|
||||
### Issue: Missing X-API-Version Header
|
||||
|
||||
**Symptom**: Response doesn't include `X-API-Version` header
|
||||
|
||||
**Cause**: Request didn't go through versioned router
|
||||
|
||||
**Solution**: Ensure the route is registered in `src/routes/versioned.ts` and mounted under `/api/:version`
|
||||
|
||||
### Issue: Deprecation Headers Not Appearing
|
||||
|
||||
**Symptom**: Deprecated version works but no deprecation headers
|
||||
|
||||
**Cause**: Version status not set to `'deprecated'` in config
|
||||
|
||||
**Solution**: Update `VERSION_CONFIGS`:
|
||||
|
||||
```typescript
|
||||
v1: {
|
||||
version: 'v1',
|
||||
status: 'deprecated', // Must be 'deprecated', not 'active'
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
},
|
||||
```
|
||||
|
||||
### Issue: Route Available in Wrong Version
|
||||
|
||||
**Symptom**: Route works in v1 but should only be in v2
|
||||
|
||||
**Cause**: Missing `versions` restriction in route registration
|
||||
|
||||
**Solution**: Add `versions` array:
|
||||
|
||||
```typescript
|
||||
{
|
||||
path: 'new-feature',
|
||||
router: newFeatureRouter,
|
||||
versions: ['v2'], // Add this to restrict availability
|
||||
},
|
||||
```
|
||||
|
||||
### Issue: Unversioned Paths Not Redirecting
|
||||
|
||||
**Symptom**: `/api/flyers` returns 404 instead of redirecting to `/api/v1/flyers`
|
||||
|
||||
**Cause**: Redirect middleware order issue in `server.ts`
|
||||
|
||||
**Solution**: Ensure redirect middleware is mounted BEFORE `createApiRouter()`:
|
||||
|
||||
```typescript
|
||||
// server.ts - correct order
|
||||
app.use('/api', redirectMiddleware); // First
|
||||
app.use('/api', createApiRouter()); // Second
|
||||
```
|
||||
|
||||
### Issue: TypeScript Errors on req.apiVersion
|
||||
|
||||
**Symptom**: `Property 'apiVersion' does not exist on type 'Request'`
|
||||
|
||||
**Cause**: Type extensions not being picked up
|
||||
|
||||
**Solution**: Ensure `src/types/express.d.ts` is included in tsconfig:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"typeRoots": ["./node_modules/@types", "./src/types"]
|
||||
},
|
||||
"include": ["src/**/*"]
|
||||
}
|
||||
```
|
||||
|
||||
### Issue: Router Cache Stale After Config Change
|
||||
|
||||
**Symptom**: Version behavior doesn't update after changing `VERSION_CONFIGS`
|
||||
|
||||
**Cause**: Routers are cached at startup
|
||||
|
||||
**Solution**: Use `refreshRouterCache()` or restart the server:
|
||||
|
||||
```typescript
|
||||
import { refreshRouterCache } from './src/routes/versioned';
|
||||
|
||||
// After config changes
|
||||
refreshRouterCache();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
### Architecture Decision Records
|
||||
|
||||
| ADR | Title |
|
||||
| ------------------------------------------------------------------------ | ---------------------------- |
|
||||
| [ADR-008](../adr/0008-api-versioning-strategy.md) | API Versioning Strategy |
|
||||
| [ADR-003](../adr/0003-standardized-input-validation-using-middleware.md) | Input Validation |
|
||||
| [ADR-028](../adr/0028-api-response-standardization.md) | API Response Standardization |
|
||||
| [ADR-018](../adr/0018-api-documentation-strategy.md) | API Documentation Strategy |
|
||||
|
||||
### Implementation Files
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------------------------------------------------------------------- | ---------------------------- |
|
||||
| [`src/config/apiVersions.ts`](../../src/config/apiVersions.ts) | Version constants and config |
|
||||
| [`src/middleware/apiVersion.middleware.ts`](../../src/middleware/apiVersion.middleware.ts) | Version detection |
|
||||
| [`src/middleware/deprecation.middleware.ts`](../../src/middleware/deprecation.middleware.ts) | Deprecation headers |
|
||||
| [`src/routes/versioned.ts`](../../src/routes/versioned.ts) | Router factory |
|
||||
| [`src/types/express.d.ts`](../../src/types/express.d.ts) | Request type extensions |
|
||||
| [`server.ts`](../../server.ts) | Application entry point |
|
||||
|
||||
### Test Files
|
||||
|
||||
| File | Description |
|
||||
| ------------------------------------------------------------------------------------------------------ | ------------------------ |
|
||||
| [`src/middleware/apiVersion.middleware.test.ts`](../../src/middleware/apiVersion.middleware.test.ts) | Version detection tests |
|
||||
| [`src/middleware/deprecation.middleware.test.ts`](../../src/middleware/deprecation.middleware.test.ts) | Deprecation header tests |
|
||||
|
||||
### External References
|
||||
|
||||
- [RFC 8594: The "Sunset" HTTP Header Field](https://datatracker.ietf.org/doc/html/rfc8594)
|
||||
- [draft-ietf-httpapi-deprecation-header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header/)
|
||||
- [RFC 8288: Web Linking](https://datatracker.ietf.org/doc/html/rfc8288)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Files to Modify for Common Tasks
|
||||
|
||||
| Task | Files |
|
||||
| ------------------------------ | ---------------------------------------------------- |
|
||||
| Add new version | `src/config/apiVersions.ts`, `src/config/swagger.ts` |
|
||||
| Deprecate version | `src/config/apiVersions.ts` |
|
||||
| Add version-specific route | `src/routes/versioned.ts` |
|
||||
| Version-specific handler logic | Route file (e.g., `src/routes/flyer.routes.ts`) |
|
||||
|
||||
### Key Functions
|
||||
|
||||
```typescript
|
||||
// Check if version is valid
|
||||
isValidApiVersion('v1'); // true
|
||||
isValidApiVersion('v99'); // false
|
||||
|
||||
// Get version from request with fallback
|
||||
getRequestApiVersion(req); // Returns 'v1' | 'v2'
|
||||
|
||||
// Check if request has valid version
|
||||
hasApiVersion(req); // boolean
|
||||
|
||||
// Get deprecation info
|
||||
getVersionDeprecation('v1'); // { deprecated: false, ... }
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
|
||||
# Type check
|
||||
podman exec -it flyer-crawler-dev npm run type-check
|
||||
|
||||
# Check version headers manually
|
||||
curl -I http://localhost:3001/api/v1/health
|
||||
|
||||
# Test deprecation (after marking v1 deprecated)
|
||||
curl -I http://localhost:3001/api/v1/health | grep -E "(Deprecation|Sunset|Link|X-API)"
|
||||
```
|
||||
curl -I http://localhost:3001/api/v1/health | grep -E "(Deprecation|Sunset|Link|X-API)"
|
||||
```
|
||||
@@ -2,6 +2,22 @@
|
||||
|
||||
Common code patterns extracted from Architecture Decision Records (ADRs). Use these as templates when writing new code.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Pattern | Key Function/Class | Import From |
|
||||
| ------------------ | ------------------------------------------------- | ------------------------------------- |
|
||||
| Error Handling | `handleDbError()`, `NotFoundError` | `src/services/db/errors.db.ts` |
|
||||
| Repository Methods | `get*`, `find*`, `list*` | `src/services/db/*.db.ts` |
|
||||
| API Responses | `sendSuccess()`, `sendPaginated()`, `sendError()` | `src/utils/apiResponse.ts` |
|
||||
| Transactions | `withTransaction()` | `src/services/db/connection.db.ts` |
|
||||
| Validation | `validateRequest()` | `src/middleware/validation.ts` |
|
||||
| Authentication | `authenticateJWT` | `src/middleware/auth.ts` |
|
||||
| Caching | `cacheService` | `src/services/cache.server.ts` |
|
||||
| Background Jobs | Queue classes | `src/services/queues.server.ts` |
|
||||
| Feature Flags | `isFeatureEnabled()`, `useFeatureFlag()` | `src/services/featureFlags.server.ts` |
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Error Handling](#error-handling)
|
||||
@@ -12,12 +28,13 @@ Common code patterns extracted from Architecture Decision Records (ADRs). Use th
|
||||
- [Authentication](#authentication)
|
||||
- [Caching](#caching)
|
||||
- [Background Jobs](#background-jobs)
|
||||
- [Feature Flags](#feature-flags)
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**ADR**: [ADR-001](../adr/0001-standardized-error-handling-for-database-operations.md)
|
||||
**ADR**: [ADR-001](../adr/0001-standardized-error-handling.md)
|
||||
|
||||
### Repository Layer Error Handling
|
||||
|
||||
@@ -47,16 +64,20 @@ export async function getFlyerById(id: number, client?: PoolClient): Promise<Fly
|
||||
```typescript
|
||||
import { sendError } from '../utils/apiResponse';
|
||||
|
||||
app.get('/api/flyers/:id', async (req, res) => {
|
||||
app.get('/api/v1/flyers/:id', async (req, res) => {
|
||||
try {
|
||||
const flyer = await flyerDb.getFlyerById(parseInt(req.params.id));
|
||||
return sendSuccess(res, flyer);
|
||||
} catch (error) {
|
||||
// IMPORTANT: Use req.originalUrl for dynamic path logging (not hardcoded paths)
|
||||
req.log.error({ error }, `Error in ${req.originalUrl.split('?')[0]}:`);
|
||||
return sendError(res, error);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**Best Practice**: Always use `req.originalUrl.split('?')[0]` in error log messages instead of hardcoded paths. This ensures logs reflect the actual request URL including version prefixes (`/api/v1/`). See [Error Logging Path Patterns](ERROR-LOGGING-PATHS.md) for details.
|
||||
|
||||
### Custom Error Types
|
||||
|
||||
```typescript
|
||||
@@ -74,7 +95,7 @@ throw new DatabaseError('Failed to insert flyer', originalError);
|
||||
|
||||
## Repository Patterns
|
||||
|
||||
**ADR**: [ADR-034](../adr/0034-repository-layer-method-naming-conventions.md)
|
||||
**ADR**: [ADR-034](../adr/0034-repository-pattern-standards.md)
|
||||
|
||||
### Method Naming Conventions
|
||||
|
||||
@@ -151,16 +172,17 @@ export async function listActiveFlyers(client?: PoolClient): Promise<Flyer[]> {
|
||||
|
||||
## API Response Patterns
|
||||
|
||||
**ADR**: [ADR-028](../adr/0028-consistent-api-response-format.md)
|
||||
**ADR**: [ADR-028](../adr/0028-api-response-standardization.md)
|
||||
|
||||
### Success Response
|
||||
|
||||
```typescript
|
||||
import { sendSuccess } from '../utils/apiResponse';
|
||||
|
||||
app.post('/api/flyers', async (req, res) => {
|
||||
app.post('/api/v1/flyers', async (req, res) => {
|
||||
const flyer = await flyerService.createFlyer(req.body);
|
||||
return sendSuccess(res, flyer, 'Flyer created successfully', 201);
|
||||
// sendSuccess(res, data, statusCode?, meta?)
|
||||
return sendSuccess(res, flyer, 201);
|
||||
});
|
||||
```
|
||||
|
||||
@@ -169,30 +191,32 @@ app.post('/api/flyers', async (req, res) => {
|
||||
```typescript
|
||||
import { sendPaginated } from '../utils/apiResponse';
|
||||
|
||||
app.get('/api/flyers', async (req, res) => {
|
||||
const { page = 1, pageSize = 20 } = req.query;
|
||||
const { items, total } = await flyerService.listFlyers(page, pageSize);
|
||||
app.get('/api/v1/flyers', async (req, res) => {
|
||||
const page = parseInt(req.query.page as string) || 1;
|
||||
const limit = parseInt(req.query.limit as string) || 20;
|
||||
const { items, total } = await flyerService.listFlyers(page, limit);
|
||||
|
||||
return sendPaginated(res, {
|
||||
items,
|
||||
total,
|
||||
page: parseInt(page),
|
||||
pageSize: parseInt(pageSize),
|
||||
});
|
||||
// sendPaginated(res, data[], { page, limit, total }, meta?)
|
||||
return sendPaginated(res, items, { page, limit, total });
|
||||
});
|
||||
```
|
||||
|
||||
### Error Response
|
||||
|
||||
```typescript
|
||||
import { sendError } from '../utils/apiResponse';
|
||||
import { sendError, sendSuccess, ErrorCode } from '../utils/apiResponse';
|
||||
|
||||
app.get('/api/flyers/:id', async (req, res) => {
|
||||
app.get('/api/v1/flyers/:id', async (req, res) => {
|
||||
try {
|
||||
const flyer = await flyerDb.getFlyerById(parseInt(req.params.id));
|
||||
return sendSuccess(res, flyer);
|
||||
} catch (error) {
|
||||
return sendError(res, error); // Automatically maps error to correct status
|
||||
// sendError(res, code, message, statusCode?, details?, meta?)
|
||||
if (error instanceof NotFoundError) {
|
||||
return sendError(res, ErrorCode.NOT_FOUND, error.message, 404);
|
||||
}
|
||||
req.log.error({ error }, `Error in ${req.originalUrl.split('?')[0]}:`);
|
||||
return sendError(res, ErrorCode.INTERNAL_ERROR, 'An error occurred', 500);
|
||||
}
|
||||
});
|
||||
```
|
||||
@@ -201,12 +225,12 @@ app.get('/api/flyers/:id', async (req, res) => {
|
||||
|
||||
## Transaction Management
|
||||
|
||||
**ADR**: [ADR-002](../adr/0002-transaction-management-pattern.md)
|
||||
**ADR**: [ADR-002](../adr/0002-standardized-transaction-management.md)
|
||||
|
||||
### Basic Transaction
|
||||
|
||||
```typescript
|
||||
import { withTransaction } from '../services/db/transaction.db';
|
||||
import { withTransaction } from '../services/db/connection.db';
|
||||
|
||||
export async function createFlyerWithItems(
|
||||
flyerData: FlyerInput,
|
||||
@@ -258,7 +282,7 @@ export async function bulkImportFlyers(flyersData: FlyerInput[]): Promise<Import
|
||||
|
||||
## Input Validation
|
||||
|
||||
**ADR**: [ADR-003](../adr/0003-input-validation-framework.md)
|
||||
**ADR**: [ADR-003](../adr/0003-standardized-input-validation-using-middleware.md)
|
||||
|
||||
### Zod Schema Definition
|
||||
|
||||
@@ -294,10 +318,10 @@ export type CreateFlyerInput = z.infer<typeof createFlyerSchema>;
|
||||
import { validateRequest } from '../middleware/validation';
|
||||
import { createFlyerSchema } from '../schemas/flyer.schemas';
|
||||
|
||||
app.post('/api/flyers', validateRequest(createFlyerSchema), async (req, res) => {
|
||||
app.post('/api/v1/flyers', validateRequest(createFlyerSchema), async (req, res) => {
|
||||
// req.body is now type-safe and validated
|
||||
const flyer = await flyerService.createFlyer(req.body);
|
||||
return sendSuccess(res, flyer, 'Flyer created successfully', 201);
|
||||
return sendSuccess(res, flyer, 201);
|
||||
});
|
||||
```
|
||||
|
||||
@@ -327,7 +351,7 @@ export async function processFlyer(data: unknown): Promise<Flyer> {
|
||||
import { authenticateJWT } from '../middleware/auth';
|
||||
|
||||
app.get(
|
||||
'/api/profile',
|
||||
'/api/v1/profile',
|
||||
authenticateJWT, // Middleware adds req.user
|
||||
async (req, res) => {
|
||||
// req.user is guaranteed to exist
|
||||
@@ -343,7 +367,7 @@ app.get(
|
||||
import { optionalAuth } from '../middleware/auth';
|
||||
|
||||
app.get(
|
||||
'/api/flyers',
|
||||
'/api/v1/flyers',
|
||||
optionalAuth, // req.user may or may not exist
|
||||
async (req, res) => {
|
||||
const flyers = req.user
|
||||
@@ -370,7 +394,7 @@ export function generateToken(user: User): string {
|
||||
|
||||
## Caching
|
||||
|
||||
**ADR**: [ADR-029](../adr/0029-redis-caching-strategy.md)
|
||||
**ADR**: [ADR-009](../adr/0009-caching-strategy-for-read-heavy-operations.md)
|
||||
|
||||
### Cache Pattern
|
||||
|
||||
@@ -410,7 +434,7 @@ export async function updateFlyer(id: number, data: UpdateFlyerInput): Promise<F
|
||||
|
||||
## Background Jobs
|
||||
|
||||
**ADR**: [ADR-036](../adr/0036-background-job-processing-architecture.md)
|
||||
**ADR**: [ADR-006](../adr/0006-background-job-processing-and-task-queues.md)
|
||||
|
||||
### Queue Job
|
||||
|
||||
@@ -469,6 +493,153 @@ const flyerWorker = new Worker(
|
||||
|
||||
---
|
||||
|
||||
## Feature Flags
|
||||
|
||||
**ADR**: [ADR-024](../adr/0024-feature-flagging-strategy.md)
|
||||
|
||||
Feature flags enable controlled feature rollout, A/B testing, and quick production disablement without redeployment. All flags default to `false` (opt-in model).
|
||||
|
||||
### Backend Usage
|
||||
|
||||
```typescript
|
||||
import { isFeatureEnabled, getFeatureFlags } from '../services/featureFlags.server';
|
||||
|
||||
// Check a specific flag in route handler
|
||||
router.get('/dashboard', async (req, res) => {
|
||||
if (isFeatureEnabled('newDashboard')) {
|
||||
return sendSuccess(res, { version: 'v2', data: await getNewDashboardData() });
|
||||
}
|
||||
return sendSuccess(res, { version: 'v1', data: await getLegacyDashboardData() });
|
||||
});
|
||||
|
||||
// Check flag in service layer
|
||||
function processFlyer(flyer: Flyer): ProcessedFlyer {
|
||||
if (isFeatureEnabled('experimentalAi')) {
|
||||
return processWithExperimentalAi(flyer);
|
||||
}
|
||||
return processWithStandardAi(flyer);
|
||||
}
|
||||
|
||||
// Get all flags (admin endpoint)
|
||||
router.get('/admin/feature-flags', requireAdmin, async (req, res) => {
|
||||
sendSuccess(res, { flags: getFeatureFlags() });
|
||||
});
|
||||
```
|
||||
|
||||
### Frontend Usage
|
||||
|
||||
```tsx
|
||||
import { useFeatureFlag, useAllFeatureFlags } from '../hooks/useFeatureFlag';
|
||||
import { FeatureFlag } from '../components/FeatureFlag';
|
||||
|
||||
// Hook approach - for logic beyond rendering
|
||||
function Dashboard() {
|
||||
const isNewDashboard = useFeatureFlag('newDashboard');
|
||||
|
||||
useEffect(() => {
|
||||
if (isNewDashboard) {
|
||||
analytics.track('new_dashboard_viewed');
|
||||
}
|
||||
}, [isNewDashboard]);
|
||||
|
||||
return isNewDashboard ? <NewDashboard /> : <LegacyDashboard />;
|
||||
}
|
||||
|
||||
// Declarative component approach
|
||||
function App() {
|
||||
return (
|
||||
<FeatureFlag feature="newDashboard" fallback={<LegacyDashboard />}>
|
||||
<NewDashboard />
|
||||
</FeatureFlag>
|
||||
);
|
||||
}
|
||||
|
||||
// Debug panel showing all flags
|
||||
function DebugPanel() {
|
||||
const flags = useAllFeatureFlags();
|
||||
return (
|
||||
<ul>
|
||||
{Object.entries(flags).map(([name, enabled]) => (
|
||||
<li key={name}>
|
||||
{name}: {enabled ? 'ON' : 'OFF'}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Adding a New Flag
|
||||
|
||||
1. **Backend** (`src/config/env.ts`):
|
||||
|
||||
```typescript
|
||||
// In featureFlagsSchema
|
||||
myNewFeature: booleanString(false), // FEATURE_MY_NEW_FEATURE
|
||||
|
||||
// In loadEnvVars()
|
||||
myNewFeature: process.env.FEATURE_MY_NEW_FEATURE,
|
||||
```
|
||||
|
||||
2. **Frontend** (`src/config.ts` and `src/vite-env.d.ts`):
|
||||
|
||||
```typescript
|
||||
// In config.ts featureFlags section
|
||||
myNewFeature: import.meta.env.VITE_FEATURE_MY_NEW_FEATURE === 'true',
|
||||
|
||||
// In vite-env.d.ts
|
||||
readonly VITE_FEATURE_MY_NEW_FEATURE?: string;
|
||||
```
|
||||
|
||||
3. **Environment** (`.env.example`):
|
||||
|
||||
```bash
|
||||
# FEATURE_MY_NEW_FEATURE=false
|
||||
# VITE_FEATURE_MY_NEW_FEATURE=false
|
||||
```
|
||||
|
||||
### Testing Feature Flags
|
||||
|
||||
```typescript
|
||||
// Backend - reset modules to test different states
|
||||
beforeEach(() => {
|
||||
vi.resetModules();
|
||||
process.env.FEATURE_NEW_DASHBOARD = 'true';
|
||||
});
|
||||
|
||||
// Frontend - mock config module
|
||||
vi.mock('../config', () => ({
|
||||
default: {
|
||||
featureFlags: {
|
||||
newDashboard: true,
|
||||
betaRecipes: false,
|
||||
},
|
||||
},
|
||||
}));
|
||||
```
|
||||
|
||||
### Flag Lifecycle
|
||||
|
||||
| Phase | Actions |
|
||||
| ---------- | -------------------------------------------------------------- |
|
||||
| **Add** | Add to schemas (backend + frontend), default `false`, document |
|
||||
| **Enable** | Set env var `='true'`, restart application |
|
||||
| **Remove** | Remove conditional code, remove from schemas, remove env vars |
|
||||
| **Sunset** | Max 3 months after full rollout - remove flag |
|
||||
|
||||
### Current Flags
|
||||
|
||||
| Flag | Backend Env Var | Frontend Env Var | Purpose |
|
||||
| ---------------- | ------------------------- | ------------------------------ | ------------------------ |
|
||||
| `bugsinkSync` | `FEATURE_BUGSINK_SYNC` | `VITE_FEATURE_BUGSINK_SYNC` | Bugsink error sync |
|
||||
| `advancedRbac` | `FEATURE_ADVANCED_RBAC` | `VITE_FEATURE_ADVANCED_RBAC` | Advanced RBAC features |
|
||||
| `newDashboard` | `FEATURE_NEW_DASHBOARD` | `VITE_FEATURE_NEW_DASHBOARD` | New dashboard experience |
|
||||
| `betaRecipes` | `FEATURE_BETA_RECIPES` | `VITE_FEATURE_BETA_RECIPES` | Beta recipe features |
|
||||
| `experimentalAi` | `FEATURE_EXPERIMENTAL_AI` | `VITE_FEATURE_EXPERIMENTAL_AI` | Experimental AI features |
|
||||
| `debugMode` | `FEATURE_DEBUG_MODE` | `VITE_FEATURE_DEBUG_MODE` | Debug mode |
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [ADR Index](../adr/index.md) - All architecture decision records
|
||||
|
||||
@@ -229,7 +229,7 @@ SELECT * FROM flyers WHERE store_id = 1;
|
||||
- Add missing indexes
|
||||
- Optimize WHERE clauses
|
||||
- Use connection pooling
|
||||
- See [ADR-034](../adr/0034-repository-layer-method-naming-conventions.md)
|
||||
- See [ADR-034](../adr/0034-repository-pattern-standards.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -237,7 +237,7 @@ SELECT * FROM flyers WHERE store_id = 1;
|
||||
|
||||
### Tests Pass on Windows, Fail in Container
|
||||
|
||||
**Cause**: Platform-specific behavior (ADR-014)
|
||||
**Cause**: Platform-specific behavior ([ADR-014](../adr/0014-containerization-and-deployment-strategy.md))
|
||||
|
||||
**Rule**: Container results are authoritative. Windows results are unreliable.
|
||||
|
||||
|
||||
@@ -93,7 +93,7 @@ When the container starts (`scripts/dev-entrypoint.sh`):
|
||||
|
||||
PM2 manages three processes in the dev container:
|
||||
|
||||
```
|
||||
```text
|
||||
+--------------------+ +------------------------+ +--------------------+
|
||||
| flyer-crawler- | | flyer-crawler- | | flyer-crawler- |
|
||||
| api-dev | | worker-dev | | vite-dev |
|
||||
@@ -404,5 +404,5 @@ podman exec -it flyer-crawler-dev pm2 restart flyer-crawler-api-dev
|
||||
- [DEBUGGING.md](DEBUGGING.md) - Debugging strategies
|
||||
- [LOGSTASH-QUICK-REF.md](../operations/LOGSTASH-QUICK-REF.md) - Logstash quick reference
|
||||
- [DEV-CONTAINER-BUGSINK.md](../DEV-CONTAINER-BUGSINK.md) - Bugsink setup in dev container
|
||||
- [ADR-014](../adr/0014-linux-only-platform.md) - Linux-only platform decision
|
||||
- [ADR-050](../adr/0050-postgresql-function-observability.md) - PostgreSQL function observability
|
||||
- [ADR-014](../adr/0014-containerization-and-deployment-strategy.md) - Containerization and deployment strategy
|
||||
- [ADR-050](../adr/0050-postgresql-function-observability.md) - PostgreSQL function observability (includes log aggregation)
|
||||
|
||||
153
docs/development/ERROR-LOGGING-PATHS.md
Normal file
153
docs/development/ERROR-LOGGING-PATHS.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# Error Logging Path Patterns
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the correct pattern for logging request paths in error handlers within Express route files. Following this pattern ensures that error logs accurately reflect the actual request URL, including any API version prefixes.
|
||||
|
||||
## The Problem
|
||||
|
||||
When ADR-008 (API Versioning Strategy) was implemented, all routes were moved from `/api/*` to `/api/v1/*`. However, some error log messages contained hardcoded paths that did not update automatically:
|
||||
|
||||
```typescript
|
||||
// INCORRECT - hardcoded path
|
||||
req.log.error({ error }, 'Error in /api/flyers/:id:');
|
||||
```
|
||||
|
||||
This caused 16 unit test failures because tests expected the error log message to contain `/api/v1/flyers/:id` but received `/api/flyers/:id`.
|
||||
|
||||
## The Solution
|
||||
|
||||
Always use `req.originalUrl` to dynamically capture the actual request path in error logs:
|
||||
|
||||
```typescript
|
||||
// CORRECT - dynamic path from request
|
||||
req.log.error({ error }, `Error in ${req.originalUrl.split('?')[0]}:`);
|
||||
```
|
||||
|
||||
### Why `req.originalUrl`?
|
||||
|
||||
| Property | Value for `/api/v1/flyers/123?active=true` | Use Case |
|
||||
| ----------------- | ------------------------------------------ | ----------------------------------- |
|
||||
| `req.url` | `/123?active=true` | Path relative to router mount point |
|
||||
| `req.path` | `/123` | Path without query string |
|
||||
| `req.originalUrl` | `/api/v1/flyers/123?active=true` | Full original request URL |
|
||||
| `req.baseUrl` | `/api/v1/flyers` | Router mount path |
|
||||
|
||||
`req.originalUrl` is the correct choice because:
|
||||
|
||||
1. It contains the full path including version prefix (`/api/v1/`)
|
||||
2. It reflects what the client actually requested
|
||||
3. It makes log messages searchable by the actual endpoint path
|
||||
4. It automatically adapts when routes are mounted at different paths
|
||||
|
||||
### Stripping Query Parameters
|
||||
|
||||
Use `.split('?')[0]` to remove query parameters from log messages:
|
||||
|
||||
```typescript
|
||||
// Request: /api/v1/flyers?page=1&limit=20
|
||||
req.originalUrl.split('?')[0]; // Returns: /api/v1/flyers
|
||||
```
|
||||
|
||||
This keeps log messages clean and prevents sensitive query parameters from appearing in logs.
|
||||
|
||||
## Standard Error Logging Pattern
|
||||
|
||||
### Basic Pattern
|
||||
|
||||
```typescript
|
||||
router.get('/:id', async (req, res) => {
|
||||
try {
|
||||
const result = await someService.getData(req.params.id);
|
||||
return sendSuccess(res, result);
|
||||
} catch (error) {
|
||||
req.log.error({ error }, `Error in ${req.originalUrl.split('?')[0]}:`);
|
||||
return sendError(res, error);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### With Additional Context
|
||||
|
||||
```typescript
|
||||
router.post('/', async (req, res) => {
|
||||
try {
|
||||
const result = await someService.createItem(req.body);
|
||||
return sendSuccess(res, result, 'Item created', 201);
|
||||
} catch (error) {
|
||||
req.log.error(
|
||||
{ error, userId: req.user?.id, body: req.body },
|
||||
`Error creating item in ${req.originalUrl.split('?')[0]}:`,
|
||||
);
|
||||
return sendError(res, error);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Descriptive Messages
|
||||
|
||||
For clarity, include a brief description of the operation:
|
||||
|
||||
```typescript
|
||||
// Good - describes the operation
|
||||
req.log.error({ error }, `Error fetching recipes in ${req.originalUrl.split('?')[0]}:`);
|
||||
req.log.error({ error }, `Error updating user profile in ${req.originalUrl.split('?')[0]}:`);
|
||||
|
||||
// Acceptable - just the path
|
||||
req.log.error({ error }, `Error in ${req.originalUrl.split('?')[0]}:`);
|
||||
|
||||
// Bad - hardcoded path
|
||||
req.log.error({ error }, 'Error in /api/recipes:');
|
||||
```
|
||||
|
||||
## Files Updated in Initial Fix (2026-01-27)
|
||||
|
||||
The following files were updated to use this pattern:
|
||||
|
||||
| File | Error Log Statements Fixed |
|
||||
| -------------------------------------- | -------------------------- |
|
||||
| `src/routes/recipe.routes.ts` | 3 |
|
||||
| `src/routes/stats.routes.ts` | 1 |
|
||||
| `src/routes/flyer.routes.ts` | 2 |
|
||||
| `src/routes/personalization.routes.ts` | 3 |
|
||||
|
||||
## Testing Error Log Messages
|
||||
|
||||
When writing tests that verify error log messages, use flexible matchers that account for versioned paths:
|
||||
|
||||
```typescript
|
||||
// Good - matches any version prefix
|
||||
expect(logSpy).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ error: expect.any(Error) }),
|
||||
expect.stringContaining('/flyers'),
|
||||
);
|
||||
|
||||
// Good - explicit version match
|
||||
expect(logSpy).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ error: expect.any(Error) }),
|
||||
expect.stringContaining('/api/v1/flyers'),
|
||||
);
|
||||
|
||||
// Bad - hardcoded unversioned path (will fail)
|
||||
expect(logSpy).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ error: expect.any(Error) }),
|
||||
'Error in /api/flyers:',
|
||||
);
|
||||
```
|
||||
|
||||
## Checklist for New Routes
|
||||
|
||||
When creating new route handlers:
|
||||
|
||||
- [ ] Use `req.originalUrl.split('?')[0]` in all error log messages
|
||||
- [ ] Include descriptive text about the operation being performed
|
||||
- [ ] Add structured context (userId, relevant IDs) to the log object
|
||||
- [ ] Write tests that verify error logs contain the versioned path
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [ADR-008: API Versioning Strategy](../adr/0008-api-versioning-strategy.md) - Versioning implementation details
|
||||
- [ADR-057: Test Remediation Post-API Versioning](../adr/0057-test-remediation-post-api-versioning.md) - Comprehensive remediation guide
|
||||
- [ADR-004: Structured Logging](../adr/0004-standardized-application-wide-structured-logging.md) - Logging standards
|
||||
- [CODE-PATTERNS.md](CODE-PATTERNS.md) - General code patterns
|
||||
- [TESTING.md](TESTING.md) - Testing guidelines
|
||||
@@ -1,5 +1,19 @@
|
||||
# Testing Guide
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Purpose |
|
||||
| ------------------------------------------------------------ | ---------------------------- |
|
||||
| `podman exec -it flyer-crawler-dev npm test` | Run all tests |
|
||||
| `podman exec -it flyer-crawler-dev npm run test:unit` | Unit tests (~2900) |
|
||||
| `podman exec -it flyer-crawler-dev npm run test:integration` | Integration tests (28 files) |
|
||||
| `podman exec -it flyer-crawler-dev npm run test:e2e` | E2E tests (11 files) |
|
||||
| `podman exec -it flyer-crawler-dev npm run type-check` | TypeScript check |
|
||||
|
||||
**Critical**: Always run tests in the dev container. Windows results are unreliable.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
@@ -76,7 +90,7 @@ To verify type-check is working correctly:
|
||||
|
||||
Example error output:
|
||||
|
||||
```
|
||||
```text
|
||||
src/pages/MyDealsPage.tsx:68:31 - error TS2339: Property 'store_name' does not exist on type 'WatchedItemDeal'.
|
||||
|
||||
68 <span>{deal.store_name}</span>
|
||||
@@ -113,15 +127,26 @@ Located throughout `src/` directory alongside source files with `.test.ts` or `.
|
||||
npm run test:unit
|
||||
```
|
||||
|
||||
### Integration Tests (5 test files)
|
||||
### Integration Tests (28 test files)
|
||||
|
||||
Located in `src/tests/integration/`:
|
||||
Located in `src/tests/integration/`. Key test files include:
|
||||
|
||||
- `admin.integration.test.ts`
|
||||
- `flyer.integration.test.ts`
|
||||
- `price.integration.test.ts`
|
||||
- `public.routes.integration.test.ts`
|
||||
- `receipt.integration.test.ts`
|
||||
| Test File | Domain |
|
||||
| -------------------------------------- | -------------------------- |
|
||||
| `admin.integration.test.ts` | Admin dashboard operations |
|
||||
| `auth.integration.test.ts` | Authentication flows |
|
||||
| `budget.integration.test.ts` | Budget management |
|
||||
| `flyer.integration.test.ts` | Flyer CRUD operations |
|
||||
| `flyer-processing.integration.test.ts` | AI flyer processing |
|
||||
| `gamification.integration.test.ts` | Achievements and points |
|
||||
| `inventory.integration.test.ts` | Inventory management |
|
||||
| `notification.integration.test.ts` | User notifications |
|
||||
| `receipt.integration.test.ts` | Receipt processing |
|
||||
| `recipe.integration.test.ts` | Recipe management |
|
||||
| `shopping-list.integration.test.ts` | Shopping list operations |
|
||||
| `user.integration.test.ts` | User profile operations |
|
||||
|
||||
See `src/tests/integration/` for the complete list.
|
||||
|
||||
Requires PostgreSQL and Redis services running.
|
||||
|
||||
@@ -129,13 +154,23 @@ Requires PostgreSQL and Redis services running.
|
||||
npm run test:integration
|
||||
```
|
||||
|
||||
### E2E Tests (3 test files)
|
||||
### E2E Tests (11 test files)
|
||||
|
||||
Located in `src/tests/e2e/`:
|
||||
Located in `src/tests/e2e/`. Full user journey tests:
|
||||
|
||||
- `deals-journey.e2e.test.ts`
|
||||
- `budget-journey.e2e.test.ts`
|
||||
- `receipt-journey.e2e.test.ts`
|
||||
| Test File | Journey |
|
||||
| --------------------------------- | ----------------------------- |
|
||||
| `admin-authorization.e2e.test.ts` | Admin access control |
|
||||
| `admin-dashboard.e2e.test.ts` | Admin dashboard flows |
|
||||
| `auth.e2e.test.ts` | Login/logout/registration |
|
||||
| `budget-journey.e2e.test.ts` | Budget tracking workflow |
|
||||
| `deals-journey.e2e.test.ts` | Finding and saving deals |
|
||||
| `error-reporting.e2e.test.ts` | Error handling verification |
|
||||
| `flyer-upload.e2e.test.ts` | Flyer upload and processing |
|
||||
| `inventory-journey.e2e.test.ts` | Pantry management |
|
||||
| `receipt-journey.e2e.test.ts` | Receipt scanning and tracking |
|
||||
| `upc-journey.e2e.test.ts` | UPC barcode scanning |
|
||||
| `user-journey.e2e.test.ts` | User profile management |
|
||||
|
||||
Requires all services (PostgreSQL, Redis, BullMQ workers) running.
|
||||
|
||||
@@ -157,20 +192,18 @@ 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,
|
||||
const store = await createStoreWithLocation(pool, {
|
||||
name: 'Test Store',
|
||||
address: '123 Main St',
|
||||
city: 'Toronto',
|
||||
province: 'ON',
|
||||
postalCode: 'M1M 1M1',
|
||||
});
|
||||
|
||||
// Returns: { storeId, addressId, storeLocationId }
|
||||
|
||||
// Cleanup stores and their locations
|
||||
await cleanupStoreLocations([storeId1, storeId2], pool, log);
|
||||
await cleanupStoreLocation(pool, store);
|
||||
```
|
||||
|
||||
### Mock Factories
|
||||
@@ -261,3 +294,214 @@ Opens a browser-based test runner with filtering and debugging capabilities.
|
||||
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
|
||||
8. **Use `req.originalUrl` in error logs** - never hardcode API paths in error messages
|
||||
9. **Use versioned API paths** - always use `/api/v1/` prefix in test requests
|
||||
10. **Use `vi.hoisted()` for module mocks** - ensure mocks are available during module initialization
|
||||
|
||||
## Testing Error Log Messages
|
||||
|
||||
When testing route error handlers, ensure assertions account for versioned API paths.
|
||||
|
||||
### Problem: Hardcoded Paths Break Tests
|
||||
|
||||
Error log messages with hardcoded paths cause test failures when API versions change:
|
||||
|
||||
```typescript
|
||||
// Production code (INCORRECT - hardcoded path)
|
||||
req.log.error({ error }, 'Error in /api/flyers/:id:');
|
||||
|
||||
// Test expects versioned path
|
||||
expect(logSpy).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ error: expect.any(Error) }),
|
||||
expect.stringContaining('/api/v1/flyers'), // FAILS - actual log has /api/flyers
|
||||
);
|
||||
```
|
||||
|
||||
### Solution: Dynamic Paths with `req.originalUrl`
|
||||
|
||||
Production code should use `req.originalUrl` for dynamic path logging:
|
||||
|
||||
```typescript
|
||||
// Production code (CORRECT - dynamic path)
|
||||
req.log.error({ error }, `Error in ${req.originalUrl.split('?')[0]}:`);
|
||||
```
|
||||
|
||||
### Writing Robust Test Assertions
|
||||
|
||||
```typescript
|
||||
// Good - matches versioned path
|
||||
expect(logSpy).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ error: expect.any(Error) }),
|
||||
expect.stringContaining('/api/v1/flyers'),
|
||||
);
|
||||
|
||||
// Good - flexible match for any version
|
||||
expect(logSpy).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ error: expect.any(Error) }),
|
||||
expect.stringMatching(/\/api\/v\d+\/flyers/),
|
||||
);
|
||||
|
||||
// Bad - hardcoded unversioned path
|
||||
expect(logSpy).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ error: expect.any(Error) }),
|
||||
'Error in /api/flyers:', // Will fail with versioned routes
|
||||
);
|
||||
```
|
||||
|
||||
See [Error Logging Path Patterns](ERROR-LOGGING-PATHS.md) for complete documentation.
|
||||
|
||||
## API Versioning in Tests (ADR-008, ADR-057)
|
||||
|
||||
All API endpoints use the `/api/v1/` prefix. Tests must use versioned paths.
|
||||
|
||||
### Configuration
|
||||
|
||||
API base URLs are configured centrally in Vitest config files:
|
||||
|
||||
| Config File | Environment Variable | Value |
|
||||
| ------------------------------ | -------------------- | ------------------------------ |
|
||||
| `vite.config.ts` | `VITE_API_BASE_URL` | `/api/v1` |
|
||||
| `vitest.config.e2e.ts` | `VITE_API_BASE_URL` | `http://localhost:3098/api/v1` |
|
||||
| `vitest.config.integration.ts` | `VITE_API_BASE_URL` | `http://localhost:3099/api/v1` |
|
||||
|
||||
### Writing API Tests
|
||||
|
||||
```typescript
|
||||
// Good - versioned path
|
||||
const response = await request.post('/api/v1/auth/login').send({...});
|
||||
|
||||
// Bad - unversioned path (will fail)
|
||||
const response = await request.post('/api/auth/login').send({...});
|
||||
```
|
||||
|
||||
### Migration Checklist
|
||||
|
||||
When API version changes (e.g., v1 to v2):
|
||||
|
||||
1. Update all Vitest config `VITE_API_BASE_URL` values
|
||||
2. Search and replace API paths in E2E tests: `grep -r "/api/v1/" src/tests/e2e/`
|
||||
3. Search and replace API paths in integration tests
|
||||
4. Verify route handler error logs use `req.originalUrl`
|
||||
5. Run full test suite in dev container
|
||||
|
||||
See [ADR-057](../adr/0057-test-remediation-post-api-versioning.md) for complete migration guidance.
|
||||
|
||||
## vi.hoisted() Pattern for Module Mocks
|
||||
|
||||
When mocking modules that are imported at module initialization time (like queues or database connections), use `vi.hoisted()` to ensure mocks are available during hoisting.
|
||||
|
||||
### Problem: Mock Not Available During Import
|
||||
|
||||
```typescript
|
||||
// BAD: Mock might not be ready when module imports it
|
||||
vi.mock('../services/queues.server', () => ({
|
||||
flyerQueue: { getJobCounts: vi.fn() }, // May not exist yet
|
||||
}));
|
||||
|
||||
import healthRouter from './health.routes'; // Imports queues.server
|
||||
```
|
||||
|
||||
### Solution: Use vi.hoisted()
|
||||
|
||||
```typescript
|
||||
// GOOD: Mocks are created during hoisting, before vi.mock runs
|
||||
const { mockQueuesModule } = vi.hoisted(() => {
|
||||
const createMockQueue = () => ({
|
||||
getJobCounts: vi.fn().mockResolvedValue({
|
||||
waiting: 0,
|
||||
active: 0,
|
||||
failed: 0,
|
||||
delayed: 0,
|
||||
}),
|
||||
});
|
||||
|
||||
return {
|
||||
mockQueuesModule: {
|
||||
flyerQueue: createMockQueue(),
|
||||
emailQueue: createMockQueue(),
|
||||
// ... additional queues
|
||||
},
|
||||
};
|
||||
});
|
||||
|
||||
// Now the mock object exists when vi.mock factory runs
|
||||
vi.mock('../services/queues.server', () => mockQueuesModule);
|
||||
|
||||
// Safe to import after mocks are defined
|
||||
import healthRouter from './health.routes';
|
||||
```
|
||||
|
||||
See [ADR-057](../adr/0057-test-remediation-post-api-versioning.md) for additional patterns.
|
||||
|
||||
## Testing Role-Based Component Visibility
|
||||
|
||||
When testing components that render differently based on user roles:
|
||||
|
||||
### Pattern: Separate Test Cases by Role
|
||||
|
||||
```typescript
|
||||
describe('for authenticated users', () => {
|
||||
beforeEach(() => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
authStatus: 'AUTHENTICATED',
|
||||
userProfile: createMockUserProfile({ role: 'user' }),
|
||||
});
|
||||
});
|
||||
|
||||
it('renders user-accessible components', () => {
|
||||
render(<MyComponent />);
|
||||
expect(screen.getByTestId('user-component')).toBeInTheDocument();
|
||||
// Admin-only should NOT be present
|
||||
expect(screen.queryByTestId('admin-only')).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('for admin users', () => {
|
||||
beforeEach(() => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
authStatus: 'AUTHENTICATED',
|
||||
userProfile: createMockUserProfile({ role: 'admin' }),
|
||||
});
|
||||
});
|
||||
|
||||
it('renders admin-only components', () => {
|
||||
render(<MyComponent />);
|
||||
expect(screen.getByTestId('admin-only')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Key Points
|
||||
|
||||
1. Create separate `describe` blocks for each role
|
||||
2. Set up role-specific mocks in `beforeEach`
|
||||
3. Test both presence AND absence of role-gated components
|
||||
4. Use `screen.queryByTestId()` for elements that should NOT exist
|
||||
|
||||
## CSS Class Assertions After UI Refactors
|
||||
|
||||
After frontend style changes, update test assertions to match new CSS classes.
|
||||
|
||||
### Handling Tailwind Class Changes
|
||||
|
||||
```typescript
|
||||
// Before refactor
|
||||
expect(selectedItem).toHaveClass('ring-2', 'ring-brand-primary');
|
||||
|
||||
// After refactor - update to new classes
|
||||
expect(selectedItem).toHaveClass('border-brand-primary', 'bg-teal-50/50');
|
||||
```
|
||||
|
||||
### Flexible Matching
|
||||
|
||||
For complex class combinations, consider partial matching:
|
||||
|
||||
```typescript
|
||||
// Check for key classes, ignore utility classes
|
||||
expect(element).toHaveClass('border-brand-primary');
|
||||
|
||||
// Or use regex for patterns
|
||||
expect(element.className).toMatch(/dark:bg-teal-\d+/);
|
||||
```
|
||||
|
||||
See [ADR-057](../adr/0057-test-remediation-post-api-versioning.md) for lessons learned from the test remediation effort.
|
||||
|
||||
272
docs/development/test-path-migration.md
Normal file
272
docs/development/test-path-migration.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Test Path Migration: Unversioned to Versioned API Paths
|
||||
|
||||
**Status**: Complete
|
||||
**Created**: 2026-01-27
|
||||
**Completed**: 2026-01-27
|
||||
**Related**: ADR-008 (API Versioning Strategy)
|
||||
|
||||
## Summary
|
||||
|
||||
All integration test files have been successfully migrated to use versioned API paths (`/api/v1/`). This resolves the redirect-related test failures introduced by ADR-008 Phase 1.
|
||||
|
||||
### Results
|
||||
|
||||
| Metric | Value |
|
||||
| ------------------------- | ---------------------------------------- |
|
||||
| Test files updated | 23 |
|
||||
| Path occurrences changed | ~70 |
|
||||
| Tests before migration | 274/348 passing |
|
||||
| Tests after migration | 345/348 passing |
|
||||
| Test failures resolved | 71 |
|
||||
| Remaining todo/skipped | 3 (known issues, not versioning-related) |
|
||||
| Type check | Passing |
|
||||
| Versioning-specific tests | 82/82 passing |
|
||||
|
||||
### Key Outcomes
|
||||
|
||||
- No `301 Moved Permanently` responses in test output
|
||||
- All redirect-related failures resolved
|
||||
- No regressions introduced
|
||||
- Unit tests unaffected (3,375/3,391 passing, pre-existing failures)
|
||||
|
||||
---
|
||||
|
||||
## Original Problem Statement
|
||||
|
||||
Integration tests failed due to redirect middleware (ADR-008 Phase 1). Server returned `301 Moved Permanently` for unversioned paths (`/api/resource`) instead of expected `200 OK`. Redirect targets versioned paths (`/api/v1/resource`).
|
||||
|
||||
**Root Cause**: Backwards-compatibility redirect in `server.ts`:
|
||||
|
||||
```typescript
|
||||
app.use('/api', (req, res, next) => {
|
||||
const versionPattern = /^\/v\d+/;
|
||||
if (!versionPattern.test(req.path)) {
|
||||
return res.redirect(301, `/api/v1${req.path}`);
|
||||
}
|
||||
next();
|
||||
});
|
||||
```
|
||||
|
||||
**Impact**: ~70 test path occurrences across 23 files returning 301 instead of expected status codes.
|
||||
|
||||
## Solution
|
||||
|
||||
Update all test API paths from `/api/{resource}` to `/api/v1/{resource}`.
|
||||
|
||||
## Files Requiring Updates
|
||||
|
||||
### Integration Tests (16 files)
|
||||
|
||||
| File | Occurrences | Domains |
|
||||
| ------------------------------------------------------------ | ----------- | ---------------------- |
|
||||
| `src/tests/integration/inventory.integration.test.ts` | 14 | inventory |
|
||||
| `src/tests/integration/receipt.integration.test.ts` | 17 | receipts |
|
||||
| `src/tests/integration/recipe.integration.test.ts` | 17 | recipes, users/recipes |
|
||||
| `src/tests/integration/user.routes.integration.test.ts` | 10 | users/shopping-lists |
|
||||
| `src/tests/integration/admin.integration.test.ts` | 7 | admin |
|
||||
| `src/tests/integration/flyer-processing.integration.test.ts` | 6 | ai/jobs |
|
||||
| `src/tests/integration/budget.integration.test.ts` | 5 | budgets |
|
||||
| `src/tests/integration/notification.integration.test.ts` | 3 | users/notifications |
|
||||
| `src/tests/integration/data-integrity.integration.test.ts` | 3 | users, admin |
|
||||
| `src/tests/integration/upc.integration.test.ts` | 3 | upc |
|
||||
| `src/tests/integration/edge-cases.integration.test.ts` | 3 | users/shopping-lists |
|
||||
| `src/tests/integration/user.integration.test.ts` | 2 | users |
|
||||
| `src/tests/integration/public.routes.integration.test.ts` | 2 | flyers, recipes |
|
||||
| `src/tests/integration/flyer.integration.test.ts` | 1 | flyers |
|
||||
| `src/tests/integration/category.routes.test.ts` | 1 | categories |
|
||||
| `src/tests/integration/gamification.integration.test.ts` | 1 | ai/jobs |
|
||||
|
||||
### E2E Tests (7 files)
|
||||
|
||||
| File | Occurrences | Domains |
|
||||
| --------------------------------------------- | ----------- | -------------------- |
|
||||
| `src/tests/e2e/inventory-journey.e2e.test.ts` | 9 | inventory |
|
||||
| `src/tests/e2e/receipt-journey.e2e.test.ts` | 9 | receipts |
|
||||
| `src/tests/e2e/budget-journey.e2e.test.ts` | 6 | budgets |
|
||||
| `src/tests/e2e/upc-journey.e2e.test.ts` | 3 | upc |
|
||||
| `src/tests/e2e/deals-journey.e2e.test.ts` | 2 | categories, users |
|
||||
| `src/tests/e2e/user-journey.e2e.test.ts` | 1 | users/shopping-lists |
|
||||
| `src/tests/e2e/flyer-upload.e2e.test.ts` | 1 | jobs |
|
||||
|
||||
## Update Pattern
|
||||
|
||||
### Find/Replace Rules
|
||||
|
||||
**Template literals** (most common):
|
||||
|
||||
```
|
||||
OLD: .get(`/api/resource/${id}`)
|
||||
NEW: .get(`/api/v1/resource/${id}`)
|
||||
```
|
||||
|
||||
**String literals**:
|
||||
|
||||
```
|
||||
OLD: .get('/api/resource')
|
||||
NEW: .get('/api/v1/resource')
|
||||
```
|
||||
|
||||
### Regex Pattern for Batch Updates
|
||||
|
||||
```regex
|
||||
Find: (\.(get|post|put|delete|patch)\([`'"])/api/([a-z])
|
||||
Replace: $1/api/v1/$3
|
||||
```
|
||||
|
||||
**Explanation**: Captures HTTP method call, inserts `/v1/` after `/api/`.
|
||||
|
||||
## Files to EXCLUDE
|
||||
|
||||
These files intentionally test unversioned path behavior:
|
||||
|
||||
| File | Reason |
|
||||
| ---------------------------------------------------- | ------------------------------------ |
|
||||
| `src/routes/versioning.integration.test.ts` | Tests redirect behavior itself |
|
||||
| `src/services/apiClient.test.ts` | Mock server URLs, not real API calls |
|
||||
| `src/services/aiApiClient.test.ts` | Mock server URLs for MSW handlers |
|
||||
| `src/services/googleGeocodingService.server.test.ts` | External Google API URL |
|
||||
|
||||
**Also exclude** (not API paths):
|
||||
|
||||
- Lines containing `vi.mock('@bull-board/api` (import mocks)
|
||||
- Lines containing `/api/v99` (intentional unsupported version tests)
|
||||
- `describe()` and `it()` block descriptions
|
||||
- Comment lines (`// `)
|
||||
|
||||
## Execution Batches
|
||||
|
||||
### Batch 1: High-Impact Integration (4 files, ~58 occurrences)
|
||||
|
||||
```bash
|
||||
# Files with most occurrences
|
||||
src/tests/integration/inventory.integration.test.ts
|
||||
src/tests/integration/receipt.integration.test.ts
|
||||
src/tests/integration/recipe.integration.test.ts
|
||||
src/tests/integration/user.routes.integration.test.ts
|
||||
```
|
||||
|
||||
### Batch 2: Medium Integration (6 files, ~27 occurrences)
|
||||
|
||||
```bash
|
||||
src/tests/integration/admin.integration.test.ts
|
||||
src/tests/integration/flyer-processing.integration.test.ts
|
||||
src/tests/integration/budget.integration.test.ts
|
||||
src/tests/integration/notification.integration.test.ts
|
||||
src/tests/integration/data-integrity.integration.test.ts
|
||||
src/tests/integration/upc.integration.test.ts
|
||||
```
|
||||
|
||||
### Batch 3: Low Integration (6 files, ~10 occurrences)
|
||||
|
||||
```bash
|
||||
src/tests/integration/edge-cases.integration.test.ts
|
||||
src/tests/integration/user.integration.test.ts
|
||||
src/tests/integration/public.routes.integration.test.ts
|
||||
src/tests/integration/flyer.integration.test.ts
|
||||
src/tests/integration/category.routes.test.ts
|
||||
src/tests/integration/gamification.integration.test.ts
|
||||
```
|
||||
|
||||
### Batch 4: E2E Tests (7 files, ~31 occurrences)
|
||||
|
||||
```bash
|
||||
src/tests/e2e/inventory-journey.e2e.test.ts
|
||||
src/tests/e2e/receipt-journey.e2e.test.ts
|
||||
src/tests/e2e/budget-journey.e2e.test.ts
|
||||
src/tests/e2e/upc-journey.e2e.test.ts
|
||||
src/tests/e2e/deals-journey.e2e.test.ts
|
||||
src/tests/e2e/user-journey.e2e.test.ts
|
||||
src/tests/e2e/flyer-upload.e2e.test.ts
|
||||
```
|
||||
|
||||
## Verification Strategy
|
||||
|
||||
### Per-Batch Verification
|
||||
|
||||
After each batch:
|
||||
|
||||
```bash
|
||||
# Type check
|
||||
podman exec -it flyer-crawler-dev npm run type-check
|
||||
|
||||
# Run specific test file
|
||||
podman exec -it flyer-crawler-dev npx vitest run <file-path> --reporter=verbose
|
||||
```
|
||||
|
||||
### Full Verification
|
||||
|
||||
After all batches:
|
||||
|
||||
```bash
|
||||
# Full integration test suite
|
||||
podman exec -it flyer-crawler-dev npm run test:integration
|
||||
|
||||
# Full E2E test suite
|
||||
podman exec -it flyer-crawler-dev npm run test:e2e
|
||||
```
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- [x] No `301 Moved Permanently` responses in test output
|
||||
- [x] All tests pass or fail for expected reasons (not redirect-related)
|
||||
- [x] Type check passes
|
||||
- [x] No regressions in unmodified tests
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### Describe Block Text
|
||||
|
||||
Do NOT modify describe/it block descriptions:
|
||||
|
||||
```typescript
|
||||
// KEEP AS-IS (documentation only):
|
||||
describe('GET /api/users/profile', () => { ... });
|
||||
|
||||
// UPDATE (actual API call):
|
||||
const response = await request.get('/api/v1/users/profile');
|
||||
```
|
||||
|
||||
### Console Logging
|
||||
|
||||
Do NOT modify debug/error logging paths:
|
||||
|
||||
```typescript
|
||||
// KEEP AS-IS:
|
||||
console.error('[DEBUG] GET /api/admin/stats failed:', ...);
|
||||
```
|
||||
|
||||
### Query Parameters
|
||||
|
||||
Include query parameters in update:
|
||||
|
||||
```typescript
|
||||
// OLD:
|
||||
.get(`/api/budgets/spending-analysis?startDate=${start}&endDate=${end}`)
|
||||
|
||||
// NEW:
|
||||
.get(`/api/v1/budgets/spending-analysis?startDate=${start}&endDate=${end}`)
|
||||
```
|
||||
|
||||
## Post-Completion Checklist
|
||||
|
||||
- [x] All 23 files updated
|
||||
- [x] ~70 path occurrences migrated
|
||||
- [x] Exclusion files unchanged
|
||||
- [x] Type check passes
|
||||
- [x] Integration tests pass (345/348)
|
||||
- [x] E2E tests pass
|
||||
- [x] Commit with message: `fix(tests): Update API paths to use /api/v1/ prefix (ADR-008)`
|
||||
|
||||
## Rollback
|
||||
|
||||
If issues arise:
|
||||
|
||||
```bash
|
||||
git checkout HEAD -- src/tests/
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- ADR-008: API Versioning Strategy
|
||||
- `docs/architecture/api-versioning-infrastructure.md`
|
||||
- `src/routes/versioning.integration.test.ts` (reference for expected behavior)
|
||||
@@ -2,134 +2,259 @@
|
||||
|
||||
Complete guide to environment variables used in Flyer Crawler.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Minimum Required Variables (Development)
|
||||
|
||||
| Variable | Example | Purpose |
|
||||
| ---------------- | ------------------------ | -------------------- |
|
||||
| `DB_HOST` | `localhost` | PostgreSQL host |
|
||||
| `DB_USER` | `postgres` | PostgreSQL username |
|
||||
| `DB_PASSWORD` | `postgres` | PostgreSQL password |
|
||||
| `DB_NAME` | `flyer_crawler_dev` | Database name |
|
||||
| `REDIS_URL` | `redis://localhost:6379` | Redis connection URL |
|
||||
| `JWT_SECRET` | (32+ character string) | JWT signing key |
|
||||
| `GEMINI_API_KEY` | `AIzaSy...` | Google Gemini API |
|
||||
|
||||
### Source of Truth
|
||||
|
||||
The Zod schema at `src/config/env.ts` is the authoritative source for all environment variables. If a variable is not in this file, it is not used by the application.
|
||||
|
||||
---
|
||||
|
||||
## Configuration by Environment
|
||||
|
||||
### Production
|
||||
|
||||
**Location**: Gitea CI/CD secrets injected during deployment
|
||||
**Path**: `/var/www/flyer-crawler.projectium.com/`
|
||||
**Note**: No `.env` file exists - all variables come from CI/CD
|
||||
| Aspect | Details |
|
||||
| -------- | ------------------------------------------ |
|
||||
| Location | Gitea CI/CD secrets injected at deployment |
|
||||
| Path | `/var/www/flyer-crawler.projectium.com/` |
|
||||
| File | No `.env` file - all from CI/CD secrets |
|
||||
|
||||
### Test
|
||||
|
||||
**Location**: Gitea CI/CD secrets + `.env.test` file
|
||||
**Path**: `/var/www/flyer-crawler-test.projectium.com/`
|
||||
**Note**: `.env.test` overrides for test-specific values
|
||||
| Aspect | Details |
|
||||
| -------- | --------------------------------------------- |
|
||||
| Location | Gitea CI/CD secrets + `.env.test` overrides |
|
||||
| Path | `/var/www/flyer-crawler-test.projectium.com/` |
|
||||
| File | `.env.test` for test-specific values |
|
||||
|
||||
### Development Container
|
||||
|
||||
**Location**: `.env.local` file in project root
|
||||
**Note**: Overrides default DSNs in `compose.dev.yml`
|
||||
| Aspect | Details |
|
||||
| -------- | --------------------------------------- |
|
||||
| Location | `.env.local` file in project root |
|
||||
| Priority | Overrides defaults in `compose.dev.yml` |
|
||||
| File | `.env.local` (gitignored) |
|
||||
|
||||
## Required Variables
|
||||
---
|
||||
|
||||
### Database
|
||||
## Complete Variable Reference
|
||||
|
||||
| Variable | Description | Example |
|
||||
| ------------------ | ---------------------------- | ------------------------------------------ |
|
||||
| `DB_HOST` | PostgreSQL host | `localhost` (dev), `projectium.com` (prod) |
|
||||
| `DB_PORT` | PostgreSQL port | `5432` |
|
||||
| `DB_USER_PROD` | Production database user | `flyer_crawler_prod` |
|
||||
| `DB_PASSWORD_PROD` | Production database password | (secret) |
|
||||
| `DB_DATABASE_PROD` | Production database name | `flyer-crawler-prod` |
|
||||
| `DB_USER_TEST` | Test database user | `flyer_crawler_test` |
|
||||
| `DB_PASSWORD_TEST` | Test database password | (secret) |
|
||||
| `DB_DATABASE_TEST` | Test database name | `flyer-crawler-test` |
|
||||
| `DB_USER` | Dev database user | `postgres` |
|
||||
| `DB_PASSWORD` | Dev database password | `postgres` |
|
||||
| `DB_NAME` | Dev database name | `flyer_crawler_dev` |
|
||||
### Database Configuration
|
||||
|
||||
**Note**: Production and test use separate `_PROD` and `_TEST` suffixed variables. Development uses unsuffixed variables.
|
||||
| Variable | Required | Default | Description |
|
||||
| ------------- | -------- | ------- | ----------------- |
|
||||
| `DB_HOST` | Yes | - | PostgreSQL host |
|
||||
| `DB_PORT` | No | `5432` | PostgreSQL port |
|
||||
| `DB_USER` | Yes | - | Database username |
|
||||
| `DB_PASSWORD` | Yes | - | Database password |
|
||||
| `DB_NAME` | Yes | - | Database name |
|
||||
|
||||
### Redis
|
||||
**Environment-Specific Variables** (Gitea Secrets):
|
||||
|
||||
| Variable | Description | Example |
|
||||
| --------------------- | ------------------------- | ------------------------------ |
|
||||
| `REDIS_URL` | Redis connection URL | `redis://localhost:6379` (dev) |
|
||||
| `REDIS_PASSWORD_PROD` | Production Redis password | (secret) |
|
||||
| `REDIS_PASSWORD_TEST` | Test Redis password | (secret) |
|
||||
| Variable | Environment | Description |
|
||||
| ------------------ | ----------- | ------------------------ |
|
||||
| `DB_USER_PROD` | Production | Production database user |
|
||||
| `DB_PASSWORD_PROD` | Production | Production database pass |
|
||||
| `DB_DATABASE_PROD` | Production | Production database name |
|
||||
| `DB_USER_TEST` | Test | Test database user |
|
||||
| `DB_PASSWORD_TEST` | Test | Test database password |
|
||||
| `DB_DATABASE_TEST` | Test | Test database name |
|
||||
|
||||
### Redis Configuration
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
| ---------------- | -------- | ------- | ------------------------- |
|
||||
| `REDIS_URL` | Yes | - | Redis connection URL |
|
||||
| `REDIS_PASSWORD` | No | - | Redis password (optional) |
|
||||
|
||||
**URL Format**: `redis://[user:password@]host:port`
|
||||
|
||||
**Examples**:
|
||||
|
||||
```bash
|
||||
# Development (no auth)
|
||||
REDIS_URL=redis://localhost:6379
|
||||
|
||||
# Production (with auth)
|
||||
REDIS_URL=redis://:${REDIS_PASSWORD_PROD}@localhost:6379
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
| Variable | Description | Example |
|
||||
| ---------------------- | -------------------------- | -------------------------------- |
|
||||
| `JWT_SECRET` | JWT token signing key | (minimum 32 characters) |
|
||||
| `SESSION_SECRET` | Session encryption key | (minimum 32 characters) |
|
||||
| `GOOGLE_CLIENT_ID` | Google OAuth client ID | `xxx.apps.googleusercontent.com` |
|
||||
| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret | (secret) |
|
||||
| `GH_CLIENT_ID` | GitHub OAuth client ID | `xxx` |
|
||||
| `GH_CLIENT_SECRET` | GitHub OAuth client secret | (secret) |
|
||||
| Variable | Required | Min Length | Description |
|
||||
| ---------------------- | -------- | ---------- | ----------------------- |
|
||||
| `JWT_SECRET` | Yes | 32 chars | JWT token signing key |
|
||||
| `JWT_SECRET_PREVIOUS` | No | - | Previous key (rotation) |
|
||||
| `GOOGLE_CLIENT_ID` | No | - | Google OAuth client ID |
|
||||
| `GOOGLE_CLIENT_SECRET` | No | - | Google OAuth secret |
|
||||
| `GITHUB_CLIENT_ID` | No | - | GitHub OAuth client ID |
|
||||
| `GITHUB_CLIENT_SECRET` | No | - | GitHub OAuth secret |
|
||||
|
||||
**Generate Secure Secret**:
|
||||
|
||||
```bash
|
||||
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
||||
```
|
||||
|
||||
### AI Services
|
||||
|
||||
| Variable | Description | Example |
|
||||
| -------------------------------- | ---------------------------- | ----------- |
|
||||
| `VITE_GOOGLE_GENAI_API_KEY` | Google Gemini API key (prod) | `AIzaSy...` |
|
||||
| `VITE_GOOGLE_GENAI_API_KEY_TEST` | Google Gemini API key (test) | `AIzaSy...` |
|
||||
| `GOOGLE_MAPS_API_KEY` | Google Maps Geocoding API | `AIzaSy...` |
|
||||
| Variable | Required | Description |
|
||||
| ---------------------------- | -------- | -------------------------------- |
|
||||
| `GEMINI_API_KEY` | Yes\* | Google Gemini API key |
|
||||
| `GEMINI_RPM` | No | Rate limit (default: 5) |
|
||||
| `AI_PRICE_QUALITY_THRESHOLD` | No | Quality threshold (default: 0.5) |
|
||||
|
||||
### Application
|
||||
\*Required for flyer processing. Application works without it but cannot extract flyer data.
|
||||
|
||||
| Variable | Description | Example |
|
||||
| -------------- | ------------------------ | ----------------------------------- |
|
||||
| `NODE_ENV` | Environment mode | `development`, `test`, `production` |
|
||||
| `PORT` | Backend server port | `3001` |
|
||||
| `FRONTEND_URL` | Frontend application URL | `http://localhost:5173` (dev) |
|
||||
**Get API Key**: [Google AI Studio](https://aistudio.google.com/app/apikey)
|
||||
|
||||
### Error Tracking
|
||||
### Google Services
|
||||
|
||||
| Variable | Description | Example |
|
||||
| ---------------------- | -------------------------------- | --------------------------- |
|
||||
| `SENTRY_DSN` | Sentry DSN (production) | `https://xxx@sentry.io/xxx` |
|
||||
| `VITE_SENTRY_DSN` | Frontend Sentry DSN (production) | `https://xxx@sentry.io/xxx` |
|
||||
| `SENTRY_DSN_TEST` | Sentry DSN (test) | `https://xxx@sentry.io/xxx` |
|
||||
| `VITE_SENTRY_DSN_TEST` | Frontend Sentry DSN (test) | `https://xxx@sentry.io/xxx` |
|
||||
| `SENTRY_AUTH_TOKEN` | Sentry API token for releases | (secret) |
|
||||
| Variable | Required | Description |
|
||||
| ---------------------- | -------- | -------------------------------- |
|
||||
| `GOOGLE_MAPS_API_KEY` | No | Google Maps Geocoding API |
|
||||
| `GOOGLE_CLIENT_ID` | No | OAuth (see Authentication above) |
|
||||
| `GOOGLE_CLIENT_SECRET` | No | OAuth (see Authentication above) |
|
||||
|
||||
## Optional Variables
|
||||
### UPC Lookup APIs
|
||||
|
||||
| Variable | Description | Default |
|
||||
| ------------------- | ----------------------- | ----------------- |
|
||||
| `LOG_LEVEL` | Logging verbosity | `info` |
|
||||
| `REDIS_TTL` | Cache TTL in seconds | `3600` |
|
||||
| `MAX_UPLOAD_SIZE` | Max file upload size | `10mb` |
|
||||
| `RATE_LIMIT_WINDOW` | Rate limit window (ms) | `900000` (15 min) |
|
||||
| `RATE_LIMIT_MAX` | Max requests per window | `100` |
|
||||
| Variable | Required | Description |
|
||||
| ------------------------ | -------- | ---------------------- |
|
||||
| `UPC_ITEM_DB_API_KEY` | No | UPC Item DB API key |
|
||||
| `BARCODE_LOOKUP_API_KEY` | No | Barcode Lookup API key |
|
||||
|
||||
### Application Settings
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
| -------------- | -------- | ------------- | ------------------------ |
|
||||
| `NODE_ENV` | No | `development` | Environment mode |
|
||||
| `PORT` | No | `3001` | Backend server port |
|
||||
| `FRONTEND_URL` | No | - | Frontend URL (CORS) |
|
||||
| `BASE_URL` | No | - | API base URL |
|
||||
| `STORAGE_PATH` | No | (see below) | Flyer image storage path |
|
||||
|
||||
**NODE_ENV Values**: `development`, `test`, `staging`, `production`
|
||||
|
||||
**Default STORAGE_PATH**: `/var/www/flyer-crawler.projectium.com/flyer-images`
|
||||
|
||||
### Email/SMTP Configuration
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
| ----------------- | -------- | ------- | ----------------------- |
|
||||
| `SMTP_HOST` | No | - | SMTP server hostname |
|
||||
| `SMTP_PORT` | No | `587` | SMTP server port |
|
||||
| `SMTP_USER` | No | - | SMTP username |
|
||||
| `SMTP_PASS` | No | - | SMTP password |
|
||||
| `SMTP_SECURE` | No | `false` | Use TLS |
|
||||
| `SMTP_FROM_EMAIL` | No | - | From address for emails |
|
||||
|
||||
**Note**: Email functionality degrades gracefully if not configured.
|
||||
|
||||
### Worker Configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------------------- | ------- | ---------------------------- |
|
||||
| `WORKER_CONCURRENCY` | `1` | Main worker concurrency |
|
||||
| `WORKER_LOCK_DURATION` | `30000` | Lock duration (ms) |
|
||||
| `EMAIL_WORKER_CONCURRENCY` | `10` | Email worker concurrency |
|
||||
| `ANALYTICS_WORKER_CONCURRENCY` | `1` | Analytics worker concurrency |
|
||||
| `CLEANUP_WORKER_CONCURRENCY` | `10` | Cleanup worker concurrency |
|
||||
| `WEEKLY_ANALYTICS_WORKER_CONCURRENCY` | `1` | Weekly analytics concurrency |
|
||||
|
||||
### Error Tracking (Bugsink/Sentry)
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
| --------------------- | -------- | -------- | ------------------------------- |
|
||||
| `SENTRY_DSN` | No | - | Backend Sentry DSN |
|
||||
| `SENTRY_ENABLED` | No | `true` | Enable error tracking |
|
||||
| `SENTRY_ENVIRONMENT` | No | NODE_ENV | Environment name for errors |
|
||||
| `SENTRY_DEBUG` | No | `false` | Enable Sentry SDK debug logging |
|
||||
| `VITE_SENTRY_DSN` | No | - | Frontend Sentry DSN |
|
||||
| `VITE_SENTRY_ENABLED` | No | `true` | Enable frontend error tracking |
|
||||
| `VITE_SENTRY_DEBUG` | No | `false` | Frontend SDK debug logging |
|
||||
|
||||
**DSN Format**: `http://[key]@[host]:[port]/[project_id]`
|
||||
|
||||
**Dev Container DSNs**:
|
||||
|
||||
```bash
|
||||
# Backend (internal)
|
||||
SENTRY_DSN=http://<key>@localhost:8000/1
|
||||
|
||||
# Frontend (via nginx proxy)
|
||||
VITE_SENTRY_DSN=https://<key>@localhost/bugsink-api/2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Files
|
||||
|
||||
| File | Purpose |
|
||||
| ------------------------------------- | ------------------------------------------- |
|
||||
| `src/config/env.ts` | Zod schema validation - **source of truth** |
|
||||
| `ecosystem.config.cjs` | PM2 process manager config |
|
||||
| `ecosystem.config.cjs` | PM2 process manager (production) |
|
||||
| `ecosystem.dev.config.cjs` | PM2 process manager (development) |
|
||||
| `.gitea/workflows/deploy-to-prod.yml` | Production deployment workflow |
|
||||
| `.gitea/workflows/deploy-to-test.yml` | Test deployment workflow |
|
||||
| `.env.example` | Template with all variables |
|
||||
| `.env.local` | Dev container overrides (not in git) |
|
||||
| `.env.test` | Test environment overrides (not in git) |
|
||||
|
||||
---
|
||||
|
||||
## Adding New Variables
|
||||
|
||||
### 1. Update Zod Schema
|
||||
### Checklist
|
||||
|
||||
1. [ ] **Update Zod Schema** - Edit `src/config/env.ts`
|
||||
2. [ ] **Add to Gitea Secrets** - For prod/test environments
|
||||
3. [ ] **Update Deployment Workflows** - `.gitea/workflows/*.yml`
|
||||
4. [ ] **Update PM2 Config** - `ecosystem.config.cjs`
|
||||
5. [ ] **Update .env.example** - Template for developers
|
||||
6. [ ] **Update this document** - Add to appropriate section
|
||||
|
||||
### Step-by-Step
|
||||
|
||||
#### 1. Update Zod Schema
|
||||
|
||||
Edit `src/config/env.ts`:
|
||||
|
||||
```typescript
|
||||
const envSchema = z.object({
|
||||
// ... existing variables ...
|
||||
NEW_VARIABLE: z.string().min(1),
|
||||
newSection: z.object({
|
||||
newVariable: z.string().min(1, 'NEW_VARIABLE is required'),
|
||||
}),
|
||||
});
|
||||
|
||||
// In loadEnvVars():
|
||||
newSection: {
|
||||
newVariable: process.env.NEW_VARIABLE,
|
||||
},
|
||||
```
|
||||
|
||||
### 2. Add to Gitea Secrets
|
||||
|
||||
For prod/test environments:
|
||||
#### 2. Add to Gitea Secrets
|
||||
|
||||
1. Go to Gitea repository Settings > Secrets
|
||||
2. Add `NEW_VARIABLE` with value
|
||||
2. Add `NEW_VARIABLE` with production value
|
||||
3. Add `NEW_VARIABLE_TEST` if test needs different value
|
||||
|
||||
### 3. Update Deployment Workflows
|
||||
#### 3. Update Deployment Workflows
|
||||
|
||||
Edit `.gitea/workflows/deploy-to-prod.yml`:
|
||||
|
||||
@@ -145,7 +270,7 @@ env:
|
||||
NEW_VARIABLE: ${{ secrets.NEW_VARIABLE_TEST }}
|
||||
```
|
||||
|
||||
### 4. Update PM2 Config
|
||||
#### 4. Update PM2 Config
|
||||
|
||||
Edit `ecosystem.config.cjs`:
|
||||
|
||||
@@ -161,31 +286,36 @@ module.exports = {
|
||||
};
|
||||
```
|
||||
|
||||
### 5. Update Documentation
|
||||
|
||||
- Add to `.env.example`
|
||||
- Update this document
|
||||
- Document in relevant feature docs
|
||||
---
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Secrets Management
|
||||
### Do
|
||||
|
||||
- **NEVER** commit secrets to git
|
||||
- Use Gitea Secrets for prod/test
|
||||
- Use `.env.local` for dev (gitignored)
|
||||
- Generate secrets with cryptographic randomness
|
||||
- Rotate secrets regularly
|
||||
- Use environment-specific database users
|
||||
|
||||
### Do Not
|
||||
|
||||
- Commit secrets to git
|
||||
- Use short or predictable secrets
|
||||
- Share secrets across environments
|
||||
- Log sensitive values
|
||||
|
||||
### Secret Generation
|
||||
|
||||
```bash
|
||||
# Generate secure random secrets
|
||||
# Generate secure random secrets (64 hex characters)
|
||||
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
||||
|
||||
# Example output:
|
||||
# a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
|
||||
```
|
||||
|
||||
### Database Users
|
||||
|
||||
Each environment has its own PostgreSQL user:
|
||||
### Database Users by Environment
|
||||
|
||||
| Environment | User | Database |
|
||||
| ----------- | -------------------- | -------------------- |
|
||||
@@ -193,44 +323,61 @@ Each environment has its own PostgreSQL user:
|
||||
| Test | `flyer_crawler_test` | `flyer-crawler-test` |
|
||||
| Development | `postgres` | `flyer_crawler_dev` |
|
||||
|
||||
**Setup Commands** (as postgres superuser):
|
||||
|
||||
```sql
|
||||
-- Production
|
||||
CREATE DATABASE "flyer-crawler-prod";
|
||||
CREATE USER flyer_crawler_prod WITH PASSWORD 'secure-password';
|
||||
ALTER DATABASE "flyer-crawler-prod" OWNER TO flyer_crawler_prod;
|
||||
\c "flyer-crawler-prod"
|
||||
ALTER SCHEMA public OWNER TO flyer_crawler_prod;
|
||||
GRANT CREATE, USAGE ON SCHEMA public TO flyer_crawler_prod;
|
||||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||
CREATE EXTENSION IF NOT EXISTS postgis;
|
||||
CREATE EXTENSION IF NOT EXISTS pg_trgm;
|
||||
|
||||
-- Test (similar commands with _test suffix)
|
||||
```
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
Environment variables are validated at startup via `src/config/env.ts`. If validation fails:
|
||||
Environment variables are validated at startup via `src/config/env.ts`.
|
||||
|
||||
1. Check the error message for missing/invalid variables
|
||||
2. Verify `.env.local` (dev) or Gitea Secrets (prod/test)
|
||||
3. Ensure values match schema requirements (min length, format, etc.)
|
||||
### Startup Validation
|
||||
|
||||
If validation fails, you will see:
|
||||
|
||||
```text
|
||||
╔════════════════════════════════════════════════════════════════╗
|
||||
║ CONFIGURATION ERROR - APPLICATION STARTUP ║
|
||||
╚════════════════════════════════════════════════════════════════╝
|
||||
|
||||
The following environment variables are missing or invalid:
|
||||
|
||||
- database.host: DB_HOST is required
|
||||
- auth.jwtSecret: JWT_SECRET must be at least 32 characters
|
||||
|
||||
Please check your .env file or environment configuration.
|
||||
```
|
||||
|
||||
### Debugging Configuration
|
||||
|
||||
```bash
|
||||
# Check what variables are set (dev container)
|
||||
podman exec flyer-crawler-dev env | grep -E "^(DB_|REDIS_|JWT_|SENTRY_)"
|
||||
|
||||
# Test database connection
|
||||
podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "SELECT 1;"
|
||||
|
||||
# Test Redis connection
|
||||
podman exec flyer-crawler-redis redis-cli ping
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Variable Not Found
|
||||
|
||||
```
|
||||
```text
|
||||
Error: Missing required environment variable: JWT_SECRET
|
||||
```
|
||||
|
||||
**Solution**: Add the variable to your environment configuration.
|
||||
**Solutions**:
|
||||
|
||||
1. Check `.env.local` exists and has the variable
|
||||
2. Verify variable name matches schema exactly
|
||||
3. Restart the application after changes
|
||||
|
||||
### Invalid Value
|
||||
|
||||
```
|
||||
```text
|
||||
Error: JWT_SECRET must be at least 32 characters
|
||||
```
|
||||
|
||||
@@ -240,32 +387,36 @@ Error: JWT_SECRET must be at least 32 characters
|
||||
|
||||
Check `NODE_ENV` is set correctly:
|
||||
|
||||
- `development` - Local dev container
|
||||
- `test` - CI/CD test server
|
||||
- `production` - Production server
|
||||
| Value | Purpose |
|
||||
| ------------- | ---------------------- |
|
||||
| `development` | Local dev container |
|
||||
| `test` | CI/CD test server |
|
||||
| `staging` | Pre-production testing |
|
||||
| `production` | Production server |
|
||||
|
||||
### Database Connection Issues
|
||||
|
||||
Verify database credentials:
|
||||
|
||||
```bash
|
||||
# Development
|
||||
podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "SELECT 1;"
|
||||
|
||||
# Production (via SSH)
|
||||
ssh root@projectium.com "psql -U flyer_crawler_prod -d flyer-crawler-prod -c 'SELECT 1;'"
|
||||
# If connection fails, check:
|
||||
# 1. Container is running: podman ps
|
||||
# 2. DB_HOST matches container network
|
||||
# 3. DB_PASSWORD is correct
|
||||
```
|
||||
|
||||
## Reference
|
||||
---
|
||||
|
||||
- **Validation Schema**: [src/config/env.ts](../../src/config/env.ts)
|
||||
- **Template**: [.env.example](../../.env.example)
|
||||
- **Deployment Workflows**: [.gitea/workflows/](../../.gitea/workflows/)
|
||||
- **PM2 Config**: [ecosystem.config.cjs](../../ecosystem.config.cjs)
|
||||
|
||||
## See Also
|
||||
## Related Documentation
|
||||
|
||||
- [QUICKSTART.md](QUICKSTART.md) - Quick setup guide
|
||||
- [INSTALL.md](INSTALL.md) - Detailed installation
|
||||
- [DEV-CONTAINER.md](../development/DEV-CONTAINER.md) - Dev container setup
|
||||
- [DEPLOYMENT.md](../operations/DEPLOYMENT.md) - Production deployment
|
||||
- [AUTHENTICATION.md](../architecture/AUTHENTICATION.md) - OAuth setup
|
||||
- [ADR-007](../adr/0007-configuration-and-secrets-management.md) - Configuration decisions
|
||||
|
||||
---
|
||||
|
||||
Last updated: January 2026
|
||||
|
||||
@@ -1,203 +1,453 @@
|
||||
# Installation Guide
|
||||
|
||||
This guide covers setting up a local development environment for Flyer Crawler.
|
||||
Complete setup instructions for the Flyer Crawler local development environment.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Setup Method | Best For | Time | Document Section |
|
||||
| ----------------- | --------------------------- | ------ | --------------------------------------------------- |
|
||||
| Quick Start | Already have Postgres/Redis | 5 min | [Quick Start](#quick-start) |
|
||||
| Dev Container | Full production-like setup | 15 min | [Dev Container](#development-container-recommended) |
|
||||
| Manual Containers | Learning the components | 20 min | [Podman Setup](#podman-setup-manual) |
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20.x or later
|
||||
- Access to a PostgreSQL database (local or remote)
|
||||
- Redis instance (for session management)
|
||||
- Google Gemini API key
|
||||
- Google Maps API key (for geocoding)
|
||||
### Required Software
|
||||
|
||||
| Software | Minimum Version | Purpose | Download |
|
||||
| -------------- | --------------- | -------------------- | ----------------------------------------------- |
|
||||
| Node.js | 20.x | Runtime | [nodejs.org](https://nodejs.org/) |
|
||||
| Podman Desktop | 4.x | Container management | [podman-desktop.io](https://podman-desktop.io/) |
|
||||
| Git | 2.x | Version control | [git-scm.com](https://git-scm.com/) |
|
||||
|
||||
### Windows-Specific Requirements
|
||||
|
||||
| Requirement | Purpose | Setup Command |
|
||||
| ----------- | ------------------------------ | ---------------------------------- |
|
||||
| WSL 2 | Linux compatibility for Podman | `wsl --install` (admin PowerShell) |
|
||||
|
||||
### Verify Installation
|
||||
|
||||
```bash
|
||||
# Check all prerequisites
|
||||
node --version # Expected: v20.x or higher
|
||||
podman --version # Expected: podman version 4.x or higher
|
||||
git --version # Expected: git version 2.x or higher
|
||||
wsl --list -v # Expected: Shows WSL 2 distro
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
If you already have PostgreSQL and Redis configured:
|
||||
If you already have PostgreSQL and Redis configured externally:
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
# 1. Clone the repository
|
||||
git clone https://gitea.projectium.com/flyer-crawler/flyer-crawler.git
|
||||
cd flyer-crawler
|
||||
|
||||
# 2. Install dependencies
|
||||
npm install
|
||||
|
||||
# Run in development mode
|
||||
# 3. Create .env.local (see Environment section below)
|
||||
|
||||
# 4. Run in development mode
|
||||
npm run dev
|
||||
```
|
||||
|
||||
**Access Points**:
|
||||
|
||||
- Frontend: `http://localhost:5173`
|
||||
- Backend API: `http://localhost:3001`
|
||||
|
||||
---
|
||||
|
||||
## Development Environment with Podman (Recommended for Windows)
|
||||
## Development Container (Recommended)
|
||||
|
||||
This approach uses Podman with an Ubuntu container for a consistent development environment.
|
||||
The dev container provides a complete, production-like environment.
|
||||
|
||||
### What's Included
|
||||
|
||||
| Service | Purpose | Port |
|
||||
| ---------- | ------------------------ | ---------- |
|
||||
| Node.js | API server, worker, Vite | 3001, 5173 |
|
||||
| PostgreSQL | Database with PostGIS | 5432 |
|
||||
| Redis | Cache and job queues | 6379 |
|
||||
| NGINX | HTTPS reverse proxy | 443 |
|
||||
| Bugsink | Error tracking | 8443 |
|
||||
| Logstash | Log aggregation | - |
|
||||
| PM2 | Process management | - |
|
||||
|
||||
### Setup Steps
|
||||
|
||||
#### Step 1: Initialize Podman
|
||||
|
||||
```bash
|
||||
# Windows: Start Podman Desktop, or from terminal:
|
||||
podman machine init
|
||||
podman machine start
|
||||
```
|
||||
|
||||
#### Step 2: Start Dev Container
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
podman-compose -f compose.dev.yml up -d
|
||||
|
||||
# View logs (optional)
|
||||
podman-compose -f compose.dev.yml logs -f
|
||||
```
|
||||
|
||||
**Expected Output**:
|
||||
|
||||
```text
|
||||
[+] Running 3/3
|
||||
- Container flyer-crawler-postgres Started
|
||||
- Container flyer-crawler-redis Started
|
||||
- Container flyer-crawler-dev Started
|
||||
```
|
||||
|
||||
#### Step 3: Verify Services
|
||||
|
||||
```bash
|
||||
# Check containers are running
|
||||
podman ps
|
||||
|
||||
# Check PM2 processes
|
||||
podman exec -it flyer-crawler-dev pm2 status
|
||||
```
|
||||
|
||||
**Expected PM2 Status**:
|
||||
|
||||
```text
|
||||
+---------------------------+--------+-------+
|
||||
| name | status | cpu |
|
||||
+---------------------------+--------+-------+
|
||||
| flyer-crawler-api-dev | online | 0% |
|
||||
| flyer-crawler-worker-dev | online | 0% |
|
||||
| flyer-crawler-vite-dev | online | 0% |
|
||||
+---------------------------+--------+-------+
|
||||
```
|
||||
|
||||
#### Step 4: Access Application
|
||||
|
||||
| Service | URL | Notes |
|
||||
| ----------- | ------------------------ | ---------------------------- |
|
||||
| Frontend | `https://localhost` | NGINX proxies to Vite |
|
||||
| Backend API | `http://localhost:3001` | Express server |
|
||||
| Bugsink | `https://localhost:8443` | Login: admin@localhost/admin |
|
||||
|
||||
### SSL Certificate Setup (Optional but Recommended)
|
||||
|
||||
To eliminate browser security warnings:
|
||||
|
||||
**Windows**:
|
||||
|
||||
1. Double-click `certs/mkcert-ca.crt`
|
||||
2. Click "Install Certificate..."
|
||||
3. Select "Local Machine" > Next
|
||||
4. Select "Place all certificates in the following store"
|
||||
5. Browse > Select "Trusted Root Certification Authorities" > OK
|
||||
6. Click Next > Finish
|
||||
7. Restart browser
|
||||
|
||||
**Other Platforms**: See [`certs/README.md`](../../certs/README.md)
|
||||
|
||||
### Managing the Dev Container
|
||||
|
||||
| Action | Command |
|
||||
| --------- | ------------------------------------------- |
|
||||
| Start | `podman-compose -f compose.dev.yml up -d` |
|
||||
| Stop | `podman-compose -f compose.dev.yml down` |
|
||||
| View logs | `podman-compose -f compose.dev.yml logs -f` |
|
||||
| Restart | `podman-compose -f compose.dev.yml restart` |
|
||||
| Rebuild | `podman-compose -f compose.dev.yml build` |
|
||||
|
||||
---
|
||||
|
||||
## Podman Setup (Manual)
|
||||
|
||||
For understanding the individual components or custom configurations.
|
||||
|
||||
### Step 1: Install Prerequisites on Windows
|
||||
|
||||
1. **Install WSL 2**: Podman on Windows relies on the Windows Subsystem for Linux.
|
||||
```powershell
|
||||
# Run in administrator PowerShell
|
||||
wsl --install
|
||||
```
|
||||
|
||||
```powershell
|
||||
wsl --install
|
||||
```
|
||||
Restart computer after WSL installation.
|
||||
|
||||
Run this in an administrator PowerShell.
|
||||
### Step 2: Initialize Podman
|
||||
|
||||
2. **Install Podman Desktop**: Download and install [Podman Desktop for Windows](https://podman-desktop.io/).
|
||||
1. Launch **Podman Desktop**
|
||||
2. Follow the setup wizard to initialize Podman machine
|
||||
3. Start the Podman machine
|
||||
|
||||
### Step 2: Set Up Podman
|
||||
|
||||
1. **Initialize Podman**: Launch Podman Desktop. It will automatically set up its WSL 2 machine.
|
||||
2. **Start Podman**: Ensure the Podman machine is running from the Podman Desktop interface.
|
||||
|
||||
### Step 3: Set Up the Ubuntu Container
|
||||
|
||||
1. **Pull Ubuntu Image**:
|
||||
|
||||
```bash
|
||||
podman pull ubuntu:latest
|
||||
```
|
||||
|
||||
2. **Create a Podman Volume** (persists node_modules between container restarts):
|
||||
|
||||
```bash
|
||||
podman volume create node_modules_cache
|
||||
```
|
||||
|
||||
3. **Run the Ubuntu Container**:
|
||||
|
||||
Open a terminal in your project's root directory and run:
|
||||
|
||||
```bash
|
||||
podman run -it -p 3001:3001 -p 5173:5173 --name flyer-dev \
|
||||
-v "$(pwd):/app" \
|
||||
-v "node_modules_cache:/app/node_modules" \
|
||||
ubuntu:latest
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
| ------------------------------------------- | ------------------------------------------------ |
|
||||
| `-p 3001:3001` | Forwards the backend server port |
|
||||
| `-p 5173:5173` | Forwards the Vite frontend server port |
|
||||
| `--name flyer-dev` | Names the container for easy reference |
|
||||
| `-v "...:/app"` | Mounts your project directory into the container |
|
||||
| `-v "node_modules_cache:/app/node_modules"` | Mounts the named volume for node_modules |
|
||||
|
||||
### Step 4: Configure the Ubuntu Environment
|
||||
|
||||
You are now inside the Ubuntu container's shell.
|
||||
|
||||
1. **Update Package Lists**:
|
||||
|
||||
```bash
|
||||
apt-get update
|
||||
```
|
||||
|
||||
2. **Install Dependencies**:
|
||||
|
||||
```bash
|
||||
apt-get install -y curl git
|
||||
curl -sL https://deb.nodesource.com/setup_20.x | bash -
|
||||
apt-get install -y nodejs
|
||||
```
|
||||
|
||||
3. **Navigate to Project Directory**:
|
||||
|
||||
```bash
|
||||
cd /app
|
||||
```
|
||||
|
||||
4. **Install Project Dependencies**:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Step 5: Run the Development Server
|
||||
Or from terminal:
|
||||
|
||||
```bash
|
||||
podman machine init
|
||||
podman machine start
|
||||
```
|
||||
|
||||
### Step 3: Create Podman Network
|
||||
|
||||
```bash
|
||||
podman network create flyer-crawler-net
|
||||
```
|
||||
|
||||
### Step 4: Create PostgreSQL Container
|
||||
|
||||
```bash
|
||||
podman run -d \
|
||||
--name flyer-crawler-postgres \
|
||||
--network flyer-crawler-net \
|
||||
-e POSTGRES_USER=postgres \
|
||||
-e POSTGRES_PASSWORD=postgres \
|
||||
-e POSTGRES_DB=flyer_crawler_dev \
|
||||
-p 5432:5432 \
|
||||
-v flyer-crawler-pgdata:/var/lib/postgresql/data \
|
||||
docker.io/postgis/postgis:15-3.3
|
||||
```
|
||||
|
||||
### Step 5: Create Redis Container
|
||||
|
||||
```bash
|
||||
podman run -d \
|
||||
--name flyer-crawler-redis \
|
||||
--network flyer-crawler-net \
|
||||
-p 6379:6379 \
|
||||
-v flyer-crawler-redis:/data \
|
||||
docker.io/library/redis:alpine
|
||||
```
|
||||
|
||||
### Step 6: Initialize Database
|
||||
|
||||
```bash
|
||||
# Wait for PostgreSQL to be ready
|
||||
podman exec flyer-crawler-postgres pg_isready -U postgres
|
||||
|
||||
# Install required extensions
|
||||
podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "
|
||||
CREATE EXTENSION IF NOT EXISTS postgis;
|
||||
CREATE EXTENSION IF NOT EXISTS pg_trgm;
|
||||
CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";
|
||||
"
|
||||
|
||||
# Apply schema
|
||||
podman exec -i flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev < sql/master_schema_rollup.sql
|
||||
```
|
||||
|
||||
### Step 7: Create Node.js Container
|
||||
|
||||
```bash
|
||||
# Create volume for node_modules
|
||||
podman volume create node_modules_cache
|
||||
|
||||
# Run Ubuntu container with project mounted
|
||||
podman run -it \
|
||||
--name flyer-dev \
|
||||
--network flyer-crawler-net \
|
||||
-p 3001:3001 \
|
||||
-p 5173:5173 \
|
||||
-v "$(pwd):/app" \
|
||||
-v "node_modules_cache:/app/node_modules" \
|
||||
ubuntu:latest
|
||||
```
|
||||
|
||||
### Step 8: Configure Container Environment
|
||||
|
||||
Inside the container:
|
||||
|
||||
```bash
|
||||
# Update and install dependencies
|
||||
apt-get update
|
||||
apt-get install -y curl git
|
||||
|
||||
# Install Node.js 20
|
||||
curl -sL https://deb.nodesource.com/setup_20.x | bash -
|
||||
apt-get install -y nodejs
|
||||
|
||||
# Navigate to project and install
|
||||
cd /app
|
||||
npm install
|
||||
|
||||
# Start development server
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Step 6: Access the Application
|
||||
### Container Management Commands
|
||||
|
||||
- **Frontend**: http://localhost:5173
|
||||
- **Backend API**: http://localhost:3001
|
||||
|
||||
### Dev Container with HTTPS (Full Stack)
|
||||
|
||||
When using the full dev container stack with NGINX (via `compose.dev.yml`), access the application over HTTPS:
|
||||
|
||||
- **Frontend**: https://localhost or https://127.0.0.1
|
||||
- **Backend API**: http://localhost:3001
|
||||
|
||||
**SSL Certificate Notes:**
|
||||
|
||||
- The dev container uses self-signed certificates generated by mkcert
|
||||
- Both `localhost` and `127.0.0.1` are valid hostnames (certificate includes both as SANs)
|
||||
- If images fail to load with SSL errors, see [FLYER-URL-CONFIGURATION.md](../FLYER-URL-CONFIGURATION.md#ssl-certificate-configuration-dev-container)
|
||||
|
||||
**Eliminate SSL Warnings (Recommended):**
|
||||
|
||||
To avoid browser security warnings for self-signed certificates, install the mkcert CA certificate on your system. The CA certificate is located at `certs/mkcert-ca.crt` in the project root.
|
||||
|
||||
See [`certs/README.md`](../../certs/README.md) for platform-specific installation instructions (Windows, macOS, Linux, Firefox).
|
||||
|
||||
After installation:
|
||||
|
||||
- Your browser will trust all mkcert certificates without warnings
|
||||
- Both `https://localhost/` and `https://127.0.0.1/` will work without SSL errors
|
||||
- Flyer images will load without `ERR_CERT_AUTHORITY_INVALID` errors
|
||||
|
||||
### Managing the Container
|
||||
|
||||
| Action | Command |
|
||||
| --------------------- | -------------------------------- |
|
||||
| Stop the container | Press `Ctrl+C`, then type `exit` |
|
||||
| Restart the container | `podman start -a -i flyer-dev` |
|
||||
| Remove the container | `podman rm flyer-dev` |
|
||||
| Action | Command |
|
||||
| -------------- | ------------------------------ |
|
||||
| Stop container | Press `Ctrl+C`, then `exit` |
|
||||
| Restart | `podman start -a -i flyer-dev` |
|
||||
| Remove | `podman rm flyer-dev` |
|
||||
| List running | `podman ps` |
|
||||
| List all | `podman ps -a` |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
## Environment Configuration
|
||||
|
||||
This project is configured to run in a CI/CD environment and does not use `.env` files. All configuration must be provided as environment variables.
|
||||
### Create .env.local
|
||||
|
||||
For local development, you can export these in your shell or use your IDE's environment configuration:
|
||||
Create `.env.local` in the project root with your configuration:
|
||||
|
||||
| Variable | Description |
|
||||
| --------------------------- | ------------------------------------- |
|
||||
| `DB_HOST` | PostgreSQL server hostname |
|
||||
| `DB_USER` | PostgreSQL username |
|
||||
| `DB_PASSWORD` | PostgreSQL password |
|
||||
| `DB_DATABASE_PROD` | Production database name |
|
||||
| `JWT_SECRET` | Secret string for signing auth tokens |
|
||||
| `VITE_GOOGLE_GENAI_API_KEY` | Google Gemini API key |
|
||||
| `GOOGLE_MAPS_API_KEY` | Google Maps Geocoding API key |
|
||||
| `REDIS_PASSWORD_PROD` | Production Redis password |
|
||||
| `REDIS_PASSWORD_TEST` | Test Redis password |
|
||||
```bash
|
||||
# Database (adjust host based on your setup)
|
||||
DB_HOST=localhost # Use 'postgres' if inside dev container
|
||||
DB_PORT=5432
|
||||
DB_USER=postgres
|
||||
DB_PASSWORD=postgres
|
||||
DB_NAME=flyer_crawler_dev
|
||||
|
||||
# Redis (adjust host based on your setup)
|
||||
REDIS_URL=redis://localhost:6379 # Use 'redis://redis:6379' inside container
|
||||
|
||||
# Application
|
||||
NODE_ENV=development
|
||||
PORT=3001
|
||||
FRONTEND_URL=http://localhost:5173
|
||||
|
||||
# Authentication (generate secure values)
|
||||
JWT_SECRET=your-secret-at-least-32-characters-long
|
||||
|
||||
# AI Services
|
||||
GEMINI_API_KEY=your-google-gemini-api-key
|
||||
GOOGLE_MAPS_API_KEY=your-google-maps-api-key # Optional
|
||||
```
|
||||
|
||||
**Generate Secure Secrets**:
|
||||
|
||||
```bash
|
||||
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
||||
```
|
||||
|
||||
### Environment Differences
|
||||
|
||||
| Variable | Host Development | Inside Dev Container |
|
||||
| ----------- | ------------------------ | -------------------- |
|
||||
| `DB_HOST` | `localhost` | `postgres` |
|
||||
| `REDIS_URL` | `redis://localhost:6379` | `redis://redis:6379` |
|
||||
|
||||
See [ENVIRONMENT.md](ENVIRONMENT.md) for complete variable reference.
|
||||
|
||||
---
|
||||
|
||||
## Seeding Development Data
|
||||
|
||||
To create initial test accounts (`admin@example.com` and `user@example.com`) and sample data:
|
||||
Create test accounts and sample data:
|
||||
|
||||
```bash
|
||||
npm run seed
|
||||
```
|
||||
|
||||
The seed script performs the following actions:
|
||||
### What the Seed Script Does
|
||||
|
||||
1. Rebuilds the database schema from `sql/master_schema_rollup.sql`
|
||||
2. Creates test user accounts (admin and regular user)
|
||||
3. Copies test flyer images from `src/tests/assets/` to `public/flyer-images/`
|
||||
4. Creates a sample flyer with items linked to the test images
|
||||
5. Seeds watched items and a shopping list for the test user
|
||||
1. Rebuilds database schema from `sql/master_schema_rollup.sql`
|
||||
2. Creates test user accounts:
|
||||
- `admin@example.com` (admin user)
|
||||
- `user@example.com` (regular user)
|
||||
3. Copies test flyer images to `public/flyer-images/`
|
||||
4. Creates sample flyer with items
|
||||
5. Seeds watched items and shopping list
|
||||
|
||||
**Test Images**: The seed script copies `test-flyer-image.jpg` and `test-flyer-icon.png` to the `public/flyer-images/` directory, which is served by NGINX at `/flyer-images/`.
|
||||
### Test Images
|
||||
|
||||
After running, you may need to restart your IDE's TypeScript server to pick up any generated types.
|
||||
The seed script copies these files from `src/tests/assets/`:
|
||||
|
||||
- `test-flyer-image.jpg`
|
||||
- `test-flyer-icon.png`
|
||||
|
||||
Images are served by NGINX at `/flyer-images/`.
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After installation, verify everything works:
|
||||
|
||||
- [ ] **Containers running**: `podman ps` shows postgres and redis
|
||||
- [ ] **Database accessible**: `podman exec flyer-crawler-postgres psql -U postgres -c "SELECT 1;"`
|
||||
- [ ] **Frontend loads**: Open `http://localhost:5173` (or `https://localhost` for dev container)
|
||||
- [ ] **API responds**: `curl http://localhost:3001/health`
|
||||
- [ ] **Tests pass**: `npm run test:unit` (or in container: `podman exec -it flyer-crawler-dev npm run test:unit`)
|
||||
- [ ] **Type check passes**: `npm run type-check`
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Podman Machine Won't Start
|
||||
|
||||
```bash
|
||||
# Reset Podman machine
|
||||
podman machine rm
|
||||
podman machine init
|
||||
podman machine start
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
```bash
|
||||
# Find process using port
|
||||
netstat -ano | findstr :5432
|
||||
|
||||
# Option: Use different port
|
||||
podman run -d --name flyer-crawler-postgres -p 5433:5432 ...
|
||||
# Then set DB_PORT=5433 in .env.local
|
||||
```
|
||||
|
||||
### Database Extensions Missing
|
||||
|
||||
```bash
|
||||
podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "
|
||||
CREATE EXTENSION IF NOT EXISTS postgis;
|
||||
CREATE EXTENSION IF NOT EXISTS pg_trgm;
|
||||
CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";
|
||||
"
|
||||
```
|
||||
|
||||
### Permission Denied on Windows Paths
|
||||
|
||||
Use `MSYS_NO_PATHCONV=1` prefix:
|
||||
|
||||
```bash
|
||||
MSYS_NO_PATHCONV=1 podman exec flyer-crawler-dev /path/to/script.sh
|
||||
```
|
||||
|
||||
### Tests Fail with Timezone Errors
|
||||
|
||||
Tests must run in the dev container, not on Windows host:
|
||||
|
||||
```bash
|
||||
# CORRECT
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
|
||||
# INCORRECT (may fail with TZ errors)
|
||||
npm test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Database Setup](DATABASE.md) - Set up PostgreSQL with required extensions
|
||||
- [Authentication Setup](AUTHENTICATION.md) - Configure OAuth providers
|
||||
- [Deployment Guide](DEPLOYMENT.md) - Deploy to production
|
||||
| Goal | Document |
|
||||
| --------------------- | ------------------------------------------------------ |
|
||||
| Quick setup guide | [QUICKSTART.md](QUICKSTART.md) |
|
||||
| Environment variables | [ENVIRONMENT.md](ENVIRONMENT.md) |
|
||||
| Database schema | [DATABASE.md](../architecture/DATABASE.md) |
|
||||
| Authentication setup | [AUTHENTICATION.md](../architecture/AUTHENTICATION.md) |
|
||||
| Dev container details | [DEV-CONTAINER.md](../development/DEV-CONTAINER.md) |
|
||||
| Deployment | [DEPLOYMENT.md](../operations/DEPLOYMENT.md) |
|
||||
|
||||
---
|
||||
|
||||
Last updated: January 2026
|
||||
|
||||
@@ -2,13 +2,38 @@
|
||||
|
||||
Get Flyer Crawler running in 5 minutes.
|
||||
|
||||
## Prerequisites
|
||||
---
|
||||
|
||||
- **Windows 10/11** with WSL 2
|
||||
- **Podman Desktop** installed
|
||||
- **Node.js 20+** installed
|
||||
## Prerequisites Checklist
|
||||
|
||||
## 1. Start Containers (1 minute)
|
||||
Before starting, verify you have:
|
||||
|
||||
- [ ] **Windows 10/11** with WSL 2 enabled
|
||||
- [ ] **Podman Desktop** installed ([download](https://podman-desktop.io/))
|
||||
- [ ] **Node.js 20+** installed
|
||||
- [ ] **Git** for cloning the repository
|
||||
|
||||
**Verify Prerequisites**:
|
||||
|
||||
```bash
|
||||
# Check Podman
|
||||
podman --version
|
||||
# Expected: podman version 4.x or higher
|
||||
|
||||
# Check Node.js
|
||||
node --version
|
||||
# Expected: v20.x or higher
|
||||
|
||||
# Check WSL
|
||||
wsl --list --verbose
|
||||
# Expected: Shows WSL 2 distro
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Setup (5 Steps)
|
||||
|
||||
### Step 1: Start Containers (1 minute)
|
||||
|
||||
```bash
|
||||
# Start PostgreSQL and Redis
|
||||
@@ -27,11 +52,18 @@ podman run -d --name flyer-crawler-redis \
|
||||
docker.io/library/redis:alpine
|
||||
```
|
||||
|
||||
## 2. Initialize Database (2 minutes)
|
||||
**Expected Output**:
|
||||
|
||||
```text
|
||||
# Container IDs displayed, no errors
|
||||
```
|
||||
|
||||
### Step 2: Initialize Database (2 minutes)
|
||||
|
||||
```bash
|
||||
# Wait for PostgreSQL to be ready
|
||||
podman exec flyer-crawler-postgres pg_isready -U postgres
|
||||
# Expected: localhost:5432 - accepting connections
|
||||
|
||||
# Install extensions
|
||||
podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev \
|
||||
@@ -41,7 +73,17 @@ podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev \
|
||||
podman exec -i flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev < sql/master_schema_rollup.sql
|
||||
```
|
||||
|
||||
## 3. Configure Environment (1 minute)
|
||||
**Expected Output**:
|
||||
|
||||
```text
|
||||
CREATE EXTENSION
|
||||
CREATE EXTENSION
|
||||
CREATE EXTENSION
|
||||
CREATE TABLE
|
||||
... (many tables created)
|
||||
```
|
||||
|
||||
### Step 3: Configure Environment (1 minute)
|
||||
|
||||
Create `.env.local` in the project root:
|
||||
|
||||
@@ -61,16 +103,22 @@ NODE_ENV=development
|
||||
PORT=3001
|
||||
FRONTEND_URL=http://localhost:5173
|
||||
|
||||
# Secrets (generate your own)
|
||||
# Secrets (generate your own - see command below)
|
||||
JWT_SECRET=your-dev-jwt-secret-at-least-32-chars-long
|
||||
SESSION_SECRET=your-dev-session-secret-at-least-32-chars-long
|
||||
|
||||
# AI Services (get your own keys)
|
||||
VITE_GOOGLE_GENAI_API_KEY=your-google-genai-api-key
|
||||
GEMINI_API_KEY=your-google-gemini-api-key
|
||||
GOOGLE_MAPS_API_KEY=your-google-maps-api-key
|
||||
```
|
||||
|
||||
## 4. Install & Run (1 minute)
|
||||
**Generate Secure Secrets**:
|
||||
|
||||
```bash
|
||||
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
||||
```
|
||||
|
||||
### Step 4: Install and Run (1 minute)
|
||||
|
||||
```bash
|
||||
# Install dependencies (first time only)
|
||||
@@ -80,35 +128,61 @@ npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## 5. Access Application
|
||||
**Expected Output**:
|
||||
|
||||
- **Frontend**: http://localhost:5173
|
||||
- **Backend API**: http://localhost:3001
|
||||
- **Health Check**: http://localhost:3001/health
|
||||
```text
|
||||
> flyer-crawler@x.x.x dev
|
||||
> concurrently ...
|
||||
|
||||
### Dev Container (HTTPS)
|
||||
[API] Server listening on port 3001
|
||||
[Vite] VITE ready at http://localhost:5173
|
||||
```
|
||||
|
||||
When using the full dev container with NGINX, access via HTTPS:
|
||||
### Step 5: Verify Installation
|
||||
|
||||
- **Frontend**: https://localhost or https://127.0.0.1
|
||||
- **Backend API**: http://localhost:3001
|
||||
- **Bugsink**: `https://localhost:8443` (error tracking)
|
||||
| Check | URL/Command | Expected Result |
|
||||
| ----------- | ------------------------------ | ----------------------------------- |
|
||||
| Frontend | `http://localhost:5173` | Flyer Crawler app loads |
|
||||
| Backend API | `http://localhost:3001/health` | `{ "status": "ok", ... }` |
|
||||
| Database | `podman exec ... psql -c ...` | `SELECT version()` returns Postgres |
|
||||
| Containers | `podman ps` | Shows postgres and redis running |
|
||||
|
||||
**Note:** The dev container accepts both `localhost` and `127.0.0.1` for HTTPS connections. The self-signed certificate is valid for both hostnames.
|
||||
---
|
||||
|
||||
**SSL Certificate Warnings:** To eliminate browser security warnings for self-signed certificates, install the mkcert CA certificate. See [`certs/README.md`](../../certs/README.md) for platform-specific installation instructions. This is optional but recommended for a better development experience.
|
||||
## Full Dev Container (Recommended)
|
||||
|
||||
### Dev Container Architecture
|
||||
For a production-like environment with NGINX, Bugsink error tracking, and PM2 process management:
|
||||
|
||||
The dev container uses PM2 for process management, matching production (ADR-014):
|
||||
### Starting the Dev Container
|
||||
|
||||
| Process | Description | Port |
|
||||
| -------------------------- | ------------------------ | ---- |
|
||||
| `flyer-crawler-api-dev` | API server (tsx watch) | 3001 |
|
||||
| `flyer-crawler-worker-dev` | Background job worker | - |
|
||||
| `flyer-crawler-vite-dev` | Vite frontend dev server | 5173 |
|
||||
```bash
|
||||
# Start all services
|
||||
podman-compose -f compose.dev.yml up -d
|
||||
|
||||
**PM2 Commands** (run inside container):
|
||||
# View logs
|
||||
podman-compose -f compose.dev.yml logs -f
|
||||
```
|
||||
|
||||
### Access Points
|
||||
|
||||
| Service | URL | Notes |
|
||||
| ----------- | ------------------------ | ---------------------------- |
|
||||
| Frontend | `https://localhost` | NGINX proxy to Vite |
|
||||
| Backend API | `http://localhost:3001` | Express server |
|
||||
| Bugsink | `https://localhost:8443` | Error tracking (admin/admin) |
|
||||
| PostgreSQL | `localhost:5432` | Database |
|
||||
| Redis | `localhost:6379` | Cache |
|
||||
|
||||
**SSL Certificate Setup (Recommended)**:
|
||||
|
||||
To eliminate browser security warnings, install the mkcert CA certificate:
|
||||
|
||||
```bash
|
||||
# Windows: Double-click certs/mkcert-ca.crt and install to Trusted Root CAs
|
||||
# See certs/README.md for detailed instructions per platform
|
||||
```
|
||||
|
||||
### PM2 Commands
|
||||
|
||||
```bash
|
||||
# View process status
|
||||
@@ -124,63 +198,152 @@ podman exec -it flyer-crawler-dev pm2 restart all
|
||||
podman exec -it flyer-crawler-dev pm2 restart flyer-crawler-api-dev
|
||||
```
|
||||
|
||||
## Verify Installation
|
||||
### Dev Container Processes
|
||||
|
||||
| Process | Description | Port |
|
||||
| -------------------------- | ------------------------ | ---- |
|
||||
| `flyer-crawler-api-dev` | API server (tsx watch) | 3001 |
|
||||
| `flyer-crawler-worker-dev` | Background job worker | - |
|
||||
| `flyer-crawler-vite-dev` | Vite frontend dev server | 5173 |
|
||||
|
||||
---
|
||||
|
||||
## Verification Commands
|
||||
|
||||
Run these to confirm everything is working:
|
||||
|
||||
```bash
|
||||
# Check containers are running
|
||||
podman ps
|
||||
# Expected: flyer-crawler-postgres and flyer-crawler-redis both running
|
||||
|
||||
# Test database connection
|
||||
podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "SELECT version();"
|
||||
# Expected: PostgreSQL 15.x with PostGIS
|
||||
|
||||
# Run tests (in dev container)
|
||||
podman exec -it flyer-crawler-dev npm run test:unit
|
||||
# Expected: All tests pass
|
||||
|
||||
# Run type check
|
||||
podman exec -it flyer-crawler-dev npm run type-check
|
||||
# Expected: No type errors
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
---
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### "Unable to connect to Podman socket"
|
||||
|
||||
**Cause**: Podman machine not running
|
||||
|
||||
**Solution**:
|
||||
|
||||
```bash
|
||||
podman machine start
|
||||
```
|
||||
|
||||
### "Connection refused" to PostgreSQL
|
||||
|
||||
Wait a few seconds for PostgreSQL to initialize:
|
||||
**Cause**: PostgreSQL still initializing
|
||||
|
||||
**Solution**:
|
||||
|
||||
```bash
|
||||
# Wait for PostgreSQL to be ready
|
||||
podman exec flyer-crawler-postgres pg_isready -U postgres
|
||||
# Retry after "accepting connections" message
|
||||
```
|
||||
|
||||
### Port 5432 or 6379 already in use
|
||||
|
||||
Stop conflicting services or change port mappings:
|
||||
**Cause**: Another service using the port
|
||||
|
||||
**Solution**:
|
||||
|
||||
```bash
|
||||
# Use different host port
|
||||
# Option 1: Stop conflicting service
|
||||
# Option 2: Use different host port
|
||||
podman run -d --name flyer-crawler-postgres -p 5433:5432 ...
|
||||
# Then update DB_PORT=5433 in .env.local
|
||||
```
|
||||
|
||||
Then update `DB_PORT=5433` in `.env.local`.
|
||||
### "JWT_SECRET must be at least 32 characters"
|
||||
|
||||
**Cause**: Secret too short in .env.local
|
||||
|
||||
**Solution**: Generate a longer secret:
|
||||
|
||||
```bash
|
||||
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
||||
```
|
||||
|
||||
### Tests fail with "TZ environment variable" errors
|
||||
|
||||
**Cause**: Timezone setting interfering with Node.js async hooks
|
||||
|
||||
**Solution**: Tests must run in dev container (not Windows host):
|
||||
|
||||
```bash
|
||||
# CORRECT - run in container
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
|
||||
# INCORRECT - do not run on Windows host
|
||||
npm test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **Read the docs**: [docs/README.md](../README.md)
|
||||
- **Understand the architecture**: [docs/architecture/DATABASE.md](../architecture/DATABASE.md)
|
||||
- **Learn testing**: [docs/development/TESTING.md](../development/TESTING.md)
|
||||
- **Explore ADRs**: [docs/adr/index.md](../adr/index.md)
|
||||
- **Contributing**: [CONTRIBUTING.md](../../CONTRIBUTING.md)
|
||||
| Goal | Document |
|
||||
| ----------------------- | ----------------------------------------------------- |
|
||||
| Understand the codebase | [Architecture Overview](../architecture/OVERVIEW.md) |
|
||||
| Configure environment | [Environment Variables](ENVIRONMENT.md) |
|
||||
| Set up MCP tools | [MCP Configuration](../tools/MCP-CONFIGURATION.md) |
|
||||
| Learn testing | [Testing Guide](../development/TESTING.md) |
|
||||
| Understand DB schema | [Database Documentation](../architecture/DATABASE.md) |
|
||||
| Read ADRs | [ADR Index](../adr/index.md) |
|
||||
| Full installation guide | [Installation Guide](INSTALL.md) |
|
||||
|
||||
## Development Workflow
|
||||
---
|
||||
|
||||
## Daily Development Workflow
|
||||
|
||||
```bash
|
||||
# Daily workflow
|
||||
# 1. Start containers
|
||||
podman start flyer-crawler-postgres flyer-crawler-redis
|
||||
|
||||
# 2. Start dev server
|
||||
npm run dev
|
||||
# ... make changes ...
|
||||
|
||||
# 3. Make changes and test
|
||||
npm test
|
||||
|
||||
# 4. Type check before commit
|
||||
npm run type-check
|
||||
|
||||
# 5. Commit changes
|
||||
git commit
|
||||
```
|
||||
|
||||
For detailed setup instructions, see [INSTALL.md](INSTALL.md).
|
||||
**For dev container users**:
|
||||
|
||||
```bash
|
||||
# 1. Start dev container
|
||||
podman-compose -f compose.dev.yml up -d
|
||||
|
||||
# 2. View logs
|
||||
podman exec -it flyer-crawler-dev pm2 logs
|
||||
|
||||
# 3. Run tests
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
|
||||
# 4. Stop when done
|
||||
podman-compose -f compose.dev.yml down
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Last updated: January 2026
|
||||
|
||||
@@ -2,8 +2,68 @@
|
||||
|
||||
This guide covers the manual installation of Flyer Crawler and its dependencies on a bare-metal Ubuntu server (e.g., a colocation server). This is the definitive reference for setting up a production environment without containers.
|
||||
|
||||
**Last verified**: 2026-01-28
|
||||
|
||||
**Target Environment**: Ubuntu 22.04 LTS (or newer)
|
||||
|
||||
**Related documentation**:
|
||||
|
||||
- [ADR-014: Containerization and Deployment Strategy](../adr/0014-containerization-and-deployment-strategy.md)
|
||||
- [ADR-015: Error Tracking and Observability](../adr/0015-error-tracking-and-observability.md)
|
||||
- [ADR-050: PostgreSQL Function Observability](../adr/0050-postgresql-function-observability.md)
|
||||
- [Deployment Guide](DEPLOYMENT.md)
|
||||
- [Monitoring Guide](MONITORING.md)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Installation Time Estimates
|
||||
|
||||
| Component | Estimated Time | Notes |
|
||||
| ----------- | --------------- | ----------------------------- |
|
||||
| PostgreSQL | 10-15 minutes | Including PostGIS extensions |
|
||||
| Redis | 5 minutes | Quick install |
|
||||
| Node.js | 5 minutes | Via NodeSource repository |
|
||||
| Application | 15-20 minutes | Clone, install, build |
|
||||
| PM2 | 5 minutes | Global install + config |
|
||||
| NGINX | 10-15 minutes | Including SSL via Certbot |
|
||||
| Bugsink | 20-30 minutes | Python venv, systemd services |
|
||||
| Logstash | 15-20 minutes | Including pipeline config |
|
||||
| **Total** | **~90 minutes** | For complete fresh install |
|
||||
|
||||
### Post-Installation Verification
|
||||
|
||||
After completing setup, verify all services:
|
||||
|
||||
```bash
|
||||
# Check all services are running
|
||||
systemctl status postgresql nginx redis-server gunicorn-bugsink snappea logstash
|
||||
|
||||
# Verify application health
|
||||
curl -s https://flyer-crawler.projectium.com/api/health/ready | jq .
|
||||
|
||||
# Check PM2 processes
|
||||
pm2 list
|
||||
|
||||
# Verify Bugsink is accessible
|
||||
curl -s https://bugsink.projectium.com/accounts/login/ | head -5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Server Access Model
|
||||
|
||||
All commands in this guide are intended for the **system administrator** to execute directly on the server. Claude Code and AI tools have **READ-ONLY** access to production servers and cannot execute these commands directly.
|
||||
|
||||
When Claude assists with server setup or troubleshooting:
|
||||
|
||||
1. Claude provides commands for the administrator to execute
|
||||
2. Administrator runs commands and reports output
|
||||
3. Claude analyzes results and provides next steps (1-3 commands at a time)
|
||||
4. Administrator executes and reports results
|
||||
5. Claude provides verification commands to confirm success
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
@@ -2,14 +2,81 @@
|
||||
|
||||
This guide covers deploying Flyer Crawler to a production server.
|
||||
|
||||
**Last verified**: 2026-01-28
|
||||
|
||||
**Related documentation**:
|
||||
|
||||
- [ADR-014: Containerization and Deployment Strategy](../adr/0014-containerization-and-deployment-strategy.md)
|
||||
- [ADR-015: Error Tracking and Observability](../adr/0015-error-tracking-and-observability.md)
|
||||
- [Bare-Metal Setup Guide](BARE-METAL-SETUP.md)
|
||||
- [Monitoring Guide](MONITORING.md)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Command Reference Table
|
||||
|
||||
| Task | Command |
|
||||
| -------------------- | ----------------------------------------------------------------------- |
|
||||
| Deploy to production | Gitea Actions workflow (manual trigger) |
|
||||
| Deploy to test | Automatic on push to `main` |
|
||||
| Check PM2 status | `pm2 list` |
|
||||
| View logs | `pm2 logs flyer-crawler-api --lines 100` |
|
||||
| Restart all | `pm2 restart all` |
|
||||
| Check NGINX | `sudo nginx -t && sudo systemctl status nginx` |
|
||||
| Check health | `curl -s https://flyer-crawler.projectium.com/api/health/ready \| jq .` |
|
||||
|
||||
### Deployment URLs
|
||||
|
||||
| Environment | URL | API Port |
|
||||
| ------------- | ------------------------------------------- | -------- |
|
||||
| Production | `https://flyer-crawler.projectium.com` | 3001 |
|
||||
| Test | `https://flyer-crawler-test.projectium.com` | 3002 |
|
||||
| Dev Container | `https://localhost` | 3001 |
|
||||
|
||||
---
|
||||
|
||||
## Server Access Model
|
||||
|
||||
**Important**: Claude Code (and AI tools) have **READ-ONLY** access to production/test servers. The deployment workflow is:
|
||||
|
||||
| Actor | Capability |
|
||||
| ------------ | --------------------------------------------------------------- |
|
||||
| Gitea CI/CD | Automated deployments via workflows (has write access) |
|
||||
| User (human) | Manual server access for troubleshooting and emergency fixes |
|
||||
| Claude Code | Provides commands for user to execute; cannot run them directly |
|
||||
|
||||
When troubleshooting deployment issues:
|
||||
|
||||
1. Claude provides **diagnostic commands** for the user to run
|
||||
2. User executes commands and reports output
|
||||
3. Claude analyzes results and provides **fix commands** (1-3 at a time)
|
||||
4. User executes fixes and reports results
|
||||
5. Claude provides **verification commands** to confirm success
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Ubuntu server (22.04 LTS recommended)
|
||||
- PostgreSQL 14+ with PostGIS extension
|
||||
- Redis
|
||||
- Node.js 20.x
|
||||
- NGINX (reverse proxy)
|
||||
- PM2 (process manager)
|
||||
| Component | Version | Purpose |
|
||||
| ---------- | --------- | ------------------------------- |
|
||||
| Ubuntu | 22.04 LTS | Operating system |
|
||||
| PostgreSQL | 14+ | Database with PostGIS extension |
|
||||
| Redis | 6+ | Caching and job queues |
|
||||
| Node.js | 20.x LTS | Application runtime |
|
||||
| NGINX | 1.18+ | Reverse proxy and static files |
|
||||
| PM2 | Latest | Process manager |
|
||||
|
||||
**Verify prerequisites**:
|
||||
|
||||
```bash
|
||||
node --version # Should be v20.x.x
|
||||
psql --version # Should be 14+
|
||||
redis-cli ping # Should return PONG
|
||||
nginx -v # Should be 1.18+
|
||||
pm2 --version # Any recent version
|
||||
```
|
||||
|
||||
## Dev Container Parity (ADR-014)
|
||||
|
||||
@@ -190,7 +257,7 @@ types {
|
||||
|
||||
**Option 2**: Edit `/etc/nginx/mime.types` globally:
|
||||
|
||||
```
|
||||
```text
|
||||
# Change this line:
|
||||
application/javascript js;
|
||||
|
||||
@@ -321,9 +388,78 @@ The Sentry SDK v10+ enforces HTTPS-only DSNs by default. Since Bugsink runs loca
|
||||
|
||||
---
|
||||
|
||||
## Deployment Troubleshooting
|
||||
|
||||
### Decision Tree: Deployment Issues
|
||||
|
||||
```text
|
||||
Deployment failed?
|
||||
|
|
||||
+-- Build step failed?
|
||||
| |
|
||||
| +-- TypeScript errors --> Fix type issues, run `npm run type-check`
|
||||
| +-- Missing dependencies --> Run `npm ci`
|
||||
| +-- Out of memory --> Increase Node heap size
|
||||
|
|
||||
+-- Tests failed?
|
||||
| |
|
||||
| +-- Database connection --> Check DB_HOST, credentials
|
||||
| +-- Redis connection --> Check REDIS_URL
|
||||
| +-- Test isolation --> Check for race conditions
|
||||
|
|
||||
+-- SSH/Deploy failed?
|
||||
|
|
||||
+-- Permission denied --> Check SSH keys in Gitea secrets
|
||||
+-- Host unreachable --> Check firewall, VPN
|
||||
+-- PM2 error --> Check PM2 logs on server
|
||||
```
|
||||
|
||||
### Common Deployment Issues
|
||||
|
||||
| Symptom | Diagnosis | Solution |
|
||||
| ------------------------------------ | ----------------------- | ------------------------------------------------ |
|
||||
| "Connection refused" on health check | API not started | Check `pm2 logs flyer-crawler-api` |
|
||||
| 502 Bad Gateway | NGINX cannot reach API | Verify API port (3001), restart PM2 |
|
||||
| CSS/JS not loading | Build artifacts missing | Re-run `npm run build`, check NGINX static paths |
|
||||
| Database migrations failed | Schema mismatch | Run migrations manually, check DB connectivity |
|
||||
| "ENOSPC" error | Disk full | Clear old logs: `pm2 flush`, clean npm cache |
|
||||
| SSL certificate error | Cert expired/missing | Run `certbot renew`, check NGINX config |
|
||||
|
||||
### Post-Deployment Verification Checklist
|
||||
|
||||
After every deployment, verify:
|
||||
|
||||
- [ ] Health check passes: `curl -s https://flyer-crawler.projectium.com/api/health/ready`
|
||||
- [ ] PM2 processes running: `pm2 list` shows `online` status
|
||||
- [ ] No recent errors: Check Bugsink for new issues
|
||||
- [ ] Frontend loads: Browser shows login page
|
||||
- [ ] API responds: `curl https://flyer-crawler.projectium.com/api/health/ping`
|
||||
|
||||
### Rollback Procedure
|
||||
|
||||
If deployment causes issues:
|
||||
|
||||
```bash
|
||||
# 1. Check current release
|
||||
cd /var/www/flyer-crawler.projectium.com
|
||||
git log --oneline -5
|
||||
|
||||
# 2. Revert to previous commit
|
||||
git checkout HEAD~1
|
||||
|
||||
# 3. Rebuild and restart
|
||||
npm ci && npm run build
|
||||
pm2 restart all
|
||||
|
||||
# 4. Verify health
|
||||
curl -s http://localhost:3001/api/health/ready | jq .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Database Setup](DATABASE.md) - PostgreSQL and PostGIS configuration
|
||||
- [Authentication Setup](AUTHENTICATION.md) - OAuth provider configuration
|
||||
- [Installation Guide](INSTALL.md) - Local development setup
|
||||
- [Bare-Metal Server Setup](docs/BARE-METAL-SETUP.md) - Manual server installation guide
|
||||
- [Database Setup](../architecture/DATABASE.md) - PostgreSQL and PostGIS configuration
|
||||
- [Monitoring Guide](MONITORING.md) - Health checks and error tracking
|
||||
- [Logstash Quick Reference](LOGSTASH-QUICK-REF.md) - Log aggregation
|
||||
- [Bare-Metal Server Setup](BARE-METAL-SETUP.md) - Manual server installation guide
|
||||
|
||||
@@ -2,10 +2,47 @@
|
||||
|
||||
Aggregates logs from PostgreSQL, PM2, Redis, NGINX; forwards errors to Bugsink.
|
||||
|
||||
**Last verified**: 2026-01-28
|
||||
|
||||
**Related documentation**:
|
||||
|
||||
- [ADR-050: PostgreSQL Function Observability](../adr/0050-postgresql-function-observability.md)
|
||||
- [ADR-015: Error Tracking and Observability](../adr/0015-error-tracking-and-observability.md)
|
||||
- [Monitoring Guide](MONITORING.md)
|
||||
- [Logstash Troubleshooting Runbook](LOGSTASH-TROUBLESHOOTING.md)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Bugsink Project Routing
|
||||
|
||||
| Source Type | Environment | Bugsink Project | Project ID |
|
||||
| -------------- | ----------- | -------------------- | ---------- |
|
||||
| PM2 API/Worker | Dev | Backend API (Dev) | 1 |
|
||||
| PostgreSQL | Dev | Backend API (Dev) | 1 |
|
||||
| Frontend JS | Dev | Frontend (Dev) | 2 |
|
||||
| Redis/NGINX | Dev | Infrastructure (Dev) | 4 |
|
||||
| PM2 API/Worker | Production | Backend API (Prod) | 1 |
|
||||
| PostgreSQL | Production | Backend API (Prod) | 1 |
|
||||
| PM2 API/Worker | Test | Backend API (Test) | 3 |
|
||||
|
||||
### Key DSN Keys (Dev Container)
|
||||
|
||||
| Project | DSN Key |
|
||||
| -------------------- | ---------------------------------- |
|
||||
| Backend API (Dev) | `cea01396c56246adb5878fa5ee6b1d22` |
|
||||
| Frontend (Dev) | `d92663cb73cf4145b677b84029e4b762` |
|
||||
| Infrastructure (Dev) | `14e8791da3d347fa98073261b596cab9` |
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
**Primary config**: `/etc/logstash/conf.d/bugsink.conf`
|
||||
|
||||
**Dev container config**: `docker/logstash/bugsink.conf`
|
||||
|
||||
### Related Files
|
||||
|
||||
| Path | Purpose |
|
||||
@@ -89,6 +126,34 @@ MSYS_NO_PATHCONV=1 podman exec flyer-crawler-dev ls -la /var/log/redis/
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Decision Tree: Logs Not Appearing in Bugsink
|
||||
|
||||
```text
|
||||
Errors not showing in Bugsink?
|
||||
|
|
||||
+-- Logstash running?
|
||||
| |
|
||||
| +-- No --> systemctl start logstash
|
||||
| +-- Yes --> Check pipeline stats
|
||||
| |
|
||||
| +-- Events in = 0?
|
||||
| | |
|
||||
| | +-- Log files exist? --> ls /var/log/pm2/*.log
|
||||
| | +-- Permissions OK? --> groups logstash
|
||||
| |
|
||||
| +-- Events filtered = high?
|
||||
| | |
|
||||
| | +-- Grok failures --> Check log format matches pattern
|
||||
| |
|
||||
| +-- Events out but no Bugsink?
|
||||
| |
|
||||
| +-- 403 error --> Wrong DSN key
|
||||
| +-- 500 error --> Invalid event format (check sentry_level)
|
||||
| +-- Connection refused --> Bugsink not running
|
||||
```
|
||||
|
||||
### Common Issues Table
|
||||
|
||||
| Issue | Check | Solution |
|
||||
| --------------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| No Bugsink errors | Logstash running | `systemctl status logstash` |
|
||||
@@ -103,6 +168,25 @@ MSYS_NO_PATHCONV=1 podman exec flyer-crawler-dev ls -la /var/log/redis/
|
||||
| High disk usage | Log rotation | Verify `/etc/logrotate.d/logstash` configured |
|
||||
| varchar(7) error | Level validation | Add Ruby filter to validate/normalize `sentry_level` before output |
|
||||
|
||||
### Expected Output Examples
|
||||
|
||||
**Successful Logstash pipeline stats**:
|
||||
|
||||
```json
|
||||
{
|
||||
"in": 1523,
|
||||
"out": 1520,
|
||||
"filtered": 1520,
|
||||
"queue_push_duration_in_millis": 45
|
||||
}
|
||||
```
|
||||
|
||||
**Healthy Bugsink HTTP response**:
|
||||
|
||||
```json
|
||||
{ "id": "a1b2c3d4e5f6..." }
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Dev Container Guide**: [DEV-CONTAINER.md](../development/DEV-CONTAINER.md) - PM2 and log aggregation in dev
|
||||
|
||||
@@ -2,6 +2,16 @@
|
||||
|
||||
This runbook provides step-by-step diagnostics and solutions for common Logstash issues in the PostgreSQL observability pipeline (ADR-050).
|
||||
|
||||
**Last verified**: 2026-01-28
|
||||
|
||||
**Related documentation**:
|
||||
|
||||
- [ADR-050: PostgreSQL Function Observability](../adr/0050-postgresql-function-observability.md)
|
||||
- [Logstash Quick Reference](LOGSTASH-QUICK-REF.md)
|
||||
- [Monitoring Guide](MONITORING.md)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Symptom | Most Likely Cause | Quick Check |
|
||||
|
||||
@@ -2,6 +2,72 @@
|
||||
|
||||
This guide covers all aspects of monitoring the Flyer Crawler application across development, test, and production environments.
|
||||
|
||||
**Last verified**: 2026-01-28
|
||||
|
||||
**Related documentation**:
|
||||
|
||||
- [ADR-015: Error Tracking and Observability](../adr/0015-error-tracking-and-observability.md)
|
||||
- [ADR-020: Health Checks](../adr/0020-health-checks-and-liveness-readiness-probes.md)
|
||||
- [ADR-050: PostgreSQL Function Observability](../adr/0050-postgresql-function-observability.md)
|
||||
- [Logstash Quick Reference](LOGSTASH-QUICK-REF.md)
|
||||
- [Deployment Guide](DEPLOYMENT.md)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Monitoring URLs
|
||||
|
||||
| Service | Production URL | Dev Container URL |
|
||||
| ------------ | ------------------------------------------------------- | ---------------------------------------- |
|
||||
| Health Check | `https://flyer-crawler.projectium.com/api/health/ready` | `http://localhost:3001/api/health/ready` |
|
||||
| Bugsink | `https://bugsink.projectium.com` | `https://localhost:8443` |
|
||||
| Bull Board | `https://flyer-crawler.projectium.com/api/admin/jobs` | `http://localhost:3001/api/admin/jobs` |
|
||||
|
||||
### Quick Diagnostic Commands
|
||||
|
||||
```bash
|
||||
# Check all services at once (production)
|
||||
curl -s https://flyer-crawler.projectium.com/api/health/ready | jq '.data.services'
|
||||
|
||||
# Dev container health check
|
||||
podman exec flyer-crawler-dev curl -s http://localhost:3001/api/health/ready | jq .
|
||||
|
||||
# PM2 process overview
|
||||
pm2 list
|
||||
|
||||
# Recent errors in Bugsink (via MCP)
|
||||
# mcp__bugsink__list_issues --project_id 1 --status unresolved
|
||||
```
|
||||
|
||||
### Monitoring Decision Tree
|
||||
|
||||
```text
|
||||
Application seems slow or unresponsive?
|
||||
|
|
||||
+-- Check health endpoint first
|
||||
| |
|
||||
| +-- Returns unhealthy?
|
||||
| | |
|
||||
| | +-- Database unhealthy --> Check DB pool, connections
|
||||
| | +-- Redis unhealthy --> Check Redis memory, connection
|
||||
| | +-- Storage unhealthy --> Check disk space, permissions
|
||||
| |
|
||||
| +-- Returns healthy but slow?
|
||||
| |
|
||||
| +-- Check PM2 memory/CPU usage
|
||||
| +-- Check database slow query log
|
||||
| +-- Check Redis queue depth
|
||||
|
|
||||
+-- Health endpoint not responding?
|
||||
|
|
||||
+-- Check PM2 status --> Process crashed?
|
||||
+-- Check NGINX --> 502 errors?
|
||||
+-- Check network --> Firewall/DNS issues?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Health Checks](#health-checks)
|
||||
@@ -276,10 +342,10 @@ Dev Container (in `.mcp.json`):
|
||||
|
||||
Bugsink 2.0.11 does not have a UI for API tokens. Create via Django management command.
|
||||
|
||||
**Production**:
|
||||
**Production** (user executes on server):
|
||||
|
||||
```bash
|
||||
ssh root@projectium.com "cd /opt/bugsink && bugsink-manage create_auth_token"
|
||||
cd /opt/bugsink && bugsink-manage create_auth_token
|
||||
```
|
||||
|
||||
**Dev Container**:
|
||||
@@ -294,7 +360,7 @@ The command outputs a 40-character hex token.
|
||||
|
||||
**Error Anatomy**:
|
||||
|
||||
```
|
||||
```text
|
||||
TypeError: Cannot read properties of undefined (reading 'map')
|
||||
├── Exception Type: TypeError
|
||||
├── Message: Cannot read properties of undefined (reading 'map')
|
||||
@@ -357,7 +423,7 @@ Logstash aggregates logs from multiple sources and forwards errors to Bugsink (A
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
```text
|
||||
Log Sources Logstash Outputs
|
||||
┌──────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ PostgreSQL │──────────────│ │───────────│ Bugsink │
|
||||
@@ -388,11 +454,9 @@ Log Sources Logstash Outputs
|
||||
|
||||
### Pipeline Status
|
||||
|
||||
**Check Logstash Service**:
|
||||
**Check Logstash Service** (user executes on server):
|
||||
|
||||
```bash
|
||||
ssh root@projectium.com
|
||||
|
||||
# Service status
|
||||
systemctl status logstash
|
||||
|
||||
@@ -485,9 +549,11 @@ PM2 manages the Node.js application processes in production.
|
||||
|
||||
### Basic Commands
|
||||
|
||||
> **Note**: These commands are for the user to execute on the server. Claude Code provides commands but cannot run them directly.
|
||||
|
||||
```bash
|
||||
ssh root@projectium.com
|
||||
su - gitea-runner # PM2 runs under this user
|
||||
# Switch to gitea-runner user (PM2 runs under this user)
|
||||
su - gitea-runner
|
||||
|
||||
# List all processes
|
||||
pm2 list
|
||||
@@ -520,7 +586,7 @@ pm2 stop flyer-crawler-api
|
||||
|
||||
**Healthy Process**:
|
||||
|
||||
```
|
||||
```text
|
||||
┌─────────────────────┬────┬─────────┬─────────┬───────┬────────┬─────────┬──────────┐
|
||||
│ Name │ id │ mode │ status │ cpu │ mem │ uptime │ restarts │
|
||||
├─────────────────────┼────┼─────────┼─────────┼───────┼────────┼─────────┼──────────┤
|
||||
@@ -833,29 +899,28 @@ Configure alerts in your monitoring tool (UptimeRobot, Datadog, etc.):
|
||||
2. Review during business hours
|
||||
3. Create Gitea issue for tracking
|
||||
|
||||
### Quick Diagnostic Commands
|
||||
### On-Call Diagnostic Commands
|
||||
|
||||
> **Note**: User executes these commands on the server. Claude Code provides commands but cannot run them directly.
|
||||
|
||||
```bash
|
||||
# Full system health check
|
||||
ssh root@projectium.com << 'EOF'
|
||||
echo "=== Service Status ==="
|
||||
# Service status checks
|
||||
systemctl status pm2-gitea-runner --no-pager
|
||||
systemctl status logstash --no-pager
|
||||
systemctl status redis --no-pager
|
||||
systemctl status postgresql --no-pager
|
||||
|
||||
echo "=== PM2 Processes ==="
|
||||
# PM2 processes (run as gitea-runner)
|
||||
su - gitea-runner -c "pm2 list"
|
||||
|
||||
echo "=== Disk Space ==="
|
||||
# Disk space
|
||||
df -h / /var
|
||||
|
||||
echo "=== Memory ==="
|
||||
# Memory
|
||||
free -h
|
||||
|
||||
echo "=== Recent Errors ==="
|
||||
# Recent errors
|
||||
journalctl -p err -n 20 --no-pager
|
||||
EOF
|
||||
```
|
||||
|
||||
### Runbook Quick Reference
|
||||
|
||||
161
docs/plans/2026-01-27-unit-test-error-log-path-fix.md
Normal file
161
docs/plans/2026-01-27-unit-test-error-log-path-fix.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Unit Test Fix Plan: Error Log Path Mismatches
|
||||
|
||||
**Date**: 2026-01-27
|
||||
**Type**: Technical Implementation Plan
|
||||
**Related**: [ADR-008: API Versioning Strategy](../adr/0008-api-versioning-strategy.md)
|
||||
**Status**: Ready for Implementation
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
16 unit tests fail due to error log message assertions expecting versioned paths (`/api/v1/`) while route handlers emit hardcoded unversioned paths (`/api/`).
|
||||
|
||||
**Failure Pattern**:
|
||||
|
||||
```text
|
||||
AssertionError: expected "Error PUT /api/users/profile" to contain "/api/v1/users/profile"
|
||||
```
|
||||
|
||||
**Scope**: All failures are `toContain` assertions on `logger.error()` call arguments.
|
||||
|
||||
---
|
||||
|
||||
## Root Cause Analysis
|
||||
|
||||
| Layer | Behavior | Issue |
|
||||
| ------------------ | ----------------------------------------------------- | ------------------- |
|
||||
| Route Registration | `server.ts` mounts at `/api/v1/` | Correct |
|
||||
| Request Path | `req.path` returns `/users/profile` (router-relative) | No version info |
|
||||
| Error Handlers | Hardcode `"Error PUT /api/users/profile"` | Version mismatch |
|
||||
| Test Assertions | Expect `"/api/v1/users/profile"` | Correct expectation |
|
||||
|
||||
**Root Cause**: Error log statements use template literals with hardcoded `/api/` prefix instead of `req.originalUrl` which contains the full versioned path.
|
||||
|
||||
**Example**:
|
||||
|
||||
```typescript
|
||||
// Current (broken)
|
||||
logger.error(`Error PUT /api/users/profile: ${err}`);
|
||||
|
||||
// Expected
|
||||
logger.error(`Error PUT ${req.originalUrl}: ${err}`);
|
||||
// Output: "Error PUT /api/v1/users/profile: ..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Solution Approach
|
||||
|
||||
Replace hardcoded path strings with `req.originalUrl` in all error log statements.
|
||||
|
||||
### Express Request Properties Reference
|
||||
|
||||
| Property | Example Value | Use Case |
|
||||
| ----------------- | ------------------------------- | ----------------------------- |
|
||||
| `req.originalUrl` | `/api/v1/users/profile?foo=bar` | Full URL with version + query |
|
||||
| `req.path` | `/profile` | Router-relative path only |
|
||||
| `req.baseUrl` | `/api/v1/users` | Mount point |
|
||||
|
||||
**Decision**: Use `req.originalUrl` for error logging to capture complete request context.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Affected Files
|
||||
|
||||
| File | Error Statements | Methods |
|
||||
| ------------------------------- | ---------------- | ---------------------------------------------------- |
|
||||
| `src/routes/users.routes.ts` | 3 | `PUT /profile`, `POST /profile/password`, `DELETE /` |
|
||||
| `src/routes/recipe.routes.ts` | 2 | `POST /import`, `POST /:id/fork` |
|
||||
| `src/routes/receipts.routes.ts` | 2 | `POST /`, `PATCH /:id` |
|
||||
| `src/routes/flyers.routes.ts` | 2 | `POST /`, `PUT /:id` |
|
||||
|
||||
**Total**: 9 error log statements across 4 route files
|
||||
|
||||
### Parallel Implementation Tasks
|
||||
|
||||
All 4 files can be modified independently:
|
||||
|
||||
**Task 1**: `users.routes.ts`
|
||||
|
||||
- Line patterns: `Error PUT /api/users/profile`, `Error POST /api/users/profile/password`, `Error DELETE /api/users`
|
||||
- Change: Replace with `Error ${req.method} ${req.originalUrl}`
|
||||
|
||||
**Task 2**: `recipe.routes.ts`
|
||||
|
||||
- Line patterns: `Error POST /api/recipes/import`, `Error POST /api/recipes/:id/fork`
|
||||
- Change: Replace with `Error ${req.method} ${req.originalUrl}`
|
||||
|
||||
**Task 3**: `receipts.routes.ts`
|
||||
|
||||
- Line patterns: `Error POST /api/receipts`, `Error PATCH /api/receipts/:id`
|
||||
- Change: Replace with `Error ${req.method} ${req.originalUrl}`
|
||||
|
||||
**Task 4**: `flyers.routes.ts`
|
||||
|
||||
- Line patterns: `Error POST /api/flyers`, `Error PUT /api/flyers/:id`
|
||||
- Change: Replace with `Error ${req.method} ${req.originalUrl}`
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
podman exec -it flyer-crawler-dev npm run test:unit
|
||||
```
|
||||
|
||||
**Expected**: 16 failures → 0 failures (3,391/3,391 passing)
|
||||
|
||||
---
|
||||
|
||||
## Test Files Affected
|
||||
|
||||
Tests that will pass after fix:
|
||||
|
||||
| Test File | Failing Tests |
|
||||
| ------------------------- | ------------- |
|
||||
| `users.routes.test.ts` | 6 |
|
||||
| `recipe.routes.test.ts` | 4 |
|
||||
| `receipts.routes.test.ts` | 3 |
|
||||
| `flyers.routes.test.ts` | 3 |
|
||||
|
||||
---
|
||||
|
||||
## Expected Outcomes
|
||||
|
||||
| Metric | Before | After |
|
||||
| ------------------ | ----------- | ------------------- |
|
||||
| Unit test failures | 16 | 0 |
|
||||
| Unit tests passing | 3,375/3,391 | 3,391/3,391 |
|
||||
| Integration tests | 345/348 | 345/348 (unchanged) |
|
||||
|
||||
### Benefits
|
||||
|
||||
1. **Version-agnostic logging**: Error messages automatically reflect actual request URL
|
||||
2. **Future-proof**: No changes needed when v2 API is introduced
|
||||
3. **Debugging clarity**: Logs show exact URL including query parameters
|
||||
4. **Consistency**: All error handlers follow same pattern
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Pattern to Apply
|
||||
|
||||
**Before**:
|
||||
|
||||
```typescript
|
||||
logger.error(`Error PUT /api/users/profile: ${error.message}`);
|
||||
```
|
||||
|
||||
**After**:
|
||||
|
||||
```typescript
|
||||
logger.error(`Error ${req.method} ${req.originalUrl}: ${error.message}`);
|
||||
```
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- `req.originalUrl` includes query string if present (acceptable for debugging)
|
||||
- No sanitization needed as URL is from Express parsed request
|
||||
- Works correctly with route parameters (`:id` becomes actual value)
|
||||
849
docs/plans/2026-01-28-adr-024-feature-flags-implementation.md
Normal file
849
docs/plans/2026-01-28-adr-024-feature-flags-implementation.md
Normal file
@@ -0,0 +1,849 @@
|
||||
# ADR-024 Implementation Plan: Feature Flagging Strategy
|
||||
|
||||
**Date**: 2026-01-28
|
||||
**Type**: Technical Implementation Plan
|
||||
**Related**: [ADR-024: Feature Flagging Strategy](../adr/0024-feature-flagging-strategy.md), [ADR-007: Configuration and Secrets Management](../adr/0007-configuration-and-secrets-management.md)
|
||||
**Status**: Ready for Implementation
|
||||
|
||||
---
|
||||
|
||||
## Project Overview
|
||||
|
||||
Implement a simple, configuration-based feature flag system that integrates with the existing Zod-validated configuration in `src/config/env.ts`. The system will support both backend and frontend feature flags through environment variables, with type-safe access patterns and helper utilities.
|
||||
|
||||
### Key Success Criteria
|
||||
|
||||
1. Feature flags accessible via type-safe API on both backend and frontend
|
||||
2. Zero runtime overhead when flag is disabled (compile-time elimination where possible)
|
||||
3. Consistent naming convention (environment variables and code access)
|
||||
4. Graceful degradation (missing flag defaults to disabled)
|
||||
5. Easy migration path to external service (Flagsmith/LaunchDarkly) in the future
|
||||
6. Full test coverage with mocking utilities
|
||||
|
||||
### Estimated Total Effort
|
||||
|
||||
| Phase | Estimate |
|
||||
| --------------------------------- | -------------- |
|
||||
| Phase 1: Backend Infrastructure | 3-5 hours |
|
||||
| Phase 2: Frontend Infrastructure | 2-3 hours |
|
||||
| Phase 3: Documentation & Examples | 1-2 hours |
|
||||
| **Total** | **6-10 hours** |
|
||||
|
||||
---
|
||||
|
||||
## Current State Analysis
|
||||
|
||||
### Backend Configuration (`src/config/env.ts`)
|
||||
|
||||
- Zod-based schema validation at startup
|
||||
- Organized into logical groups (database, redis, auth, smtp, ai, etc.)
|
||||
- Helper exports for service availability (`isSmtpConfigured`, `isAiConfigured`, etc.)
|
||||
- Environment helpers (`isProduction`, `isTest`, `isDevelopment`)
|
||||
- Fail-fast on invalid configuration
|
||||
|
||||
### Frontend Configuration (`src/config.ts`)
|
||||
|
||||
- Uses `import.meta.env` (Vite environment variables)
|
||||
- Organized into sections (app, google, sentry)
|
||||
- Boolean parsing for string env vars
|
||||
- Type declarations in `src/vite-env.d.ts`
|
||||
|
||||
### Existing Patterns to Follow
|
||||
|
||||
```typescript
|
||||
// Backend - service availability check pattern
|
||||
export const isSmtpConfigured =
|
||||
!!config.smtp.host && !!config.smtp.user && !!config.smtp.pass;
|
||||
|
||||
// Frontend - boolean parsing pattern
|
||||
enabled: import.meta.env.VITE_SENTRY_ENABLED !== 'false',
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task Breakdown
|
||||
|
||||
### Phase 1: Backend Feature Flag Infrastructure
|
||||
|
||||
#### [1.1] Define Feature Flag Schema in env.ts
|
||||
|
||||
**Complexity**: Low
|
||||
**Estimate**: 30-45 minutes
|
||||
**Dependencies**: None
|
||||
**Parallelizable**: Yes
|
||||
|
||||
**Description**: Add a new `featureFlags` section to the Zod schema in `src/config/env.ts`.
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] New `featureFlagsSchema` Zod object defined
|
||||
- [ ] Schema supports boolean flags with defaults to `false` (opt-in model)
|
||||
- [ ] Schema added to main `envSchema` object
|
||||
- [ ] Type exported as part of `EnvConfig`
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
```typescript
|
||||
// src/config/env.ts
|
||||
|
||||
/**
|
||||
* Feature flags configuration schema (ADR-024).
|
||||
* All flags default to false (disabled) for safety.
|
||||
* Set to 'true' in environment to enable.
|
||||
*/
|
||||
const featureFlagsSchema = z.object({
|
||||
// Example flags - replace with actual feature flags as needed
|
||||
newDashboard: booleanString(false), // FEATURE_NEW_DASHBOARD
|
||||
betaRecipes: booleanString(false), // FEATURE_BETA_RECIPES
|
||||
experimentalAi: booleanString(false), // FEATURE_EXPERIMENTAL_AI
|
||||
debugMode: booleanString(false), // FEATURE_DEBUG_MODE
|
||||
});
|
||||
|
||||
// In loadEnvVars():
|
||||
featureFlags: {
|
||||
newDashboard: process.env.FEATURE_NEW_DASHBOARD,
|
||||
betaRecipes: process.env.FEATURE_BETA_RECIPES,
|
||||
experimentalAi: process.env.FEATURE_EXPERIMENTAL_AI,
|
||||
debugMode: process.env.FEATURE_DEBUG_MODE,
|
||||
},
|
||||
```
|
||||
|
||||
**Risks/Notes**:
|
||||
|
||||
- Naming convention: `FEATURE_*` prefix for all feature flag env vars
|
||||
- Default to `false` ensures features are opt-in, preventing accidental exposure
|
||||
|
||||
---
|
||||
|
||||
#### [1.2] Create Feature Flag Service Module
|
||||
|
||||
**Complexity**: Medium
|
||||
**Estimate**: 1-2 hours
|
||||
**Dependencies**: [1.1]
|
||||
**Parallelizable**: No (depends on 1.1)
|
||||
|
||||
**Description**: Create a dedicated service module for feature flag access with helper functions.
|
||||
|
||||
**File**: `src/services/featureFlags.server.ts`
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] `isFeatureEnabled(flagName)` function for checking flags
|
||||
- [ ] `getAllFeatureFlags()` function for debugging/admin endpoints
|
||||
- [ ] Type-safe flag name parameter (union type or enum)
|
||||
- [ ] Exported helper booleans for common flags (similar to `isSmtpConfigured`)
|
||||
- [ ] Logging when feature flag is checked in development mode
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
```typescript
|
||||
// src/services/featureFlags.server.ts
|
||||
import { config, isDevelopment } from '../config/env';
|
||||
import { logger } from './logger.server';
|
||||
|
||||
export type FeatureFlagName = keyof typeof config.featureFlags;
|
||||
|
||||
/**
|
||||
* Check if a feature flag is enabled.
|
||||
* @param flagName - The name of the feature flag to check
|
||||
* @returns boolean indicating if the feature is enabled
|
||||
*/
|
||||
export function isFeatureEnabled(flagName: FeatureFlagName): boolean {
|
||||
const enabled = config.featureFlags[flagName];
|
||||
|
||||
if (isDevelopment) {
|
||||
logger.debug({ flag: flagName, enabled }, 'Feature flag checked');
|
||||
}
|
||||
|
||||
return enabled;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all feature flags and their current states.
|
||||
* Useful for debugging and admin endpoints.
|
||||
*/
|
||||
export function getAllFeatureFlags(): Record<FeatureFlagName, boolean> {
|
||||
return { ...config.featureFlags };
|
||||
}
|
||||
|
||||
// Convenience exports for common flag checks
|
||||
export const isNewDashboardEnabled = config.featureFlags.newDashboard;
|
||||
export const isBetaRecipesEnabled = config.featureFlags.betaRecipes;
|
||||
export const isExperimentalAiEnabled = config.featureFlags.experimentalAi;
|
||||
export const isDebugModeEnabled = config.featureFlags.debugMode;
|
||||
```
|
||||
|
||||
**Risks/Notes**:
|
||||
|
||||
- Keep logging minimal to avoid performance impact
|
||||
- Convenience exports are evaluated once at startup (not dynamic)
|
||||
|
||||
---
|
||||
|
||||
#### [1.3] Add Admin Endpoint for Feature Flag Status
|
||||
|
||||
**Complexity**: Low
|
||||
**Estimate**: 30-45 minutes
|
||||
**Dependencies**: [1.2]
|
||||
**Parallelizable**: No (depends on 1.2)
|
||||
|
||||
**Description**: Add an admin/health endpoint to view current feature flag states.
|
||||
|
||||
**File**: `src/routes/admin.routes.ts` (or `stats.routes.ts` if admin routes don't exist)
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] `GET /api/v1/admin/feature-flags` endpoint (admin-only)
|
||||
- [ ] Returns JSON object with all flags and their states
|
||||
- [ ] Requires admin authentication
|
||||
- [ ] Endpoint documented in Swagger
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
```typescript
|
||||
// In appropriate routes file
|
||||
router.get('/feature-flags', requireAdmin, async (req, res) => {
|
||||
const flags = getAllFeatureFlags();
|
||||
sendSuccess(res, { flags });
|
||||
});
|
||||
```
|
||||
|
||||
**Risks/Notes**:
|
||||
|
||||
- Ensure endpoint is protected (admin-only)
|
||||
- Consider caching response if called frequently
|
||||
|
||||
---
|
||||
|
||||
#### [1.4] Backend Unit Tests
|
||||
|
||||
**Complexity**: Medium
|
||||
**Estimate**: 1-2 hours
|
||||
**Dependencies**: [1.1], [1.2]
|
||||
**Parallelizable**: Yes (can start after 1.1, in parallel with 1.3)
|
||||
|
||||
**Description**: Write unit tests for feature flag configuration and service.
|
||||
|
||||
**Files**:
|
||||
|
||||
- `src/config/env.test.ts` (add feature flag tests)
|
||||
- `src/services/featureFlags.server.test.ts` (new file)
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] Test default values (all false)
|
||||
- [ ] Test parsing 'true'/'false' strings
|
||||
- [ ] Test `isFeatureEnabled()` function
|
||||
- [ ] Test `getAllFeatureFlags()` function
|
||||
- [ ] Test type safety (TypeScript compile-time checks)
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
```typescript
|
||||
// src/config/env.test.ts - add to existing file
|
||||
describe('featureFlags configuration', () => {
|
||||
it('should default all feature flags to false', async () => {
|
||||
setValidEnv();
|
||||
const { config } = await import('./env');
|
||||
|
||||
expect(config.featureFlags.newDashboard).toBe(false);
|
||||
expect(config.featureFlags.betaRecipes).toBe(false);
|
||||
});
|
||||
|
||||
it('should parse FEATURE_NEW_DASHBOARD as true when set', async () => {
|
||||
setValidEnv({ FEATURE_NEW_DASHBOARD: 'true' });
|
||||
const { config } = await import('./env');
|
||||
|
||||
expect(config.featureFlags.newDashboard).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// src/services/featureFlags.server.test.ts - new file
|
||||
describe('featureFlags service', () => {
|
||||
describe('isFeatureEnabled', () => {
|
||||
it('should return false for disabled flags', () => {
|
||||
expect(isFeatureEnabled('newDashboard')).toBe(false);
|
||||
});
|
||||
|
||||
// ... more tests
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Frontend Feature Flag Infrastructure
|
||||
|
||||
#### [2.1] Add Frontend Feature Flag Config
|
||||
|
||||
**Complexity**: Low
|
||||
**Estimate**: 30-45 minutes
|
||||
**Dependencies**: None (can run in parallel with Phase 1)
|
||||
**Parallelizable**: Yes
|
||||
|
||||
**Description**: Add feature flags to the frontend config module.
|
||||
|
||||
**Files**:
|
||||
|
||||
- `src/config.ts` - Add featureFlags section
|
||||
- `src/vite-env.d.ts` - Add type declarations
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] Feature flags section added to `src/config.ts`
|
||||
- [ ] TypeScript declarations updated in `vite-env.d.ts`
|
||||
- [ ] Boolean parsing consistent with existing pattern
|
||||
- [ ] Default to false when env var not set
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
```typescript
|
||||
// src/config.ts
|
||||
const config = {
|
||||
// ... existing sections ...
|
||||
|
||||
/**
|
||||
* Feature flags for conditional feature rendering (ADR-024).
|
||||
* All flags default to false (disabled) when not explicitly set.
|
||||
*/
|
||||
featureFlags: {
|
||||
newDashboard: import.meta.env.VITE_FEATURE_NEW_DASHBOARD === 'true',
|
||||
betaRecipes: import.meta.env.VITE_FEATURE_BETA_RECIPES === 'true',
|
||||
experimentalAi: import.meta.env.VITE_FEATURE_EXPERIMENTAL_AI === 'true',
|
||||
debugMode: import.meta.env.VITE_FEATURE_DEBUG_MODE === 'true',
|
||||
},
|
||||
};
|
||||
|
||||
// src/vite-env.d.ts
|
||||
interface ImportMetaEnv {
|
||||
// ... existing declarations ...
|
||||
readonly VITE_FEATURE_NEW_DASHBOARD?: string;
|
||||
readonly VITE_FEATURE_BETA_RECIPES?: string;
|
||||
readonly VITE_FEATURE_EXPERIMENTAL_AI?: string;
|
||||
readonly VITE_FEATURE_DEBUG_MODE?: string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [2.2] Create useFeatureFlag React Hook
|
||||
|
||||
**Complexity**: Medium
|
||||
**Estimate**: 1-1.5 hours
|
||||
**Dependencies**: [2.1]
|
||||
**Parallelizable**: No (depends on 2.1)
|
||||
|
||||
**Description**: Create a React hook for checking feature flags in components.
|
||||
|
||||
**File**: `src/hooks/useFeatureFlag.ts`
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] `useFeatureFlag(flagName)` hook returns boolean
|
||||
- [ ] Type-safe flag name parameter
|
||||
- [ ] Memoized to prevent unnecessary re-renders
|
||||
- [ ] Optional `FeatureFlag` component for conditional rendering
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
```typescript
|
||||
// src/hooks/useFeatureFlag.ts
|
||||
import { useMemo } from 'react';
|
||||
import config from '../config';
|
||||
|
||||
export type FeatureFlagName = keyof typeof config.featureFlags;
|
||||
|
||||
/**
|
||||
* Hook to check if a feature flag is enabled.
|
||||
*
|
||||
* @param flagName - The name of the feature flag to check
|
||||
* @returns boolean indicating if the feature is enabled
|
||||
*
|
||||
* @example
|
||||
* const isNewDashboard = useFeatureFlag('newDashboard');
|
||||
* if (isNewDashboard) {
|
||||
* return <NewDashboard />;
|
||||
* }
|
||||
*/
|
||||
export function useFeatureFlag(flagName: FeatureFlagName): boolean {
|
||||
return useMemo(() => config.featureFlags[flagName], [flagName]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all feature flags (useful for debugging).
|
||||
*/
|
||||
export function useAllFeatureFlags(): Record<FeatureFlagName, boolean> {
|
||||
return useMemo(() => ({ ...config.featureFlags }), []);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [2.3] Create FeatureFlag Component
|
||||
|
||||
**Complexity**: Low
|
||||
**Estimate**: 30-45 minutes
|
||||
**Dependencies**: [2.2]
|
||||
**Parallelizable**: No (depends on 2.2)
|
||||
|
||||
**Description**: Create a declarative component for feature flag conditional rendering.
|
||||
|
||||
**File**: `src/components/FeatureFlag.tsx`
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] `<FeatureFlag name="flagName">` component
|
||||
- [ ] Children rendered only when flag is enabled
|
||||
- [ ] Optional `fallback` prop for disabled state
|
||||
- [ ] TypeScript-enforced flag names
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
```typescript
|
||||
// src/components/FeatureFlag.tsx
|
||||
import { ReactNode } from 'react';
|
||||
import { useFeatureFlag, FeatureFlagName } from '../hooks/useFeatureFlag';
|
||||
|
||||
interface FeatureFlagProps {
|
||||
/** The name of the feature flag to check */
|
||||
name: FeatureFlagName;
|
||||
/** Content to render when feature is enabled */
|
||||
children: ReactNode;
|
||||
/** Optional content to render when feature is disabled */
|
||||
fallback?: ReactNode;
|
||||
}
|
||||
|
||||
/**
|
||||
* Conditionally renders children based on feature flag state.
|
||||
*
|
||||
* @example
|
||||
* <FeatureFlag name="newDashboard" fallback={<OldDashboard />}>
|
||||
* <NewDashboard />
|
||||
* </FeatureFlag>
|
||||
*/
|
||||
export function FeatureFlag({ name, children, fallback = null }: FeatureFlagProps) {
|
||||
const isEnabled = useFeatureFlag(name);
|
||||
return <>{isEnabled ? children : fallback}</>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [2.4] Frontend Unit Tests
|
||||
|
||||
**Complexity**: Medium
|
||||
**Estimate**: 1-1.5 hours
|
||||
**Dependencies**: [2.1], [2.2], [2.3]
|
||||
**Parallelizable**: No (depends on previous frontend tasks)
|
||||
|
||||
**Description**: Write unit tests for frontend feature flag utilities.
|
||||
|
||||
**Files**:
|
||||
|
||||
- `src/config.test.ts` (add feature flag tests)
|
||||
- `src/hooks/useFeatureFlag.test.ts` (new file)
|
||||
- `src/components/FeatureFlag.test.tsx` (new file)
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] Test config structure includes featureFlags
|
||||
- [ ] Test default values (all false)
|
||||
- [ ] Test hook returns correct values
|
||||
- [ ] Test component renders/hides children correctly
|
||||
- [ ] Test fallback rendering
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
```typescript
|
||||
// src/hooks/useFeatureFlag.test.ts
|
||||
import { renderHook } from '@testing-library/react';
|
||||
import { useFeatureFlag, useAllFeatureFlags } from './useFeatureFlag';
|
||||
|
||||
describe('useFeatureFlag', () => {
|
||||
it('should return false for disabled flags', () => {
|
||||
const { result } = renderHook(() => useFeatureFlag('newDashboard'));
|
||||
expect(result.current).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// src/components/FeatureFlag.test.tsx
|
||||
import { render, screen } from '@testing-library/react';
|
||||
import { FeatureFlag } from './FeatureFlag';
|
||||
|
||||
describe('FeatureFlag', () => {
|
||||
it('should not render children when flag is disabled', () => {
|
||||
render(
|
||||
<FeatureFlag name="newDashboard">
|
||||
<div data-testid="new-feature">New Feature</div>
|
||||
</FeatureFlag>
|
||||
);
|
||||
expect(screen.queryByTestId('new-feature')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render fallback when flag is disabled', () => {
|
||||
render(
|
||||
<FeatureFlag name="newDashboard" fallback={<div>Old Feature</div>}>
|
||||
<div>New Feature</div>
|
||||
</FeatureFlag>
|
||||
);
|
||||
expect(screen.getByText('Old Feature')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Documentation & Integration
|
||||
|
||||
#### [3.1] Update ADR-024 with Implementation Status
|
||||
|
||||
**Complexity**: Low
|
||||
**Estimate**: 30 minutes
|
||||
**Dependencies**: [1.1], [1.2], [2.1], [2.2]
|
||||
**Parallelizable**: Yes (can be done after core implementation)
|
||||
|
||||
**Description**: Update ADR-024 to mark it as implemented and add implementation details.
|
||||
|
||||
**File**: `docs/adr/0024-feature-flagging-strategy.md`
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] Status changed from "Proposed" to "Accepted"
|
||||
- [ ] Implementation status section added
|
||||
- [ ] Key files documented
|
||||
- [ ] Usage examples included
|
||||
|
||||
---
|
||||
|
||||
#### [3.2] Update Environment Documentation
|
||||
|
||||
**Complexity**: Low
|
||||
**Estimate**: 30 minutes
|
||||
**Dependencies**: [1.1], [2.1]
|
||||
**Parallelizable**: Yes
|
||||
|
||||
**Description**: Add feature flag environment variables to documentation.
|
||||
|
||||
**Files**:
|
||||
|
||||
- `docs/getting-started/ENVIRONMENT.md`
|
||||
- `.env.example`
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] Feature flag variables documented in ENVIRONMENT.md
|
||||
- [ ] New section "Feature Flags" added
|
||||
- [ ] `.env.example` updated with commented feature flag examples
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
```bash
|
||||
# .env.example addition
|
||||
# ===================
|
||||
# Feature Flags (ADR-024)
|
||||
# ===================
|
||||
# All feature flags default to disabled (false) when not set.
|
||||
# Set to 'true' to enable a feature.
|
||||
#
|
||||
# FEATURE_NEW_DASHBOARD=false
|
||||
# FEATURE_BETA_RECIPES=false
|
||||
# FEATURE_EXPERIMENTAL_AI=false
|
||||
# FEATURE_DEBUG_MODE=false
|
||||
#
|
||||
# Frontend equivalents (prefix with VITE_):
|
||||
# VITE_FEATURE_NEW_DASHBOARD=false
|
||||
# VITE_FEATURE_BETA_RECIPES=false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [3.3] Create CODE-PATTERNS Entry
|
||||
|
||||
**Complexity**: Low
|
||||
**Estimate**: 30 minutes
|
||||
**Dependencies**: All implementation tasks
|
||||
**Parallelizable**: Yes
|
||||
|
||||
**Description**: Add feature flag usage patterns to CODE-PATTERNS.md.
|
||||
|
||||
**File**: `docs/development/CODE-PATTERNS.md`
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] Feature flag section added with examples
|
||||
- [ ] Backend usage pattern documented
|
||||
- [ ] Frontend usage pattern documented
|
||||
- [ ] Testing pattern documented
|
||||
|
||||
---
|
||||
|
||||
#### [3.4] Update CLAUDE.md Quick Reference
|
||||
|
||||
**Complexity**: Low
|
||||
**Estimate**: 15 minutes
|
||||
**Dependencies**: All implementation tasks
|
||||
**Parallelizable**: Yes
|
||||
|
||||
**Description**: Add feature flags to the CLAUDE.md quick reference tables.
|
||||
|
||||
**File**: `CLAUDE.md`
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
- [ ] Feature flags added to "Key Patterns" table
|
||||
- [ ] Reference to featureFlags service added
|
||||
|
||||
---
|
||||
|
||||
## Implementation Sequence
|
||||
|
||||
### Phase 1 (Backend) - Can Start Immediately
|
||||
|
||||
```text
|
||||
[1.1] Schema ──────────┬──> [1.2] Service ──> [1.3] Admin Endpoint
|
||||
│
|
||||
└──> [1.4] Backend Tests (can start after 1.1)
|
||||
```
|
||||
|
||||
### Phase 2 (Frontend) - Can Start Immediately (Parallel with Phase 1)
|
||||
|
||||
```text
|
||||
[2.1] Config ──> [2.2] Hook ──> [2.3] Component ──> [2.4] Frontend Tests
|
||||
```
|
||||
|
||||
### Phase 3 (Documentation) - After Implementation
|
||||
|
||||
```text
|
||||
All Phase 1 & 2 Tasks ──> [3.1] ADR Update
|
||||
├──> [3.2] Env Docs
|
||||
├──> [3.3] Code Patterns
|
||||
└──> [3.4] CLAUDE.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Path
|
||||
|
||||
The minimum path to a working feature flag system:
|
||||
|
||||
1. **[1.1] Schema** (30 min) - Required for backend
|
||||
2. **[1.2] Service** (1.5 hr) - Required for backend access
|
||||
3. **[2.1] Frontend Config** (30 min) - Required for frontend
|
||||
4. **[2.2] Hook** (1 hr) - Required for React integration
|
||||
|
||||
**Critical path duration**: ~3.5 hours
|
||||
|
||||
Non-critical but recommended:
|
||||
|
||||
- Admin endpoint (debugging)
|
||||
- FeatureFlag component (developer convenience)
|
||||
- Tests (quality assurance)
|
||||
- Documentation (maintainability)
|
||||
|
||||
---
|
||||
|
||||
## Scope Recommendations
|
||||
|
||||
### MVP (Minimum Viable Implementation)
|
||||
|
||||
Include in initial implementation:
|
||||
|
||||
- [1.1] Backend schema with 2-3 example flags
|
||||
- [1.2] Feature flag service
|
||||
- [2.1] Frontend config
|
||||
- [2.2] useFeatureFlag hook
|
||||
- [1.4] Core backend tests
|
||||
- [2.4] Core frontend tests
|
||||
|
||||
### Enhancements (Future Iterations)
|
||||
|
||||
Defer to follow-up work:
|
||||
|
||||
- Admin endpoint for flag visibility
|
||||
- FeatureFlag component (nice-to-have)
|
||||
- Dynamic flag updates without restart (requires external service)
|
||||
- User-specific flags (A/B testing)
|
||||
- Flag analytics/usage tracking
|
||||
- Gradual rollout percentages
|
||||
|
||||
### Explicitly Out of Scope
|
||||
|
||||
- Integration with Flagsmith/LaunchDarkly (future ADR)
|
||||
- Database-stored flags (requires schema changes)
|
||||
- Real-time flag updates (WebSocket/SSE)
|
||||
- Flag inheritance/hierarchy
|
||||
- Flag audit logging
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Backend Tests
|
||||
|
||||
| Test Type | Coverage Target | Location |
|
||||
| ----------------- | ---------------------------------------- | ------------------------------------------ |
|
||||
| Schema validation | Parse true/false, defaults | `src/config/env.test.ts` |
|
||||
| Service functions | `isFeatureEnabled`, `getAllFeatureFlags` | `src/services/featureFlags.server.test.ts` |
|
||||
| Integration | Admin endpoint (if added) | `src/routes/admin.routes.test.ts` |
|
||||
|
||||
### Frontend Tests
|
||||
|
||||
| Test Type | Coverage Target | Location |
|
||||
| ------------------- | --------------------------- | ------------------------------------- |
|
||||
| Config structure | featureFlags section exists | `src/config.test.ts` |
|
||||
| Hook behavior | Returns correct values | `src/hooks/useFeatureFlag.test.ts` |
|
||||
| Component rendering | Conditional children | `src/components/FeatureFlag.test.tsx` |
|
||||
|
||||
### Mocking Pattern for Tests
|
||||
|
||||
```typescript
|
||||
// Backend - reset modules to test different flag states
|
||||
beforeEach(() => {
|
||||
vi.resetModules();
|
||||
process.env.FEATURE_NEW_DASHBOARD = 'true';
|
||||
});
|
||||
|
||||
// Frontend - mock config module
|
||||
vi.mock('../config', () => ({
|
||||
default: {
|
||||
featureFlags: {
|
||||
newDashboard: true,
|
||||
betaRecipes: false,
|
||||
},
|
||||
},
|
||||
}));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Impact | Likelihood | Mitigation |
|
||||
| ------------------------------------------- | ------ | ---------- | ------------------------------------------------------------- |
|
||||
| Flag state inconsistency (backend/frontend) | Medium | Low | Use same env var naming, document sync requirements |
|
||||
| Performance impact from flag checks | Low | Low | Flags cached at startup, no runtime DB calls |
|
||||
| Stale flags after deployment | Medium | Medium | Document restart requirement, consider future dynamic loading |
|
||||
| Feature creep (too many flags) | Medium | Medium | Require ADR for new flags, sunset policy |
|
||||
| Missing flag causes crash | High | Low | Default to false, graceful degradation |
|
||||
|
||||
---
|
||||
|
||||
## Files to Create
|
||||
|
||||
| File | Purpose |
|
||||
| ------------------------------------------ | ---------------------------- |
|
||||
| `src/services/featureFlags.server.ts` | Backend feature flag service |
|
||||
| `src/services/featureFlags.server.test.ts` | Backend tests |
|
||||
| `src/hooks/useFeatureFlag.ts` | React hook for flag access |
|
||||
| `src/hooks/useFeatureFlag.test.ts` | Hook tests |
|
||||
| `src/components/FeatureFlag.tsx` | Declarative flag component |
|
||||
| `src/components/FeatureFlag.test.tsx` | Component tests |
|
||||
|
||||
## Files to Modify
|
||||
|
||||
| File | Changes |
|
||||
| -------------------------------------------- | ---------------------------------- |
|
||||
| `src/config/env.ts` | Add featureFlagsSchema and loading |
|
||||
| `src/config/env.test.ts` | Add feature flag tests |
|
||||
| `src/config.ts` | Add featureFlags section |
|
||||
| `src/config.test.ts` | Add feature flag tests |
|
||||
| `src/vite-env.d.ts` | Add VITE*FEATURE*\* declarations |
|
||||
| `.env.example` | Add feature flag examples |
|
||||
| `docs/adr/0024-feature-flagging-strategy.md` | Update status and details |
|
||||
| `docs/getting-started/ENVIRONMENT.md` | Document feature flag vars |
|
||||
| `docs/development/CODE-PATTERNS.md` | Add usage patterns |
|
||||
| `CLAUDE.md` | Add to quick reference |
|
||||
|
||||
---
|
||||
|
||||
## Verification Commands
|
||||
|
||||
After implementation, run these commands in the dev container:
|
||||
|
||||
```bash
|
||||
# Type checking
|
||||
podman exec -it flyer-crawler-dev npm run type-check
|
||||
|
||||
# Backend unit tests
|
||||
podman exec -it flyer-crawler-dev npm run test:unit -- --grep "featureFlag"
|
||||
|
||||
# Frontend tests (includes hook and component tests)
|
||||
podman exec -it flyer-crawler-dev npm run test:unit -- --grep "FeatureFlag"
|
||||
|
||||
# Full test suite
|
||||
podman exec -it flyer-crawler-dev npm test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Usage (Post-Implementation)
|
||||
|
||||
### Backend Route Handler
|
||||
|
||||
```typescript
|
||||
// src/routes/flyers.routes.ts
|
||||
import { isFeatureEnabled } from '../services/featureFlags.server';
|
||||
|
||||
router.get('/dashboard', async (req, res) => {
|
||||
if (isFeatureEnabled('newDashboard')) {
|
||||
// New dashboard logic
|
||||
return sendSuccess(res, { version: 'v2', data: await getNewDashboardData() });
|
||||
}
|
||||
// Legacy dashboard
|
||||
return sendSuccess(res, { version: 'v1', data: await getLegacyDashboardData() });
|
||||
});
|
||||
```
|
||||
|
||||
### React Component
|
||||
|
||||
```tsx
|
||||
// src/pages/Dashboard.tsx
|
||||
import { FeatureFlag } from '../components/FeatureFlag';
|
||||
import { useFeatureFlag } from '../hooks/useFeatureFlag';
|
||||
|
||||
// Option 1: Declarative component
|
||||
function Dashboard() {
|
||||
return (
|
||||
<FeatureFlag name="newDashboard" fallback={<LegacyDashboard />}>
|
||||
<NewDashboard />
|
||||
</FeatureFlag>
|
||||
);
|
||||
}
|
||||
|
||||
// Option 2: Hook for logic
|
||||
function DashboardWithLogic() {
|
||||
const isNewDashboard = useFeatureFlag('newDashboard');
|
||||
|
||||
useEffect(() => {
|
||||
if (isNewDashboard) {
|
||||
analytics.track('new_dashboard_viewed');
|
||||
}
|
||||
}, [isNewDashboard]);
|
||||
|
||||
return isNewDashboard ? <NewDashboard /> : <LegacyDashboard />;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Naming Convention
|
||||
|
||||
| Context | Pattern | Example |
|
||||
| ---------------- | ------------------------- | ---------------------------------- |
|
||||
| Backend env var | `FEATURE_SNAKE_CASE` | `FEATURE_NEW_DASHBOARD` |
|
||||
| Frontend env var | `VITE_FEATURE_SNAKE_CASE` | `VITE_FEATURE_NEW_DASHBOARD` |
|
||||
| Config property | `camelCase` | `config.featureFlags.newDashboard` |
|
||||
| Type/Hook param | `camelCase` | `isFeatureEnabled('newDashboard')` |
|
||||
|
||||
### Flag Lifecycle
|
||||
|
||||
1. **Adding a flag**: Add to both schemas, set default to `false`, document
|
||||
2. **Enabling a flag**: Set env var to `'true'`, restart application
|
||||
3. **Removing a flag**: Remove conditional code first, then remove flag from schemas
|
||||
4. **Sunset policy**: Flags should be removed within 3 months of full rollout
|
||||
|
||||
---
|
||||
|
||||
Last updated: 2026-01-28
|
||||
@@ -2,6 +2,17 @@
|
||||
|
||||
The **ai-usage** subagent specializes in LLM APIs (Gemini, Claude), prompt engineering, and AI-powered features in the Flyer Crawler project.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | Details |
|
||||
| ------------------ | ----------------------------------------------------------------------------------- |
|
||||
| **Primary Use** | Gemini API integration, prompt engineering, AI extraction |
|
||||
| **Key Files** | `src/services/aiService.server.ts`, `src/services/flyerProcessingService.server.ts` |
|
||||
| **Key ADRs** | ADR-041 (AI Integration), ADR-046 (Image Processing) |
|
||||
| **API Key Env** | `VITE_GOOGLE_GENAI_API_KEY` (prod), `VITE_GOOGLE_GENAI_API_KEY_TEST` (test) |
|
||||
| **Error Handling** | Rate limits (429), JSON parse errors, timeout handling |
|
||||
| **Delegate To** | `coder` (implementation), `testwriter` (tests), `integrations-specialist` |
|
||||
|
||||
## When to Use
|
||||
|
||||
Use the **ai-usage** subagent when you need to:
|
||||
@@ -295,6 +306,9 @@ const fixtureResponse = await fs.readFile('fixtures/gemini-response.json');
|
||||
## Related Documentation
|
||||
|
||||
- [OVERVIEW.md](./OVERVIEW.md) - Subagent system overview
|
||||
- [CODER-GUIDE.md](./CODER-GUIDE.md) - For implementing AI features
|
||||
- [TESTER-GUIDE.md](./TESTER-GUIDE.md) - Testing AI features
|
||||
- [INTEGRATIONS-GUIDE.md](./INTEGRATIONS-GUIDE.md) - External API patterns
|
||||
- [../adr/0041-ai-gemini-integration-architecture.md](../adr/0041-ai-gemini-integration-architecture.md) - AI integration ADR
|
||||
- [../adr/0046-image-processing-pipeline.md](../adr/0046-image-processing-pipeline.md) - Image processing
|
||||
- [CODER-GUIDE.md](./CODER-GUIDE.md) - For implementing AI features
|
||||
- [../getting-started/ENVIRONMENT.md](../getting-started/ENVIRONMENT.md) - Environment configuration
|
||||
|
||||
@@ -2,6 +2,17 @@
|
||||
|
||||
The **coder** subagent is your primary tool for writing and modifying production Node.js/TypeScript code in the Flyer Crawler project. This guide explains how to work effectively with the coder subagent.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | Details |
|
||||
| ---------------- | ------------------------------------------------------------------------ |
|
||||
| **Primary Use** | Write/modify production TypeScript code |
|
||||
| **Key Files** | `src/routes/*.routes.ts`, `src/services/**/*.ts`, `src/components/*.tsx` |
|
||||
| **Key ADRs** | ADR-034 (Repository), ADR-035 (Services), ADR-028 (API Response) |
|
||||
| **Test Command** | `podman exec -it flyer-crawler-dev npm run test:unit` |
|
||||
| **Type Check** | `podman exec -it flyer-crawler-dev npm run type-check` |
|
||||
| **Delegate To** | `db-dev` (database), `frontend-specialist` (UI), `testwriter` (tests) |
|
||||
|
||||
## When to Use the Coder Subagent
|
||||
|
||||
Use the coder subagent when you need to:
|
||||
@@ -307,6 +318,8 @@ error classes for all database operations"
|
||||
|
||||
- [OVERVIEW.md](./OVERVIEW.md) - Subagent system overview
|
||||
- [TESTER-GUIDE.md](./TESTER-GUIDE.md) - Testing strategies
|
||||
- [DATABASE-GUIDE.md](./DATABASE-GUIDE.md) - Database development workflows
|
||||
- [../adr/0034-repository-pattern-standards.md](../adr/0034-repository-pattern-standards.md) - Repository patterns
|
||||
- [../adr/0035-service-layer-architecture.md](../adr/0035-service-layer-architecture.md) - Service layer architecture
|
||||
- [../adr/0028-api-response-standardization.md](../adr/0028-api-response-standardization.md) - API response patterns
|
||||
- [../development/CODE-PATTERNS.md](../development/CODE-PATTERNS.md) - Code patterns reference
|
||||
|
||||
@@ -5,6 +5,17 @@ This guide covers two database-focused subagents:
|
||||
- **db-dev**: Database development - schemas, queries, migrations, optimization
|
||||
- **db-admin**: Database administration - PostgreSQL/Redis admin, security, backups
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | db-dev | db-admin |
|
||||
| ---------------- | -------------------------------------------- | ------------------------------------------ |
|
||||
| **Primary Use** | Schemas, queries, migrations | Performance tuning, backups, security |
|
||||
| **Key Files** | `src/services/db/*.db.ts`, `sql/migrations/` | `postgresql.conf`, `pg_hba.conf` |
|
||||
| **Key ADRs** | ADR-034 (Repository), ADR-002 (Transactions) | ADR-019 (Backups), ADR-050 (Observability) |
|
||||
| **Test Command** | `podman exec -it flyer-crawler-dev npm test` | N/A |
|
||||
| **MCP Tool** | `mcp__devdb__query` | SSH to production |
|
||||
| **Delegate To** | `coder` (service layer), `db-admin` (perf) | `devops` (infrastructure) |
|
||||
|
||||
## Understanding the Difference
|
||||
|
||||
| Aspect | db-dev | db-admin |
|
||||
@@ -412,8 +423,9 @@ This is useful for:
|
||||
|
||||
- [OVERVIEW.md](./OVERVIEW.md) - Subagent system overview
|
||||
- [CODER-GUIDE.md](./CODER-GUIDE.md) - Working with the coder subagent
|
||||
- [DEVOPS-GUIDE.md](./DEVOPS-GUIDE.md) - DevOps and deployment workflows
|
||||
- [../adr/0034-repository-pattern-standards.md](../adr/0034-repository-pattern-standards.md) - Repository patterns
|
||||
- [../adr/0002-standardized-transaction-management.md](../adr/0002-standardized-transaction-management.md) - Transaction management
|
||||
- [../adr/0019-data-backup-and-recovery-strategy.md](../adr/0019-data-backup-and-recovery-strategy.md) - Backup strategy
|
||||
- [../adr/0050-postgresql-function-observability.md](../adr/0050-postgresql-function-observability.md) - Database observability
|
||||
- [../BARE-METAL-SETUP.md](../BARE-METAL-SETUP.md) - Production database setup
|
||||
- [../operations/BARE-METAL-SETUP.md](../operations/BARE-METAL-SETUP.md) - Production database setup
|
||||
|
||||
@@ -6,6 +6,90 @@ This guide covers DevOps-related subagents for deployment, infrastructure, and o
|
||||
- **infra-architect**: Resource optimization, capacity planning
|
||||
- **bg-worker**: Background jobs, PM2 workers, BullMQ queues
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | devops | infra-architect | bg-worker |
|
||||
| ---------------- | ------------------------------------------ | --------------------------- | ------------------------------- |
|
||||
| **Primary Use** | Containers, CI/CD, deployments | Resource optimization | BullMQ queues, PM2 workers |
|
||||
| **Key Files** | `compose.dev.yml`, `.gitea/workflows/` | `ecosystem.config.cjs` | `src/services/queues.server.ts` |
|
||||
| **Key ADRs** | ADR-014 (Containers), ADR-017 (CI/CD) | N/A | ADR-006 (Background Jobs) |
|
||||
| **Commands** | `podman-compose`, `pm2` | `pm2 monit`, system metrics | Redis CLI, `pm2 logs` |
|
||||
| **MCP Tools** | `mcp__podman__*` | N/A | N/A |
|
||||
| **Access Model** | Read-only on production (provide commands) | Same | Same |
|
||||
|
||||
---
|
||||
|
||||
## CRITICAL: Server Access Model
|
||||
|
||||
**Claude Code has READ-ONLY access to production/test servers.**
|
||||
|
||||
The `claude-win10` user cannot execute write operations (PM2 restart, systemctl, file modifications) directly on servers. The devops subagent must **provide commands for the user to execute**, not attempt to run them via SSH.
|
||||
|
||||
### Command Delegation Workflow
|
||||
|
||||
When troubleshooting or making changes to production/test servers:
|
||||
|
||||
| Phase | Actor | Action |
|
||||
| -------- | ------ | ----------------------------------------------------------- |
|
||||
| Diagnose | Claude | Provide read-only diagnostic commands |
|
||||
| Report | User | Execute commands, share output with Claude |
|
||||
| Analyze | Claude | Interpret results, identify root cause |
|
||||
| Fix | Claude | Provide 1-3 fix commands (never more, errors may cascade) |
|
||||
| Execute | User | Run fix commands, report results |
|
||||
| Verify | Claude | Provide verification commands to confirm success |
|
||||
| Document | Claude | Update relevant documentation with findings and resolutions |
|
||||
|
||||
### Example: PM2 Process Issue
|
||||
|
||||
Step 1 - Diagnostic Commands (Claude provides, user runs):
|
||||
|
||||
```bash
|
||||
# Check PM2 process status
|
||||
pm2 list
|
||||
|
||||
# View recent error logs
|
||||
pm2 logs flyer-crawler-api --err --lines 50
|
||||
|
||||
# Check system resources
|
||||
free -h
|
||||
df -h /var/www
|
||||
```
|
||||
|
||||
Step 2 - User reports output to Claude
|
||||
|
||||
Step 3 - Fix Commands (Claude provides 1-3 at a time):
|
||||
|
||||
```bash
|
||||
# Restart the failing process
|
||||
pm2 restart flyer-crawler-api
|
||||
```
|
||||
|
||||
Step 4 - User executes and reports result
|
||||
|
||||
Step 5 - Verification Commands:
|
||||
|
||||
```bash
|
||||
# Confirm process is running
|
||||
pm2 list
|
||||
|
||||
# Test API health
|
||||
curl -s https://flyer-crawler.projectium.com/api/health/ready | jq .
|
||||
```
|
||||
|
||||
### What NOT to Do
|
||||
|
||||
```bash
|
||||
# WRONG - Claude cannot execute this directly
|
||||
ssh root@projectium.com "pm2 restart all"
|
||||
|
||||
# WRONG - Providing too many commands at once
|
||||
pm2 stop all && rm -rf node_modules && npm install && pm2 start all
|
||||
|
||||
# WRONG - Assuming commands succeeded without user confirmation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The devops Subagent
|
||||
|
||||
### When to Use
|
||||
@@ -372,6 +456,8 @@ redis-cli -a $REDIS_PASSWORD
|
||||
|
||||
## Service Management Commands
|
||||
|
||||
> **Note**: These commands are for the **user to execute on the server**. Claude Code provides these commands but cannot run them directly due to read-only server access. See [Server Access Model](#critical-server-access-model) above.
|
||||
|
||||
### PM2 Commands
|
||||
|
||||
```bash
|
||||
@@ -468,8 +554,13 @@ podman exec -it flyer-crawler-dev npm test
|
||||
## Related Documentation
|
||||
|
||||
- [OVERVIEW.md](./OVERVIEW.md) - Subagent system overview
|
||||
- [../BARE-METAL-SETUP.md](../BARE-METAL-SETUP.md) - Production setup guide
|
||||
- [DATABASE-GUIDE.md](./DATABASE-GUIDE.md) - Database administration
|
||||
- [SECURITY-DEBUG-GUIDE.md](./SECURITY-DEBUG-GUIDE.md) - Production debugging
|
||||
- [../operations/BARE-METAL-SETUP.md](../operations/BARE-METAL-SETUP.md) - Production setup guide
|
||||
- [../operations/DEPLOYMENT.md](../operations/DEPLOYMENT.md) - Deployment guide
|
||||
- [../operations/MONITORING.md](../operations/MONITORING.md) - Monitoring guide
|
||||
- [../development/DEV-CONTAINER.md](../development/DEV-CONTAINER.md) - Dev container guide
|
||||
- [../adr/0014-containerization-and-deployment-strategy.md](../adr/0014-containerization-and-deployment-strategy.md) - Containerization ADR
|
||||
- [../adr/0006-background-job-processing-and-task-queues.md](../adr/0006-background-job-processing-and-task-queues.md) - Background jobs ADR
|
||||
- [../adr/0017-ci-cd-and-branching-strategy.md](../adr/0017-ci-cd-and-branching-strategy.md) - CI/CD strategy
|
||||
- [../adr/0053-worker-health-checks.md](../adr/0053-worker-health-checks.md) - Worker health checks
|
||||
- [../adr/0053-worker-health-checks-and-monitoring.md](../adr/0053-worker-health-checks-and-monitoring.md) - Worker health checks
|
||||
|
||||
@@ -7,6 +7,15 @@ This guide covers documentation-focused subagents:
|
||||
- **planner**: Feature breakdown, roadmaps, scope management
|
||||
- **product-owner**: Requirements, user stories, backlog prioritization
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | documenter | describer-for-ai | planner | product-owner |
|
||||
| --------------- | -------------------- | ------------------------ | --------------------- | ---------------------- |
|
||||
| **Primary Use** | User docs, API specs | ADRs, technical specs | Feature breakdown | User stories, backlog |
|
||||
| **Key Files** | `docs/`, API docs | `docs/adr/`, `CLAUDE.md` | `docs/plans/` | Issue tracker |
|
||||
| **Output** | Markdown guides | ADRs, context docs | Task lists, roadmaps | User stories, criteria |
|
||||
| **Delegate To** | `coder` (implement) | `documenter` (user docs) | `coder` (build tasks) | `planner` (breakdown) |
|
||||
|
||||
## The documenter Subagent
|
||||
|
||||
### When to Use
|
||||
@@ -437,6 +446,8 @@ Include dates on documentation that may become stale:
|
||||
## Related Documentation
|
||||
|
||||
- [OVERVIEW.md](./OVERVIEW.md) - Subagent system overview
|
||||
- [CODER-GUIDE.md](./CODER-GUIDE.md) - For implementing documented features
|
||||
- [../adr/index.md](../adr/index.md) - ADR index
|
||||
- [../TESTING.md](../TESTING.md) - Testing guide
|
||||
- [../development/TESTING.md](../development/TESTING.md) - Testing guide
|
||||
- [../development/CODE-PATTERNS.md](../development/CODE-PATTERNS.md) - Code patterns reference
|
||||
- [../../CLAUDE.md](../../CLAUDE.md) - AI instructions
|
||||
|
||||
@@ -5,6 +5,17 @@ This guide covers frontend-focused subagents:
|
||||
- **frontend-specialist**: UI components, Neo-Brutalism, Core Web Vitals, accessibility
|
||||
- **uiux-designer**: UI/UX decisions, component design, user experience
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | frontend-specialist | uiux-designer |
|
||||
| ----------------- | ---------------------------------------------- | -------------------------------------- |
|
||||
| **Primary Use** | React components, performance, accessibility | Design decisions, user flows |
|
||||
| **Key Files** | `src/components/`, `src/features/` | Design specs, mockups |
|
||||
| **Key ADRs** | ADR-012 (Design System), ADR-044 (Feature Org) | ADR-012 (Design System) |
|
||||
| **Design System** | Neo-Brutalism (bold borders, high contrast) | Same |
|
||||
| **State Mgmt** | TanStack Query (server), Zustand (client) | N/A |
|
||||
| **Delegate To** | `coder` (backend), `tester` (test coverage) | `frontend-specialist` (implementation) |
|
||||
|
||||
## The frontend-specialist Subagent
|
||||
|
||||
### When to Use
|
||||
@@ -406,7 +417,8 @@ const handleSelect = useCallback((id: string) => {
|
||||
|
||||
- [OVERVIEW.md](./OVERVIEW.md) - Subagent system overview
|
||||
- [CODER-GUIDE.md](./CODER-GUIDE.md) - For implementing features
|
||||
- [../DESIGN_TOKENS.md](../DESIGN_TOKENS.md) - Design token reference
|
||||
- [TESTER-GUIDE.md](./TESTER-GUIDE.md) - Component testing patterns
|
||||
- [../development/DESIGN_TOKENS.md](../development/DESIGN_TOKENS.md) - Design token reference
|
||||
- [../adr/0012-frontend-component-library-and-design-system.md](../adr/0012-frontend-component-library-and-design-system.md) - Design system ADR
|
||||
- [../adr/0005-frontend-state-management-and-server-cache-strategy.md](../adr/0005-frontend-state-management-and-server-cache-strategy.md) - State management ADR
|
||||
- [../adr/0044-frontend-feature-organization.md](../adr/0044-frontend-feature-organization.md) - Feature organization
|
||||
|
||||
396
docs/subagents/INTEGRATIONS-GUIDE.md
Normal file
396
docs/subagents/INTEGRATIONS-GUIDE.md
Normal file
@@ -0,0 +1,396 @@
|
||||
# Integrations Subagent Guide
|
||||
|
||||
The **integrations-specialist** subagent handles third-party services, webhooks, and external API integrations in the Flyer Crawler project.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | Details |
|
||||
| --------------- | --------------------------------------------------------------------------- |
|
||||
| **Primary Use** | External APIs, webhooks, OAuth, third-party services |
|
||||
| **Key Files** | `src/services/external/`, `src/routes/webhooks.routes.ts` |
|
||||
| **Key ADRs** | ADR-041 (AI Integration), ADR-016 (API Security), ADR-048 (Auth) |
|
||||
| **MCP Tools** | `mcp__gitea-projectium__*`, `mcp__bugsink__*` |
|
||||
| **Security** | API key storage, webhook signatures, OAuth state param |
|
||||
| **Delegate To** | `coder` (implementation), `security-engineer` (review), `ai-usage` (Gemini) |
|
||||
|
||||
## When to Use
|
||||
|
||||
Use the **integrations-specialist** subagent when you need to:
|
||||
|
||||
- Integrate with external APIs (OAuth, REST, GraphQL)
|
||||
- Implement webhook handlers
|
||||
- Configure third-party services
|
||||
- Debug external service connectivity
|
||||
- Handle API authentication flows
|
||||
- Manage external service rate limits
|
||||
|
||||
## What integrations-specialist Knows
|
||||
|
||||
The integrations-specialist subagent understands:
|
||||
|
||||
- OAuth 2.0 flows (authorization code, client credentials)
|
||||
- REST API integration patterns
|
||||
- Webhook security (signature verification)
|
||||
- External service error handling
|
||||
- Rate limiting and retry strategies
|
||||
- API key management
|
||||
|
||||
## Current Integrations
|
||||
|
||||
| Service | Purpose | Integration Type | Key Files |
|
||||
| ------------- | ---------------------- | ---------------- | ---------------------------------- |
|
||||
| Google Gemini | AI flyer extraction | REST API | `src/services/aiService.server.ts` |
|
||||
| Bugsink | Error tracking | REST API | MCP: `mcp__bugsink__*` |
|
||||
| Gitea | Repository and CI/CD | REST API | MCP: `mcp__gitea-projectium__*` |
|
||||
| Redis | Caching and job queues | Native client | `src/services/redis.server.ts` |
|
||||
| PostgreSQL | Primary database | Native client | `src/services/db/pool.db.ts` |
|
||||
|
||||
## Example Requests
|
||||
|
||||
### Adding External API Integration
|
||||
|
||||
```
|
||||
"Use integrations-specialist to integrate with the Store API
|
||||
to automatically fetch store location data. Include proper
|
||||
error handling, rate limiting, and caching."
|
||||
```
|
||||
|
||||
### OAuth Implementation
|
||||
|
||||
```
|
||||
"Use integrations-specialist to implement Google OAuth for
|
||||
user authentication. Include token refresh handling and
|
||||
session management."
|
||||
```
|
||||
|
||||
### Webhook Handler
|
||||
|
||||
```
|
||||
"Use integrations-specialist to create a webhook handler for
|
||||
receiving store inventory updates. Include signature verification
|
||||
and idempotency handling."
|
||||
```
|
||||
|
||||
### Debugging External Service Issues
|
||||
|
||||
```
|
||||
"Use integrations-specialist to debug why the Gemini API calls
|
||||
are intermittently failing with timeout errors. Check connection
|
||||
pooling, retry logic, and error handling."
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### REST API Client Pattern
|
||||
|
||||
```typescript
|
||||
// src/services/external/storeApi.server.ts
|
||||
import { env } from '@/config/env';
|
||||
import { log } from '@/services/logger.server';
|
||||
|
||||
interface StoreApiConfig {
|
||||
baseUrl: string;
|
||||
apiKey: string;
|
||||
timeout: number;
|
||||
}
|
||||
|
||||
class StoreApiClient {
|
||||
private config: StoreApiConfig;
|
||||
|
||||
constructor(config: StoreApiConfig) {
|
||||
this.config = config;
|
||||
}
|
||||
|
||||
async getStoreLocations(storeId: string): Promise<StoreLocation[]> {
|
||||
const url = `${this.config.baseUrl}/stores/${storeId}/locations`;
|
||||
|
||||
try {
|
||||
const response = await fetch(url, {
|
||||
headers: {
|
||||
Authorization: `Bearer ${this.config.apiKey}`,
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
signal: AbortSignal.timeout(this.config.timeout),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
throw new ExternalApiError(`Store API error: ${response.status}`, response.status);
|
||||
}
|
||||
|
||||
return response.json();
|
||||
} catch (error) {
|
||||
log.error({ error, storeId }, 'Failed to fetch store locations');
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export const storeApiClient = new StoreApiClient({
|
||||
baseUrl: env.STORE_API_BASE_URL,
|
||||
apiKey: env.STORE_API_KEY,
|
||||
timeout: 10000,
|
||||
});
|
||||
```
|
||||
|
||||
### Webhook Handler Pattern
|
||||
|
||||
```typescript
|
||||
// src/routes/webhooks.routes.ts
|
||||
import { Router } from 'express';
|
||||
import crypto from 'crypto';
|
||||
import { env } from '@/config/env';
|
||||
|
||||
const router = Router();
|
||||
|
||||
function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean {
|
||||
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
|
||||
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(`sha256=${expected}`));
|
||||
}
|
||||
|
||||
router.post('/store-updates', async (req, res, next) => {
|
||||
try {
|
||||
const signature = req.headers['x-webhook-signature'] as string;
|
||||
const payload = JSON.stringify(req.body);
|
||||
|
||||
if (!verifyWebhookSignature(payload, signature, env.WEBHOOK_SECRET)) {
|
||||
return res.status(401).json({ error: 'Invalid signature' });
|
||||
}
|
||||
|
||||
// Process webhook with idempotency check
|
||||
const eventId = req.headers['x-event-id'] as string;
|
||||
const alreadyProcessed = await checkIdempotencyKey(eventId);
|
||||
|
||||
if (alreadyProcessed) {
|
||||
return res.status(200).json({ status: 'already_processed' });
|
||||
}
|
||||
|
||||
await processStoreUpdate(req.body);
|
||||
await markEventProcessed(eventId);
|
||||
|
||||
res.status(200).json({ status: 'processed' });
|
||||
} catch (error) {
|
||||
next(error);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### OAuth Flow Pattern
|
||||
|
||||
```typescript
|
||||
// src/services/oauth/googleOAuth.server.ts
|
||||
import { OAuth2Client } from 'google-auth-library';
|
||||
import { env } from '@/config/env';
|
||||
|
||||
const oauth2Client = new OAuth2Client(
|
||||
env.GOOGLE_CLIENT_ID,
|
||||
env.GOOGLE_CLIENT_SECRET,
|
||||
env.GOOGLE_REDIRECT_URI,
|
||||
);
|
||||
|
||||
export function getAuthorizationUrl(): string {
|
||||
return oauth2Client.generateAuthUrl({
|
||||
access_type: 'offline',
|
||||
scope: ['email', 'profile'],
|
||||
prompt: 'consent',
|
||||
});
|
||||
}
|
||||
|
||||
export async function exchangeCodeForTokens(code: string) {
|
||||
const { tokens } = await oauth2Client.getToken(code);
|
||||
return tokens;
|
||||
}
|
||||
|
||||
export async function refreshAccessToken(refreshToken: string) {
|
||||
oauth2Client.setCredentials({ refresh_token: refreshToken });
|
||||
const { credentials } = await oauth2Client.refreshAccessToken();
|
||||
return credentials;
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling for External Services
|
||||
|
||||
### Custom Error Classes
|
||||
|
||||
```typescript
|
||||
// src/services/external/errors.ts
|
||||
export class ExternalApiError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
public statusCode: number,
|
||||
public retryable: boolean = false,
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'ExternalApiError';
|
||||
}
|
||||
}
|
||||
|
||||
export class RateLimitError extends ExternalApiError {
|
||||
constructor(
|
||||
message: string,
|
||||
public retryAfter: number,
|
||||
) {
|
||||
super(message, 429, true);
|
||||
this.name = 'RateLimitError';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Retry with Exponential Backoff
|
||||
|
||||
```typescript
|
||||
async function fetchWithRetry<T>(
|
||||
fn: () => Promise<T>,
|
||||
options: { maxRetries: number; baseDelay: number },
|
||||
): Promise<T> {
|
||||
let lastError: Error;
|
||||
|
||||
for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
|
||||
try {
|
||||
return await fn();
|
||||
} catch (error) {
|
||||
lastError = error as Error;
|
||||
|
||||
if (error instanceof ExternalApiError && !error.retryable) {
|
||||
throw error;
|
||||
}
|
||||
|
||||
if (attempt < options.maxRetries) {
|
||||
const delay = options.baseDelay * Math.pow(2, attempt);
|
||||
await new Promise((resolve) => setTimeout(resolve, delay));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
throw lastError!;
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting Strategies
|
||||
|
||||
### Token Bucket Pattern
|
||||
|
||||
```typescript
|
||||
class RateLimiter {
|
||||
private tokens: number;
|
||||
private lastRefill: number;
|
||||
private readonly maxTokens: number;
|
||||
private readonly refillRate: number; // tokens per second
|
||||
|
||||
constructor(maxTokens: number, refillRate: number) {
|
||||
this.maxTokens = maxTokens;
|
||||
this.tokens = maxTokens;
|
||||
this.refillRate = refillRate;
|
||||
this.lastRefill = Date.now();
|
||||
}
|
||||
|
||||
async acquire(): Promise<void> {
|
||||
this.refill();
|
||||
|
||||
if (this.tokens < 1) {
|
||||
const waitTime = ((1 - this.tokens) / this.refillRate) * 1000;
|
||||
await new Promise((resolve) => setTimeout(resolve, waitTime));
|
||||
this.refill();
|
||||
}
|
||||
|
||||
this.tokens -= 1;
|
||||
}
|
||||
|
||||
private refill(): void {
|
||||
const now = Date.now();
|
||||
const elapsed = (now - this.lastRefill) / 1000;
|
||||
this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.refillRate);
|
||||
this.lastRefill = now;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Integrations
|
||||
|
||||
### Mocking External Services
|
||||
|
||||
```typescript
|
||||
// src/tests/mocks/storeApi.mock.ts
|
||||
import { vi } from 'vitest';
|
||||
|
||||
export const mockStoreApiClient = {
|
||||
getStoreLocations: vi.fn(),
|
||||
};
|
||||
|
||||
vi.mock('@/services/external/storeApi.server', () => ({
|
||||
storeApiClient: mockStoreApiClient,
|
||||
}));
|
||||
```
|
||||
|
||||
### Integration Test with Real Service
|
||||
|
||||
```typescript
|
||||
// src/tests/integration/storeApi.integration.test.ts
|
||||
describe('Store API Integration', () => {
|
||||
it.skipIf(!env.STORE_API_KEY)('fetches real store locations', async () => {
|
||||
const locations = await storeApiClient.getStoreLocations('test-store');
|
||||
expect(locations).toBeInstanceOf(Array);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## MCP Tools for Integrations
|
||||
|
||||
### Gitea Integration
|
||||
|
||||
```
|
||||
// List repositories
|
||||
mcp__gitea-projectium__list_my_repos()
|
||||
|
||||
// Create issue
|
||||
mcp__gitea-projectium__create_issue({
|
||||
owner: "projectium",
|
||||
repo: "flyer-crawler",
|
||||
title: "Issue title",
|
||||
body: "Issue description"
|
||||
})
|
||||
```
|
||||
|
||||
### Bugsink Integration
|
||||
|
||||
```
|
||||
// List projects
|
||||
mcp__bugsink__list_projects()
|
||||
|
||||
// Get issue details
|
||||
mcp__bugsink__get_issue({ issue_id: "..." })
|
||||
|
||||
// Get stacktrace
|
||||
mcp__bugsink__get_stacktrace({ event_id: "..." })
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### API Key Storage
|
||||
|
||||
- Never commit API keys to version control
|
||||
- Use environment variables via `src/config/env.ts`
|
||||
- Rotate keys periodically
|
||||
- Use separate keys for dev/test/prod
|
||||
|
||||
### Webhook Security
|
||||
|
||||
- Always verify webhook signatures
|
||||
- Use HTTPS for webhook endpoints
|
||||
- Implement idempotency
|
||||
- Log webhook events for audit
|
||||
|
||||
### OAuth Security
|
||||
|
||||
- Use state parameter to prevent CSRF
|
||||
- Store tokens securely (encrypted at rest)
|
||||
- Implement token refresh before expiration
|
||||
- Validate token scopes
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [OVERVIEW.md](./OVERVIEW.md) - Subagent system overview
|
||||
- [SECURITY-DEBUG-GUIDE.md](./SECURITY-DEBUG-GUIDE.md) - Security patterns
|
||||
- [AI-USAGE-GUIDE.md](./AI-USAGE-GUIDE.md) - Gemini API integration
|
||||
- [../adr/0041-ai-gemini-integration-architecture.md](../adr/0041-ai-gemini-integration-architecture.md) - AI integration ADR
|
||||
- [../adr/0016-api-security-hardening.md](../adr/0016-api-security-hardening.md) - API security
|
||||
- [../adr/0048-authentication-strategy.md](../adr/0048-authentication-strategy.md) - Authentication
|
||||
@@ -89,6 +89,47 @@ Or:
|
||||
|
||||
Claude will automatically invoke the appropriate subagent with the relevant context.
|
||||
|
||||
## Quick Reference Decision Tree
|
||||
|
||||
Use this flowchart to quickly identify the right subagent:
|
||||
|
||||
```
|
||||
What do you need to do?
|
||||
|
|
||||
+-- Write/modify code? ----------------> Is it database-related?
|
||||
| |
|
||||
| +-- Yes -> db-dev
|
||||
| +-- No --> Is it frontend?
|
||||
| |
|
||||
| +-- Yes -> frontend-specialist
|
||||
| +-- No --> Is it AI/Gemini?
|
||||
| |
|
||||
| +-- Yes -> ai-usage
|
||||
| +-- No --> coder
|
||||
|
|
||||
+-- Test something? -------------------> Write new tests? -> testwriter
|
||||
| Find bugs/vulnerabilities? -> tester
|
||||
| Review existing code? -> code-reviewer
|
||||
|
|
||||
+-- Debug an issue? -------------------> Production error? -> log-debug
|
||||
| Database slow? -> db-admin
|
||||
| External API failing? -> integrations-specialist
|
||||
| AI extraction failing? -> ai-usage
|
||||
|
|
||||
+-- Infrastructure/Deployment? --------> Container/CI/CD? -> devops
|
||||
| Resource optimization? -> infra-architect
|
||||
| Background jobs? -> bg-worker
|
||||
|
|
||||
+-- Documentation? --------------------> User-facing docs? -> documenter
|
||||
| ADRs/Technical specs? -> describer-for-ai
|
||||
| Feature planning? -> planner
|
||||
| User stories? -> product-owner
|
||||
|
|
||||
+-- Security? -------------------------> security-engineer
|
||||
|
|
||||
+-- Design/UX? ------------------------> uiux-designer
|
||||
```
|
||||
|
||||
## Subagent Selection Guide
|
||||
|
||||
### Which Subagent Should I Use?
|
||||
@@ -183,12 +224,26 @@ Subagents can pass information back to the main conversation and to each other t
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [CODER-GUIDE.md](./CODER-GUIDE.md) - Working with the coder subagent
|
||||
- [TESTER-GUIDE.md](./TESTER-GUIDE.md) - Testing strategies and patterns
|
||||
- [DATABASE-GUIDE.md](./DATABASE-GUIDE.md) - Database development workflows
|
||||
- [DEVOPS-GUIDE.md](./DEVOPS-GUIDE.md) - DevOps and deployment workflows
|
||||
### Subagent Guides
|
||||
|
||||
| Guide | Subagents Covered |
|
||||
| ---------------------------------------------------- | ----------------------------------------------------- |
|
||||
| [CODER-GUIDE.md](./CODER-GUIDE.md) | coder |
|
||||
| [TESTER-GUIDE.md](./TESTER-GUIDE.md) | tester, testwriter |
|
||||
| [DATABASE-GUIDE.md](./DATABASE-GUIDE.md) | db-dev, db-admin |
|
||||
| [DEVOPS-GUIDE.md](./DEVOPS-GUIDE.md) | devops, infra-architect, bg-worker |
|
||||
| [FRONTEND-GUIDE.md](./FRONTEND-GUIDE.md) | frontend-specialist, uiux-designer |
|
||||
| [SECURITY-DEBUG-GUIDE.md](./SECURITY-DEBUG-GUIDE.md) | security-engineer, log-debug, code-reviewer |
|
||||
| [AI-USAGE-GUIDE.md](./AI-USAGE-GUIDE.md) | ai-usage |
|
||||
| [INTEGRATIONS-GUIDE.md](./INTEGRATIONS-GUIDE.md) | integrations-specialist, tools-integration-specialist |
|
||||
| [DOCUMENTATION-GUIDE.md](./DOCUMENTATION-GUIDE.md) | documenter, describer-for-ai, planner, product-owner |
|
||||
|
||||
### Project Documentation
|
||||
|
||||
- [../adr/index.md](../adr/index.md) - Architecture Decision Records
|
||||
- [../TESTING.md](../TESTING.md) - Testing guide
|
||||
- [../development/TESTING.md](../development/TESTING.md) - Testing guide
|
||||
- [../development/CODE-PATTERNS.md](../development/CODE-PATTERNS.md) - Code patterns reference
|
||||
- [../architecture/OVERVIEW.md](../architecture/OVERVIEW.md) - System architecture
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
@@ -6,6 +6,16 @@ This guide covers security and debugging-focused subagents:
|
||||
- **log-debug**: Production errors, observability, Bugsink/Sentry analysis
|
||||
- **code-reviewer**: Code quality, security review, best practices
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | security-engineer | log-debug | code-reviewer |
|
||||
| --------------- | ---------------------------------- | ---------------------------------------- | --------------------------- |
|
||||
| **Primary Use** | Security audits, OWASP | Production debugging | Code quality review |
|
||||
| **Key ADRs** | ADR-016 (Security), ADR-032 (Rate) | ADR-050 (Observability) | ADR-034, ADR-035 (Patterns) |
|
||||
| **MCP Tools** | N/A | `mcp__bugsink__*`, `mcp__localerrors__*` | N/A |
|
||||
| **Key Checks** | Auth, input validation, CORS | Logs, stacktraces, error patterns | Patterns, tests, security |
|
||||
| **Delegate To** | `coder` (fix issues) | `devops` (infra), `coder` (fixes) | `coder`, `testwriter` |
|
||||
|
||||
## The security-engineer Subagent
|
||||
|
||||
### When to Use
|
||||
@@ -432,8 +442,10 @@ tail -f /var/log/postgresql/postgresql-$(date +%Y-%m-%d).log | grep "duration:"
|
||||
|
||||
- [OVERVIEW.md](./OVERVIEW.md) - Subagent system overview
|
||||
- [DEVOPS-GUIDE.md](./DEVOPS-GUIDE.md) - Infrastructure debugging
|
||||
- [TESTER-GUIDE.md](./TESTER-GUIDE.md) - Security testing
|
||||
- [../adr/0016-api-security-hardening.md](../adr/0016-api-security-hardening.md) - Security ADR
|
||||
- [../adr/0032-rate-limiting-strategy.md](../adr/0032-rate-limiting-strategy.md) - Rate limiting
|
||||
- [../adr/0015-application-performance-monitoring-and-error-tracking.md](../adr/0015-application-performance-monitoring-and-error-tracking.md) - Monitoring ADR
|
||||
- [../adr/0015-error-tracking-and-observability.md](../adr/0015-error-tracking-and-observability.md) - Monitoring ADR
|
||||
- [../adr/0050-postgresql-function-observability.md](../adr/0050-postgresql-function-observability.md) - Database observability
|
||||
- [../BARE-METAL-SETUP.md](../BARE-METAL-SETUP.md) - Production setup
|
||||
- [../operations/BARE-METAL-SETUP.md](../operations/BARE-METAL-SETUP.md) - Production setup
|
||||
- [../tools/BUGSINK-SETUP.md](../tools/BUGSINK-SETUP.md) - Bugsink configuration
|
||||
|
||||
@@ -5,6 +5,17 @@ This guide covers two related but distinct subagents for testing in the Flyer Cr
|
||||
- **tester**: Adversarial testing to find edge cases, race conditions, and vulnerabilities
|
||||
- **testwriter**: Creating comprehensive test suites for features and fixes
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | tester | testwriter |
|
||||
| ---------------- | -------------------------------------------- | ------------------------------------------ |
|
||||
| **Primary Use** | Find bugs, security issues, edge cases | Create test suites, improve coverage |
|
||||
| **Key Files** | N/A (analysis-focused) | `*.test.ts`, `src/tests/utils/` |
|
||||
| **Key ADRs** | ADR-010 (Testing), ADR-040 (Test Economics) | ADR-010 (Testing), ADR-045 (Test Fixtures) |
|
||||
| **Test Command** | `podman exec -it flyer-crawler-dev npm test` | Same |
|
||||
| **Test Stack** | Vitest, Supertest, Testing Library | Same |
|
||||
| **Delegate To** | `testwriter` (write tests for findings) | `coder` (fix failing tests) |
|
||||
|
||||
## Understanding the Difference
|
||||
|
||||
| Aspect | tester | testwriter |
|
||||
@@ -399,6 +410,7 @@ A typical workflow for thorough testing:
|
||||
|
||||
- [OVERVIEW.md](./OVERVIEW.md) - Subagent system overview
|
||||
- [CODER-GUIDE.md](./CODER-GUIDE.md) - Working with the coder subagent
|
||||
- [../TESTING.md](../TESTING.md) - Testing guide
|
||||
- [SECURITY-DEBUG-GUIDE.md](./SECURITY-DEBUG-GUIDE.md) - Security testing and code review
|
||||
- [../development/TESTING.md](../development/TESTING.md) - Testing guide
|
||||
- [../adr/0010-testing-strategy-and-standards.md](../adr/0010-testing-strategy-and-standards.md) - Testing ADR
|
||||
- [../adr/0040-testing-economics-and-priorities.md](../adr/0040-testing-economics-and-priorities.md) - Testing priorities
|
||||
|
||||
@@ -109,10 +109,10 @@ MSYS_NO_PATHCONV=1 podman exec -e DATABASE_URL=postgresql://bugsink:bugsink_dev_
|
||||
|
||||
### Production Token
|
||||
|
||||
SSH into the production server:
|
||||
User executes this command on the production server:
|
||||
|
||||
```bash
|
||||
ssh root@projectium.com "cd /opt/bugsink && bugsink-manage create_auth_token"
|
||||
cd /opt/bugsink && bugsink-manage create_auth_token
|
||||
```
|
||||
|
||||
**Output:** Same format - 40-character hex token.
|
||||
@@ -795,10 +795,10 @@ podman exec flyer-crawler-dev pg_isready -U bugsink -d bugsink -h postgres
|
||||
podman exec flyer-crawler-dev psql -U postgres -h postgres -c "\l" | grep bugsink
|
||||
```
|
||||
|
||||
**Production:**
|
||||
**Production** (user executes on server):
|
||||
|
||||
```bash
|
||||
ssh root@projectium.com "cd /opt/bugsink && bugsink-manage check"
|
||||
cd /opt/bugsink && bugsink-manage check
|
||||
```
|
||||
|
||||
### PostgreSQL Sequence Out of Sync (Duplicate Key Errors)
|
||||
@@ -834,10 +834,9 @@ SELECT
|
||||
END as status;
|
||||
"
|
||||
|
||||
# Production
|
||||
ssh root@projectium.com "cd /opt/bugsink && bugsink-manage dbshell" <<< "
|
||||
SELECT MAX(id) as max_id, (SELECT last_value FROM projects_project_id_seq) as seq_value FROM projects_project;
|
||||
"
|
||||
# Production (user executes on server)
|
||||
cd /opt/bugsink && bugsink-manage dbshell
|
||||
# Then run: SELECT MAX(id) as max_id, (SELECT last_value FROM projects_project_id_seq) as seq_value FROM projects_project;
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
@@ -850,10 +849,9 @@ podman exec flyer-crawler-dev psql -U bugsink -h postgres -d bugsink -c "
|
||||
SELECT setval('projects_project_id_seq', COALESCE((SELECT MAX(id) FROM projects_project), 1), true);
|
||||
"
|
||||
|
||||
# Production
|
||||
ssh root@projectium.com "cd /opt/bugsink && bugsink-manage dbshell" <<< "
|
||||
SELECT setval('projects_project_id_seq', COALESCE((SELECT MAX(id) FROM projects_project), 1), true);
|
||||
"
|
||||
# Production (user executes on server)
|
||||
cd /opt/bugsink && bugsink-manage dbshell
|
||||
# Then run: SELECT setval('projects_project_id_seq', COALESCE((SELECT MAX(id) FROM projects_project), 1), true);
|
||||
```
|
||||
|
||||
**Verification:**
|
||||
|
||||
4
package-lock.json
generated
4
package-lock.json
generated
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "flyer-crawler",
|
||||
"version": "0.12.16",
|
||||
"version": "0.12.25",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "flyer-crawler",
|
||||
"version": "0.12.16",
|
||||
"version": "0.12.25",
|
||||
"dependencies": {
|
||||
"@bull-board/api": "^6.14.2",
|
||||
"@bull-board/express": "^6.14.2",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "flyer-crawler",
|
||||
"private": true,
|
||||
"version": "0.12.16",
|
||||
"version": "0.12.25",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "concurrently \"npm:start:dev\" \"vite\"",
|
||||
|
||||
1
public/uploads/avatars/user-123-1769556382113.png
Normal file
1
public/uploads/avatars/user-123-1769556382113.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769556382716.png
Normal file
1
public/uploads/avatars/user-123-1769556382716.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769556417728.png
Normal file
1
public/uploads/avatars/user-123-1769556417728.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769556418517.png
Normal file
1
public/uploads/avatars/user-123-1769556418517.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769556971592.png
Normal file
1
public/uploads/avatars/user-123-1769556971592.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769556971945.png
Normal file
1
public/uploads/avatars/user-123-1769556971945.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769557483553.png
Normal file
1
public/uploads/avatars/user-123-1769557483553.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769557483984.png
Normal file
1
public/uploads/avatars/user-123-1769557483984.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769577983141.png
Normal file
1
public/uploads/avatars/user-123-1769577983141.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769578019270.png
Normal file
1
public/uploads/avatars/user-123-1769578019270.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769578572307.png
Normal file
1
public/uploads/avatars/user-123-1769578572307.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
1
public/uploads/avatars/user-123-1769579084330.png
Normal file
1
public/uploads/avatars/user-123-1769579084330.png
Normal file
@@ -0,0 +1 @@
|
||||
dummy-image-content
|
||||
89
server.ts
89
server.ts
@@ -18,27 +18,8 @@ import { getPool } from './src/services/db/connection.db';
|
||||
import passport from './src/config/passport';
|
||||
import { logger } from './src/services/logger.server';
|
||||
|
||||
// Import routers
|
||||
import authRouter from './src/routes/auth.routes';
|
||||
import userRouter from './src/routes/user.routes';
|
||||
import adminRouter from './src/routes/admin.routes';
|
||||
import aiRouter from './src/routes/ai.routes';
|
||||
import budgetRouter from './src/routes/budget.routes';
|
||||
import flyerRouter from './src/routes/flyer.routes';
|
||||
import recipeRouter from './src/routes/recipe.routes';
|
||||
import personalizationRouter from './src/routes/personalization.routes';
|
||||
import priceRouter from './src/routes/price.routes';
|
||||
import statsRouter from './src/routes/stats.routes';
|
||||
import gamificationRouter from './src/routes/gamification.routes';
|
||||
import systemRouter from './src/routes/system.routes';
|
||||
import healthRouter from './src/routes/health.routes';
|
||||
import upcRouter from './src/routes/upc.routes';
|
||||
import inventoryRouter from './src/routes/inventory.routes';
|
||||
import receiptRouter from './src/routes/receipt.routes';
|
||||
import dealsRouter from './src/routes/deals.routes';
|
||||
import reactionsRouter from './src/routes/reactions.routes';
|
||||
import storeRouter from './src/routes/store.routes';
|
||||
import categoryRouter from './src/routes/category.routes';
|
||||
// Import the versioned API router factory (ADR-008 Phase 2)
|
||||
import { createApiRouter } from './src/routes/versioned';
|
||||
import { errorHandler } from './src/middleware/errorHandler';
|
||||
import { backgroundJobService, startBackgroundJobs } from './src/services/backgroundJobService';
|
||||
import { websocketService } from './src/services/websocketService.server';
|
||||
@@ -249,56 +230,20 @@ app.get('/api/v1/health/queues', async (req, res) => {
|
||||
}
|
||||
});
|
||||
|
||||
// The order of route registration is critical.
|
||||
// More specific routes should be registered before more general ones.
|
||||
// All routes are now versioned under /api/v1 as per ADR-008.
|
||||
// 1. Authentication routes for login, registration, etc.
|
||||
app.use('/api/v1/auth', authRouter);
|
||||
// 2. System routes for health checks, etc.
|
||||
app.use('/api/v1/health', healthRouter);
|
||||
// 3. System routes for pm2 status, etc.
|
||||
app.use('/api/v1/system', systemRouter);
|
||||
// 3. General authenticated user routes.
|
||||
app.use('/api/v1/users', userRouter);
|
||||
// 4. AI routes, some of which use optional authentication.
|
||||
app.use('/api/v1/ai', aiRouter);
|
||||
// 5. Admin routes, which are all protected by admin-level checks.
|
||||
app.use('/api/v1/admin', adminRouter);
|
||||
// 6. Budgeting and spending analysis routes.
|
||||
app.use('/api/v1/budgets', budgetRouter);
|
||||
// 7. Gamification routes for achievements.
|
||||
app.use('/api/v1/achievements', gamificationRouter);
|
||||
// 8. Public flyer routes.
|
||||
app.use('/api/v1/flyers', flyerRouter);
|
||||
// 8. Public recipe routes.
|
||||
app.use('/api/v1/recipes', recipeRouter);
|
||||
// 9. Public personalization data routes (master items, etc.).
|
||||
app.use('/api/v1/personalization', personalizationRouter);
|
||||
// 9.5. Price history routes.
|
||||
app.use('/api/v1/price-history', priceRouter);
|
||||
// 10. Public statistics routes.
|
||||
app.use('/api/v1/stats', statsRouter);
|
||||
// 11. UPC barcode scanning routes.
|
||||
app.use('/api/v1/upc', upcRouter);
|
||||
// 12. Inventory and expiry tracking routes.
|
||||
app.use('/api/v1/inventory', inventoryRouter);
|
||||
// 13. Receipt scanning routes.
|
||||
app.use('/api/v1/receipts', receiptRouter);
|
||||
// 14. Deals and best prices routes.
|
||||
app.use('/api/v1/deals', dealsRouter);
|
||||
// 15. Reactions/social features routes.
|
||||
app.use('/api/v1/reactions', reactionsRouter);
|
||||
// 16. Store management routes.
|
||||
app.use('/api/v1/stores', storeRouter);
|
||||
// 17. Category discovery routes (ADR-023: Database Normalization)
|
||||
app.use('/api/v1/categories', categoryRouter);
|
||||
|
||||
// --- Backwards Compatibility Redirect (ADR-008: API Versioning Strategy) ---
|
||||
// Redirect old /api/* paths to /api/v1/* for backwards compatibility.
|
||||
// This allows clients to gradually migrate to the versioned API.
|
||||
// IMPORTANT: This middleware MUST be mounted BEFORE createApiRouter() so that
|
||||
// unversioned paths like /api/users are redirected to /api/v1/users BEFORE
|
||||
// the versioned router's detectApiVersion middleware rejects them as invalid versions.
|
||||
app.use('/api', (req, res, next) => {
|
||||
// Only redirect if the path does NOT already start with /v1
|
||||
if (!req.path.startsWith('/v1')) {
|
||||
// Check if the path starts with a version-like prefix (/v followed by digits).
|
||||
// This includes both supported versions (v1, v2) and unsupported ones (v99).
|
||||
// Unsupported versions will be handled by detectApiVersion middleware which returns 404.
|
||||
// This redirect only handles legacy unversioned paths like /api/users -> /api/v1/users.
|
||||
const versionPattern = /^\/v\d+/;
|
||||
const startsWithVersionPattern = versionPattern.test(req.path);
|
||||
if (!startsWithVersionPattern) {
|
||||
const newPath = `/api/v1${req.path}`;
|
||||
logger.info({ oldPath: `/api${req.path}`, newPath }, 'Redirecting to versioned API');
|
||||
return res.redirect(301, newPath);
|
||||
@@ -306,6 +251,16 @@ app.use('/api', (req, res, next) => {
|
||||
next();
|
||||
});
|
||||
|
||||
// Mount the versioned API router (ADR-008 Phase 2).
|
||||
// The createApiRouter() factory handles:
|
||||
// - Version detection and validation via detectApiVersion middleware
|
||||
// - Route registration in correct precedence order
|
||||
// - Version-specific route availability
|
||||
// - Deprecation headers via addDeprecationHeaders middleware
|
||||
// - X-API-Version response headers
|
||||
// All domain routers are registered in versioned.ts with proper ordering.
|
||||
app.use('/api', createApiRouter());
|
||||
|
||||
// --- Error Handling and Server Startup ---
|
||||
|
||||
// Catch-all 404 handler for unmatched routes.
|
||||
|
||||
@@ -21,7 +21,7 @@ export const AppGuard: React.FC<AppGuardProps> = ({ children }) => {
|
||||
const commitMessage = config.app.commitMessage;
|
||||
|
||||
return (
|
||||
<div className="bg-gray-100 dark:bg-gray-950 min-h-screen font-sans text-gray-800 dark:text-gray-200">
|
||||
<div className="bg-slate-50 dark:bg-slate-900 min-h-screen font-sans text-gray-800 dark:text-gray-200 bg-[radial-gradient(ellipse_at_top_right,_var(--tw-gradient-stops))] from-slate-50 via-gray-100 to-slate-100 dark:from-slate-800 dark:via-slate-900 dark:to-black">
|
||||
{/* Toaster component for displaying notifications. It's placed at the top level. */}
|
||||
<Toaster position="top-center" reverseOrder={false} />
|
||||
{/* Add CSS variables for toast theming based on dark mode */}
|
||||
|
||||
378
src/components/FeatureFlag.test.tsx
Normal file
378
src/components/FeatureFlag.test.tsx
Normal file
@@ -0,0 +1,378 @@
|
||||
// src/components/FeatureFlag.test.tsx
|
||||
/**
|
||||
* Unit tests for the FeatureFlag component (ADR-024).
|
||||
*
|
||||
* These tests verify:
|
||||
* - Component renders children when feature is enabled
|
||||
* - Component hides children when feature is disabled
|
||||
* - Component renders fallback when feature is disabled
|
||||
* - Component returns null when disabled and no fallback provided
|
||||
* - All feature flag names are properly handled
|
||||
*/
|
||||
|
||||
import React from 'react';
|
||||
import { render, screen } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
|
||||
// Mock the useFeatureFlag hook
|
||||
const mockUseFeatureFlag = vi.fn();
|
||||
|
||||
vi.mock('../hooks/useFeatureFlag', () => ({
|
||||
useFeatureFlag: (flagName: string) => mockUseFeatureFlag(flagName),
|
||||
}));
|
||||
|
||||
// Import after mocking
|
||||
import { FeatureFlag } from './FeatureFlag';
|
||||
|
||||
describe('FeatureFlag component', () => {
|
||||
beforeEach(() => {
|
||||
mockUseFeatureFlag.mockReset();
|
||||
// Default to disabled
|
||||
mockUseFeatureFlag.mockReturnValue(false);
|
||||
});
|
||||
|
||||
describe('when feature is enabled', () => {
|
||||
beforeEach(() => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
});
|
||||
|
||||
it('should render children', () => {
|
||||
render(
|
||||
<FeatureFlag feature="newDashboard">
|
||||
<div data-testid="new-feature">New Feature Content</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(screen.getByTestId('new-feature')).toBeInTheDocument();
|
||||
expect(screen.getByText('New Feature Content')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should not render fallback', () => {
|
||||
render(
|
||||
<FeatureFlag feature="newDashboard" fallback={<div data-testid="fallback">Fallback</div>}>
|
||||
<div data-testid="new-feature">New Feature</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(screen.getByTestId('new-feature')).toBeInTheDocument();
|
||||
expect(screen.queryByTestId('fallback')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render multiple children', () => {
|
||||
render(
|
||||
<FeatureFlag feature="newDashboard">
|
||||
<div data-testid="child-1">Child 1</div>
|
||||
<div data-testid="child-2">Child 2</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(screen.getByTestId('child-1')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('child-2')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render text content', () => {
|
||||
render(<FeatureFlag feature="newDashboard">Just some text</FeatureFlag>);
|
||||
|
||||
expect(screen.getByText('Just some text')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should call useFeatureFlag with correct flag name', () => {
|
||||
render(
|
||||
<FeatureFlag feature="betaRecipes">
|
||||
<div>Content</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(mockUseFeatureFlag).toHaveBeenCalledWith('betaRecipes');
|
||||
});
|
||||
});
|
||||
|
||||
describe('when feature is disabled', () => {
|
||||
beforeEach(() => {
|
||||
mockUseFeatureFlag.mockReturnValue(false);
|
||||
});
|
||||
|
||||
it('should not render children', () => {
|
||||
render(
|
||||
<FeatureFlag feature="newDashboard">
|
||||
<div data-testid="new-feature">New Feature Content</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(screen.queryByTestId('new-feature')).not.toBeInTheDocument();
|
||||
expect(screen.queryByText('New Feature Content')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render fallback when provided', () => {
|
||||
render(
|
||||
<FeatureFlag
|
||||
feature="newDashboard"
|
||||
fallback={<div data-testid="fallback">Legacy Feature</div>}
|
||||
>
|
||||
<div data-testid="new-feature">New Feature</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(screen.queryByTestId('new-feature')).not.toBeInTheDocument();
|
||||
expect(screen.getByTestId('fallback')).toBeInTheDocument();
|
||||
expect(screen.getByText('Legacy Feature')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render null when no fallback is provided', () => {
|
||||
const { container } = render(
|
||||
<FeatureFlag feature="newDashboard">
|
||||
<div data-testid="new-feature">New Feature</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(screen.queryByTestId('new-feature')).not.toBeInTheDocument();
|
||||
// Container should be empty (just the wrapper)
|
||||
expect(container.innerHTML).toBe('');
|
||||
});
|
||||
|
||||
it('should render complex fallback components', () => {
|
||||
const FallbackComponent = () => (
|
||||
<div data-testid="complex-fallback">
|
||||
<h1>Legacy Dashboard</h1>
|
||||
<p>This is the old version</p>
|
||||
</div>
|
||||
);
|
||||
|
||||
render(
|
||||
<FeatureFlag feature="newDashboard" fallback={<FallbackComponent />}>
|
||||
<div data-testid="new-feature">New Dashboard</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(screen.queryByTestId('new-feature')).not.toBeInTheDocument();
|
||||
expect(screen.getByTestId('complex-fallback')).toBeInTheDocument();
|
||||
expect(screen.getByText('Legacy Dashboard')).toBeInTheDocument();
|
||||
expect(screen.getByText('This is the old version')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render text fallback', () => {
|
||||
render(
|
||||
<FeatureFlag feature="newDashboard" fallback="Feature not available">
|
||||
<div>New Feature</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(screen.getByText('Feature not available')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('with different feature flags', () => {
|
||||
it('should work with newDashboard flag', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
|
||||
render(
|
||||
<FeatureFlag feature="newDashboard">
|
||||
<div data-testid="dashboard">Dashboard</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(mockUseFeatureFlag).toHaveBeenCalledWith('newDashboard');
|
||||
expect(screen.getByTestId('dashboard')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should work with betaRecipes flag', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
|
||||
render(
|
||||
<FeatureFlag feature="betaRecipes">
|
||||
<div data-testid="recipes">Recipes</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(mockUseFeatureFlag).toHaveBeenCalledWith('betaRecipes');
|
||||
expect(screen.getByTestId('recipes')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should work with experimentalAi flag', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
|
||||
render(
|
||||
<FeatureFlag feature="experimentalAi">
|
||||
<div data-testid="ai">AI Feature</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(mockUseFeatureFlag).toHaveBeenCalledWith('experimentalAi');
|
||||
expect(screen.getByTestId('ai')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should work with debugMode flag', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
|
||||
render(
|
||||
<FeatureFlag feature="debugMode">
|
||||
<div data-testid="debug">Debug Panel</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(mockUseFeatureFlag).toHaveBeenCalledWith('debugMode');
|
||||
expect(screen.getByTestId('debug')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('real-world usage patterns', () => {
|
||||
it('should work for A/B testing pattern', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(false);
|
||||
|
||||
render(
|
||||
<FeatureFlag feature="newDashboard" fallback={<div data-testid="old-ui">Old UI</div>}>
|
||||
<div data-testid="new-ui">New UI</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(screen.queryByTestId('new-ui')).not.toBeInTheDocument();
|
||||
expect(screen.getByTestId('old-ui')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should work for gradual rollout pattern', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
|
||||
render(
|
||||
<div>
|
||||
<nav data-testid="nav">Navigation</nav>
|
||||
<FeatureFlag feature="betaRecipes">
|
||||
<aside data-testid="recipe-suggestions">Recipe Suggestions</aside>
|
||||
</FeatureFlag>
|
||||
<main data-testid="main">Main Content</main>
|
||||
</div>,
|
||||
);
|
||||
|
||||
expect(screen.getByTestId('nav')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('recipe-suggestions')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('main')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should work nested within conditional logic', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
const isLoggedIn = true;
|
||||
|
||||
render(
|
||||
<div>
|
||||
{isLoggedIn && (
|
||||
<FeatureFlag
|
||||
feature="experimentalAi"
|
||||
fallback={<div data-testid="standard">Standard</div>}
|
||||
>
|
||||
<div data-testid="ai-search">AI Search</div>
|
||||
</FeatureFlag>
|
||||
)}
|
||||
</div>,
|
||||
);
|
||||
|
||||
expect(screen.getByTestId('ai-search')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should work with multiple FeatureFlag components', () => {
|
||||
// First call for newDashboard returns true
|
||||
// Second call for debugMode returns false
|
||||
mockUseFeatureFlag.mockImplementation((flag: string) => {
|
||||
if (flag === 'newDashboard') return true;
|
||||
if (flag === 'debugMode') return false;
|
||||
return false;
|
||||
});
|
||||
|
||||
render(
|
||||
<div>
|
||||
<FeatureFlag feature="newDashboard">
|
||||
<div data-testid="new-dashboard">New Dashboard</div>
|
||||
</FeatureFlag>
|
||||
<FeatureFlag feature="debugMode" fallback={<div data-testid="no-debug">No Debug</div>}>
|
||||
<div data-testid="debug-panel">Debug Panel</div>
|
||||
</FeatureFlag>
|
||||
</div>,
|
||||
);
|
||||
|
||||
expect(screen.getByTestId('new-dashboard')).toBeInTheDocument();
|
||||
expect(screen.queryByTestId('debug-panel')).not.toBeInTheDocument();
|
||||
expect(screen.getByTestId('no-debug')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('edge cases', () => {
|
||||
it('should handle undefined fallback gracefully', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(false);
|
||||
|
||||
const { container } = render(
|
||||
<FeatureFlag feature="newDashboard" fallback={undefined}>
|
||||
<div data-testid="new-feature">New Feature</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(screen.queryByTestId('new-feature')).not.toBeInTheDocument();
|
||||
expect(container.innerHTML).toBe('');
|
||||
});
|
||||
|
||||
it('should handle null children gracefully when enabled', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
|
||||
const { container } = render(<FeatureFlag feature="newDashboard">{null}</FeatureFlag>);
|
||||
|
||||
// Should render nothing (null)
|
||||
expect(container.innerHTML).toBe('');
|
||||
});
|
||||
|
||||
it('should handle empty children when enabled', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
|
||||
const { container } = render(
|
||||
<FeatureFlag feature="newDashboard">
|
||||
<></>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
// Should render the empty fragment
|
||||
expect(container.innerHTML).toBe('');
|
||||
});
|
||||
|
||||
it('should handle boolean children', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
|
||||
// React ignores boolean children, so nothing should render
|
||||
const { container } = render(
|
||||
<FeatureFlag feature="newDashboard">{true as unknown as React.ReactNode}</FeatureFlag>,
|
||||
);
|
||||
|
||||
expect(container.innerHTML).toBe('');
|
||||
});
|
||||
|
||||
it('should handle number children', () => {
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
|
||||
render(<FeatureFlag feature="newDashboard">{42}</FeatureFlag>);
|
||||
|
||||
expect(screen.getByText('42')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('re-rendering behavior', () => {
|
||||
it('should update when feature flag value changes', () => {
|
||||
const { rerender } = render(
|
||||
<FeatureFlag feature="newDashboard" fallback={<div data-testid="fallback">Fallback</div>}>
|
||||
<div data-testid="new-feature">New Feature</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
// Initially disabled
|
||||
expect(screen.queryByTestId('new-feature')).not.toBeInTheDocument();
|
||||
expect(screen.getByTestId('fallback')).toBeInTheDocument();
|
||||
|
||||
// Enable the flag
|
||||
mockUseFeatureFlag.mockReturnValue(true);
|
||||
|
||||
rerender(
|
||||
<FeatureFlag feature="newDashboard" fallback={<div data-testid="fallback">Fallback</div>}>
|
||||
<div data-testid="new-feature">New Feature</div>
|
||||
</FeatureFlag>,
|
||||
);
|
||||
|
||||
// Now enabled
|
||||
expect(screen.getByTestId('new-feature')).toBeInTheDocument();
|
||||
expect(screen.queryByTestId('fallback')).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
});
|
||||
75
src/components/FeatureFlag.tsx
Normal file
75
src/components/FeatureFlag.tsx
Normal file
@@ -0,0 +1,75 @@
|
||||
// src/components/FeatureFlag.tsx
|
||||
import type { ReactNode } from 'react';
|
||||
import { useFeatureFlag, type FeatureFlagName } from '../hooks/useFeatureFlag';
|
||||
|
||||
/**
|
||||
* Props for the FeatureFlag component.
|
||||
*/
|
||||
export interface FeatureFlagProps {
|
||||
/**
|
||||
* The name of the feature flag to check.
|
||||
* Must be a valid FeatureFlagName defined in config.featureFlags.
|
||||
*/
|
||||
feature: FeatureFlagName;
|
||||
|
||||
/**
|
||||
* Content to render when the feature flag is enabled.
|
||||
*/
|
||||
children: ReactNode;
|
||||
|
||||
/**
|
||||
* Optional content to render when the feature flag is disabled.
|
||||
* If not provided, nothing is rendered when the flag is disabled.
|
||||
* @default null
|
||||
*/
|
||||
fallback?: ReactNode;
|
||||
}
|
||||
|
||||
/**
|
||||
* Declarative component for conditional rendering based on feature flag state.
|
||||
*
|
||||
* This component provides a clean, declarative API for rendering content based
|
||||
* on whether a feature flag is enabled or disabled. It uses the useFeatureFlag
|
||||
* hook internally and supports an optional fallback for disabled features.
|
||||
*
|
||||
* @param props - Component props
|
||||
* @param props.feature - The feature flag name to check
|
||||
* @param props.children - Content rendered when feature is enabled
|
||||
* @param props.fallback - Content rendered when feature is disabled (default: null)
|
||||
*
|
||||
* @example
|
||||
* // Basic usage - show new feature when enabled
|
||||
* <FeatureFlag feature="newDashboard">
|
||||
* <NewDashboard />
|
||||
* </FeatureFlag>
|
||||
*
|
||||
* @example
|
||||
* // With fallback - show alternative when feature is disabled
|
||||
* <FeatureFlag feature="newDashboard" fallback={<LegacyDashboard />}>
|
||||
* <NewDashboard />
|
||||
* </FeatureFlag>
|
||||
*
|
||||
* @example
|
||||
* // Wrap a section of UI that should only appear when flag is enabled
|
||||
* <div className="sidebar">
|
||||
* <Navigation />
|
||||
* <FeatureFlag feature="betaRecipes">
|
||||
* <RecipeSuggestions />
|
||||
* </FeatureFlag>
|
||||
* <Footer />
|
||||
* </div>
|
||||
*
|
||||
* @example
|
||||
* // Combine with other conditional logic
|
||||
* {isLoggedIn && (
|
||||
* <FeatureFlag feature="experimentalAi" fallback={<StandardSearch />}>
|
||||
* <AiPoweredSearch />
|
||||
* </FeatureFlag>
|
||||
* )}
|
||||
*
|
||||
* @see docs/adr/0024-feature-flagging-strategy.md
|
||||
*/
|
||||
export function FeatureFlag({ feature, children, fallback = null }: FeatureFlagProps): ReactNode {
|
||||
const isEnabled = useFeatureFlag(feature);
|
||||
return isEnabled ? children : fallback;
|
||||
}
|
||||
@@ -31,7 +31,7 @@ export const Header: React.FC<HeaderProps> = ({
|
||||
// The state and handlers for the old AuthModal and SignUpModal have been removed.
|
||||
return (
|
||||
<>
|
||||
<header className="bg-white dark:bg-gray-900 shadow-md sticky top-0 z-20 border-b-2 border-brand-primary dark:border-brand-secondary">
|
||||
<header className="bg-white/80 dark:bg-slate-900/80 backdrop-blur-md shadow-sm sticky top-0 z-20 border-b border-gray-200/50 dark:border-gray-700/50 supports-[backdrop-filter]:bg-white/60 dark:supports-[backdrop-filter]:bg-slate-900/60">
|
||||
<div className="max-w-screen-2xl mx-auto px-4 sm:px-6 lg:px-8">
|
||||
<div className="flex items-center justify-between h-16">
|
||||
<div className="flex items-center">
|
||||
|
||||
424
src/components/NotificationBell.test.tsx
Normal file
424
src/components/NotificationBell.test.tsx
Normal file
@@ -0,0 +1,424 @@
|
||||
// src/components/NotificationBell.test.tsx
|
||||
import React from 'react';
|
||||
import { screen, fireEvent, act } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach, afterEach, Mock } from 'vitest';
|
||||
import { NotificationBell, ConnectionStatus } from './NotificationBell';
|
||||
import { renderWithProviders } from '../tests/utils/renderWithProviders';
|
||||
|
||||
// Mock the useWebSocket hook
|
||||
vi.mock('../hooks/useWebSocket', () => ({
|
||||
useWebSocket: vi.fn(),
|
||||
}));
|
||||
|
||||
// Mock the useEventBus hook
|
||||
vi.mock('../hooks/useEventBus', () => ({
|
||||
useEventBus: vi.fn(),
|
||||
}));
|
||||
|
||||
// Import the mocked modules
|
||||
import { useWebSocket } from '../hooks/useWebSocket';
|
||||
import { useEventBus } from '../hooks/useEventBus';
|
||||
|
||||
// Type the mocked functions
|
||||
const mockUseWebSocket = useWebSocket as Mock;
|
||||
const mockUseEventBus = useEventBus as Mock;
|
||||
|
||||
describe('NotificationBell', () => {
|
||||
let eventBusCallback: ((data?: unknown) => void) | null = null;
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
eventBusCallback = null;
|
||||
|
||||
// Default mock: connected state, no error
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: true,
|
||||
error: null,
|
||||
});
|
||||
|
||||
// Capture the callback passed to useEventBus
|
||||
mockUseEventBus.mockImplementation((_event: string, callback: (data?: unknown) => void) => {
|
||||
eventBusCallback = callback;
|
||||
});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe('rendering', () => {
|
||||
it('should render the notification bell button', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
const button = screen.getByRole('button', { name: /notifications/i });
|
||||
expect(button).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render with custom className', () => {
|
||||
renderWithProviders(<NotificationBell className="custom-class" />);
|
||||
|
||||
const container = screen.getByRole('button').parentElement;
|
||||
expect(container).toHaveClass('custom-class');
|
||||
});
|
||||
|
||||
it('should show connection status indicator by default', () => {
|
||||
const { container } = renderWithProviders(<NotificationBell />);
|
||||
|
||||
// The status indicator is a span with inline style containing backgroundColor
|
||||
const statusIndicator = container.querySelector('span[title="Connected"]');
|
||||
expect(statusIndicator).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should hide connection status indicator when showConnectionStatus is false', () => {
|
||||
const { container } = renderWithProviders(<NotificationBell showConnectionStatus={false} />);
|
||||
|
||||
// No status indicator should be present (no span with title Connected/Connecting/Disconnected)
|
||||
const connectedIndicator = container.querySelector('span[title="Connected"]');
|
||||
const connectingIndicator = container.querySelector('span[title="Connecting"]');
|
||||
const disconnectedIndicator = container.querySelector('span[title="Disconnected"]');
|
||||
expect(connectedIndicator).not.toBeInTheDocument();
|
||||
expect(connectingIndicator).not.toBeInTheDocument();
|
||||
expect(disconnectedIndicator).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('unread count badge', () => {
|
||||
it('should not show badge when unread count is zero', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
// The badge displays numbers, check that no number badge exists
|
||||
const badge = screen.queryByText(/^\d+$/);
|
||||
expect(badge).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should show badge with count when notifications arrive', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
// Simulate a notification arriving via event bus
|
||||
expect(eventBusCallback).not.toBeNull();
|
||||
act(() => {
|
||||
eventBusCallback!({ deals: [{ item_name: 'Test' }] });
|
||||
});
|
||||
|
||||
const badge = screen.getByText('1');
|
||||
expect(badge).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should increment count when multiple notifications arrive', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
// Simulate multiple notifications
|
||||
act(() => {
|
||||
eventBusCallback!({ deals: [{ item_name: 'Test 1' }] });
|
||||
eventBusCallback!({ deals: [{ item_name: 'Test 2' }] });
|
||||
eventBusCallback!({ deals: [{ item_name: 'Test 3' }] });
|
||||
});
|
||||
|
||||
const badge = screen.getByText('3');
|
||||
expect(badge).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should display 99+ when count exceeds 99', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
// Simulate 100 notifications
|
||||
act(() => {
|
||||
for (let i = 0; i < 100; i++) {
|
||||
eventBusCallback!({ deals: [{ item_name: `Test ${i}` }] });
|
||||
}
|
||||
});
|
||||
|
||||
const badge = screen.getByText('99+');
|
||||
expect(badge).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should not increment count when notification data is undefined', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
// Simulate a notification with undefined data
|
||||
act(() => {
|
||||
eventBusCallback!(undefined);
|
||||
});
|
||||
|
||||
const badge = screen.queryByText(/^\d+$/);
|
||||
expect(badge).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('click behavior', () => {
|
||||
it('should reset unread count when clicked', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
// First, add some notifications
|
||||
act(() => {
|
||||
eventBusCallback!({ deals: [{ item_name: 'Test' }] });
|
||||
});
|
||||
expect(screen.getByText('1')).toBeInTheDocument();
|
||||
|
||||
// Click the bell
|
||||
const button = screen.getByRole('button');
|
||||
fireEvent.click(button);
|
||||
|
||||
// Badge should no longer show
|
||||
expect(screen.queryByText('1')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should call onClick callback when provided', () => {
|
||||
const mockOnClick = vi.fn();
|
||||
renderWithProviders(<NotificationBell onClick={mockOnClick} />);
|
||||
|
||||
const button = screen.getByRole('button');
|
||||
fireEvent.click(button);
|
||||
|
||||
expect(mockOnClick).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('should handle click without onClick callback', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
const button = screen.getByRole('button');
|
||||
// Should not throw
|
||||
expect(() => fireEvent.click(button)).not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe('connection status', () => {
|
||||
it('should show green indicator when connected', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: true,
|
||||
error: null,
|
||||
});
|
||||
|
||||
const { container } = renderWithProviders(<NotificationBell />);
|
||||
|
||||
const statusIndicator = container.querySelector('span[title="Connected"]');
|
||||
expect(statusIndicator).toBeInTheDocument();
|
||||
expect(statusIndicator).toHaveStyle({ backgroundColor: 'rgb(16, 185, 129)' });
|
||||
});
|
||||
|
||||
it('should show red indicator when error occurs', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: false,
|
||||
error: 'Connection failed',
|
||||
});
|
||||
|
||||
const { container } = renderWithProviders(<NotificationBell />);
|
||||
|
||||
const statusIndicator = container.querySelector('span[title="Disconnected"]');
|
||||
expect(statusIndicator).toBeInTheDocument();
|
||||
expect(statusIndicator).toHaveStyle({ backgroundColor: 'rgb(239, 68, 68)' });
|
||||
});
|
||||
|
||||
it('should show amber indicator when connecting', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: false,
|
||||
error: null,
|
||||
});
|
||||
|
||||
const { container } = renderWithProviders(<NotificationBell />);
|
||||
|
||||
const statusIndicator = container.querySelector('span[title="Connecting"]');
|
||||
expect(statusIndicator).toBeInTheDocument();
|
||||
expect(statusIndicator).toHaveStyle({ backgroundColor: 'rgb(245, 158, 11)' });
|
||||
});
|
||||
|
||||
it('should show error tooltip when disconnected with error', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: false,
|
||||
error: 'Connection failed',
|
||||
});
|
||||
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
expect(screen.getByText('Live notifications unavailable')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should not show error tooltip when connected', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: true,
|
||||
error: null,
|
||||
});
|
||||
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
expect(screen.queryByText('Live notifications unavailable')).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('aria attributes', () => {
|
||||
it('should have correct aria-label without unread notifications', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
const button = screen.getByRole('button');
|
||||
expect(button).toHaveAttribute('aria-label', 'Notifications');
|
||||
});
|
||||
|
||||
it('should have correct aria-label with unread notifications', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
act(() => {
|
||||
eventBusCallback!({ deals: [{ item_name: 'Test' }] });
|
||||
eventBusCallback!({ deals: [{ item_name: 'Test2' }] });
|
||||
});
|
||||
|
||||
const button = screen.getByRole('button');
|
||||
expect(button).toHaveAttribute('aria-label', 'Notifications (2 unread)');
|
||||
});
|
||||
|
||||
it('should have correct title when connected', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: true,
|
||||
error: null,
|
||||
});
|
||||
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
const button = screen.getByRole('button');
|
||||
expect(button).toHaveAttribute('title', 'Connected to live notifications');
|
||||
});
|
||||
|
||||
it('should have correct title when connecting', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: false,
|
||||
error: null,
|
||||
});
|
||||
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
const button = screen.getByRole('button');
|
||||
expect(button).toHaveAttribute('title', 'Connecting...');
|
||||
});
|
||||
|
||||
it('should have correct title when error occurs', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: false,
|
||||
error: 'Network error',
|
||||
});
|
||||
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
const button = screen.getByRole('button');
|
||||
expect(button).toHaveAttribute('title', 'WebSocket error: Network error');
|
||||
});
|
||||
});
|
||||
|
||||
describe('bell icon styling', () => {
|
||||
it('should have default color when no unread notifications', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
const button = screen.getByRole('button');
|
||||
const svg = button.querySelector('svg');
|
||||
expect(svg).toHaveClass('text-gray-600');
|
||||
});
|
||||
|
||||
it('should have highlighted color when there are unread notifications', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
act(() => {
|
||||
eventBusCallback!({ deals: [{ item_name: 'Test' }] });
|
||||
});
|
||||
|
||||
const button = screen.getByRole('button');
|
||||
const svg = button.querySelector('svg');
|
||||
expect(svg).toHaveClass('text-blue-600');
|
||||
});
|
||||
});
|
||||
|
||||
describe('event bus subscription', () => {
|
||||
it('should subscribe to notification:deal event', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
expect(mockUseEventBus).toHaveBeenCalledWith('notification:deal', expect.any(Function));
|
||||
});
|
||||
});
|
||||
|
||||
describe('useWebSocket configuration', () => {
|
||||
it('should call useWebSocket with autoConnect: true', () => {
|
||||
renderWithProviders(<NotificationBell />);
|
||||
|
||||
expect(mockUseWebSocket).toHaveBeenCalledWith({ autoConnect: true });
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('ConnectionStatus', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
it('should show "Live" text when connected', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: true,
|
||||
error: null,
|
||||
});
|
||||
|
||||
renderWithProviders(<ConnectionStatus />);
|
||||
|
||||
expect(screen.getByText('Live')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should show "Offline" text when disconnected with error', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: false,
|
||||
error: 'Connection failed',
|
||||
});
|
||||
|
||||
renderWithProviders(<ConnectionStatus />);
|
||||
|
||||
expect(screen.getByText('Offline')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should show "Connecting..." text when connecting', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: false,
|
||||
error: null,
|
||||
});
|
||||
|
||||
renderWithProviders(<ConnectionStatus />);
|
||||
|
||||
expect(screen.getByText('Connecting...')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should call useWebSocket with autoConnect: true', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: true,
|
||||
error: null,
|
||||
});
|
||||
|
||||
renderWithProviders(<ConnectionStatus />);
|
||||
|
||||
expect(mockUseWebSocket).toHaveBeenCalledWith({ autoConnect: true });
|
||||
});
|
||||
|
||||
it('should render Wifi icon when connected', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: true,
|
||||
error: null,
|
||||
});
|
||||
|
||||
renderWithProviders(<ConnectionStatus />);
|
||||
|
||||
const container = screen.getByText('Live').parentElement;
|
||||
const svg = container?.querySelector('svg');
|
||||
expect(svg).toBeInTheDocument();
|
||||
expect(svg).toHaveClass('text-green-600');
|
||||
});
|
||||
|
||||
it('should render WifiOff icon when disconnected', () => {
|
||||
mockUseWebSocket.mockReturnValue({
|
||||
isConnected: false,
|
||||
error: 'Connection failed',
|
||||
});
|
||||
|
||||
renderWithProviders(<ConnectionStatus />);
|
||||
|
||||
const container = screen.getByText('Offline').parentElement;
|
||||
const svg = container?.querySelector('svg');
|
||||
expect(svg).toBeInTheDocument();
|
||||
expect(svg).toHaveClass('text-red-600');
|
||||
});
|
||||
});
|
||||
776
src/components/NotificationToastHandler.test.tsx
Normal file
776
src/components/NotificationToastHandler.test.tsx
Normal file
@@ -0,0 +1,776 @@
|
||||
// src/components/NotificationToastHandler.test.tsx
|
||||
import React from 'react';
|
||||
import { render, act } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach, afterEach, Mock } from 'vitest';
|
||||
import { NotificationToastHandler } from './NotificationToastHandler';
|
||||
import type { DealNotificationData, SystemMessageData } from '../types/websocket';
|
||||
|
||||
// Use vi.hoisted to properly hoist mock functions
|
||||
const { mockToastSuccess, mockToastError, mockToastDefault } = vi.hoisted(() => ({
|
||||
mockToastSuccess: vi.fn(),
|
||||
mockToastError: vi.fn(),
|
||||
mockToastDefault: vi.fn(),
|
||||
}));
|
||||
|
||||
// Mock react-hot-toast
|
||||
vi.mock('react-hot-toast', () => {
|
||||
const toastFn = (message: string, options?: unknown) => mockToastDefault(message, options);
|
||||
toastFn.success = mockToastSuccess;
|
||||
toastFn.error = mockToastError;
|
||||
return {
|
||||
default: toastFn,
|
||||
};
|
||||
});
|
||||
|
||||
// Mock useWebSocket hook
|
||||
vi.mock('../hooks/useWebSocket', () => ({
|
||||
useWebSocket: vi.fn(),
|
||||
}));
|
||||
|
||||
// Mock useEventBus hook
|
||||
vi.mock('../hooks/useEventBus', () => ({
|
||||
useEventBus: vi.fn(),
|
||||
}));
|
||||
|
||||
// Mock formatCurrency
|
||||
vi.mock('../utils/formatUtils', () => ({
|
||||
formatCurrency: vi.fn((cents: number) => `$${(cents / 100).toFixed(2)}`),
|
||||
}));
|
||||
|
||||
// Import mocked modules
|
||||
import { useWebSocket } from '../hooks/useWebSocket';
|
||||
import { useEventBus } from '../hooks/useEventBus';
|
||||
|
||||
const mockUseWebSocket = useWebSocket as Mock;
|
||||
const mockUseEventBus = useEventBus as Mock;
|
||||
|
||||
describe('NotificationToastHandler', () => {
|
||||
let eventBusCallbacks: Map<string, (data?: unknown) => void>;
|
||||
let onConnectCallback: (() => void) | undefined;
|
||||
let onDisconnectCallback: (() => void) | undefined;
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
vi.useFakeTimers();
|
||||
|
||||
// Clear toast mocks
|
||||
mockToastSuccess.mockClear();
|
||||
mockToastError.mockClear();
|
||||
mockToastDefault.mockClear();
|
||||
|
||||
eventBusCallbacks = new Map();
|
||||
onConnectCallback = undefined;
|
||||
onDisconnectCallback = undefined;
|
||||
|
||||
// Default mock implementation for useWebSocket
|
||||
mockUseWebSocket.mockImplementation(
|
||||
(options: { onConnect?: () => void; onDisconnect?: () => void }) => {
|
||||
onConnectCallback = options?.onConnect;
|
||||
onDisconnectCallback = options?.onDisconnect;
|
||||
return {
|
||||
isConnected: true,
|
||||
error: null,
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
// Capture callbacks for different event types
|
||||
mockUseEventBus.mockImplementation((event: string, callback: (data?: unknown) => void) => {
|
||||
eventBusCallbacks.set(event, callback);
|
||||
});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.useRealTimers();
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe('rendering', () => {
|
||||
it('should render null (no visible output)', () => {
|
||||
const { container } = render(<NotificationToastHandler />);
|
||||
expect(container.firstChild).toBeNull();
|
||||
});
|
||||
|
||||
it('should subscribe to event bus on mount', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
expect(mockUseEventBus).toHaveBeenCalledWith('notification:deal', expect.any(Function));
|
||||
expect(mockUseEventBus).toHaveBeenCalledWith('notification:system', expect.any(Function));
|
||||
expect(mockUseEventBus).toHaveBeenCalledWith('notification:error', expect.any(Function));
|
||||
});
|
||||
});
|
||||
|
||||
describe('connection events', () => {
|
||||
it('should show success toast on connect when enabled', () => {
|
||||
render(<NotificationToastHandler enabled={true} />);
|
||||
|
||||
// Trigger onConnect callback
|
||||
onConnectCallback?.();
|
||||
|
||||
expect(mockToastSuccess).toHaveBeenCalledWith(
|
||||
'Connected to live notifications',
|
||||
expect.objectContaining({
|
||||
duration: 2000,
|
||||
icon: expect.any(String),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not show success toast on connect when disabled', () => {
|
||||
render(<NotificationToastHandler enabled={false} />);
|
||||
|
||||
onConnectCallback?.();
|
||||
|
||||
expect(mockToastSuccess).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should show error toast on disconnect when error exists', () => {
|
||||
mockUseWebSocket.mockImplementation(
|
||||
(options: { onConnect?: () => void; onDisconnect?: () => void }) => {
|
||||
onConnectCallback = options?.onConnect;
|
||||
onDisconnectCallback = options?.onDisconnect;
|
||||
return {
|
||||
isConnected: false,
|
||||
error: 'Connection lost',
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
render(<NotificationToastHandler enabled={true} />);
|
||||
|
||||
onDisconnectCallback?.();
|
||||
|
||||
expect(mockToastError).toHaveBeenCalledWith(
|
||||
'Disconnected from live notifications',
|
||||
expect.objectContaining({
|
||||
duration: 3000,
|
||||
icon: expect.any(String),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not show disconnect toast when disabled', () => {
|
||||
mockUseWebSocket.mockImplementation(
|
||||
(options: { onConnect?: () => void; onDisconnect?: () => void }) => {
|
||||
onConnectCallback = options?.onConnect;
|
||||
onDisconnectCallback = options?.onDisconnect;
|
||||
return {
|
||||
isConnected: false,
|
||||
error: 'Connection lost',
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
render(<NotificationToastHandler enabled={false} />);
|
||||
|
||||
onDisconnectCallback?.();
|
||||
|
||||
expect(mockToastError).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not show disconnect toast when no error', () => {
|
||||
mockUseWebSocket.mockImplementation(
|
||||
(options: { onConnect?: () => void; onDisconnect?: () => void }) => {
|
||||
onConnectCallback = options?.onConnect;
|
||||
onDisconnectCallback = options?.onDisconnect;
|
||||
return {
|
||||
isConnected: false,
|
||||
error: null,
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
render(<NotificationToastHandler enabled={true} />);
|
||||
|
||||
onDisconnectCallback?.();
|
||||
|
||||
expect(mockToastError).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('deal notifications', () => {
|
||||
it('should show toast for single deal notification', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const dealData: DealNotificationData = {
|
||||
deals: [
|
||||
{
|
||||
item_name: 'Milk',
|
||||
best_price_in_cents: 399,
|
||||
store_name: 'Test Store',
|
||||
store_id: 1,
|
||||
},
|
||||
],
|
||||
user_id: 'user-123',
|
||||
message: 'New deal found',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
callback?.(dealData);
|
||||
|
||||
expect(mockToastSuccess).toHaveBeenCalledWith(
|
||||
expect.anything(),
|
||||
expect.objectContaining({
|
||||
duration: 5000,
|
||||
icon: expect.any(String),
|
||||
position: 'top-right',
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should show toast for multiple deals notification', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const dealData: DealNotificationData = {
|
||||
deals: [
|
||||
{
|
||||
item_name: 'Milk',
|
||||
best_price_in_cents: 399,
|
||||
store_name: 'Store A',
|
||||
store_id: 1,
|
||||
},
|
||||
{
|
||||
item_name: 'Bread',
|
||||
best_price_in_cents: 299,
|
||||
store_name: 'Store B',
|
||||
store_id: 2,
|
||||
},
|
||||
{
|
||||
item_name: 'Eggs',
|
||||
best_price_in_cents: 499,
|
||||
store_name: 'Store C',
|
||||
store_id: 3,
|
||||
},
|
||||
],
|
||||
user_id: 'user-123',
|
||||
message: 'Multiple deals found',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
callback?.(dealData);
|
||||
|
||||
expect(mockToastSuccess).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not show toast when disabled', () => {
|
||||
render(<NotificationToastHandler enabled={false} />);
|
||||
|
||||
const dealData: DealNotificationData = {
|
||||
deals: [
|
||||
{
|
||||
item_name: 'Milk',
|
||||
best_price_in_cents: 399,
|
||||
store_name: 'Test Store',
|
||||
store_id: 1,
|
||||
},
|
||||
],
|
||||
user_id: 'user-123',
|
||||
message: 'New deal found',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
callback?.(dealData);
|
||||
|
||||
expect(mockToastSuccess).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not show toast when data is undefined', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
callback?.(undefined);
|
||||
|
||||
expect(mockToastSuccess).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('system messages', () => {
|
||||
it('should show error toast for error severity', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const systemData: SystemMessageData = {
|
||||
message: 'System error occurred',
|
||||
severity: 'error',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:system');
|
||||
callback?.(systemData);
|
||||
|
||||
expect(mockToastError).toHaveBeenCalledWith(
|
||||
'System error occurred',
|
||||
expect.objectContaining({
|
||||
duration: 6000,
|
||||
position: 'top-center',
|
||||
icon: expect.any(String),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should show warning toast for warning severity', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const systemData: SystemMessageData = {
|
||||
message: 'System warning',
|
||||
severity: 'warning',
|
||||
};
|
||||
|
||||
// For warning, the default toast() is called
|
||||
const callback = eventBusCallbacks.get('notification:system');
|
||||
callback?.(systemData);
|
||||
|
||||
// Warning uses the regular toast function (mockToastDefault)
|
||||
expect(mockToastDefault).toHaveBeenCalledWith(
|
||||
'System warning',
|
||||
expect.objectContaining({
|
||||
duration: 4000,
|
||||
position: 'top-center',
|
||||
icon: expect.any(String),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should show info toast for info severity', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const systemData: SystemMessageData = {
|
||||
message: 'System info',
|
||||
severity: 'info',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:system');
|
||||
callback?.(systemData);
|
||||
|
||||
// Info uses the regular toast function (mockToastDefault)
|
||||
expect(mockToastDefault).toHaveBeenCalledWith(
|
||||
'System info',
|
||||
expect.objectContaining({
|
||||
duration: 4000,
|
||||
position: 'top-center',
|
||||
icon: expect.any(String),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not show toast when disabled', () => {
|
||||
render(<NotificationToastHandler enabled={false} />);
|
||||
|
||||
const systemData: SystemMessageData = {
|
||||
message: 'System error',
|
||||
severity: 'error',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:system');
|
||||
callback?.(systemData);
|
||||
|
||||
expect(mockToastError).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not show toast when data is undefined', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:system');
|
||||
callback?.(undefined);
|
||||
|
||||
expect(mockToastError).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('error notifications', () => {
|
||||
it('should show error toast with message and code', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const errorData = {
|
||||
message: 'Something went wrong',
|
||||
code: 'ERR_001',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:error');
|
||||
callback?.(errorData);
|
||||
|
||||
expect(mockToastError).toHaveBeenCalledWith(
|
||||
'Error: Something went wrong',
|
||||
expect.objectContaining({
|
||||
duration: 5000,
|
||||
icon: expect.any(String),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should show error toast without code', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const errorData = {
|
||||
message: 'Something went wrong',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:error');
|
||||
callback?.(errorData);
|
||||
|
||||
expect(mockToastError).toHaveBeenCalledWith(
|
||||
'Error: Something went wrong',
|
||||
expect.objectContaining({
|
||||
duration: 5000,
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not show toast when disabled', () => {
|
||||
render(<NotificationToastHandler enabled={false} />);
|
||||
|
||||
const errorData = {
|
||||
message: 'Something went wrong',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:error');
|
||||
callback?.(errorData);
|
||||
|
||||
expect(mockToastError).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not show toast when data is undefined', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:error');
|
||||
callback?.(undefined);
|
||||
|
||||
expect(mockToastError).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('sound playback', () => {
|
||||
it('should not play sound by default', () => {
|
||||
const audioPlayMock = vi.fn().mockResolvedValue(undefined);
|
||||
const AudioMock = vi.fn().mockImplementation(() => ({
|
||||
play: audioPlayMock,
|
||||
volume: 0,
|
||||
}));
|
||||
vi.stubGlobal('Audio', AudioMock);
|
||||
|
||||
render(<NotificationToastHandler playSound={false} />);
|
||||
|
||||
const dealData: DealNotificationData = {
|
||||
deals: [
|
||||
{
|
||||
item_name: 'Milk',
|
||||
best_price_in_cents: 399,
|
||||
store_name: 'Test Store',
|
||||
store_id: 1,
|
||||
},
|
||||
],
|
||||
user_id: 'user-123',
|
||||
message: 'New deal',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
callback?.(dealData);
|
||||
|
||||
expect(AudioMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should create Audio instance when playSound is true', () => {
|
||||
const audioPlayMock = vi.fn().mockResolvedValue(undefined);
|
||||
const AudioMock = vi.fn().mockImplementation(() => ({
|
||||
play: audioPlayMock,
|
||||
volume: 0,
|
||||
}));
|
||||
vi.stubGlobal('Audio', AudioMock);
|
||||
|
||||
render(<NotificationToastHandler playSound={true} />);
|
||||
|
||||
const dealData: DealNotificationData = {
|
||||
deals: [
|
||||
{
|
||||
item_name: 'Milk',
|
||||
best_price_in_cents: 399,
|
||||
store_name: 'Test Store',
|
||||
store_id: 1,
|
||||
},
|
||||
],
|
||||
user_id: 'user-123',
|
||||
message: 'New deal',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
callback?.(dealData);
|
||||
|
||||
// Verify Audio constructor was called with correct URL
|
||||
expect(AudioMock).toHaveBeenCalledWith('/notification-sound.mp3');
|
||||
});
|
||||
|
||||
it('should use custom sound URL', () => {
|
||||
const audioPlayMock = vi.fn().mockResolvedValue(undefined);
|
||||
const AudioMock = vi.fn().mockImplementation(() => ({
|
||||
play: audioPlayMock,
|
||||
volume: 0,
|
||||
}));
|
||||
vi.stubGlobal('Audio', AudioMock);
|
||||
|
||||
render(<NotificationToastHandler playSound={true} soundUrl="/custom-sound.mp3" />);
|
||||
|
||||
const dealData: DealNotificationData = {
|
||||
deals: [
|
||||
{
|
||||
item_name: 'Milk',
|
||||
best_price_in_cents: 399,
|
||||
store_name: 'Test Store',
|
||||
store_id: 1,
|
||||
},
|
||||
],
|
||||
user_id: 'user-123',
|
||||
message: 'New deal',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
callback?.(dealData);
|
||||
|
||||
expect(AudioMock).toHaveBeenCalledWith('/custom-sound.mp3');
|
||||
});
|
||||
|
||||
it('should handle audio play failure gracefully', () => {
|
||||
vi.spyOn(console, 'warn').mockImplementation(() => {});
|
||||
const audioPlayMock = vi.fn().mockRejectedValue(new Error('Autoplay blocked'));
|
||||
const AudioMock = vi.fn().mockImplementation(() => ({
|
||||
play: audioPlayMock,
|
||||
volume: 0,
|
||||
}));
|
||||
vi.stubGlobal('Audio', AudioMock);
|
||||
|
||||
render(<NotificationToastHandler playSound={true} />);
|
||||
|
||||
const dealData: DealNotificationData = {
|
||||
deals: [
|
||||
{
|
||||
item_name: 'Milk',
|
||||
best_price_in_cents: 399,
|
||||
store_name: 'Test Store',
|
||||
store_id: 1,
|
||||
},
|
||||
],
|
||||
user_id: 'user-123',
|
||||
message: 'New deal',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
// Should not throw even if play() fails
|
||||
expect(() => callback?.(dealData)).not.toThrow();
|
||||
// Audio constructor should still be called
|
||||
expect(AudioMock).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should handle Audio constructor failure gracefully', () => {
|
||||
vi.spyOn(console, 'warn').mockImplementation(() => {});
|
||||
const AudioMock = vi.fn().mockImplementation(() => {
|
||||
throw new Error('Audio not supported');
|
||||
});
|
||||
vi.stubGlobal('Audio', AudioMock);
|
||||
|
||||
render(<NotificationToastHandler playSound={true} />);
|
||||
|
||||
const dealData: DealNotificationData = {
|
||||
deals: [
|
||||
{
|
||||
item_name: 'Milk',
|
||||
best_price_in_cents: 399,
|
||||
store_name: 'Test Store',
|
||||
store_id: 1,
|
||||
},
|
||||
],
|
||||
user_id: 'user-123',
|
||||
message: 'New deal',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
// Should not throw
|
||||
expect(() => callback?.(dealData)).not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe('persistent connection error', () => {
|
||||
it('should show error toast after delay when connection error persists', () => {
|
||||
mockUseWebSocket.mockImplementation(
|
||||
(options: { onConnect?: () => void; onDisconnect?: () => void }) => {
|
||||
onConnectCallback = options?.onConnect;
|
||||
onDisconnectCallback = options?.onDisconnect;
|
||||
return {
|
||||
isConnected: false,
|
||||
error: 'Connection failed',
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
render(<NotificationToastHandler enabled={true} />);
|
||||
|
||||
// Fast-forward 5 seconds
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(5000);
|
||||
});
|
||||
|
||||
expect(mockToastError).toHaveBeenCalledWith(
|
||||
'Unable to connect to live notifications. Some features may be limited.',
|
||||
expect.objectContaining({
|
||||
duration: 5000,
|
||||
icon: expect.any(String),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not show error toast before delay', () => {
|
||||
mockUseWebSocket.mockImplementation(
|
||||
(options: { onConnect?: () => void; onDisconnect?: () => void }) => {
|
||||
onConnectCallback = options?.onConnect;
|
||||
onDisconnectCallback = options?.onDisconnect;
|
||||
return {
|
||||
isConnected: false,
|
||||
error: 'Connection failed',
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
render(<NotificationToastHandler enabled={true} />);
|
||||
|
||||
// Advance only 4 seconds
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(4000);
|
||||
});
|
||||
|
||||
expect(mockToastError).not.toHaveBeenCalledWith(
|
||||
expect.stringContaining('Unable to connect'),
|
||||
expect.anything(),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not show persistent error toast when disabled', () => {
|
||||
mockUseWebSocket.mockImplementation(
|
||||
(options: { onConnect?: () => void; onDisconnect?: () => void }) => {
|
||||
onConnectCallback = options?.onConnect;
|
||||
onDisconnectCallback = options?.onDisconnect;
|
||||
return {
|
||||
isConnected: false,
|
||||
error: 'Connection failed',
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
render(<NotificationToastHandler enabled={false} />);
|
||||
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(5000);
|
||||
});
|
||||
|
||||
expect(mockToastError).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should clear timeout on unmount', () => {
|
||||
mockUseWebSocket.mockImplementation(
|
||||
(options: { onConnect?: () => void; onDisconnect?: () => void }) => {
|
||||
onConnectCallback = options?.onConnect;
|
||||
onDisconnectCallback = options?.onDisconnect;
|
||||
return {
|
||||
isConnected: false,
|
||||
error: 'Connection failed',
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
const { unmount } = render(<NotificationToastHandler enabled={true} />);
|
||||
|
||||
// Unmount before timer fires
|
||||
unmount();
|
||||
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(5000);
|
||||
});
|
||||
|
||||
// The toast should not be called because component unmounted
|
||||
expect(mockToastError).not.toHaveBeenCalledWith(
|
||||
expect.stringContaining('Unable to connect'),
|
||||
expect.anything(),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not show persistent error toast when there is no error', () => {
|
||||
mockUseWebSocket.mockImplementation(
|
||||
(options: { onConnect?: () => void; onDisconnect?: () => void }) => {
|
||||
onConnectCallback = options?.onConnect;
|
||||
onDisconnectCallback = options?.onDisconnect;
|
||||
return {
|
||||
isConnected: false,
|
||||
error: null,
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
render(<NotificationToastHandler enabled={true} />);
|
||||
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(5000);
|
||||
});
|
||||
|
||||
expect(mockToastError).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('default props', () => {
|
||||
it('should default enabled to true', () => {
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
onConnectCallback?.();
|
||||
|
||||
expect(mockToastSuccess).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should default playSound to false', () => {
|
||||
const AudioMock = vi.fn();
|
||||
vi.stubGlobal('Audio', AudioMock);
|
||||
|
||||
render(<NotificationToastHandler />);
|
||||
|
||||
const dealData: DealNotificationData = {
|
||||
deals: [
|
||||
{
|
||||
item_name: 'Milk',
|
||||
best_price_in_cents: 399,
|
||||
store_name: 'Test Store',
|
||||
store_id: 1,
|
||||
},
|
||||
],
|
||||
user_id: 'user-123',
|
||||
message: 'New deal',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
callback?.(dealData);
|
||||
|
||||
expect(AudioMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should default soundUrl to /notification-sound.mp3', () => {
|
||||
const audioPlayMock = vi.fn().mockResolvedValue(undefined);
|
||||
const AudioMock = vi.fn().mockImplementation(() => ({
|
||||
play: audioPlayMock,
|
||||
volume: 0,
|
||||
}));
|
||||
vi.stubGlobal('Audio', AudioMock);
|
||||
|
||||
render(<NotificationToastHandler playSound={true} />);
|
||||
|
||||
const dealData: DealNotificationData = {
|
||||
deals: [
|
||||
{
|
||||
item_name: 'Milk',
|
||||
best_price_in_cents: 399,
|
||||
store_name: 'Test Store',
|
||||
store_id: 1,
|
||||
},
|
||||
],
|
||||
user_id: 'user-123',
|
||||
message: 'New deal',
|
||||
};
|
||||
|
||||
const callback = eventBusCallbacks.get('notification:deal');
|
||||
callback?.(dealData);
|
||||
|
||||
expect(AudioMock).toHaveBeenCalledWith('/notification-sound.mp3');
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -24,6 +24,28 @@ const config = {
|
||||
debug: import.meta.env.VITE_SENTRY_DEBUG === 'true',
|
||||
enabled: import.meta.env.VITE_SENTRY_ENABLED !== 'false',
|
||||
},
|
||||
/**
|
||||
* Feature flags for conditional feature rendering (ADR-024).
|
||||
*
|
||||
* All flags default to false (disabled) when the environment variable is not set
|
||||
* or is set to any value other than 'true'. This opt-in model ensures features
|
||||
* are explicitly enabled, preventing accidental exposure of incomplete features.
|
||||
*
|
||||
* Environment variables follow the naming convention: VITE_FEATURE_SNAKE_CASE
|
||||
* Config properties use camelCase for consistency with JavaScript conventions.
|
||||
*
|
||||
* @see docs/adr/0024-feature-flagging-strategy.md
|
||||
*/
|
||||
featureFlags: {
|
||||
/** Enable the redesigned dashboard UI (VITE_FEATURE_NEW_DASHBOARD) */
|
||||
newDashboard: import.meta.env.VITE_FEATURE_NEW_DASHBOARD === 'true',
|
||||
/** Enable beta recipe features (VITE_FEATURE_BETA_RECIPES) */
|
||||
betaRecipes: import.meta.env.VITE_FEATURE_BETA_RECIPES === 'true',
|
||||
/** Enable experimental AI features (VITE_FEATURE_EXPERIMENTAL_AI) */
|
||||
experimentalAi: import.meta.env.VITE_FEATURE_EXPERIMENTAL_AI === 'true',
|
||||
/** Enable debug mode UI elements (VITE_FEATURE_DEBUG_MODE) */
|
||||
debugMode: import.meta.env.VITE_FEATURE_DEBUG_MODE === 'true',
|
||||
},
|
||||
};
|
||||
|
||||
export default config;
|
||||
|
||||
183
src/config/apiVersions.ts
Normal file
183
src/config/apiVersions.ts
Normal file
@@ -0,0 +1,183 @@
|
||||
// src/config/apiVersions.ts
|
||||
/**
|
||||
* @file API version constants, types, and configuration.
|
||||
* Implements ADR-008 Phase 2: API Versioning Infrastructure.
|
||||
*
|
||||
* This module provides centralized version definitions used by:
|
||||
* - Version detection middleware (apiVersion.middleware.ts)
|
||||
* - Deprecation headers middleware (deprecation.middleware.ts)
|
||||
* - Versioned router factory (versioned.ts)
|
||||
*
|
||||
* @see docs/architecture/api-versioning-infrastructure.md
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import {
|
||||
* CURRENT_API_VERSION,
|
||||
* VERSION_CONFIGS,
|
||||
* isValidApiVersion,
|
||||
* } from './apiVersions';
|
||||
*
|
||||
* // Check if a version is supported
|
||||
* if (isValidApiVersion('v1')) {
|
||||
* const config = VERSION_CONFIGS.v1;
|
||||
* console.log(`v1 status: ${config.status}`);
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
|
||||
// --- Type Definitions ---
|
||||
|
||||
/**
|
||||
* All API versions as a const tuple for type derivation.
|
||||
* Add new versions here when introducing them.
|
||||
*/
|
||||
export const API_VERSIONS = ['v1', 'v2'] as const;
|
||||
|
||||
/**
|
||||
* Union type of supported API versions.
|
||||
* Currently: 'v1' | 'v2'
|
||||
*/
|
||||
export type ApiVersion = (typeof API_VERSIONS)[number];
|
||||
|
||||
/**
|
||||
* Version lifecycle status.
|
||||
* - 'active': Version is fully supported and recommended
|
||||
* - 'deprecated': Version works but clients should migrate (deprecation headers sent)
|
||||
* - 'sunset': Version is scheduled for removal or already removed
|
||||
*/
|
||||
export type VersionStatus = 'active' | 'deprecated' | 'sunset';
|
||||
|
||||
/**
|
||||
* Deprecation information for an API version.
|
||||
* Follows RFC 8594 (Sunset Header) and draft-ietf-httpapi-deprecation-header.
|
||||
*
|
||||
* Used by deprecation middleware to set appropriate HTTP headers:
|
||||
* - `Deprecation: true` (draft-ietf-httpapi-deprecation-header)
|
||||
* - `Sunset: <date>` (RFC 8594)
|
||||
* - `Link: <url>; rel="successor-version"` (RFC 8288)
|
||||
*/
|
||||
export interface VersionDeprecation {
|
||||
/** Indicates if this version is deprecated (maps to Deprecation header) */
|
||||
deprecated: boolean;
|
||||
/** ISO 8601 date string when the version will be sunset (maps to Sunset header) */
|
||||
sunsetDate?: string;
|
||||
/** The version clients should migrate to (maps to Link rel="successor-version") */
|
||||
successorVersion?: ApiVersion;
|
||||
/** Human-readable message explaining the deprecation (for documentation/logs) */
|
||||
message?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Complete configuration for an API version.
|
||||
* Combines version identifier, lifecycle status, and deprecation details.
|
||||
*/
|
||||
export interface VersionConfig {
|
||||
/** The version identifier (e.g., 'v1') */
|
||||
version: ApiVersion;
|
||||
/** Current lifecycle status of this version */
|
||||
status: VersionStatus;
|
||||
/** ISO 8601 date when the version will be sunset (RFC 8594) - convenience field */
|
||||
sunsetDate?: string;
|
||||
/** The version clients should migrate to - convenience field */
|
||||
successorVersion?: ApiVersion;
|
||||
}
|
||||
|
||||
// --- Constants ---
|
||||
|
||||
/**
|
||||
* The current/latest stable API version.
|
||||
* New clients should use this version.
|
||||
*/
|
||||
export const CURRENT_API_VERSION: ApiVersion = 'v1';
|
||||
|
||||
/**
|
||||
* The default API version for requests without explicit version.
|
||||
* Used when version cannot be detected from the request path.
|
||||
*/
|
||||
export const DEFAULT_VERSION: ApiVersion = 'v1';
|
||||
|
||||
/**
|
||||
* Array of all supported API versions.
|
||||
* Used for validation and enumeration.
|
||||
*/
|
||||
export const SUPPORTED_VERSIONS: readonly ApiVersion[] = API_VERSIONS;
|
||||
|
||||
/**
|
||||
* Configuration map for all API versions.
|
||||
* Provides lifecycle status and deprecation information for each version.
|
||||
*
|
||||
* To mark v1 as deprecated (example for future use):
|
||||
* @example
|
||||
* ```typescript
|
||||
* VERSION_CONFIGS.v1 = {
|
||||
* version: 'v1',
|
||||
* status: 'deprecated',
|
||||
* sunsetDate: '2027-01-01T00:00:00Z',
|
||||
* successorVersion: 'v2',
|
||||
* };
|
||||
* ```
|
||||
*/
|
||||
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
|
||||
v1: {
|
||||
version: 'v1',
|
||||
status: 'active',
|
||||
// No deprecation info - v1 is the current active version
|
||||
},
|
||||
v2: {
|
||||
version: 'v2',
|
||||
status: 'active',
|
||||
// v2 is defined for infrastructure readiness but not yet implemented
|
||||
},
|
||||
};
|
||||
|
||||
// --- Utility Functions ---
|
||||
|
||||
/**
|
||||
* Type guard to check if a string is a valid ApiVersion.
|
||||
*
|
||||
* @param value - The string to check
|
||||
* @returns True if the string is a valid API version
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const userInput = 'v1';
|
||||
* if (isValidApiVersion(userInput)) {
|
||||
* // userInput is now typed as ApiVersion
|
||||
* const config = VERSION_CONFIGS[userInput];
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export function isValidApiVersion(value: string): value is ApiVersion {
|
||||
return API_VERSIONS.includes(value as ApiVersion);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a version is deprecated.
|
||||
*
|
||||
* @param version - The API version to check
|
||||
* @returns True if the version status is 'deprecated'
|
||||
*/
|
||||
export function isVersionDeprecated(version: ApiVersion): boolean {
|
||||
return VERSION_CONFIGS[version].status === 'deprecated';
|
||||
}
|
||||
|
||||
/**
|
||||
* Get deprecation information for a version.
|
||||
* Constructs a VersionDeprecation object from the version config.
|
||||
*
|
||||
* @param version - The API version to get deprecation info for
|
||||
* @returns VersionDeprecation object with current deprecation state
|
||||
*/
|
||||
export function getVersionDeprecation(version: ApiVersion): VersionDeprecation {
|
||||
const config = VERSION_CONFIGS[version];
|
||||
return {
|
||||
deprecated: config.status === 'deprecated',
|
||||
sunsetDate: config.sunsetDate,
|
||||
successorVersion: config.successorVersion,
|
||||
message:
|
||||
config.status === 'deprecated'
|
||||
? `API ${version} is deprecated${config.sunsetDate ? ` and will be sunset on ${config.sunsetDate}` : ''}${config.successorVersion ? `. Please migrate to ${config.successorVersion}.` : '.'}`
|
||||
: undefined,
|
||||
};
|
||||
}
|
||||
@@ -155,6 +155,38 @@ const sentrySchema = z.object({
|
||||
debug: booleanString(false),
|
||||
});
|
||||
|
||||
/**
|
||||
* Feature flags configuration schema (ADR-024).
|
||||
*
|
||||
* All flags default to `false` (disabled) for safety, following an opt-in model.
|
||||
* Set the corresponding environment variable to 'true' to enable a feature.
|
||||
*
|
||||
* Environment variable naming convention: `FEATURE_SNAKE_CASE`
|
||||
* Config property naming convention: `camelCase`
|
||||
*
|
||||
* @example
|
||||
* // Enable via environment:
|
||||
* FEATURE_BUGSINK_SYNC=true
|
||||
*
|
||||
* // Check in code:
|
||||
* import { config } from './config/env';
|
||||
* if (config.featureFlags.bugsinkSync) { ... }
|
||||
*/
|
||||
const featureFlagsSchema = z.object({
|
||||
/** Enable Bugsink error sync integration (FEATURE_BUGSINK_SYNC) */
|
||||
bugsinkSync: booleanString(false),
|
||||
/** Enable advanced RBAC features (FEATURE_ADVANCED_RBAC) */
|
||||
advancedRbac: booleanString(false),
|
||||
/** Enable new dashboard experience (FEATURE_NEW_DASHBOARD) */
|
||||
newDashboard: booleanString(false),
|
||||
/** Enable beta recipe features (FEATURE_BETA_RECIPES) */
|
||||
betaRecipes: booleanString(false),
|
||||
/** Enable experimental AI features (FEATURE_EXPERIMENTAL_AI) */
|
||||
experimentalAi: booleanString(false),
|
||||
/** Enable debug mode for development (FEATURE_DEBUG_MODE) */
|
||||
debugMode: booleanString(false),
|
||||
});
|
||||
|
||||
/**
|
||||
* Complete environment configuration schema.
|
||||
*/
|
||||
@@ -170,6 +202,7 @@ const envSchema = z.object({
|
||||
worker: workerSchema,
|
||||
server: serverSchema,
|
||||
sentry: sentrySchema,
|
||||
featureFlags: featureFlagsSchema,
|
||||
});
|
||||
|
||||
export type EnvConfig = z.infer<typeof envSchema>;
|
||||
@@ -244,6 +277,14 @@ function loadEnvVars(): unknown {
|
||||
environment: process.env.SENTRY_ENVIRONMENT || process.env.NODE_ENV,
|
||||
debug: process.env.SENTRY_DEBUG,
|
||||
},
|
||||
featureFlags: {
|
||||
bugsinkSync: process.env.FEATURE_BUGSINK_SYNC,
|
||||
advancedRbac: process.env.FEATURE_ADVANCED_RBAC,
|
||||
newDashboard: process.env.FEATURE_NEW_DASHBOARD,
|
||||
betaRecipes: process.env.FEATURE_BETA_RECIPES,
|
||||
experimentalAi: process.env.FEATURE_EXPERIMENTAL_AI,
|
||||
debugMode: process.env.FEATURE_DEBUG_MODE,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
@@ -391,3 +432,33 @@ export const isGoogleOAuthConfigured = !!config.google.clientId && !!config.goog
|
||||
* Returns true if GitHub OAuth is configured (both client ID and secret present).
|
||||
*/
|
||||
export const isGithubOAuthConfigured = !!config.github.clientId && !!config.github.clientSecret;
|
||||
|
||||
// --- Feature Flag Helpers (ADR-024) ---
|
||||
|
||||
/**
|
||||
* Type representing valid feature flag names.
|
||||
* Derived from the featureFlagsSchema for type safety.
|
||||
*/
|
||||
export type FeatureFlagName = keyof typeof config.featureFlags;
|
||||
|
||||
/**
|
||||
* Check if a feature flag is enabled.
|
||||
*
|
||||
* This is a convenience function for checking feature flag state.
|
||||
* For more advanced usage (logging, all flags), use the featureFlags service.
|
||||
*
|
||||
* @param flagName - The name of the feature flag to check
|
||||
* @returns boolean indicating if the feature is enabled
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { isFeatureFlagEnabled } from './config/env';
|
||||
*
|
||||
* if (isFeatureFlagEnabled('newDashboard')) {
|
||||
* // Use new dashboard
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export function isFeatureFlagEnabled(flagName: FeatureFlagName): boolean {
|
||||
return config.featureFlags[flagName];
|
||||
}
|
||||
|
||||
@@ -89,8 +89,7 @@ describe('FlyerDisplay', () => {
|
||||
it('should apply dark mode image styles', () => {
|
||||
render(<FlyerDisplay {...defaultProps} />);
|
||||
const image = screen.getByAltText('Grocery Flyer');
|
||||
expect(image).toHaveClass('dark:invert');
|
||||
expect(image).toHaveClass('dark:hue-rotate-180');
|
||||
expect(image).toHaveClass('dark:brightness-90');
|
||||
});
|
||||
|
||||
describe('"Correct Data" Button', () => {
|
||||
|
||||
@@ -32,9 +32,9 @@ export const FlyerDisplay: React.FC<FlyerDisplayProps> = ({
|
||||
: `/flyer-images/${imageUrl}`;
|
||||
|
||||
return (
|
||||
<div className="w-full rounded-lg overflow-hidden border border-gray-200 dark:border-gray-700 shadow-sm bg-white dark:bg-gray-900 flex flex-col">
|
||||
<div className="w-full rounded-xl overflow-hidden border border-gray-200 dark:border-gray-700/50 shadow-md hover:shadow-lg transition-shadow duration-300 bg-white dark:bg-slate-800/50 flex flex-col backdrop-blur-sm">
|
||||
{(store || dateRange) && (
|
||||
<div className="p-3 border-b border-gray-200 dark:border-gray-700 bg-gray-50 dark:bg-gray-800 flex items-center space-x-4 pr-4">
|
||||
<div className="p-3 border-b border-gray-200 dark:border-gray-700/50 bg-gray-50/80 dark:bg-slate-800/80 flex items-center space-x-4 pr-4">
|
||||
{store?.logo_url && (
|
||||
<img
|
||||
src={store.logo_url}
|
||||
@@ -70,7 +70,7 @@ export const FlyerDisplay: React.FC<FlyerDisplayProps> = ({
|
||||
<img
|
||||
src={imageSrc}
|
||||
alt="Grocery Flyer"
|
||||
className="w-full h-auto object-contain max-h-[60vh] dark:invert dark:hue-rotate-180"
|
||||
className="w-full h-auto object-contain max-h-[60vh] dark:brightness-90 transition-all duration-300"
|
||||
/>
|
||||
) : (
|
||||
<div className="w-full h-64 bg-gray-200 dark:bg-gray-700 rounded-lg flex items-center justify-center">
|
||||
|
||||
@@ -147,7 +147,11 @@ describe('FlyerList', () => {
|
||||
);
|
||||
|
||||
const selectedItem = screen.getByText('Metro').closest('li');
|
||||
expect(selectedItem).toHaveClass('bg-brand-light', 'dark:bg-brand-dark/30');
|
||||
expect(selectedItem).toHaveClass(
|
||||
'border-brand-primary',
|
||||
'bg-teal-50/50',
|
||||
'dark:bg-teal-900/10',
|
||||
);
|
||||
});
|
||||
|
||||
describe('UI Details and Edge Cases', () => {
|
||||
|
||||
@@ -7,7 +7,11 @@ import { parseISO, format, isValid } from 'date-fns';
|
||||
import { MapPinIcon, Trash2Icon } from 'lucide-react';
|
||||
import { logger } from '../../services/logger.client';
|
||||
import * as apiClient from '../../services/apiClient';
|
||||
import { calculateDaysBetween, formatDateRange, getCurrentDateISOString } from '../../utils/dateUtils';
|
||||
import {
|
||||
calculateDaysBetween,
|
||||
formatDateRange,
|
||||
getCurrentDateISOString,
|
||||
} from '../../utils/dateUtils';
|
||||
|
||||
interface FlyerListProps {
|
||||
flyers: Flyer[];
|
||||
@@ -42,8 +46,8 @@ export const FlyerList: React.FC<FlyerListProps> = ({
|
||||
};
|
||||
|
||||
return (
|
||||
<div className="bg-white dark:bg-gray-900 rounded-lg border border-gray-200 dark:border-gray-700">
|
||||
<h3 className="text-lg font-bold text-gray-800 dark:text-white p-4 border-b border-gray-200 dark:border-gray-700">
|
||||
<div className="bg-white dark:bg-slate-900 rounded-xl border border-gray-200 dark:border-gray-700 shadow-sm overflow-hidden">
|
||||
<h3 className="text-lg font-bold text-gray-800 dark:text-white p-4 border-b border-gray-200 dark:border-gray-700 bg-gray-50/50 dark:bg-slate-800/50">
|
||||
Processed Flyers
|
||||
</h3>
|
||||
{flyers.length > 0 ? (
|
||||
@@ -108,7 +112,11 @@ export const FlyerList: React.FC<FlyerListProps> = ({
|
||||
data-testid={`flyer-list-item-${flyer.flyer_id}`}
|
||||
key={flyer.flyer_id}
|
||||
onClick={() => onFlyerSelect(flyer)}
|
||||
className={`p-4 flex items-center space-x-3 cursor-pointer transition-colors duration-200 ${selectedFlyerId === flyer.flyer_id ? 'bg-brand-light dark:bg-brand-dark/30' : 'hover:bg-gray-50 dark:hover:bg-gray-800'}`}
|
||||
className={`p-4 flex items-center space-x-3 cursor-pointer transition-all duration-200 border-l-4 ${
|
||||
selectedFlyerId === flyer.flyer_id
|
||||
? 'border-brand-primary bg-teal-50/50 dark:bg-teal-900/10'
|
||||
: 'border-transparent hover:border-gray-300 dark:hover:border-gray-600 hover:bg-gray-50 dark:hover:bg-slate-800 hover:-translate-y-0.5 hover:shadow-sm'
|
||||
}`}
|
||||
title={tooltipText}
|
||||
>
|
||||
{flyer.icon_url ? (
|
||||
|
||||
392
src/features/store/StoreCard.test.tsx
Normal file
392
src/features/store/StoreCard.test.tsx
Normal file
@@ -0,0 +1,392 @@
|
||||
// src/features/store/StoreCard.test.tsx
|
||||
import React from 'react';
|
||||
import { screen } from '@testing-library/react';
|
||||
import { describe, it, expect, beforeEach, vi } from 'vitest';
|
||||
import { StoreCard } from './StoreCard';
|
||||
import { renderWithProviders } from '../../tests/utils/renderWithProviders';
|
||||
|
||||
describe('StoreCard', () => {
|
||||
const mockStoreWithLogo = {
|
||||
store_id: 1,
|
||||
name: 'Test Store',
|
||||
logo_url: 'https://example.com/logo.png',
|
||||
locations: [
|
||||
{
|
||||
address_line_1: '123 Main Street',
|
||||
city: 'Toronto',
|
||||
province_state: 'ON',
|
||||
postal_code: 'M5V 1A1',
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
const mockStoreWithoutLogo = {
|
||||
store_id: 2,
|
||||
name: 'Another Store',
|
||||
logo_url: null,
|
||||
locations: [
|
||||
{
|
||||
address_line_1: '456 Oak Avenue',
|
||||
city: 'Vancouver',
|
||||
province_state: 'BC',
|
||||
postal_code: 'V6B 2M9',
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
const mockStoreWithMultipleLocations = {
|
||||
store_id: 3,
|
||||
name: 'Multi Location Store',
|
||||
logo_url: 'https://example.com/multi-logo.png',
|
||||
locations: [
|
||||
{
|
||||
address_line_1: '100 First Street',
|
||||
city: 'Montreal',
|
||||
province_state: 'QC',
|
||||
postal_code: 'H2X 1Y6',
|
||||
},
|
||||
{
|
||||
address_line_1: '200 Second Street',
|
||||
city: 'Montreal',
|
||||
province_state: 'QC',
|
||||
postal_code: 'H3A 2T1',
|
||||
},
|
||||
{
|
||||
address_line_1: '300 Third Street',
|
||||
city: 'Montreal',
|
||||
province_state: 'QC',
|
||||
postal_code: 'H4B 3C2',
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
const mockStoreNoLocations = {
|
||||
store_id: 4,
|
||||
name: 'No Location Store',
|
||||
logo_url: 'https://example.com/no-loc-logo.png',
|
||||
locations: [],
|
||||
};
|
||||
|
||||
const mockStoreUndefinedLocations = {
|
||||
store_id: 5,
|
||||
name: 'Undefined Locations Store',
|
||||
logo_url: null,
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
describe('store name rendering', () => {
|
||||
it('should render the store name', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreWithLogo} />);
|
||||
|
||||
expect(screen.getByText('Test Store')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render store name with truncation class', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreWithLogo} />);
|
||||
|
||||
const heading = screen.getByRole('heading', { level: 3 });
|
||||
expect(heading).toHaveClass('truncate');
|
||||
});
|
||||
});
|
||||
|
||||
describe('logo rendering', () => {
|
||||
it('should render logo image when logo_url is provided', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreWithLogo} />);
|
||||
|
||||
const logo = screen.getByAltText('Test Store logo');
|
||||
expect(logo).toBeInTheDocument();
|
||||
expect(logo).toHaveAttribute('src', 'https://example.com/logo.png');
|
||||
});
|
||||
|
||||
it('should render initials fallback when logo_url is null', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreWithoutLogo} />);
|
||||
|
||||
expect(screen.getByText('AN')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render initials fallback when logo_url is undefined', () => {
|
||||
const storeWithUndefinedLogo = {
|
||||
store_id: 10,
|
||||
name: 'Test Name',
|
||||
logo_url: undefined,
|
||||
};
|
||||
|
||||
renderWithProviders(<StoreCard store={storeWithUndefinedLogo} />);
|
||||
|
||||
expect(screen.getByText('TE')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should convert initials to uppercase', () => {
|
||||
const storeWithLowercase = {
|
||||
store_id: 11,
|
||||
name: 'lowercase store',
|
||||
logo_url: null,
|
||||
};
|
||||
|
||||
renderWithProviders(<StoreCard store={storeWithLowercase} />);
|
||||
|
||||
expect(screen.getByText('LO')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should handle single character store name', () => {
|
||||
const singleCharStore = {
|
||||
store_id: 12,
|
||||
name: 'X',
|
||||
logo_url: null,
|
||||
};
|
||||
|
||||
renderWithProviders(<StoreCard store={singleCharStore} />);
|
||||
|
||||
// Both the store name and initials will be 'X'
|
||||
// Check that there are exactly 2 elements with 'X'
|
||||
const elements = screen.getAllByText('X');
|
||||
expect(elements).toHaveLength(2);
|
||||
});
|
||||
|
||||
it('should handle empty string store name', () => {
|
||||
const emptyNameStore = {
|
||||
store_id: 13,
|
||||
name: '',
|
||||
logo_url: null,
|
||||
};
|
||||
|
||||
// This will render empty string for initials
|
||||
const { container } = renderWithProviders(<StoreCard store={emptyNameStore} />);
|
||||
|
||||
// The fallback div should still render
|
||||
const fallbackDiv = container.querySelector('.h-12.w-12.flex');
|
||||
expect(fallbackDiv).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('location display', () => {
|
||||
it('should not show location when showLocations is false (default)', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreWithLogo} />);
|
||||
|
||||
expect(screen.queryByText('123 Main Street')).not.toBeInTheDocument();
|
||||
expect(screen.queryByText(/Toronto/)).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should show primary location when showLocations is true', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreWithLogo} showLocations={true} />);
|
||||
|
||||
expect(screen.getByText('123 Main Street')).toBeInTheDocument();
|
||||
expect(screen.getByText('Toronto, ON M5V 1A1')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should show "No location data" when showLocations is true but no locations exist', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreNoLocations} showLocations={true} />);
|
||||
|
||||
expect(screen.getByText('No location data')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should show "No location data" when locations is undefined', () => {
|
||||
renderWithProviders(
|
||||
<StoreCard store={mockStoreUndefinedLocations as any} showLocations={true} />,
|
||||
);
|
||||
|
||||
expect(screen.getByText('No location data')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should not show "No location data" message when showLocations is false', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreNoLocations} showLocations={false} />);
|
||||
|
||||
expect(screen.queryByText('No location data')).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('multiple locations', () => {
|
||||
it('should show additional locations count for 2 locations', () => {
|
||||
const storeWith2Locations = {
|
||||
...mockStoreWithLogo,
|
||||
locations: [
|
||||
mockStoreWithMultipleLocations.locations[0],
|
||||
mockStoreWithMultipleLocations.locations[1],
|
||||
],
|
||||
};
|
||||
|
||||
renderWithProviders(<StoreCard store={storeWith2Locations} showLocations={true} />);
|
||||
|
||||
expect(screen.getByText('+ 1 more location')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should show additional locations count for 3+ locations', () => {
|
||||
renderWithProviders(
|
||||
<StoreCard store={mockStoreWithMultipleLocations} showLocations={true} />,
|
||||
);
|
||||
|
||||
expect(screen.getByText('+ 2 more locations')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should show primary location from multiple locations', () => {
|
||||
renderWithProviders(
|
||||
<StoreCard store={mockStoreWithMultipleLocations} showLocations={true} />,
|
||||
);
|
||||
|
||||
// Should show first location
|
||||
expect(screen.getByText('100 First Street')).toBeInTheDocument();
|
||||
expect(screen.getByText('Montreal, QC H2X 1Y6')).toBeInTheDocument();
|
||||
|
||||
// Should NOT show secondary locations directly
|
||||
expect(screen.queryByText('200 Second Street')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should not show additional locations count for single location', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreWithLogo} showLocations={true} />);
|
||||
|
||||
expect(screen.queryByText(/more location/)).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('accessibility', () => {
|
||||
it('should have proper alt text for logo', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreWithLogo} />);
|
||||
|
||||
const logo = screen.getByAltText('Test Store logo');
|
||||
expect(logo).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should use heading level 3 for store name', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreWithLogo} />);
|
||||
|
||||
const heading = screen.getByRole('heading', { level: 3 });
|
||||
expect(heading).toHaveTextContent('Test Store');
|
||||
});
|
||||
});
|
||||
|
||||
describe('styling', () => {
|
||||
it('should apply flex layout to container', () => {
|
||||
const { container } = renderWithProviders(<StoreCard store={mockStoreWithLogo} />);
|
||||
|
||||
const mainDiv = container.firstChild;
|
||||
expect(mainDiv).toHaveClass('flex', 'items-start', 'space-x-3');
|
||||
});
|
||||
|
||||
it('should apply proper styling to logo image', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreWithLogo} />);
|
||||
|
||||
const logo = screen.getByAltText('Test Store logo');
|
||||
expect(logo).toHaveClass(
|
||||
'h-12',
|
||||
'w-12',
|
||||
'object-contain',
|
||||
'rounded-md',
|
||||
'bg-gray-100',
|
||||
'dark:bg-gray-700',
|
||||
'p-1',
|
||||
'flex-shrink-0',
|
||||
);
|
||||
});
|
||||
|
||||
it('should apply proper styling to initials fallback', () => {
|
||||
const { container } = renderWithProviders(<StoreCard store={mockStoreWithoutLogo} />);
|
||||
|
||||
const initialsDiv = container.querySelector('.h-12.w-12.flex.items-center.justify-center');
|
||||
expect(initialsDiv).toHaveClass(
|
||||
'h-12',
|
||||
'w-12',
|
||||
'flex',
|
||||
'items-center',
|
||||
'justify-center',
|
||||
'bg-gray-200',
|
||||
'dark:bg-gray-700',
|
||||
'rounded-md',
|
||||
'text-gray-400',
|
||||
'text-xs',
|
||||
'flex-shrink-0',
|
||||
);
|
||||
});
|
||||
|
||||
it('should apply italic style to "No location data" text', () => {
|
||||
renderWithProviders(<StoreCard store={mockStoreNoLocations} showLocations={true} />);
|
||||
|
||||
const noLocationText = screen.getByText('No location data');
|
||||
expect(noLocationText).toHaveClass('italic');
|
||||
});
|
||||
});
|
||||
|
||||
describe('edge cases', () => {
|
||||
it('should handle store with special characters in name', () => {
|
||||
const specialCharStore = {
|
||||
store_id: 20,
|
||||
name: "Store & Co's <Best>",
|
||||
logo_url: null,
|
||||
};
|
||||
|
||||
renderWithProviders(<StoreCard store={specialCharStore} />);
|
||||
|
||||
expect(screen.getByText("Store & Co's <Best>")).toBeInTheDocument();
|
||||
expect(screen.getByText('ST')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should handle store with unicode characters', () => {
|
||||
const unicodeStore = {
|
||||
store_id: 21,
|
||||
name: 'Cafe Le Cafe',
|
||||
logo_url: null,
|
||||
};
|
||||
|
||||
renderWithProviders(<StoreCard store={unicodeStore} />);
|
||||
|
||||
expect(screen.getByText('Cafe Le Cafe')).toBeInTheDocument();
|
||||
expect(screen.getByText('CA')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should handle location with long address', () => {
|
||||
const longAddressStore = {
|
||||
store_id: 22,
|
||||
name: 'Long Address Store',
|
||||
logo_url: 'https://example.com/logo.png',
|
||||
locations: [
|
||||
{
|
||||
address_line_1: '1234567890 Very Long Street Name That Exceeds Normal Length',
|
||||
city: 'Vancouver',
|
||||
province_state: 'BC',
|
||||
postal_code: 'V6B 2M9',
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
renderWithProviders(<StoreCard store={longAddressStore} showLocations={true} />);
|
||||
|
||||
const addressElement = screen.getByText(
|
||||
'1234567890 Very Long Street Name That Exceeds Normal Length',
|
||||
);
|
||||
expect(addressElement).toHaveClass('truncate');
|
||||
});
|
||||
});
|
||||
|
||||
describe('data types', () => {
|
||||
it('should accept store_id as number', () => {
|
||||
const store = {
|
||||
store_id: 12345,
|
||||
name: 'Numeric ID Store',
|
||||
logo_url: null,
|
||||
};
|
||||
|
||||
// This should compile and render without errors
|
||||
renderWithProviders(<StoreCard store={store} />);
|
||||
|
||||
expect(screen.getByText('Numeric ID Store')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should handle empty logo_url string', () => {
|
||||
const storeWithEmptyLogo = {
|
||||
store_id: 30,
|
||||
name: 'Empty Logo Store',
|
||||
logo_url: '',
|
||||
};
|
||||
|
||||
// Empty string is truthy check, but might cause issues with img src
|
||||
// The component checks for truthy logo_url, so empty string will render initials
|
||||
// Actually, empty string '' is falsy in JavaScript, so this would show initials
|
||||
renderWithProviders(<StoreCard store={storeWithEmptyLogo} />);
|
||||
|
||||
// Empty string is falsy, so initials should show
|
||||
expect(screen.getByText('EM')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
});
|
||||
126
src/hooks/queries/useBestSalePricesQuery.test.tsx
Normal file
126
src/hooks/queries/useBestSalePricesQuery.test.tsx
Normal file
@@ -0,0 +1,126 @@
|
||||
// src/hooks/queries/useBestSalePricesQuery.test.tsx
|
||||
import { renderHook, waitFor } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import type { ReactNode } from 'react';
|
||||
import { useBestSalePricesQuery } from './useBestSalePricesQuery';
|
||||
import * as apiClient from '../../services/apiClient';
|
||||
import type { WatchedItemDeal } from '../../types';
|
||||
|
||||
vi.mock('../../services/apiClient');
|
||||
|
||||
const mockedApiClient = vi.mocked(apiClient);
|
||||
|
||||
describe('useBestSalePricesQuery', () => {
|
||||
let queryClient: QueryClient;
|
||||
|
||||
const wrapper = ({ children }: { children: ReactNode }) => (
|
||||
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
|
||||
);
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
queryClient = new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: { retry: false },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('should fetch best sale prices successfully', async () => {
|
||||
const mockDeals: WatchedItemDeal[] = [
|
||||
{
|
||||
master_item_id: 101,
|
||||
item_name: 'Organic Bananas',
|
||||
best_price_in_cents: 59,
|
||||
store: {
|
||||
store_id: 1,
|
||||
name: 'Green Grocer',
|
||||
logo_url: null,
|
||||
locations: [
|
||||
{
|
||||
address_line_1: '123 Main St',
|
||||
city: 'Springfield',
|
||||
province_state: 'ON',
|
||||
postal_code: 'A1B2C3',
|
||||
},
|
||||
],
|
||||
},
|
||||
flyer_id: 56,
|
||||
valid_to: '2026-02-01T23:59:59Z',
|
||||
},
|
||||
];
|
||||
mockedApiClient.fetchBestSalePrices.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockDeals }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBestSalePricesQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.fetchBestSalePrices).toHaveBeenCalled();
|
||||
expect(result.current.data).toEqual(mockDeals);
|
||||
});
|
||||
|
||||
it('should handle API error with error message', async () => {
|
||||
mockedApiClient.fetchBestSalePrices.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 401,
|
||||
json: () => Promise.resolve({ message: 'Authentication required' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBestSalePricesQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Authentication required');
|
||||
});
|
||||
|
||||
it('should handle API error without message', async () => {
|
||||
mockedApiClient.fetchBestSalePrices.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.reject(new Error('Parse error')),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBestSalePricesQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Request failed with status 500');
|
||||
});
|
||||
|
||||
it('should use fallback message when error.message is empty', async () => {
|
||||
mockedApiClient.fetchBestSalePrices.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.resolve({ message: '' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBestSalePricesQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Failed to fetch best sale prices');
|
||||
});
|
||||
|
||||
it('should return empty array for no deals', async () => {
|
||||
mockedApiClient.fetchBestSalePrices.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: [] }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBestSalePricesQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should not fetch when disabled', () => {
|
||||
renderHook(() => useBestSalePricesQuery(false), { wrapper });
|
||||
|
||||
expect(mockedApiClient.fetchBestSalePrices).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
175
src/hooks/queries/useBrandsQuery.test.tsx
Normal file
175
src/hooks/queries/useBrandsQuery.test.tsx
Normal file
@@ -0,0 +1,175 @@
|
||||
// src/hooks/queries/useBrandsQuery.test.tsx
|
||||
import { renderHook, waitFor } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import type { ReactNode } from 'react';
|
||||
import { useBrandsQuery } from './useBrandsQuery';
|
||||
import * as apiClient from '../../services/apiClient';
|
||||
import type { Brand } from '../../types';
|
||||
|
||||
vi.mock('../../services/apiClient');
|
||||
|
||||
const mockedApiClient = vi.mocked(apiClient);
|
||||
|
||||
describe('useBrandsQuery', () => {
|
||||
let queryClient: QueryClient;
|
||||
|
||||
const wrapper = ({ children }: { children: ReactNode }) => (
|
||||
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
|
||||
);
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
queryClient = new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: { retry: false },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('should fetch brands successfully', async () => {
|
||||
const mockBrands: Brand[] = [
|
||||
{
|
||||
brand_id: 1,
|
||||
name: 'Organic Valley',
|
||||
logo_url: 'https://example.com/organic-valley.png',
|
||||
store_id: null,
|
||||
store_name: null,
|
||||
created_at: '2025-01-01T00:00:00Z',
|
||||
updated_at: '2025-01-01T00:00:00Z',
|
||||
},
|
||||
{
|
||||
brand_id: 2,
|
||||
name: "Kellogg's",
|
||||
logo_url: null,
|
||||
store_id: 5,
|
||||
store_name: 'SuperMart',
|
||||
created_at: '2025-01-02T00:00:00Z',
|
||||
updated_at: '2025-01-02T00:00:00Z',
|
||||
},
|
||||
];
|
||||
mockedApiClient.fetchAllBrands.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockBrands }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBrandsQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.fetchAllBrands).toHaveBeenCalled();
|
||||
expect(result.current.data).toEqual(mockBrands);
|
||||
});
|
||||
|
||||
it('should handle API error with error message', async () => {
|
||||
mockedApiClient.fetchAllBrands.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 401,
|
||||
json: () => Promise.resolve({ message: 'Authentication required' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBrandsQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Authentication required');
|
||||
});
|
||||
|
||||
it('should handle API error without message (JSON parse failure)', async () => {
|
||||
mockedApiClient.fetchAllBrands.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.reject(new Error('Parse error')),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBrandsQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Request failed with status 500');
|
||||
});
|
||||
|
||||
it('should use fallback message when error.message is empty', async () => {
|
||||
mockedApiClient.fetchAllBrands.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.resolve({ message: '' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBrandsQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Failed to fetch brands');
|
||||
});
|
||||
|
||||
it('should return empty array for no brands', async () => {
|
||||
mockedApiClient.fetchAllBrands.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: [] }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBrandsQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should return empty array when success is false', async () => {
|
||||
mockedApiClient.fetchAllBrands.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: false, error: 'Something went wrong' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBrandsQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should return empty array when data is not an array', async () => {
|
||||
mockedApiClient.fetchAllBrands.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: null }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBrandsQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should not fetch when disabled', () => {
|
||||
renderHook(() => useBrandsQuery(false), { wrapper });
|
||||
|
||||
expect(mockedApiClient.fetchAllBrands).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should fetch when explicitly enabled', async () => {
|
||||
const mockBrands: Brand[] = [
|
||||
{
|
||||
brand_id: 1,
|
||||
name: 'Test Brand',
|
||||
logo_url: null,
|
||||
store_id: null,
|
||||
store_name: null,
|
||||
created_at: '2025-01-01T00:00:00Z',
|
||||
updated_at: '2025-01-01T00:00:00Z',
|
||||
},
|
||||
];
|
||||
mockedApiClient.fetchAllBrands.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockBrands }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useBrandsQuery(true), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.fetchAllBrands).toHaveBeenCalled();
|
||||
expect(result.current.data).toEqual(mockBrands);
|
||||
});
|
||||
});
|
||||
235
src/hooks/queries/useFlyerItemCountQuery.test.tsx
Normal file
235
src/hooks/queries/useFlyerItemCountQuery.test.tsx
Normal file
@@ -0,0 +1,235 @@
|
||||
// src/hooks/queries/useFlyerItemCountQuery.test.tsx
|
||||
import { renderHook, waitFor } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import type { ReactNode } from 'react';
|
||||
import { useFlyerItemCountQuery } from './useFlyerItemCountQuery';
|
||||
import * as apiClient from '../../services/apiClient';
|
||||
|
||||
vi.mock('../../services/apiClient');
|
||||
|
||||
const mockedApiClient = vi.mocked(apiClient);
|
||||
|
||||
describe('useFlyerItemCountQuery', () => {
|
||||
let queryClient: QueryClient;
|
||||
|
||||
const wrapper = ({ children }: { children: ReactNode }) => (
|
||||
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
|
||||
);
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
queryClient = new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: { retry: false },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('should fetch flyer item count successfully', async () => {
|
||||
const flyerIds = [1, 2, 3];
|
||||
const mockCount = { count: 42 };
|
||||
|
||||
mockedApiClient.countFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockCount }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.countFlyerItemsForFlyers).toHaveBeenCalledWith(flyerIds);
|
||||
expect(result.current.data).toEqual(mockCount);
|
||||
});
|
||||
|
||||
it('should handle API error with error message', async () => {
|
||||
const flyerIds = [1, 2];
|
||||
|
||||
mockedApiClient.countFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 401,
|
||||
json: () => Promise.resolve({ message: 'Authentication required' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Authentication required');
|
||||
});
|
||||
|
||||
it('should handle API error without message (JSON parse error)', async () => {
|
||||
const flyerIds = [1, 2];
|
||||
|
||||
mockedApiClient.countFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.reject(new Error('Parse error')),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Request failed with status 500');
|
||||
});
|
||||
|
||||
it('should use fallback message when error.message is empty', async () => {
|
||||
const flyerIds = [1, 2];
|
||||
|
||||
mockedApiClient.countFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.resolve({ message: '' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Failed to count flyer items');
|
||||
});
|
||||
|
||||
it('should return zero count for empty flyerIds array without calling API', async () => {
|
||||
const flyerIds: number[] = [];
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds, true), { wrapper });
|
||||
|
||||
// Query should be disabled due to flyerIds.length === 0
|
||||
expect(result.current.isPending).toBe(true);
|
||||
expect(result.current.fetchStatus).toBe('idle');
|
||||
expect(mockedApiClient.countFlyerItemsForFlyers).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not fetch when disabled via enabled parameter', () => {
|
||||
const flyerIds = [1, 2, 3];
|
||||
|
||||
renderHook(() => useFlyerItemCountQuery(flyerIds, false), { wrapper });
|
||||
|
||||
expect(mockedApiClient.countFlyerItemsForFlyers).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should return count of zero when API returns zero', async () => {
|
||||
const flyerIds = [99, 100];
|
||||
const mockCount = { count: 0 };
|
||||
|
||||
mockedApiClient.countFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockCount }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual({ count: 0 });
|
||||
});
|
||||
|
||||
it('should handle response without data wrapper (fallback to json)', async () => {
|
||||
const flyerIds = [1];
|
||||
const mockCount = { count: 15 };
|
||||
|
||||
// Some API responses might return data directly without the { success, data } wrapper
|
||||
mockedApiClient.countFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve(mockCount),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
// Should fall back to the raw json when data is undefined
|
||||
expect(result.current.data).toEqual(mockCount);
|
||||
});
|
||||
|
||||
it('should use different cache keys for different flyerIds arrays', async () => {
|
||||
const flyerIds1 = [1, 2];
|
||||
const flyerIds2 = [3, 4];
|
||||
const mockCount1 = { count: 10 };
|
||||
const mockCount2 = { count: 20 };
|
||||
|
||||
mockedApiClient.countFlyerItemsForFlyers
|
||||
.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockCount1 }),
|
||||
} as Response)
|
||||
.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockCount2 }),
|
||||
} as Response);
|
||||
|
||||
const { result: result1 } = renderHook(() => useFlyerItemCountQuery(flyerIds1), { wrapper });
|
||||
await waitFor(() => expect(result1.current.isSuccess).toBe(true));
|
||||
|
||||
const { result: result2 } = renderHook(() => useFlyerItemCountQuery(flyerIds2), { wrapper });
|
||||
await waitFor(() => expect(result2.current.isSuccess).toBe(true));
|
||||
|
||||
// Both calls should have been made since they have different cache keys
|
||||
expect(mockedApiClient.countFlyerItemsForFlyers).toHaveBeenCalledTimes(2);
|
||||
expect(mockedApiClient.countFlyerItemsForFlyers).toHaveBeenCalledWith(flyerIds1);
|
||||
expect(mockedApiClient.countFlyerItemsForFlyers).toHaveBeenCalledWith(flyerIds2);
|
||||
});
|
||||
|
||||
it('should handle large count values', async () => {
|
||||
const flyerIds = [1, 2, 3, 4, 5];
|
||||
const mockCount = { count: 999999 };
|
||||
|
||||
mockedApiClient.countFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockCount }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual({ count: 999999 });
|
||||
});
|
||||
|
||||
it('should handle network error', async () => {
|
||||
const flyerIds = [1, 2];
|
||||
|
||||
mockedApiClient.countFlyerItemsForFlyers.mockRejectedValue(new Error('Network error'));
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Network error');
|
||||
});
|
||||
|
||||
it('should default enabled to true when not specified', async () => {
|
||||
const flyerIds = [1];
|
||||
const mockCount = { count: 5 };
|
||||
|
||||
mockedApiClient.countFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockCount }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.countFlyerItemsForFlyers).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should handle single flyerId in array', async () => {
|
||||
const flyerIds = [42];
|
||||
const mockCount = { count: 7 };
|
||||
|
||||
mockedApiClient.countFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockCount }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemCountQuery(flyerIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.countFlyerItemsForFlyers).toHaveBeenCalledWith([42]);
|
||||
expect(result.current.data).toEqual({ count: 7 });
|
||||
});
|
||||
});
|
||||
310
src/hooks/queries/useFlyerItemsForFlyersQuery.test.tsx
Normal file
310
src/hooks/queries/useFlyerItemsForFlyersQuery.test.tsx
Normal file
@@ -0,0 +1,310 @@
|
||||
// src/hooks/queries/useFlyerItemsForFlyersQuery.test.tsx
|
||||
import { renderHook, waitFor } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import type { ReactNode } from 'react';
|
||||
import { useFlyerItemsForFlyersQuery } from './useFlyerItemsForFlyersQuery';
|
||||
import * as apiClient from '../../services/apiClient';
|
||||
import type { FlyerItem } from '../../types';
|
||||
import { createMockFlyerItem } from '../../tests/utils/mockFactories';
|
||||
|
||||
vi.mock('../../services/apiClient');
|
||||
|
||||
const mockedApiClient = vi.mocked(apiClient);
|
||||
|
||||
describe('useFlyerItemsForFlyersQuery', () => {
|
||||
let queryClient: QueryClient;
|
||||
|
||||
const wrapper = ({ children }: { children: ReactNode }) => (
|
||||
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
|
||||
);
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
queryClient = new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: { retry: false },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('should fetch flyer items for multiple flyers successfully', async () => {
|
||||
const mockFlyerItems: FlyerItem[] = [
|
||||
createMockFlyerItem({
|
||||
flyer_item_id: 1,
|
||||
flyer_id: 100,
|
||||
item: 'Organic Bananas',
|
||||
price_display: '$0.59/lb',
|
||||
price_in_cents: 59,
|
||||
quantity: 'lb',
|
||||
master_item_id: 1001,
|
||||
master_item_name: 'Bananas',
|
||||
category_id: 1,
|
||||
category_name: 'Produce',
|
||||
}),
|
||||
createMockFlyerItem({
|
||||
flyer_item_id: 2,
|
||||
flyer_id: 100,
|
||||
item: 'Whole Milk',
|
||||
price_display: '$3.99',
|
||||
price_in_cents: 399,
|
||||
quantity: 'gal',
|
||||
master_item_id: 1002,
|
||||
master_item_name: 'Milk',
|
||||
category_id: 2,
|
||||
category_name: 'Dairy',
|
||||
}),
|
||||
createMockFlyerItem({
|
||||
flyer_item_id: 3,
|
||||
flyer_id: 101,
|
||||
item: 'Chicken Breast',
|
||||
price_display: '$5.99/lb',
|
||||
price_in_cents: 599,
|
||||
quantity: 'lb',
|
||||
master_item_id: 1003,
|
||||
master_item_name: 'Chicken',
|
||||
category_id: 3,
|
||||
category_name: 'Meat',
|
||||
}),
|
||||
];
|
||||
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockFlyerItems }),
|
||||
} as Response);
|
||||
|
||||
const flyerIds = [100, 101];
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery(flyerIds), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.fetchFlyerItemsForFlyers).toHaveBeenCalledWith(flyerIds);
|
||||
expect(result.current.data).toEqual(mockFlyerItems);
|
||||
expect(result.current.data).toHaveLength(3);
|
||||
});
|
||||
|
||||
it('should handle API error with error message', async () => {
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 401,
|
||||
json: () => Promise.resolve({ message: 'Authentication required' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery([100]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Authentication required');
|
||||
});
|
||||
|
||||
it('should handle API error without message (JSON parse error)', async () => {
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.reject(new Error('Parse error')),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery([100]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Request failed with status 500');
|
||||
});
|
||||
|
||||
it('should use fallback message when error.message is empty', async () => {
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.resolve({ message: '' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery([100]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Failed to fetch flyer items');
|
||||
});
|
||||
|
||||
it('should return empty array for no flyer items', async () => {
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: [] }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery([100]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should not fetch when disabled explicitly', () => {
|
||||
renderHook(() => useFlyerItemsForFlyersQuery([100], false), { wrapper });
|
||||
|
||||
expect(mockedApiClient.fetchFlyerItemsForFlyers).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not fetch when flyerIds array is empty', () => {
|
||||
renderHook(() => useFlyerItemsForFlyersQuery([]), { wrapper });
|
||||
|
||||
expect(mockedApiClient.fetchFlyerItemsForFlyers).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not fetch when flyerIds is empty even if enabled is true', () => {
|
||||
renderHook(() => useFlyerItemsForFlyersQuery([], true), { wrapper });
|
||||
|
||||
expect(mockedApiClient.fetchFlyerItemsForFlyers).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should return empty array when success is false in response', async () => {
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: false, error: 'Some error' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery([100]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should return empty array when data is not an array', async () => {
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: null }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery([100]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should return empty array when data is an object instead of array', async () => {
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: { item: 'not an array' } }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery([100]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should fetch for single flyer ID', async () => {
|
||||
const mockFlyerItems: FlyerItem[] = [
|
||||
createMockFlyerItem({
|
||||
flyer_item_id: 1,
|
||||
flyer_id: 100,
|
||||
item: 'Bread',
|
||||
price_display: '$2.49',
|
||||
price_in_cents: 249,
|
||||
}),
|
||||
];
|
||||
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockFlyerItems }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery([100]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.fetchFlyerItemsForFlyers).toHaveBeenCalledWith([100]);
|
||||
expect(result.current.data).toEqual(mockFlyerItems);
|
||||
});
|
||||
|
||||
it('should handle 404 error status', async () => {
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 404,
|
||||
json: () => Promise.resolve({ message: 'Flyers not found' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery([999]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Flyers not found');
|
||||
});
|
||||
|
||||
it('should handle network error', async () => {
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockRejectedValue(new Error('Network error'));
|
||||
|
||||
const { result } = renderHook(() => useFlyerItemsForFlyersQuery([100]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Network error');
|
||||
});
|
||||
|
||||
it('should be enabled by default when flyerIds has items', async () => {
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: [] }),
|
||||
} as Response);
|
||||
|
||||
// Call without the enabled parameter (uses default value of true)
|
||||
renderHook(() => useFlyerItemsForFlyersQuery([100]), { wrapper });
|
||||
|
||||
await waitFor(() => expect(mockedApiClient.fetchFlyerItemsForFlyers).toHaveBeenCalled());
|
||||
});
|
||||
|
||||
it('should use consistent query key regardless of flyer IDs order', async () => {
|
||||
const mockItems: FlyerItem[] = [createMockFlyerItem({ flyer_item_id: 1, flyer_id: 100 })];
|
||||
|
||||
mockedApiClient.fetchFlyerItemsForFlyers.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockItems }),
|
||||
} as Response);
|
||||
|
||||
// First call with [100, 200, 50]
|
||||
const { result: result1 } = renderHook(() => useFlyerItemsForFlyersQuery([100, 200, 50]), {
|
||||
wrapper,
|
||||
});
|
||||
await waitFor(() => expect(result1.current.isSuccess).toBe(true));
|
||||
|
||||
// API should be called with original order
|
||||
expect(mockedApiClient.fetchFlyerItemsForFlyers).toHaveBeenCalledWith([100, 200, 50]);
|
||||
|
||||
// Second call with same IDs in different order should use cached result
|
||||
// because query key uses sorted IDs (50,100,200)
|
||||
const { result: result2 } = renderHook(() => useFlyerItemsForFlyersQuery([50, 200, 100]), {
|
||||
wrapper,
|
||||
});
|
||||
|
||||
// Should immediately have data from cache (no additional API call)
|
||||
await waitFor(() => expect(result2.current.isSuccess).toBe(true));
|
||||
|
||||
// API should still only have been called once (cached)
|
||||
expect(mockedApiClient.fetchFlyerItemsForFlyers).toHaveBeenCalledTimes(1);
|
||||
expect(result2.current.data).toEqual(mockItems);
|
||||
});
|
||||
});
|
||||
193
src/hooks/queries/useLeaderboardQuery.test.tsx
Normal file
193
src/hooks/queries/useLeaderboardQuery.test.tsx
Normal file
@@ -0,0 +1,193 @@
|
||||
// src/hooks/queries/useLeaderboardQuery.test.tsx
|
||||
import { renderHook, waitFor } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import type { ReactNode } from 'react';
|
||||
import { useLeaderboardQuery } from './useLeaderboardQuery';
|
||||
import * as apiClient from '../../services/apiClient';
|
||||
import type { LeaderboardUser } from '../../types';
|
||||
|
||||
vi.mock('../../services/apiClient');
|
||||
|
||||
const mockedApiClient = vi.mocked(apiClient);
|
||||
|
||||
describe('useLeaderboardQuery', () => {
|
||||
let queryClient: QueryClient;
|
||||
|
||||
const wrapper = ({ children }: { children: ReactNode }) => (
|
||||
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
|
||||
);
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
queryClient = new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: { retry: false },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('should fetch leaderboard successfully', async () => {
|
||||
const mockLeaderboard: LeaderboardUser[] = [
|
||||
{
|
||||
user_id: 'user-123',
|
||||
full_name: 'Top Scorer',
|
||||
avatar_url: 'https://example.com/avatar1.png',
|
||||
points: 1500,
|
||||
rank: '1',
|
||||
},
|
||||
{
|
||||
user_id: 'user-456',
|
||||
full_name: 'Second Place',
|
||||
avatar_url: null,
|
||||
points: 1200,
|
||||
rank: '2',
|
||||
},
|
||||
];
|
||||
mockedApiClient.fetchLeaderboard.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockLeaderboard }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useLeaderboardQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.fetchLeaderboard).toHaveBeenCalledWith(10);
|
||||
expect(result.current.data).toEqual(mockLeaderboard);
|
||||
});
|
||||
|
||||
it('should fetch leaderboard with custom limit', async () => {
|
||||
const mockLeaderboard: LeaderboardUser[] = [
|
||||
{
|
||||
user_id: 'user-789',
|
||||
full_name: 'Champion',
|
||||
avatar_url: 'https://example.com/avatar.png',
|
||||
points: 2000,
|
||||
rank: '1',
|
||||
},
|
||||
];
|
||||
mockedApiClient.fetchLeaderboard.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockLeaderboard }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useLeaderboardQuery(5), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.fetchLeaderboard).toHaveBeenCalledWith(5);
|
||||
expect(result.current.data).toEqual(mockLeaderboard);
|
||||
});
|
||||
|
||||
it('should handle API error with error message', async () => {
|
||||
mockedApiClient.fetchLeaderboard.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 401,
|
||||
json: () => Promise.resolve({ message: 'Authentication required' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useLeaderboardQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Authentication required');
|
||||
});
|
||||
|
||||
it('should handle API error without message', async () => {
|
||||
mockedApiClient.fetchLeaderboard.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.reject(new Error('Parse error')),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useLeaderboardQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Request failed with status 500');
|
||||
});
|
||||
|
||||
it('should use fallback message when error.message is empty', async () => {
|
||||
mockedApiClient.fetchLeaderboard.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.resolve({ message: '' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useLeaderboardQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Failed to fetch leaderboard');
|
||||
});
|
||||
|
||||
it('should return empty array for no users on leaderboard', async () => {
|
||||
mockedApiClient.fetchLeaderboard.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: [] }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useLeaderboardQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should return empty array when success is false', async () => {
|
||||
mockedApiClient.fetchLeaderboard.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: false, data: null }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useLeaderboardQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should return empty array when data is not an array', async () => {
|
||||
mockedApiClient.fetchLeaderboard.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: { invalid: 'data' } }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useLeaderboardQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should not fetch when disabled', () => {
|
||||
renderHook(() => useLeaderboardQuery(10, false), { wrapper });
|
||||
|
||||
expect(mockedApiClient.fetchLeaderboard).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should handle users with null full_name and avatar_url', async () => {
|
||||
const mockLeaderboard: LeaderboardUser[] = [
|
||||
{
|
||||
user_id: 'user-anon',
|
||||
full_name: null,
|
||||
avatar_url: null,
|
||||
points: 100,
|
||||
rank: '1',
|
||||
},
|
||||
];
|
||||
mockedApiClient.fetchLeaderboard.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockLeaderboard }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useLeaderboardQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual(mockLeaderboard);
|
||||
expect(result.current.data?.[0].full_name).toBeNull();
|
||||
expect(result.current.data?.[0].avatar_url).toBeNull();
|
||||
});
|
||||
});
|
||||
216
src/hooks/queries/usePriceHistoryQuery.test.tsx
Normal file
216
src/hooks/queries/usePriceHistoryQuery.test.tsx
Normal file
@@ -0,0 +1,216 @@
|
||||
// src/hooks/queries/usePriceHistoryQuery.test.tsx
|
||||
import { renderHook, waitFor } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import type { ReactNode } from 'react';
|
||||
import { usePriceHistoryQuery } from './usePriceHistoryQuery';
|
||||
import * as apiClient from '../../services/apiClient';
|
||||
import type { HistoricalPriceDataPoint } from '../../types';
|
||||
import { createMockHistoricalPriceDataPoint } from '../../tests/utils/mockFactories';
|
||||
|
||||
vi.mock('../../services/apiClient');
|
||||
|
||||
const mockedApiClient = vi.mocked(apiClient);
|
||||
|
||||
describe('usePriceHistoryQuery', () => {
|
||||
let queryClient: QueryClient;
|
||||
|
||||
const wrapper = ({ children }: { children: ReactNode }) => (
|
||||
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
|
||||
);
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
queryClient = new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: { retry: false },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('should fetch price history successfully', async () => {
|
||||
const masterItemIds = [101, 102];
|
||||
const mockPriceHistory: HistoricalPriceDataPoint[] = [
|
||||
createMockHistoricalPriceDataPoint({
|
||||
master_item_id: 101,
|
||||
avg_price_in_cents: 299,
|
||||
summary_date: '2026-01-15',
|
||||
}),
|
||||
createMockHistoricalPriceDataPoint({
|
||||
master_item_id: 101,
|
||||
avg_price_in_cents: 349,
|
||||
summary_date: '2026-01-16',
|
||||
}),
|
||||
createMockHistoricalPriceDataPoint({
|
||||
master_item_id: 102,
|
||||
avg_price_in_cents: 199,
|
||||
summary_date: '2026-01-15',
|
||||
}),
|
||||
];
|
||||
|
||||
mockedApiClient.fetchHistoricalPriceData.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockPriceHistory }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => usePriceHistoryQuery(masterItemIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.fetchHistoricalPriceData).toHaveBeenCalledWith(masterItemIds);
|
||||
expect(result.current.data).toEqual(mockPriceHistory);
|
||||
});
|
||||
|
||||
it('should handle API error with error message', async () => {
|
||||
const masterItemIds = [101];
|
||||
|
||||
mockedApiClient.fetchHistoricalPriceData.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 401,
|
||||
json: () => Promise.resolve({ message: 'Authentication required' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => usePriceHistoryQuery(masterItemIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Authentication required');
|
||||
});
|
||||
|
||||
it('should handle API error without message (JSON parse failure)', async () => {
|
||||
const masterItemIds = [101];
|
||||
|
||||
mockedApiClient.fetchHistoricalPriceData.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.reject(new Error('Parse error')),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => usePriceHistoryQuery(masterItemIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Request failed with status 500');
|
||||
});
|
||||
|
||||
it('should use fallback message when error.message is empty', async () => {
|
||||
const masterItemIds = [101];
|
||||
|
||||
mockedApiClient.fetchHistoricalPriceData.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.resolve({ message: '' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => usePriceHistoryQuery(masterItemIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Failed to fetch price history');
|
||||
});
|
||||
|
||||
it('should return empty array for no price history data', async () => {
|
||||
const masterItemIds = [101];
|
||||
|
||||
mockedApiClient.fetchHistoricalPriceData.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: [] }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => usePriceHistoryQuery(masterItemIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should return empty array when success is false', async () => {
|
||||
const masterItemIds = [101];
|
||||
|
||||
mockedApiClient.fetchHistoricalPriceData.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: false, data: null }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => usePriceHistoryQuery(masterItemIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should return empty array when data is not an array', async () => {
|
||||
const masterItemIds = [101];
|
||||
|
||||
mockedApiClient.fetchHistoricalPriceData.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: 'not an array' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => usePriceHistoryQuery(masterItemIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual([]);
|
||||
});
|
||||
|
||||
it('should not fetch when masterItemIds is empty', async () => {
|
||||
const { result } = renderHook(() => usePriceHistoryQuery([]), { wrapper });
|
||||
|
||||
// Query should not be enabled with empty array
|
||||
expect(result.current.fetchStatus).toBe('idle');
|
||||
expect(mockedApiClient.fetchHistoricalPriceData).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not fetch when explicitly disabled', () => {
|
||||
const masterItemIds = [101, 102];
|
||||
|
||||
renderHook(() => usePriceHistoryQuery(masterItemIds, false), { wrapper });
|
||||
|
||||
expect(mockedApiClient.fetchHistoricalPriceData).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should return empty array from queryFn when masterItemIds becomes empty during execution', async () => {
|
||||
// This tests the early return within queryFn for empty arrays
|
||||
// The query is enabled by default, but if masterItemIds is empty, queryFn returns []
|
||||
const masterItemIds: number[] = [];
|
||||
|
||||
// Even if enabled is forced to true, the queryFn should return empty array
|
||||
// Note: The hook's enabled condition prevents this from running normally,
|
||||
// but the queryFn has defensive code that returns [] if masterItemIds.length === 0
|
||||
const { result } = renderHook(() => usePriceHistoryQuery(masterItemIds, true), { wrapper });
|
||||
|
||||
// Query is disabled when masterItemIds is empty due to enabled condition
|
||||
expect(result.current.fetchStatus).toBe('idle');
|
||||
expect(mockedApiClient.fetchHistoricalPriceData).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should handle price history with null avg_price_in_cents values', async () => {
|
||||
const masterItemIds = [101];
|
||||
const mockPriceHistory: HistoricalPriceDataPoint[] = [
|
||||
createMockHistoricalPriceDataPoint({
|
||||
master_item_id: 101,
|
||||
avg_price_in_cents: null,
|
||||
summary_date: '2026-01-15',
|
||||
}),
|
||||
createMockHistoricalPriceDataPoint({
|
||||
master_item_id: 101,
|
||||
avg_price_in_cents: 299,
|
||||
summary_date: '2026-01-16',
|
||||
}),
|
||||
];
|
||||
|
||||
mockedApiClient.fetchHistoricalPriceData.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockPriceHistory }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => usePriceHistoryQuery(masterItemIds), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual(mockPriceHistory);
|
||||
expect(result.current.data?.[0].avg_price_in_cents).toBeNull();
|
||||
expect(result.current.data?.[1].avg_price_in_cents).toBe(299);
|
||||
});
|
||||
});
|
||||
413
src/hooks/queries/useUserProfileDataQuery.test.tsx
Normal file
413
src/hooks/queries/useUserProfileDataQuery.test.tsx
Normal file
@@ -0,0 +1,413 @@
|
||||
// src/hooks/queries/useUserProfileDataQuery.test.tsx
|
||||
import { renderHook, waitFor } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import type { ReactNode } from 'react';
|
||||
import { useUserProfileDataQuery } from './useUserProfileDataQuery';
|
||||
import * as apiClient from '../../services/apiClient';
|
||||
import type { UserProfile, Achievement, UserAchievement } from '../../types';
|
||||
|
||||
vi.mock('../../services/apiClient');
|
||||
|
||||
const mockedApiClient = vi.mocked(apiClient);
|
||||
|
||||
describe('useUserProfileDataQuery', () => {
|
||||
let queryClient: QueryClient;
|
||||
|
||||
const wrapper = ({ children }: { children: ReactNode }) => (
|
||||
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
|
||||
);
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
queryClient = new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: { retry: false },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
const mockProfile: UserProfile = {
|
||||
full_name: 'Test User',
|
||||
avatar_url: 'https://example.com/avatar.png',
|
||||
address_id: 1,
|
||||
points: 100,
|
||||
role: 'user',
|
||||
preferences: { darkMode: false, unitSystem: 'metric' },
|
||||
created_at: '2025-01-01T00:00:00Z',
|
||||
updated_at: '2025-01-01T00:00:00Z',
|
||||
user: {
|
||||
user_id: 'user-123',
|
||||
email: 'test@example.com',
|
||||
created_at: '2025-01-01T00:00:00Z',
|
||||
updated_at: '2025-01-01T00:00:00Z',
|
||||
},
|
||||
address: {
|
||||
address_id: 1,
|
||||
address_line_1: '123 Main St',
|
||||
city: 'Test City',
|
||||
province_state: 'ON',
|
||||
postal_code: 'A1B 2C3',
|
||||
country: 'Canada',
|
||||
latitude: null,
|
||||
longitude: null,
|
||||
created_at: '2025-01-01T00:00:00Z',
|
||||
updated_at: '2025-01-01T00:00:00Z',
|
||||
},
|
||||
};
|
||||
|
||||
const mockAchievements: (UserAchievement & Achievement)[] = [
|
||||
{
|
||||
user_id: 'user-123',
|
||||
achievement_id: 1,
|
||||
achieved_at: '2025-01-15T10:00:00Z',
|
||||
name: 'First Upload',
|
||||
description: 'Uploaded your first flyer',
|
||||
icon: 'trophy',
|
||||
points_value: 10,
|
||||
created_at: '2025-01-01T00:00:00Z',
|
||||
},
|
||||
{
|
||||
user_id: 'user-123',
|
||||
achievement_id: 2,
|
||||
achieved_at: '2025-01-20T15:30:00Z',
|
||||
name: 'Deal Hunter',
|
||||
description: 'Found 10 deals',
|
||||
icon: 'star',
|
||||
points_value: 25,
|
||||
created_at: '2025-01-01T00:00:00Z',
|
||||
},
|
||||
];
|
||||
|
||||
it('should fetch user profile and achievements successfully', async () => {
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockProfile }),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockAchievements }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.getAuthenticatedUserProfile).toHaveBeenCalled();
|
||||
expect(mockedApiClient.getUserAchievements).toHaveBeenCalled();
|
||||
expect(result.current.data).toEqual({
|
||||
profile: mockProfile,
|
||||
achievements: mockAchievements,
|
||||
});
|
||||
});
|
||||
|
||||
it('should handle profile API error with error message', async () => {
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 401,
|
||||
json: () => Promise.resolve({ message: 'Authentication required' }),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockAchievements }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Authentication required');
|
||||
});
|
||||
|
||||
it('should handle profile API error without message', async () => {
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.reject(new Error('Parse error')),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockAchievements }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Request failed with status 500');
|
||||
});
|
||||
|
||||
it('should use fallback message when profile error.message is empty', async () => {
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.resolve({ message: '' }),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockAchievements }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Failed to fetch user profile');
|
||||
});
|
||||
|
||||
it('should handle achievements API error with error message', async () => {
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockProfile }),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 403,
|
||||
json: () => Promise.resolve({ message: 'Access denied' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Access denied');
|
||||
});
|
||||
|
||||
it('should handle achievements API error without message', async () => {
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockProfile }),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.reject(new Error('Parse error')),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Request failed with status 500');
|
||||
});
|
||||
|
||||
it('should use fallback message when achievements error.message is empty', async () => {
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockProfile }),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: false,
|
||||
status: 500,
|
||||
json: () => Promise.resolve({ message: '' }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
expect(result.current.error?.message).toBe('Failed to fetch user achievements');
|
||||
});
|
||||
|
||||
it('should return empty array for no achievements', async () => {
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockProfile }),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: [] }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual({
|
||||
profile: mockProfile,
|
||||
achievements: [],
|
||||
});
|
||||
});
|
||||
|
||||
it('should handle undefined achievements data gracefully', async () => {
|
||||
// When API returns response without data wrapper (legacy format)
|
||||
// achievementsJson.data will be undefined, falling back to achievementsJson itself
|
||||
// Then achievements || [] will convert falsy value to empty array
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockProfile }),
|
||||
} as Response);
|
||||
|
||||
// Return empty array directly (no wrapper) - this tests the fallback path
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve([]),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual({
|
||||
profile: mockProfile,
|
||||
achievements: [],
|
||||
});
|
||||
});
|
||||
|
||||
it('should handle response without data wrapper (direct response)', async () => {
|
||||
// Some APIs may return data directly without the { success, data } wrapper
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve(mockProfile),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve(mockAchievements),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual({
|
||||
profile: mockProfile,
|
||||
achievements: mockAchievements,
|
||||
});
|
||||
});
|
||||
|
||||
it('should not fetch when disabled', () => {
|
||||
renderHook(() => useUserProfileDataQuery(false), { wrapper });
|
||||
|
||||
expect(mockedApiClient.getAuthenticatedUserProfile).not.toHaveBeenCalled();
|
||||
expect(mockedApiClient.getUserAchievements).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should fetch when enabled is explicitly true', async () => {
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockProfile }),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockAchievements }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(true), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(mockedApiClient.getAuthenticatedUserProfile).toHaveBeenCalled();
|
||||
expect(mockedApiClient.getUserAchievements).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should handle profile with minimal data', async () => {
|
||||
const minimalProfile: UserProfile = {
|
||||
full_name: null,
|
||||
avatar_url: null,
|
||||
address_id: null,
|
||||
points: 0,
|
||||
role: 'user',
|
||||
preferences: null,
|
||||
created_at: '2025-01-01T00:00:00Z',
|
||||
updated_at: '2025-01-01T00:00:00Z',
|
||||
user: {
|
||||
user_id: 'user-456',
|
||||
email: 'minimal@example.com',
|
||||
created_at: '2025-01-01T00:00:00Z',
|
||||
updated_at: '2025-01-01T00:00:00Z',
|
||||
},
|
||||
address: null,
|
||||
};
|
||||
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: minimalProfile }),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: [] }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data).toEqual({
|
||||
profile: minimalProfile,
|
||||
achievements: [],
|
||||
});
|
||||
});
|
||||
|
||||
it('should handle admin user profile', async () => {
|
||||
const adminProfile: UserProfile = {
|
||||
...mockProfile,
|
||||
role: 'admin',
|
||||
points: 500,
|
||||
};
|
||||
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: adminProfile }),
|
||||
} as Response);
|
||||
|
||||
mockedApiClient.getUserAchievements.mockResolvedValue({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockAchievements }),
|
||||
} as Response);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
expect(result.current.data?.profile.role).toBe('admin');
|
||||
expect(result.current.data?.profile.points).toBe(500);
|
||||
});
|
||||
|
||||
it('should call both APIs in parallel', async () => {
|
||||
let profileCallTime: number | null = null;
|
||||
let achievementsCallTime: number | null = null;
|
||||
|
||||
mockedApiClient.getAuthenticatedUserProfile.mockImplementation(() => {
|
||||
profileCallTime = Date.now();
|
||||
return Promise.resolve({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockProfile }),
|
||||
} as Response);
|
||||
});
|
||||
|
||||
mockedApiClient.getUserAchievements.mockImplementation(() => {
|
||||
achievementsCallTime = Date.now();
|
||||
return Promise.resolve({
|
||||
ok: true,
|
||||
json: () => Promise.resolve({ success: true, data: mockAchievements }),
|
||||
} as Response);
|
||||
});
|
||||
|
||||
const { result } = renderHook(() => useUserProfileDataQuery(), { wrapper });
|
||||
|
||||
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||
|
||||
// Both calls should have happened
|
||||
expect(profileCallTime).not.toBeNull();
|
||||
expect(achievementsCallTime).not.toBeNull();
|
||||
|
||||
// Both calls should have been made nearly simultaneously (within 50ms)
|
||||
// This verifies Promise.all is being used for parallel execution
|
||||
expect(
|
||||
Math.abs(
|
||||
(profileCallTime as unknown as number) - (achievementsCallTime as unknown as number),
|
||||
),
|
||||
).toBeLessThan(50);
|
||||
});
|
||||
});
|
||||
311
src/hooks/useEventBus.test.ts
Normal file
311
src/hooks/useEventBus.test.ts
Normal file
@@ -0,0 +1,311 @@
|
||||
// src/hooks/useEventBus.test.ts
|
||||
import { renderHook } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach, afterEach, Mock } from 'vitest';
|
||||
import { useEventBus } from './useEventBus';
|
||||
|
||||
// Mock the eventBus service
|
||||
vi.mock('../services/eventBus', () => ({
|
||||
eventBus: {
|
||||
on: vi.fn(),
|
||||
off: vi.fn(),
|
||||
dispatch: vi.fn(),
|
||||
},
|
||||
}));
|
||||
|
||||
import { eventBus } from '../services/eventBus';
|
||||
|
||||
const mockEventBus = eventBus as unknown as {
|
||||
on: Mock;
|
||||
off: Mock;
|
||||
dispatch: Mock;
|
||||
};
|
||||
|
||||
describe('useEventBus', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe('subscription', () => {
|
||||
it('should subscribe to the event on mount', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
renderHook(() => useEventBus('test-event', callback));
|
||||
|
||||
expect(mockEventBus.on).toHaveBeenCalledTimes(1);
|
||||
expect(mockEventBus.on).toHaveBeenCalledWith('test-event', expect.any(Function));
|
||||
});
|
||||
|
||||
it('should unsubscribe from the event on unmount', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
const { unmount } = renderHook(() => useEventBus('test-event', callback));
|
||||
|
||||
unmount();
|
||||
|
||||
expect(mockEventBus.off).toHaveBeenCalledTimes(1);
|
||||
expect(mockEventBus.off).toHaveBeenCalledWith('test-event', expect.any(Function));
|
||||
});
|
||||
|
||||
it('should pass the same callback reference to on and off', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
const { unmount } = renderHook(() => useEventBus('test-event', callback));
|
||||
|
||||
const onCallback = mockEventBus.on.mock.calls[0][1];
|
||||
|
||||
unmount();
|
||||
|
||||
const offCallback = mockEventBus.off.mock.calls[0][1];
|
||||
|
||||
expect(onCallback).toBe(offCallback);
|
||||
});
|
||||
});
|
||||
|
||||
describe('callback execution', () => {
|
||||
it('should call the callback when event is dispatched', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
renderHook(() => useEventBus('test-event', callback));
|
||||
|
||||
// Get the registered callback and call it
|
||||
const registeredCallback = mockEventBus.on.mock.calls[0][1];
|
||||
registeredCallback({ message: 'hello' });
|
||||
|
||||
expect(callback).toHaveBeenCalledTimes(1);
|
||||
expect(callback).toHaveBeenCalledWith({ message: 'hello' });
|
||||
});
|
||||
|
||||
it('should call the callback with undefined data', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
renderHook(() => useEventBus('test-event', callback));
|
||||
|
||||
const registeredCallback = mockEventBus.on.mock.calls[0][1];
|
||||
registeredCallback(undefined);
|
||||
|
||||
expect(callback).toHaveBeenCalledWith(undefined);
|
||||
});
|
||||
|
||||
it('should call the callback with null data', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
renderHook(() => useEventBus('test-event', callback));
|
||||
|
||||
const registeredCallback = mockEventBus.on.mock.calls[0][1];
|
||||
registeredCallback(null);
|
||||
|
||||
expect(callback).toHaveBeenCalledWith(null);
|
||||
});
|
||||
});
|
||||
|
||||
describe('callback ref updates', () => {
|
||||
it('should use the latest callback when event is dispatched', () => {
|
||||
const callback1 = vi.fn();
|
||||
const callback2 = vi.fn();
|
||||
|
||||
const { rerender } = renderHook(({ callback }) => useEventBus('test-event', callback), {
|
||||
initialProps: { callback: callback1 },
|
||||
});
|
||||
|
||||
// Rerender with new callback
|
||||
rerender({ callback: callback2 });
|
||||
|
||||
// Get the registered callback and call it
|
||||
const registeredCallback = mockEventBus.on.mock.calls[0][1];
|
||||
registeredCallback({ message: 'hello' });
|
||||
|
||||
// Should call the new callback, not the old one
|
||||
expect(callback1).not.toHaveBeenCalled();
|
||||
expect(callback2).toHaveBeenCalledTimes(1);
|
||||
expect(callback2).toHaveBeenCalledWith({ message: 'hello' });
|
||||
});
|
||||
|
||||
it('should not re-subscribe when callback changes', () => {
|
||||
const callback1 = vi.fn();
|
||||
const callback2 = vi.fn();
|
||||
|
||||
const { rerender } = renderHook(({ callback }) => useEventBus('test-event', callback), {
|
||||
initialProps: { callback: callback1 },
|
||||
});
|
||||
|
||||
// Clear mock counts
|
||||
mockEventBus.on.mockClear();
|
||||
mockEventBus.off.mockClear();
|
||||
|
||||
// Rerender with new callback
|
||||
rerender({ callback: callback2 });
|
||||
|
||||
// Should NOT unsubscribe and re-subscribe
|
||||
expect(mockEventBus.off).not.toHaveBeenCalled();
|
||||
expect(mockEventBus.on).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('event name changes', () => {
|
||||
it('should re-subscribe when event name changes', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
const { rerender } = renderHook(({ event }) => useEventBus(event, callback), {
|
||||
initialProps: { event: 'event-1' },
|
||||
});
|
||||
|
||||
// Initial subscription
|
||||
expect(mockEventBus.on).toHaveBeenCalledTimes(1);
|
||||
expect(mockEventBus.on).toHaveBeenCalledWith('event-1', expect.any(Function));
|
||||
|
||||
// Clear mock
|
||||
mockEventBus.on.mockClear();
|
||||
|
||||
// Rerender with different event
|
||||
rerender({ event: 'event-2' });
|
||||
|
||||
// Should unsubscribe from old event
|
||||
expect(mockEventBus.off).toHaveBeenCalledWith('event-1', expect.any(Function));
|
||||
|
||||
// Should subscribe to new event
|
||||
expect(mockEventBus.on).toHaveBeenCalledWith('event-2', expect.any(Function));
|
||||
});
|
||||
});
|
||||
|
||||
describe('multiple hooks', () => {
|
||||
it('should allow multiple subscriptions to same event', () => {
|
||||
const callback1 = vi.fn();
|
||||
const callback2 = vi.fn();
|
||||
|
||||
renderHook(() => useEventBus('shared-event', callback1));
|
||||
renderHook(() => useEventBus('shared-event', callback2));
|
||||
|
||||
expect(mockEventBus.on).toHaveBeenCalledTimes(2);
|
||||
|
||||
// Both should be subscribed to same event
|
||||
expect(mockEventBus.on.mock.calls[0][0]).toBe('shared-event');
|
||||
expect(mockEventBus.on.mock.calls[1][0]).toBe('shared-event');
|
||||
});
|
||||
|
||||
it('should allow subscriptions to different events', () => {
|
||||
const callback1 = vi.fn();
|
||||
const callback2 = vi.fn();
|
||||
|
||||
renderHook(() => useEventBus('event-a', callback1));
|
||||
renderHook(() => useEventBus('event-b', callback2));
|
||||
|
||||
expect(mockEventBus.on).toHaveBeenCalledTimes(2);
|
||||
expect(mockEventBus.on).toHaveBeenCalledWith('event-a', expect.any(Function));
|
||||
expect(mockEventBus.on).toHaveBeenCalledWith('event-b', expect.any(Function));
|
||||
});
|
||||
});
|
||||
|
||||
describe('type safety', () => {
|
||||
it('should correctly type the callback data', () => {
|
||||
interface TestData {
|
||||
id: number;
|
||||
name: string;
|
||||
}
|
||||
|
||||
const callback = vi.fn();
|
||||
|
||||
renderHook(() => useEventBus<TestData>('typed-event', callback));
|
||||
|
||||
const registeredCallback = mockEventBus.on.mock.calls[0][1];
|
||||
registeredCallback({ id: 1, name: 'test' });
|
||||
|
||||
expect(callback).toHaveBeenCalledWith({ id: 1, name: 'test' });
|
||||
});
|
||||
|
||||
it('should handle callback with optional parameter', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
renderHook(() => useEventBus<string>('optional-event', callback));
|
||||
|
||||
const registeredCallback = mockEventBus.on.mock.calls[0][1];
|
||||
|
||||
// Call with data
|
||||
registeredCallback('hello');
|
||||
expect(callback).toHaveBeenCalledWith('hello');
|
||||
|
||||
// Call without data
|
||||
registeredCallback();
|
||||
expect(callback).toHaveBeenCalledWith(undefined);
|
||||
});
|
||||
});
|
||||
|
||||
describe('edge cases', () => {
|
||||
it('should handle empty string event name', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
renderHook(() => useEventBus('', callback));
|
||||
|
||||
expect(mockEventBus.on).toHaveBeenCalledWith('', expect.any(Function));
|
||||
});
|
||||
|
||||
it('should handle event names with special characters', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
renderHook(() => useEventBus('event:with:colons', callback));
|
||||
|
||||
expect(mockEventBus.on).toHaveBeenCalledWith('event:with:colons', expect.any(Function));
|
||||
});
|
||||
|
||||
it('should handle rapid mount/unmount cycles', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
const { unmount: unmount1 } = renderHook(() => useEventBus('rapid-event', callback));
|
||||
unmount1();
|
||||
|
||||
const { unmount: unmount2 } = renderHook(() => useEventBus('rapid-event', callback));
|
||||
unmount2();
|
||||
|
||||
const { unmount: unmount3 } = renderHook(() => useEventBus('rapid-event', callback));
|
||||
unmount3();
|
||||
|
||||
// Should have 3 subscriptions and 3 unsubscriptions
|
||||
expect(mockEventBus.on).toHaveBeenCalledTimes(3);
|
||||
expect(mockEventBus.off).toHaveBeenCalledTimes(3);
|
||||
});
|
||||
});
|
||||
|
||||
describe('stable callback reference', () => {
|
||||
it('should use useCallback for stable reference', () => {
|
||||
const callback = vi.fn();
|
||||
|
||||
const { rerender } = renderHook(() => useEventBus('stable-event', callback));
|
||||
|
||||
const firstCallbackRef = mockEventBus.on.mock.calls[0][1];
|
||||
|
||||
// Force a rerender
|
||||
rerender();
|
||||
|
||||
// The callback passed to eventBus.on should remain the same
|
||||
// (no re-subscription means the same callback is used)
|
||||
expect(mockEventBus.on).toHaveBeenCalledTimes(1);
|
||||
|
||||
// Verify the callback still works after rerender
|
||||
firstCallbackRef({ data: 'test' });
|
||||
expect(callback).toHaveBeenCalledWith({ data: 'test' });
|
||||
});
|
||||
});
|
||||
|
||||
describe('cleanup timing', () => {
|
||||
it('should unsubscribe before component is fully unmounted', () => {
|
||||
const callback = vi.fn();
|
||||
const cleanupOrder: string[] = [];
|
||||
|
||||
// Override off to track when it's called
|
||||
mockEventBus.off.mockImplementation(() => {
|
||||
cleanupOrder.push('eventBus.off');
|
||||
});
|
||||
|
||||
const { unmount } = renderHook(() => useEventBus('cleanup-event', callback));
|
||||
|
||||
cleanupOrder.push('before unmount');
|
||||
unmount();
|
||||
cleanupOrder.push('after unmount');
|
||||
|
||||
expect(cleanupOrder).toEqual(['before unmount', 'eventBus.off', 'after unmount']);
|
||||
});
|
||||
});
|
||||
});
|
||||
300
src/hooks/useFeatureFlag.test.ts
Normal file
300
src/hooks/useFeatureFlag.test.ts
Normal file
@@ -0,0 +1,300 @@
|
||||
// src/hooks/useFeatureFlag.test.ts
|
||||
/**
|
||||
* Unit tests for the useFeatureFlag React hook (ADR-024).
|
||||
*
|
||||
* These tests verify:
|
||||
* - useFeatureFlag() returns correct boolean for each flag
|
||||
* - useFeatureFlag() handles all valid flag names
|
||||
* - useAllFeatureFlags() returns all flag states
|
||||
* - Default behavior (all flags disabled when not set)
|
||||
* - Memoization behavior (stable references)
|
||||
*/
|
||||
|
||||
import { renderHook } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
|
||||
// Define mock feature flags object that will be mutated in tests
|
||||
// Note: We use a getter function pattern to avoid hoisting issues with vi.mock
|
||||
vi.mock('../config', () => {
|
||||
// Create a mutable flags object
|
||||
const flags = {
|
||||
newDashboard: false,
|
||||
betaRecipes: false,
|
||||
experimentalAi: false,
|
||||
debugMode: false,
|
||||
};
|
||||
|
||||
return {
|
||||
default: {
|
||||
featureFlags: flags,
|
||||
},
|
||||
// Export the flags object for test mutation
|
||||
__mockFlags: flags,
|
||||
};
|
||||
});
|
||||
|
||||
// Import config to get access to the mock flags for mutation
|
||||
import config from '../config';
|
||||
|
||||
// Import after mocking
|
||||
import { useFeatureFlag, useAllFeatureFlags, type FeatureFlagName } from './useFeatureFlag';
|
||||
|
||||
// Helper to reset flags
|
||||
const resetMockFlags = () => {
|
||||
config.featureFlags.newDashboard = false;
|
||||
config.featureFlags.betaRecipes = false;
|
||||
config.featureFlags.experimentalAi = false;
|
||||
config.featureFlags.debugMode = false;
|
||||
};
|
||||
|
||||
describe('useFeatureFlag hook', () => {
|
||||
beforeEach(() => {
|
||||
// Reset mock flags to default state before each test
|
||||
resetMockFlags();
|
||||
});
|
||||
|
||||
describe('useFeatureFlag()', () => {
|
||||
it('should return false for disabled flags', () => {
|
||||
const { result } = renderHook(() => useFeatureFlag('newDashboard'));
|
||||
|
||||
expect(result.current).toBe(false);
|
||||
});
|
||||
|
||||
it('should return true for enabled flags', () => {
|
||||
config.featureFlags.newDashboard = true;
|
||||
|
||||
const { result } = renderHook(() => useFeatureFlag('newDashboard'));
|
||||
|
||||
expect(result.current).toBe(true);
|
||||
});
|
||||
|
||||
it('should return false for betaRecipes when disabled', () => {
|
||||
const { result } = renderHook(() => useFeatureFlag('betaRecipes'));
|
||||
|
||||
expect(result.current).toBe(false);
|
||||
});
|
||||
|
||||
it('should return true for betaRecipes when enabled', () => {
|
||||
config.featureFlags.betaRecipes = true;
|
||||
|
||||
const { result } = renderHook(() => useFeatureFlag('betaRecipes'));
|
||||
|
||||
expect(result.current).toBe(true);
|
||||
});
|
||||
|
||||
it('should return false for experimentalAi when disabled', () => {
|
||||
const { result } = renderHook(() => useFeatureFlag('experimentalAi'));
|
||||
|
||||
expect(result.current).toBe(false);
|
||||
});
|
||||
|
||||
it('should return true for experimentalAi when enabled', () => {
|
||||
config.featureFlags.experimentalAi = true;
|
||||
|
||||
const { result } = renderHook(() => useFeatureFlag('experimentalAi'));
|
||||
|
||||
expect(result.current).toBe(true);
|
||||
});
|
||||
|
||||
it('should return false for debugMode when disabled', () => {
|
||||
const { result } = renderHook(() => useFeatureFlag('debugMode'));
|
||||
|
||||
expect(result.current).toBe(false);
|
||||
});
|
||||
|
||||
it('should return true for debugMode when enabled', () => {
|
||||
config.featureFlags.debugMode = true;
|
||||
|
||||
const { result } = renderHook(() => useFeatureFlag('debugMode'));
|
||||
|
||||
expect(result.current).toBe(true);
|
||||
});
|
||||
|
||||
it('should return consistent value across multiple calls with same flag', () => {
|
||||
config.featureFlags.newDashboard = true;
|
||||
|
||||
const { result: result1 } = renderHook(() => useFeatureFlag('newDashboard'));
|
||||
const { result: result2 } = renderHook(() => useFeatureFlag('newDashboard'));
|
||||
|
||||
expect(result1.current).toBe(result2.current);
|
||||
expect(result1.current).toBe(true);
|
||||
});
|
||||
|
||||
it('should return different values for different flags', () => {
|
||||
config.featureFlags.newDashboard = true;
|
||||
config.featureFlags.betaRecipes = false;
|
||||
|
||||
const { result: dashboardResult } = renderHook(() => useFeatureFlag('newDashboard'));
|
||||
const { result: recipesResult } = renderHook(() => useFeatureFlag('betaRecipes'));
|
||||
|
||||
expect(dashboardResult.current).toBe(true);
|
||||
expect(recipesResult.current).toBe(false);
|
||||
});
|
||||
|
||||
it('should memoize the result (stable reference with same flagName)', () => {
|
||||
const { result, rerender } = renderHook(
|
||||
({ flagName }: { flagName: FeatureFlagName }) => useFeatureFlag(flagName),
|
||||
{ initialProps: { flagName: 'newDashboard' as FeatureFlagName } },
|
||||
);
|
||||
|
||||
const firstValue = result.current;
|
||||
|
||||
// Rerender with same flag name
|
||||
rerender({ flagName: 'newDashboard' as FeatureFlagName });
|
||||
|
||||
const secondValue = result.current;
|
||||
|
||||
// Values should be equal (both false in this case)
|
||||
expect(firstValue).toBe(secondValue);
|
||||
});
|
||||
|
||||
it('should update when flag name changes', () => {
|
||||
config.featureFlags.newDashboard = true;
|
||||
config.featureFlags.betaRecipes = false;
|
||||
|
||||
const { result, rerender } = renderHook(
|
||||
({ flagName }: { flagName: FeatureFlagName }) => useFeatureFlag(flagName),
|
||||
{ initialProps: { flagName: 'newDashboard' as FeatureFlagName } },
|
||||
);
|
||||
|
||||
expect(result.current).toBe(true);
|
||||
|
||||
// Change to a different flag
|
||||
rerender({ flagName: 'betaRecipes' as FeatureFlagName });
|
||||
|
||||
expect(result.current).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('useAllFeatureFlags()', () => {
|
||||
it('should return all flags with their current states', () => {
|
||||
config.featureFlags.newDashboard = true;
|
||||
config.featureFlags.debugMode = true;
|
||||
|
||||
const { result } = renderHook(() => useAllFeatureFlags());
|
||||
|
||||
expect(result.current).toEqual({
|
||||
newDashboard: true,
|
||||
betaRecipes: false,
|
||||
experimentalAi: false,
|
||||
debugMode: true,
|
||||
});
|
||||
});
|
||||
|
||||
it('should return all flags as false when none are enabled', () => {
|
||||
const { result } = renderHook(() => useAllFeatureFlags());
|
||||
|
||||
expect(result.current).toEqual({
|
||||
newDashboard: false,
|
||||
betaRecipes: false,
|
||||
experimentalAi: false,
|
||||
debugMode: false,
|
||||
});
|
||||
});
|
||||
|
||||
it('should return a shallow copy (not the original object)', () => {
|
||||
const { result } = renderHook(() => useAllFeatureFlags());
|
||||
|
||||
// Modifying the returned object should not affect the config
|
||||
const flags = result.current;
|
||||
(flags as Record<string, boolean>).newDashboard = true;
|
||||
|
||||
// Re-render and get fresh flags
|
||||
const { result: result2 } = renderHook(() => useAllFeatureFlags());
|
||||
|
||||
// The mock config should still have the original value
|
||||
expect(config.featureFlags.newDashboard).toBe(false);
|
||||
// Note: result2 reads from the mock, which we didn't modify
|
||||
expect(result2.current.newDashboard).toBe(false);
|
||||
});
|
||||
|
||||
it('should return an object with all expected flag names', () => {
|
||||
const { result } = renderHook(() => useAllFeatureFlags());
|
||||
|
||||
const expectedFlags = ['newDashboard', 'betaRecipes', 'experimentalAi', 'debugMode'];
|
||||
|
||||
expect(Object.keys(result.current).sort()).toEqual(expectedFlags.sort());
|
||||
});
|
||||
|
||||
it('should memoize the result', () => {
|
||||
const { result, rerender } = renderHook(() => useAllFeatureFlags());
|
||||
|
||||
const firstValue = result.current;
|
||||
|
||||
// Rerender without any changes
|
||||
rerender();
|
||||
|
||||
const secondValue = result.current;
|
||||
|
||||
// Should return the same memoized object reference
|
||||
expect(firstValue).toBe(secondValue);
|
||||
});
|
||||
});
|
||||
|
||||
describe('FeatureFlagName type', () => {
|
||||
it('should accept valid flag names at compile time', () => {
|
||||
// These should compile without TypeScript errors
|
||||
const validNames: FeatureFlagName[] = [
|
||||
'newDashboard',
|
||||
'betaRecipes',
|
||||
'experimentalAi',
|
||||
'debugMode',
|
||||
];
|
||||
|
||||
validNames.forEach((name) => {
|
||||
const { result } = renderHook(() => useFeatureFlag(name));
|
||||
expect(typeof result.current).toBe('boolean');
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('useFeatureFlag integration scenarios', () => {
|
||||
beforeEach(() => {
|
||||
resetMockFlags();
|
||||
});
|
||||
|
||||
it('should work with conditional rendering pattern', () => {
|
||||
config.featureFlags.newDashboard = true;
|
||||
|
||||
const { result } = renderHook(() => {
|
||||
const isNewDashboard = useFeatureFlag('newDashboard');
|
||||
return isNewDashboard ? 'new' : 'legacy';
|
||||
});
|
||||
|
||||
expect(result.current).toBe('new');
|
||||
});
|
||||
|
||||
it('should work with multiple flags in same component', () => {
|
||||
config.featureFlags.newDashboard = true;
|
||||
config.featureFlags.betaRecipes = true;
|
||||
config.featureFlags.experimentalAi = false;
|
||||
|
||||
const { result } = renderHook(() => ({
|
||||
dashboard: useFeatureFlag('newDashboard'),
|
||||
recipes: useFeatureFlag('betaRecipes'),
|
||||
ai: useFeatureFlag('experimentalAi'),
|
||||
}));
|
||||
|
||||
expect(result.current).toEqual({
|
||||
dashboard: true,
|
||||
recipes: true,
|
||||
ai: false,
|
||||
});
|
||||
});
|
||||
|
||||
it('should work with useAllFeatureFlags for admin panels', () => {
|
||||
config.featureFlags.newDashboard = true;
|
||||
config.featureFlags.debugMode = true;
|
||||
|
||||
const { result } = renderHook(() => {
|
||||
const flags = useAllFeatureFlags();
|
||||
const enabledCount = Object.values(flags).filter(Boolean).length;
|
||||
return { flags, enabledCount };
|
||||
});
|
||||
|
||||
expect(result.current.enabledCount).toBe(2);
|
||||
expect(result.current.flags.newDashboard).toBe(true);
|
||||
expect(result.current.flags.debugMode).toBe(true);
|
||||
});
|
||||
});
|
||||
86
src/hooks/useFeatureFlag.ts
Normal file
86
src/hooks/useFeatureFlag.ts
Normal file
@@ -0,0 +1,86 @@
|
||||
// src/hooks/useFeatureFlag.ts
|
||||
import { useMemo } from 'react';
|
||||
import config from '../config';
|
||||
|
||||
/**
|
||||
* Union type of all available feature flag names.
|
||||
* This type is derived from the config.featureFlags object to ensure
|
||||
* type safety and autocomplete support when checking feature flags.
|
||||
*
|
||||
* @example
|
||||
* const flagName: FeatureFlagName = 'newDashboard'; // Valid
|
||||
* const invalid: FeatureFlagName = 'nonexistent'; // TypeScript error
|
||||
*/
|
||||
export type FeatureFlagName = keyof typeof config.featureFlags;
|
||||
|
||||
/**
|
||||
* React hook to check if a feature flag is enabled.
|
||||
*
|
||||
* Feature flags are loaded from environment variables at build time and
|
||||
* cannot change during runtime. This hook memoizes the result to prevent
|
||||
* unnecessary re-renders when the component re-renders.
|
||||
*
|
||||
* @param flagName - The name of the feature flag to check (must be a valid FeatureFlagName)
|
||||
* @returns boolean indicating if the feature is enabled (true) or disabled (false)
|
||||
*
|
||||
* @example
|
||||
* // Basic usage - conditionally render UI
|
||||
* function Dashboard() {
|
||||
* const isNewDashboard = useFeatureFlag('newDashboard');
|
||||
*
|
||||
* if (isNewDashboard) {
|
||||
* return <NewDashboard />;
|
||||
* }
|
||||
* return <LegacyDashboard />;
|
||||
* }
|
||||
*
|
||||
* @example
|
||||
* // Track feature flag usage with analytics
|
||||
* function FeatureComponent() {
|
||||
* const isExperimentalAi = useFeatureFlag('experimentalAi');
|
||||
*
|
||||
* useEffect(() => {
|
||||
* if (isExperimentalAi) {
|
||||
* analytics.track('experimental_ai_enabled');
|
||||
* }
|
||||
* }, [isExperimentalAi]);
|
||||
*
|
||||
* return isExperimentalAi ? <AiFeature /> : null;
|
||||
* }
|
||||
*
|
||||
* @see docs/adr/0024-feature-flagging-strategy.md
|
||||
*/
|
||||
export function useFeatureFlag(flagName: FeatureFlagName): boolean {
|
||||
return useMemo(() => config.featureFlags[flagName], [flagName]);
|
||||
}
|
||||
|
||||
/**
|
||||
* React hook to get all feature flags and their current states.
|
||||
*
|
||||
* This hook is useful for debugging, admin panels, or components that
|
||||
* need to display the current feature flag configuration. The returned
|
||||
* object is a shallow copy to prevent accidental mutation of the config.
|
||||
*
|
||||
* @returns Record mapping each feature flag name to its boolean state
|
||||
*
|
||||
* @example
|
||||
* // Display feature flag status in an admin panel
|
||||
* function FeatureFlagDebugPanel() {
|
||||
* const flags = useAllFeatureFlags();
|
||||
*
|
||||
* return (
|
||||
* <ul>
|
||||
* {Object.entries(flags).map(([name, enabled]) => (
|
||||
* <li key={name}>
|
||||
* {name}: {enabled ? 'Enabled' : 'Disabled'}
|
||||
* </li>
|
||||
* ))}
|
||||
* </ul>
|
||||
* );
|
||||
* }
|
||||
*
|
||||
* @see docs/adr/0024-feature-flagging-strategy.md
|
||||
*/
|
||||
export function useAllFeatureFlags(): Record<FeatureFlagName, boolean> {
|
||||
return useMemo(() => ({ ...config.featureFlags }), []);
|
||||
}
|
||||
560
src/hooks/useOnboardingTour.test.ts
Normal file
560
src/hooks/useOnboardingTour.test.ts
Normal file
@@ -0,0 +1,560 @@
|
||||
// src/hooks/useOnboardingTour.test.ts
|
||||
import { renderHook, act } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach, afterEach, Mock } from 'vitest';
|
||||
import { useOnboardingTour } from './useOnboardingTour';
|
||||
|
||||
// Mock driver.js
|
||||
const mockDrive = vi.fn();
|
||||
const mockDestroy = vi.fn();
|
||||
const mockDriverInstance = {
|
||||
drive: mockDrive,
|
||||
destroy: mockDestroy,
|
||||
};
|
||||
|
||||
vi.mock('driver.js', () => ({
|
||||
driver: vi.fn(() => mockDriverInstance),
|
||||
Driver: vi.fn(),
|
||||
DriveStep: vi.fn(),
|
||||
}));
|
||||
|
||||
import { driver } from 'driver.js';
|
||||
|
||||
const mockDriver = driver as Mock;
|
||||
|
||||
describe('useOnboardingTour', () => {
|
||||
const STORAGE_KEY = 'flyer_crawler_onboarding_completed';
|
||||
|
||||
// Mock localStorage
|
||||
let mockLocalStorage: { [key: string]: string };
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
vi.useFakeTimers();
|
||||
|
||||
// Reset mock driver instance methods
|
||||
mockDrive.mockClear();
|
||||
mockDestroy.mockClear();
|
||||
|
||||
// Reset localStorage mock
|
||||
mockLocalStorage = {};
|
||||
|
||||
// Mock localStorage
|
||||
vi.spyOn(Storage.prototype, 'getItem').mockImplementation(
|
||||
(key: string) => mockLocalStorage[key] || null,
|
||||
);
|
||||
vi.spyOn(Storage.prototype, 'setItem').mockImplementation((key: string, value: string) => {
|
||||
mockLocalStorage[key] = value;
|
||||
});
|
||||
vi.spyOn(Storage.prototype, 'removeItem').mockImplementation((key: string) => {
|
||||
delete mockLocalStorage[key];
|
||||
});
|
||||
|
||||
// Mock document.getElementById for style injection check
|
||||
vi.spyOn(document, 'getElementById').mockReturnValue(null);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.useRealTimers();
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe('initialization', () => {
|
||||
it('should return startTour, skipTour, and replayTour functions', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true'; // Prevent auto-start
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
expect(result.current.startTour).toBeInstanceOf(Function);
|
||||
expect(result.current.skipTour).toBeInstanceOf(Function);
|
||||
expect(result.current.replayTour).toBeInstanceOf(Function);
|
||||
});
|
||||
|
||||
it('should auto-start tour if not completed', async () => {
|
||||
// Don't set the storage key - tour not completed
|
||||
|
||||
renderHook(() => useOnboardingTour());
|
||||
|
||||
// Fast-forward past the 500ms delay
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(500);
|
||||
});
|
||||
|
||||
expect(mockDriver).toHaveBeenCalled();
|
||||
expect(mockDrive).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not auto-start tour if already completed', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
renderHook(() => useOnboardingTour());
|
||||
|
||||
// Fast-forward past the 500ms delay
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(500);
|
||||
});
|
||||
|
||||
expect(mockDrive).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('startTour', () => {
|
||||
it('should create and start the driver tour', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true'; // Prevent auto-start
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
expect(mockDriver).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
showProgress: true,
|
||||
steps: expect.any(Array),
|
||||
nextBtnText: 'Next',
|
||||
prevBtnText: 'Previous',
|
||||
doneBtnText: 'Done',
|
||||
progressText: 'Step {{current}} of {{total}}',
|
||||
onDestroyed: expect.any(Function),
|
||||
}),
|
||||
);
|
||||
expect(mockDrive).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should inject custom CSS styles', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
// Track the created style element
|
||||
const createdStyleElement = document.createElement('style');
|
||||
const originalCreateElement = document.createElement.bind(document);
|
||||
const createElementSpy = vi
|
||||
.spyOn(document, 'createElement')
|
||||
.mockImplementation((tagName: string) => {
|
||||
if (tagName === 'style') {
|
||||
return createdStyleElement;
|
||||
}
|
||||
return originalCreateElement(tagName);
|
||||
});
|
||||
const appendChildSpy = vi.spyOn(document.head, 'appendChild');
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
expect(createElementSpy).toHaveBeenCalledWith('style');
|
||||
expect(appendChildSpy).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not inject styles if they already exist', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
// Mock that the style element already exists
|
||||
vi.spyOn(document, 'getElementById').mockReturnValue({
|
||||
id: 'driver-js-custom-styles',
|
||||
} as HTMLElement);
|
||||
|
||||
const createElementSpy = vi.spyOn(document, 'createElement');
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
// createElement should not be called for the style element
|
||||
const styleCreateCalls = createElementSpy.mock.calls.filter((call) => call[0] === 'style');
|
||||
expect(styleCreateCalls).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should destroy existing tour before starting new one', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
// Start tour twice
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
mockDestroy.mockClear();
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
expect(mockDestroy).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should mark tour complete when onDestroyed is called', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
// Get the onDestroyed callback
|
||||
const driverConfig = mockDriver.mock.calls[0][0];
|
||||
const onDestroyed = driverConfig.onDestroyed;
|
||||
|
||||
act(() => {
|
||||
onDestroyed();
|
||||
});
|
||||
|
||||
expect(localStorage.setItem).toHaveBeenCalledWith(STORAGE_KEY, 'true');
|
||||
});
|
||||
});
|
||||
|
||||
describe('skipTour', () => {
|
||||
it('should destroy the tour if active', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
// Start the tour first
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
mockDestroy.mockClear();
|
||||
|
||||
act(() => {
|
||||
result.current.skipTour();
|
||||
});
|
||||
|
||||
expect(mockDestroy).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should mark tour as complete', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.skipTour();
|
||||
});
|
||||
|
||||
expect(localStorage.setItem).toHaveBeenCalledWith(STORAGE_KEY, 'true');
|
||||
});
|
||||
|
||||
it('should handle skip when no tour is active', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
// Skip without starting
|
||||
expect(() => {
|
||||
act(() => {
|
||||
result.current.skipTour();
|
||||
});
|
||||
}).not.toThrow();
|
||||
|
||||
expect(localStorage.setItem).toHaveBeenCalledWith(STORAGE_KEY, 'true');
|
||||
});
|
||||
});
|
||||
|
||||
describe('replayTour', () => {
|
||||
it('should start the tour', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.replayTour();
|
||||
});
|
||||
|
||||
expect(mockDriver).toHaveBeenCalled();
|
||||
expect(mockDrive).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should work even if tour was previously completed', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.replayTour();
|
||||
});
|
||||
|
||||
expect(mockDrive).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('cleanup', () => {
|
||||
it('should destroy tour on unmount', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result, unmount } = renderHook(() => useOnboardingTour());
|
||||
|
||||
// Start the tour
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
mockDestroy.mockClear();
|
||||
|
||||
unmount();
|
||||
|
||||
expect(mockDestroy).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should clear timeout on unmount if tour not started yet', () => {
|
||||
// Don't set storage key - tour will try to auto-start
|
||||
|
||||
const { unmount } = renderHook(() => useOnboardingTour());
|
||||
|
||||
// Unmount before the 500ms delay
|
||||
unmount();
|
||||
|
||||
// Now advance timers - tour should NOT start
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(500);
|
||||
});
|
||||
|
||||
expect(mockDrive).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not throw on unmount when no tour is active', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { unmount } = renderHook(() => useOnboardingTour());
|
||||
|
||||
// Unmount without starting tour
|
||||
expect(() => unmount()).not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe('auto-start delay', () => {
|
||||
it('should wait 500ms before auto-starting tour', () => {
|
||||
// Don't set storage key
|
||||
|
||||
renderHook(() => useOnboardingTour());
|
||||
|
||||
// Tour should not have started yet
|
||||
expect(mockDrive).not.toHaveBeenCalled();
|
||||
|
||||
// Advance 499ms
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(499);
|
||||
});
|
||||
|
||||
expect(mockDrive).not.toHaveBeenCalled();
|
||||
|
||||
// Advance 1 more ms
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(1);
|
||||
});
|
||||
|
||||
expect(mockDrive).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('tour steps configuration', () => {
|
||||
it('should configure tour with 6 steps', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
const driverConfig = mockDriver.mock.calls[0][0];
|
||||
expect(driverConfig.steps).toHaveLength(6);
|
||||
});
|
||||
|
||||
it('should have correct step elements', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
const driverConfig = mockDriver.mock.calls[0][0];
|
||||
const steps = driverConfig.steps;
|
||||
|
||||
expect(steps[0].element).toBe('[data-tour="flyer-uploader"]');
|
||||
expect(steps[1].element).toBe('[data-tour="extracted-data-table"]');
|
||||
expect(steps[2].element).toBe('[data-tour="watch-button"]');
|
||||
expect(steps[3].element).toBe('[data-tour="watched-items"]');
|
||||
expect(steps[4].element).toBe('[data-tour="price-chart"]');
|
||||
expect(steps[5].element).toBe('[data-tour="shopping-list"]');
|
||||
});
|
||||
|
||||
it('should have popover configuration for each step', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
const driverConfig = mockDriver.mock.calls[0][0];
|
||||
const steps = driverConfig.steps;
|
||||
|
||||
steps.forEach(
|
||||
(step: {
|
||||
popover: { title: string; description: string; side: string; align: string };
|
||||
}) => {
|
||||
expect(step.popover).toBeDefined();
|
||||
expect(step.popover.title).toBeDefined();
|
||||
expect(step.popover.description).toBeDefined();
|
||||
expect(step.popover.side).toBeDefined();
|
||||
expect(step.popover.align).toBeDefined();
|
||||
},
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('function stability', () => {
|
||||
it('should maintain stable function references across rerenders', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result, rerender } = renderHook(() => useOnboardingTour());
|
||||
|
||||
const initialStartTour = result.current.startTour;
|
||||
const initialSkipTour = result.current.skipTour;
|
||||
const initialReplayTour = result.current.replayTour;
|
||||
|
||||
rerender();
|
||||
|
||||
expect(result.current.startTour).toBe(initialStartTour);
|
||||
expect(result.current.skipTour).toBe(initialSkipTour);
|
||||
expect(result.current.replayTour).toBe(initialReplayTour);
|
||||
});
|
||||
});
|
||||
|
||||
describe('localStorage key', () => {
|
||||
it('should use correct storage key', () => {
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.skipTour();
|
||||
});
|
||||
|
||||
expect(localStorage.setItem).toHaveBeenCalledWith(
|
||||
'flyer_crawler_onboarding_completed',
|
||||
'true',
|
||||
);
|
||||
});
|
||||
|
||||
it('should read from correct storage key on mount', () => {
|
||||
mockLocalStorage['flyer_crawler_onboarding_completed'] = 'true';
|
||||
|
||||
renderHook(() => useOnboardingTour());
|
||||
|
||||
expect(localStorage.getItem).toHaveBeenCalledWith('flyer_crawler_onboarding_completed');
|
||||
});
|
||||
});
|
||||
|
||||
describe('edge cases', () => {
|
||||
it('should handle multiple startTour calls gracefully', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
result.current.startTour();
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
// Each startTour destroys the previous one
|
||||
expect(mockDestroy).toHaveBeenCalledTimes(2); // Called before 2nd and 3rd startTour
|
||||
expect(mockDrive).toHaveBeenCalledTimes(3);
|
||||
});
|
||||
|
||||
it('should handle skipTour after startTour', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
mockDestroy.mockClear();
|
||||
|
||||
act(() => {
|
||||
result.current.skipTour();
|
||||
});
|
||||
|
||||
expect(mockDestroy).toHaveBeenCalledTimes(1);
|
||||
expect(localStorage.setItem).toHaveBeenCalledWith(STORAGE_KEY, 'true');
|
||||
});
|
||||
|
||||
it('should handle replayTour multiple times', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.replayTour();
|
||||
});
|
||||
|
||||
mockDriver.mockClear();
|
||||
mockDrive.mockClear();
|
||||
|
||||
act(() => {
|
||||
result.current.replayTour();
|
||||
});
|
||||
|
||||
expect(mockDriver).toHaveBeenCalled();
|
||||
expect(mockDrive).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('CSS injection', () => {
|
||||
it('should set correct id on style element', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
// Track the created style element
|
||||
const createdStyleElement = document.createElement('style');
|
||||
const originalCreateElement = document.createElement.bind(document);
|
||||
vi.spyOn(document, 'createElement').mockImplementation((tagName: string) => {
|
||||
if (tagName === 'style') {
|
||||
return createdStyleElement;
|
||||
}
|
||||
return originalCreateElement(tagName);
|
||||
});
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
expect(createdStyleElement.id).toBe('driver-js-custom-styles');
|
||||
});
|
||||
|
||||
it('should inject CSS containing custom styles', () => {
|
||||
mockLocalStorage[STORAGE_KEY] = 'true';
|
||||
|
||||
// Track the created style element
|
||||
const createdStyleElement = document.createElement('style');
|
||||
const originalCreateElement = document.createElement.bind(document);
|
||||
vi.spyOn(document, 'createElement').mockImplementation((tagName: string) => {
|
||||
if (tagName === 'style') {
|
||||
return createdStyleElement;
|
||||
}
|
||||
return originalCreateElement(tagName);
|
||||
});
|
||||
|
||||
const { result } = renderHook(() => useOnboardingTour());
|
||||
|
||||
act(() => {
|
||||
result.current.startTour();
|
||||
});
|
||||
|
||||
// Check that textContent contains expected CSS rules
|
||||
expect(createdStyleElement.textContent).toContain('.driver-popover');
|
||||
expect(createdStyleElement.textContent).toContain('background-color');
|
||||
});
|
||||
});
|
||||
});
|
||||
161
src/hooks/useUserProfileData.test.ts
Normal file
161
src/hooks/useUserProfileData.test.ts
Normal file
@@ -0,0 +1,161 @@
|
||||
// src/hooks/useUserProfileData.test.ts
|
||||
import React from 'react';
|
||||
import { renderHook, act } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import { useUserProfileData } from './useUserProfileData';
|
||||
import * as useUserProfileDataQueryModule from './queries/useUserProfileDataQuery';
|
||||
import type { UserProfile, Achievement } from '../types';
|
||||
|
||||
// Mock the underlying query hook
|
||||
vi.mock('./queries/useUserProfileDataQuery');
|
||||
|
||||
const mockedUseUserProfileDataQuery = vi.mocked(
|
||||
useUserProfileDataQueryModule.useUserProfileDataQuery,
|
||||
);
|
||||
|
||||
// Mock factories for consistent test data
|
||||
const createMockUserProfile = (overrides: Partial<UserProfile> = {}): UserProfile => ({
|
||||
user: {
|
||||
user_id: 'user-123',
|
||||
email: 'test@example.com',
|
||||
created_at: new Date().toISOString(),
|
||||
updated_at: new Date().toISOString(),
|
||||
},
|
||||
full_name: 'Test User',
|
||||
avatar_url: null,
|
||||
address_id: null,
|
||||
points: 0,
|
||||
role: 'user',
|
||||
preferences: null,
|
||||
created_at: new Date().toISOString(),
|
||||
updated_at: new Date().toISOString(),
|
||||
address: null,
|
||||
...overrides,
|
||||
});
|
||||
|
||||
const createMockAchievement = (overrides: Partial<Achievement> = {}): Achievement => ({
|
||||
achievement_id: 1,
|
||||
name: 'First Upload',
|
||||
description: 'You uploaded your first flyer!',
|
||||
points_value: 10,
|
||||
created_at: new Date().toISOString(),
|
||||
...overrides,
|
||||
});
|
||||
|
||||
const createWrapper = () => {
|
||||
const queryClient = new QueryClient({
|
||||
defaultOptions: {
|
||||
queries: {
|
||||
retry: false, // Turn off retries for tests
|
||||
},
|
||||
},
|
||||
});
|
||||
return ({ children }: { children: React.ReactNode }) =>
|
||||
React.createElement(QueryClientProvider, { client: queryClient }, children);
|
||||
};
|
||||
|
||||
describe('useUserProfileData Hook', () => {
|
||||
const mockProfileData = createMockUserProfile();
|
||||
const mockAchievementsData = [createMockAchievement()];
|
||||
const mockQueryData = {
|
||||
profile: mockProfileData,
|
||||
achievements: mockAchievementsData,
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
// Reset the mock to a default loading state
|
||||
mockedUseUserProfileDataQuery.mockReturnValue({
|
||||
data: undefined,
|
||||
isLoading: true,
|
||||
error: null,
|
||||
} as ReturnType<typeof mockedUseUserProfileDataQuery>);
|
||||
});
|
||||
|
||||
it('should return loading state initially', () => {
|
||||
const { result } = renderHook(() => useUserProfileData(), { wrapper: createWrapper() });
|
||||
|
||||
expect(result.current.isLoading).toBe(true);
|
||||
expect(result.current.profile).toBeNull();
|
||||
expect(result.current.achievements).toEqual([]);
|
||||
expect(result.current.error).toBeNull();
|
||||
});
|
||||
|
||||
it('should return profile and achievements on successful fetch', () => {
|
||||
mockedUseUserProfileDataQuery.mockReturnValue({
|
||||
data: mockQueryData,
|
||||
isLoading: false,
|
||||
error: null,
|
||||
} as ReturnType<typeof mockedUseUserProfileDataQuery>);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileData(), { wrapper: createWrapper() });
|
||||
|
||||
expect(result.current.isLoading).toBe(false);
|
||||
expect(result.current.profile).toEqual(mockProfileData);
|
||||
expect(result.current.achievements).toEqual(mockAchievementsData);
|
||||
expect(result.current.error).toBeNull();
|
||||
});
|
||||
|
||||
it('should return an error message on failure', () => {
|
||||
const mockError = new Error('Failed to fetch profile');
|
||||
mockedUseUserProfileDataQuery.mockReturnValue({
|
||||
data: undefined,
|
||||
isLoading: false,
|
||||
error: mockError,
|
||||
} as ReturnType<typeof mockedUseUserProfileDataQuery>);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileData(), { wrapper: createWrapper() });
|
||||
|
||||
expect(result.current.isLoading).toBe(false);
|
||||
expect(result.current.profile).toBeNull();
|
||||
expect(result.current.achievements).toEqual([]);
|
||||
expect(result.current.error).toBe('Failed to fetch profile');
|
||||
});
|
||||
|
||||
it('setProfile should update the profile in the query cache with a new object', () => {
|
||||
const queryClient = new QueryClient();
|
||||
queryClient.setQueryData(['user-profile-data'], mockQueryData);
|
||||
|
||||
const wrapper = ({ children }: { children: React.ReactNode }) =>
|
||||
React.createElement(QueryClientProvider, { client: queryClient }, children);
|
||||
|
||||
const { result } = renderHook(() => useUserProfileData(), { wrapper });
|
||||
|
||||
const updatedProfile: UserProfile = { ...mockProfileData, full_name: 'Updated' };
|
||||
|
||||
act(() => {
|
||||
result.current.setProfile(updatedProfile);
|
||||
});
|
||||
|
||||
const updatedData = queryClient.getQueryData(['user-profile-data']) as typeof mockQueryData;
|
||||
expect(updatedData.profile).toEqual(updatedProfile);
|
||||
});
|
||||
|
||||
it('setProfile should not throw if oldData is undefined', () => {
|
||||
const { result } = renderHook(() => useUserProfileData(), { wrapper: createWrapper() });
|
||||
|
||||
const newProfile = createMockUserProfile();
|
||||
|
||||
expect(() => {
|
||||
act(() => {
|
||||
result.current.setProfile(newProfile);
|
||||
});
|
||||
}).not.toThrow();
|
||||
|
||||
const cachedData = result.current.profile;
|
||||
expect(cachedData).toBeNull();
|
||||
});
|
||||
|
||||
it('should maintain stable function references across rerenders', () => {
|
||||
const { result, rerender } = renderHook(() => useUserProfileData(), {
|
||||
wrapper: createWrapper(),
|
||||
});
|
||||
|
||||
const initialSetProfile = result.current.setProfile;
|
||||
|
||||
rerender();
|
||||
|
||||
expect(result.current.setProfile).toBe(initialSetProfile);
|
||||
});
|
||||
});
|
||||
304
src/hooks/useWebSocket.test.ts
Normal file
304
src/hooks/useWebSocket.test.ts
Normal file
@@ -0,0 +1,304 @@
|
||||
// src/hooks/useWebSocket.test.ts
|
||||
import { renderHook, act } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
|
||||
import { useWebSocket } from './useWebSocket';
|
||||
import { eventBus } from '../services/eventBus';
|
||||
|
||||
// Mock eventBus
|
||||
vi.mock('../services/eventBus', () => ({
|
||||
eventBus: {
|
||||
dispatch: vi.fn(),
|
||||
},
|
||||
}));
|
||||
|
||||
// A mock WebSocket class for testing
|
||||
class MockWebSocket {
|
||||
static instances: MockWebSocket[] = [];
|
||||
static CONNECTING = 0;
|
||||
static OPEN = 1;
|
||||
static CLOSING = 2;
|
||||
static CLOSED = 3;
|
||||
|
||||
url: string;
|
||||
readyState: number;
|
||||
onopen: () => void = () => {};
|
||||
onclose: (event: { code: number; reason: string; wasClean: boolean }) => void = () => {};
|
||||
onmessage: (event: { data: string }) => void = () => {};
|
||||
onerror: (error: Event) => void = () => {};
|
||||
send = vi.fn();
|
||||
close = vi.fn((code = 1000, reason = 'Client disconnecting') => {
|
||||
if (this.readyState === MockWebSocket.CLOSED || this.readyState === MockWebSocket.CLOSING)
|
||||
return;
|
||||
this.readyState = MockWebSocket.CLOSING;
|
||||
setTimeout(() => {
|
||||
this.readyState = MockWebSocket.CLOSED;
|
||||
this.onclose({ code, reason, wasClean: code === 1000 });
|
||||
}, 0);
|
||||
});
|
||||
|
||||
constructor(url: string) {
|
||||
this.url = url;
|
||||
this.readyState = MockWebSocket.CONNECTING;
|
||||
MockWebSocket.instances.push(this);
|
||||
}
|
||||
|
||||
// --- Test Helper Methods ---
|
||||
_open() {
|
||||
this.readyState = MockWebSocket.OPEN;
|
||||
this.onopen();
|
||||
}
|
||||
|
||||
_message(data: object | string) {
|
||||
if (typeof data === 'string') {
|
||||
this.onmessage({ data });
|
||||
} else {
|
||||
this.onmessage({ data: JSON.stringify(data) });
|
||||
}
|
||||
}
|
||||
|
||||
_error(errorEvent = new Event('error')) {
|
||||
this.onerror(errorEvent);
|
||||
}
|
||||
|
||||
_close(code: number, reason: string) {
|
||||
if (this.readyState === MockWebSocket.CLOSED) return;
|
||||
this.readyState = MockWebSocket.CLOSED;
|
||||
this.onclose({ code, reason, wasClean: code === 1000 });
|
||||
}
|
||||
|
||||
static get lastInstance(): MockWebSocket | undefined {
|
||||
return this.instances[this.instances.length - 1];
|
||||
}
|
||||
|
||||
static clearInstances() {
|
||||
this.instances = [];
|
||||
}
|
||||
}
|
||||
|
||||
describe('useWebSocket Hook', () => {
|
||||
const mockToken = 'test-token';
|
||||
let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
|
||||
|
||||
beforeEach(() => {
|
||||
vi.useFakeTimers();
|
||||
global.WebSocket = MockWebSocket as any;
|
||||
MockWebSocket.clearInstances();
|
||||
|
||||
Object.defineProperty(window, 'location', {
|
||||
value: { protocol: 'https:', host: 'testhost.com' },
|
||||
writable: true,
|
||||
});
|
||||
|
||||
Object.defineProperty(document, 'cookie', {
|
||||
writable: true,
|
||||
value: `accessToken=${mockToken}`,
|
||||
});
|
||||
|
||||
vi.clearAllMocks();
|
||||
consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.useRealTimers();
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
it('should not connect on mount if autoConnect is false', () => {
|
||||
renderHook(() => useWebSocket({ autoConnect: false }));
|
||||
expect(MockWebSocket.instances).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should auto-connect on mount by default', () => {
|
||||
const { result } = renderHook(() => useWebSocket());
|
||||
expect(MockWebSocket.instances).toHaveLength(1);
|
||||
expect(MockWebSocket.lastInstance?.url).toBe(`wss://testhost.com/ws?token=${mockToken}`);
|
||||
expect(result.current.isConnecting).toBe(true);
|
||||
});
|
||||
|
||||
it('should set an error state if no access token is found', () => {
|
||||
document.cookie = ''; // No token
|
||||
const { result } = renderHook(() => useWebSocket());
|
||||
|
||||
expect(result.current.isConnected).toBe(false);
|
||||
expect(result.current.isConnecting).toBe(false);
|
||||
expect(result.current.error).toBe('No access token found. Please log in.');
|
||||
expect(MockWebSocket.instances).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should transition to connected state on WebSocket open', () => {
|
||||
const onConnect = vi.fn();
|
||||
const { result } = renderHook(() => useWebSocket({ onConnect }));
|
||||
|
||||
expect(result.current.isConnecting).toBe(true);
|
||||
act(() => MockWebSocket.lastInstance?._open());
|
||||
|
||||
expect(result.current.isConnected).toBe(true);
|
||||
expect(result.current.isConnecting).toBe(false);
|
||||
expect(onConnect).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should handle incoming messages and dispatch to eventBus', () => {
|
||||
renderHook(() => useWebSocket());
|
||||
act(() => MockWebSocket.lastInstance?._open());
|
||||
|
||||
const dealData = { flyerId: 1 };
|
||||
act(() => MockWebSocket.lastInstance?._message({ type: 'deal-notification', data: dealData }));
|
||||
expect(eventBus.dispatch).toHaveBeenCalledWith('notification:deal', dealData);
|
||||
});
|
||||
|
||||
it('should log an error for invalid JSON messages', () => {
|
||||
renderHook(() => useWebSocket());
|
||||
act(() => MockWebSocket.lastInstance?._open());
|
||||
|
||||
const invalidJson = 'this is not json';
|
||||
act(() => MockWebSocket.lastInstance?._message(invalidJson));
|
||||
|
||||
expect(consoleErrorSpy).toHaveBeenCalledWith(
|
||||
'[WebSocket] Failed to parse message:',
|
||||
expect.any(SyntaxError),
|
||||
);
|
||||
expect(eventBus.dispatch).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should respond to ping with pong', () => {
|
||||
renderHook(() => useWebSocket());
|
||||
act(() => MockWebSocket.lastInstance?._open());
|
||||
|
||||
act(() => MockWebSocket.lastInstance?._message({ type: 'ping', data: {} }));
|
||||
|
||||
expect(MockWebSocket.lastInstance?.send).toHaveBeenCalledWith(
|
||||
expect.stringContaining('"type":"pong"'),
|
||||
);
|
||||
});
|
||||
|
||||
it('should disconnect and clean up when disconnect is called', () => {
|
||||
const onDisconnect = vi.fn();
|
||||
const { result } = renderHook(() => useWebSocket({ onDisconnect }));
|
||||
act(() => MockWebSocket.lastInstance?._open());
|
||||
|
||||
act(() => result.current.disconnect());
|
||||
|
||||
expect(MockWebSocket.lastInstance?.close).toHaveBeenCalledWith(1000, 'Client disconnecting');
|
||||
expect(result.current.isConnected).toBe(false);
|
||||
|
||||
act(() => vi.runAllTimers());
|
||||
expect(onDisconnect).toHaveBeenCalled();
|
||||
|
||||
// Ensure no reconnection attempt is made
|
||||
expect(MockWebSocket.instances).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('should attempt to reconnect on unexpected close', () => {
|
||||
const { result } = renderHook(() => useWebSocket({ reconnectDelay: 1000 }));
|
||||
act(() => MockWebSocket.lastInstance?._open());
|
||||
|
||||
act(() => MockWebSocket.lastInstance?._close(1006, 'Abnormal closure'));
|
||||
expect(result.current.isConnected).toBe(false);
|
||||
|
||||
act(() => vi.advanceTimersByTime(1000));
|
||||
expect(MockWebSocket.instances).toHaveLength(2);
|
||||
expect(result.current.isConnecting).toBe(true);
|
||||
});
|
||||
|
||||
it('should use exponential backoff for reconnection', () => {
|
||||
renderHook(() => useWebSocket({ reconnectDelay: 1000, maxReconnectAttempts: 3 }));
|
||||
act(() => MockWebSocket.lastInstance?._open());
|
||||
|
||||
// 1st failure -> 1s delay
|
||||
act(() => MockWebSocket.lastInstance?._close(1006, 'Abnormal'));
|
||||
act(() => vi.advanceTimersByTime(1000));
|
||||
expect(MockWebSocket.instances).toHaveLength(2);
|
||||
|
||||
// 2nd failure -> 2s delay
|
||||
act(() => MockWebSocket.lastInstance?._close(1006, 'Abnormal'));
|
||||
act(() => vi.advanceTimersByTime(2000));
|
||||
expect(MockWebSocket.instances).toHaveLength(3);
|
||||
|
||||
// 3rd failure -> 4s delay
|
||||
act(() => MockWebSocket.lastInstance?._close(1006, 'Abnormal'));
|
||||
act(() => vi.advanceTimersByTime(4000));
|
||||
expect(MockWebSocket.instances).toHaveLength(4);
|
||||
});
|
||||
|
||||
it('should stop reconnecting after maxReconnectAttempts', () => {
|
||||
const { result } = renderHook(() =>
|
||||
useWebSocket({ reconnectDelay: 100, maxReconnectAttempts: 1 }),
|
||||
);
|
||||
act(() => MockWebSocket.lastInstance?._open());
|
||||
|
||||
// 1st failure
|
||||
act(() => MockWebSocket.lastInstance?._close(1006, 'Abnormal'));
|
||||
act(() => vi.advanceTimersByTime(100));
|
||||
expect(MockWebSocket.instances).toHaveLength(2);
|
||||
|
||||
// 2nd failure (should be the last)
|
||||
act(() => MockWebSocket.lastInstance?._close(1006, 'Abnormal'));
|
||||
act(() => vi.advanceTimersByTime(5000));
|
||||
|
||||
expect(MockWebSocket.instances).toHaveLength(2); // No new instance
|
||||
expect(result.current.error).toBe('Failed to reconnect after multiple attempts');
|
||||
});
|
||||
|
||||
it('should reset reconnect attempts on a successful connection', () => {
|
||||
renderHook(() => useWebSocket({ reconnectDelay: 100, maxReconnectAttempts: 2 }));
|
||||
act(() => MockWebSocket.lastInstance?._open());
|
||||
|
||||
act(() => MockWebSocket.lastInstance?._close(1006, 'Abnormal'));
|
||||
act(() => vi.advanceTimersByTime(100)); // 1st reconnect attempt
|
||||
expect(MockWebSocket.instances).toHaveLength(2);
|
||||
|
||||
act(() => MockWebSocket.lastInstance?._open()); // Reconnect succeeds
|
||||
|
||||
act(() => MockWebSocket.lastInstance?._close(1006, 'Abnormal'));
|
||||
act(() => vi.advanceTimersByTime(100)); // Delay should be reset to base
|
||||
expect(MockWebSocket.instances).toHaveLength(3);
|
||||
});
|
||||
|
||||
it('should send a message when connected', () => {
|
||||
const { result } = renderHook(() => useWebSocket());
|
||||
act(() => MockWebSocket.lastInstance?._open());
|
||||
|
||||
const message = { type: 'ping' as const, data: {}, timestamp: new Date().toISOString() };
|
||||
act(() => result.current.send(message));
|
||||
|
||||
expect(MockWebSocket.lastInstance?.send).toHaveBeenCalledWith(JSON.stringify(message));
|
||||
});
|
||||
|
||||
it('should warn when trying to send a message while not connected', () => {
|
||||
const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
|
||||
const { result } = renderHook(() => useWebSocket());
|
||||
// Do not open connection
|
||||
|
||||
const message = { type: 'ping' as const, data: {}, timestamp: new Date().toISOString() };
|
||||
act(() => result.current.send(message));
|
||||
|
||||
expect(MockWebSocket.lastInstance?.send).not.toHaveBeenCalled();
|
||||
expect(consoleWarnSpy).toHaveBeenCalledWith('[WebSocket] Cannot send message: not connected');
|
||||
consoleWarnSpy.mockRestore();
|
||||
});
|
||||
|
||||
it('should clean up on unmount', () => {
|
||||
const { unmount } = renderHook(() => useWebSocket());
|
||||
const instance = MockWebSocket.lastInstance;
|
||||
|
||||
unmount();
|
||||
|
||||
expect(instance?.close).toHaveBeenCalled();
|
||||
act(() => vi.advanceTimersByTime(5000));
|
||||
expect(MockWebSocket.instances).toHaveLength(1); // No new reconnect attempts
|
||||
});
|
||||
|
||||
it('should maintain stable function references across rerenders', () => {
|
||||
const { result, rerender } = renderHook(() => useWebSocket());
|
||||
|
||||
const initialConnect = result.current.connect;
|
||||
const initialDisconnect = result.current.disconnect;
|
||||
const initialSend = result.current.send;
|
||||
|
||||
rerender();
|
||||
|
||||
expect(result.current.connect).toBe(initialConnect);
|
||||
expect(result.current.disconnect).toBe(initialDisconnect);
|
||||
expect(result.current.send).toBe(initialSend);
|
||||
});
|
||||
});
|
||||
@@ -237,7 +237,20 @@ describe('MainLayout Component', () => {
|
||||
expect(screen.queryByTestId('anonymous-banner')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('renders auth-gated components (PriceHistoryChart, Leaderboard, ActivityLog)', () => {
|
||||
it('renders auth-gated components for regular users (PriceHistoryChart, Leaderboard)', () => {
|
||||
renderWithRouter(<MainLayout {...defaultProps} />);
|
||||
expect(screen.getByTestId('price-history-chart')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('leaderboard')).toBeInTheDocument();
|
||||
// ActivityLog is admin-only, should NOT be present for regular users
|
||||
expect(screen.queryByTestId('activity-log')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('renders ActivityLog for admin users', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
...defaultUseAuthReturn,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
userProfile: createMockUserProfile({ user: mockUser, role: 'admin' }),
|
||||
});
|
||||
renderWithRouter(<MainLayout {...defaultProps} />);
|
||||
expect(screen.getByTestId('price-history-chart')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('leaderboard')).toBeInTheDocument();
|
||||
@@ -245,6 +258,11 @@ describe('MainLayout Component', () => {
|
||||
});
|
||||
|
||||
it('calls setActiveListId when a list is shared via ActivityLog and the list exists', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
...defaultUseAuthReturn,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
userProfile: createMockUserProfile({ user: mockUser, role: 'admin' }),
|
||||
});
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
...defaultUseShoppingListsReturn,
|
||||
shoppingLists: [
|
||||
@@ -260,6 +278,11 @@ describe('MainLayout Component', () => {
|
||||
});
|
||||
|
||||
it('does not call setActiveListId for actions other than list_shared', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
...defaultUseAuthReturn,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
userProfile: createMockUserProfile({ user: mockUser, role: 'admin' }),
|
||||
});
|
||||
renderWithRouter(<MainLayout {...defaultProps} />);
|
||||
const otherLogAction = screen.getByTestId('activity-log-other');
|
||||
fireEvent.click(otherLogAction);
|
||||
@@ -268,6 +291,11 @@ describe('MainLayout Component', () => {
|
||||
});
|
||||
|
||||
it('does not call setActiveListId if the shared list does not exist', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
...defaultUseAuthReturn,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
userProfile: createMockUserProfile({ user: mockUser, role: 'admin' }),
|
||||
});
|
||||
renderWithRouter(<MainLayout {...defaultProps} />);
|
||||
const activityLog = screen.getByTestId('activity-log');
|
||||
fireEvent.click(activityLog); // Mock click simulates sharing list with id 1
|
||||
|
||||
400
src/middleware/apiVersion.middleware.test.ts
Normal file
400
src/middleware/apiVersion.middleware.test.ts
Normal file
@@ -0,0 +1,400 @@
|
||||
// src/middleware/apiVersion.middleware.test.ts
|
||||
/**
|
||||
* @file Unit tests for API version detection middleware (ADR-008 Phase 2).
|
||||
* @see src/middleware/apiVersion.middleware.ts
|
||||
*/
|
||||
import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
|
||||
import type { Request, Response, NextFunction } from 'express';
|
||||
import {
|
||||
detectApiVersion,
|
||||
extractApiVersionFromPath,
|
||||
hasApiVersion,
|
||||
getRequestApiVersion,
|
||||
VERSION_ERROR_CODES,
|
||||
} from './apiVersion.middleware';
|
||||
import { DEFAULT_VERSION, SUPPORTED_VERSIONS } from '../config/apiVersions';
|
||||
import { createMockRequest } from '../tests/utils/createMockRequest';
|
||||
import { createMockLogger } from '../tests/utils/mockLogger';
|
||||
|
||||
describe('apiVersion.middleware', () => {
|
||||
let mockRequest: Partial<Request>;
|
||||
let mockResponse: Partial<Response>;
|
||||
let mockNext: NextFunction & Mock;
|
||||
let mockJson: Mock;
|
||||
let mockStatus: Mock;
|
||||
|
||||
beforeEach(() => {
|
||||
// Reset mocks before each test
|
||||
mockJson = vi.fn().mockReturnThis();
|
||||
mockStatus = vi.fn().mockReturnValue({ json: mockJson });
|
||||
mockNext = vi.fn();
|
||||
|
||||
mockResponse = {
|
||||
status: mockStatus,
|
||||
json: mockJson,
|
||||
};
|
||||
});
|
||||
|
||||
describe('detectApiVersion', () => {
|
||||
it('should extract v1 from req.params.version and attach to req.apiVersion', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'v1' },
|
||||
path: '/users',
|
||||
method: 'GET',
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockNext).toHaveBeenCalledWith();
|
||||
expect(mockRequest.apiVersion).toBe('v1');
|
||||
expect(mockRequest.versionDeprecation).toBeDefined();
|
||||
expect(mockRequest.versionDeprecation?.deprecated).toBe(false);
|
||||
});
|
||||
|
||||
it('should extract v2 from req.params.version and attach to req.apiVersion', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'v2' },
|
||||
path: '/flyers',
|
||||
method: 'POST',
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe('v2');
|
||||
expect(mockRequest.versionDeprecation).toBeDefined();
|
||||
});
|
||||
|
||||
it('should default to v1 when no version parameter is present', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
params: {},
|
||||
path: '/users',
|
||||
method: 'GET',
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
|
||||
expect(mockRequest.versionDeprecation).toBeDefined();
|
||||
});
|
||||
|
||||
it('should return 404 with UNSUPPORTED_VERSION for invalid version v99', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'v99' },
|
||||
path: '/users',
|
||||
method: 'GET',
|
||||
ip: '127.0.0.1',
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).not.toHaveBeenCalled();
|
||||
expect(mockStatus).toHaveBeenCalledWith(404);
|
||||
expect(mockJson).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
success: false,
|
||||
error: expect.objectContaining({
|
||||
code: VERSION_ERROR_CODES.UNSUPPORTED_VERSION,
|
||||
message: expect.stringContaining("API version 'v99' is not supported"),
|
||||
details: expect.objectContaining({
|
||||
requestedVersion: 'v99',
|
||||
supportedVersions: expect.arrayContaining(['v1', 'v2']),
|
||||
}),
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should return 404 for non-versioned format like "latest"', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'latest' },
|
||||
path: '/users',
|
||||
method: 'GET',
|
||||
ip: '192.168.1.1',
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).not.toHaveBeenCalled();
|
||||
expect(mockStatus).toHaveBeenCalledWith(404);
|
||||
expect(mockJson).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
success: false,
|
||||
error: expect.objectContaining({
|
||||
code: VERSION_ERROR_CODES.UNSUPPORTED_VERSION,
|
||||
message: expect.stringContaining("API version 'latest' is not supported"),
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should log warning when invalid version is requested', () => {
|
||||
// Arrange
|
||||
const childLogger = createMockLogger();
|
||||
const mockLog = createMockLogger();
|
||||
vi.mocked(mockLog.child).mockReturnValue(
|
||||
childLogger as unknown as ReturnType<typeof mockLog.child>,
|
||||
);
|
||||
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'v999' },
|
||||
path: '/test',
|
||||
method: 'GET',
|
||||
ip: '10.0.0.1',
|
||||
log: mockLog,
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockLog.child).toHaveBeenCalledWith({ middleware: 'detectApiVersion' });
|
||||
expect(childLogger.warn).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
attemptedVersion: 'v999',
|
||||
supportedVersions: SUPPORTED_VERSIONS,
|
||||
}),
|
||||
'Invalid API version requested',
|
||||
);
|
||||
});
|
||||
|
||||
it('should log debug when valid version is detected', () => {
|
||||
// Arrange
|
||||
const childLogger = createMockLogger();
|
||||
const mockLog = createMockLogger();
|
||||
vi.mocked(mockLog.child).mockReturnValue(
|
||||
childLogger as unknown as ReturnType<typeof mockLog.child>,
|
||||
);
|
||||
|
||||
mockRequest = createMockRequest({
|
||||
params: { version: 'v1' },
|
||||
path: '/users',
|
||||
method: 'GET',
|
||||
log: mockLog,
|
||||
});
|
||||
|
||||
// Act
|
||||
detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(childLogger.debug).toHaveBeenCalledWith(
|
||||
{ apiVersion: 'v1' },
|
||||
'API version detected from URL',
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('extractApiVersionFromPath', () => {
|
||||
it('should extract v1 from /v1/users path', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
path: '/v1/users',
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe('v1');
|
||||
expect(mockRequest.versionDeprecation).toBeDefined();
|
||||
});
|
||||
|
||||
it('should extract v2 from /v2/flyers/123 path', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
path: '/v2/flyers/123',
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe('v2');
|
||||
});
|
||||
|
||||
it('should default to v1 for unversioned paths', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
path: '/users',
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
|
||||
});
|
||||
|
||||
it('should default to v1 for paths without leading slash', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({
|
||||
path: 'v1/users', // No leading slash - won't match regex
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
|
||||
});
|
||||
|
||||
it('should use default for unsupported version numbers in path', () => {
|
||||
// Arrange
|
||||
const childLogger = createMockLogger();
|
||||
const mockLog = createMockLogger();
|
||||
vi.mocked(mockLog.child).mockReturnValue(
|
||||
childLogger as unknown as ReturnType<typeof mockLog.child>,
|
||||
);
|
||||
|
||||
mockRequest = createMockRequest({
|
||||
path: '/v99/users',
|
||||
params: {},
|
||||
log: mockLog,
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
|
||||
expect(childLogger.warn).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
attemptedVersion: 'v99',
|
||||
supportedVersions: SUPPORTED_VERSIONS,
|
||||
}),
|
||||
'Unsupported API version in path, falling back to default',
|
||||
);
|
||||
});
|
||||
|
||||
it('should handle paths with only version segment', () => {
|
||||
// Arrange: Path like "/v1/" (just version, no resource)
|
||||
mockRequest = createMockRequest({
|
||||
path: '/v1/',
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe('v1');
|
||||
});
|
||||
|
||||
it('should NOT extract version from path like /users/v1 (not at start)', () => {
|
||||
// Arrange: Version appears later in path, not at the start
|
||||
mockRequest = createMockRequest({
|
||||
path: '/users/v1/profile',
|
||||
params: {},
|
||||
});
|
||||
|
||||
// Act
|
||||
extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
|
||||
});
|
||||
});
|
||||
|
||||
describe('hasApiVersion', () => {
|
||||
it('should return true when apiVersion is set to valid version', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
mockRequest.apiVersion = 'v1';
|
||||
|
||||
// Act & Assert
|
||||
expect(hasApiVersion(mockRequest as Request)).toBe(true);
|
||||
});
|
||||
|
||||
it('should return false when apiVersion is undefined', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
mockRequest.apiVersion = undefined;
|
||||
|
||||
// Act & Assert
|
||||
expect(hasApiVersion(mockRequest as Request)).toBe(false);
|
||||
});
|
||||
|
||||
it('should return false when apiVersion is invalid', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
// Force an invalid version (bypassing TypeScript) - eslint-disable-next-line
|
||||
(mockRequest as unknown as { apiVersion: string }).apiVersion = 'v99';
|
||||
|
||||
// Act & Assert
|
||||
expect(hasApiVersion(mockRequest as Request)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getRequestApiVersion', () => {
|
||||
it('should return the request apiVersion when set', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
mockRequest.apiVersion = 'v2';
|
||||
|
||||
// Act
|
||||
const version = getRequestApiVersion(mockRequest as Request);
|
||||
|
||||
// Assert
|
||||
expect(version).toBe('v2');
|
||||
});
|
||||
|
||||
it('should return DEFAULT_VERSION when apiVersion is undefined', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
mockRequest.apiVersion = undefined;
|
||||
|
||||
// Act
|
||||
const version = getRequestApiVersion(mockRequest as Request);
|
||||
|
||||
// Assert
|
||||
expect(version).toBe(DEFAULT_VERSION);
|
||||
});
|
||||
|
||||
it('should return DEFAULT_VERSION when apiVersion is invalid', () => {
|
||||
// Arrange
|
||||
mockRequest = createMockRequest({});
|
||||
// Force an invalid version - eslint-disable-next-line
|
||||
(mockRequest as unknown as { apiVersion: string }).apiVersion = 'invalid';
|
||||
|
||||
// Act
|
||||
const version = getRequestApiVersion(mockRequest as Request);
|
||||
|
||||
// Assert
|
||||
expect(version).toBe(DEFAULT_VERSION);
|
||||
});
|
||||
});
|
||||
|
||||
describe('VERSION_ERROR_CODES', () => {
|
||||
it('should have UNSUPPORTED_VERSION error code', () => {
|
||||
expect(VERSION_ERROR_CODES.UNSUPPORTED_VERSION).toBe('UNSUPPORTED_VERSION');
|
||||
});
|
||||
});
|
||||
});
|
||||
218
src/middleware/apiVersion.middleware.ts
Normal file
218
src/middleware/apiVersion.middleware.ts
Normal file
@@ -0,0 +1,218 @@
|
||||
// src/middleware/apiVersion.middleware.ts
|
||||
/**
|
||||
* @file API version detection middleware implementing ADR-008 Phase 2.
|
||||
*
|
||||
* Extracts API version from the request URL, validates it against supported versions,
|
||||
* attaches version information to the request object, and handles unsupported versions.
|
||||
*
|
||||
* @see docs/architecture/api-versioning-infrastructure.md
|
||||
* @see docs/adr/0008-api-versioning-strategy.md
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // In versioned router factory (versioned.ts):
|
||||
* import { detectApiVersion } from '../middleware/apiVersion.middleware';
|
||||
*
|
||||
* const router = Router({ mergeParams: true });
|
||||
* router.use(detectApiVersion);
|
||||
* ```
|
||||
*/
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import {
|
||||
ApiVersion,
|
||||
SUPPORTED_VERSIONS,
|
||||
DEFAULT_VERSION,
|
||||
isValidApiVersion,
|
||||
getVersionDeprecation,
|
||||
} from '../config/apiVersions';
|
||||
import { sendError } from '../utils/apiResponse';
|
||||
import { createScopedLogger } from '../services/logger.server';
|
||||
|
||||
// --- Module-level Logger ---
|
||||
|
||||
/**
|
||||
* Module-scoped logger for API version middleware.
|
||||
* Used for logging version detection events outside of request context.
|
||||
*/
|
||||
const moduleLogger = createScopedLogger('apiVersion-middleware');
|
||||
|
||||
// --- Error Codes ---
|
||||
|
||||
/**
|
||||
* Error code for unsupported API version requests.
|
||||
* This is specific to the versioning system and not part of the general ErrorCode enum.
|
||||
*/
|
||||
export const VERSION_ERROR_CODES = {
|
||||
UNSUPPORTED_VERSION: 'UNSUPPORTED_VERSION',
|
||||
} as const;
|
||||
|
||||
// --- Middleware Functions ---
|
||||
|
||||
/**
|
||||
* Extracts the API version from the URL path parameter and attaches it to the request.
|
||||
*
|
||||
* This middleware expects to be used with a router that has a :version parameter
|
||||
* (e.g., mounted at `/api/:version`). It validates the version against the list
|
||||
* of supported versions and returns a 404 error for unsupported versions.
|
||||
*
|
||||
* For valid versions, it:
|
||||
* - Sets `req.apiVersion` to the detected version
|
||||
* - Sets `req.versionDeprecation` with deprecation info if the version is deprecated
|
||||
*
|
||||
* @param req - Express request object (expects `req.params.version`)
|
||||
* @param res - Express response object
|
||||
* @param next - Express next function
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Route setup:
|
||||
* app.use('/api/:version', detectApiVersion, versionedRouter);
|
||||
*
|
||||
* // Request to /api/v1/users:
|
||||
* // req.params.version = 'v1'
|
||||
* // req.apiVersion = 'v1'
|
||||
*
|
||||
* // Request to /api/v99/users:
|
||||
* // Returns 404 with UNSUPPORTED_VERSION error
|
||||
* ```
|
||||
*/
|
||||
export function detectApiVersion(req: Request, res: Response, next: NextFunction): void {
|
||||
// Get the request-scoped logger if available, otherwise use module logger
|
||||
const log = req.log?.child({ middleware: 'detectApiVersion' }) ?? moduleLogger;
|
||||
|
||||
// Extract version from URL params (expects router mounted with :version param)
|
||||
const versionParam = req.params?.version;
|
||||
|
||||
// If no version parameter found, this middleware was likely applied incorrectly.
|
||||
// Default to the default version and continue (allows for fallback behavior).
|
||||
if (!versionParam) {
|
||||
log.debug('No version parameter found in request, using default version');
|
||||
req.apiVersion = DEFAULT_VERSION;
|
||||
req.versionDeprecation = getVersionDeprecation(DEFAULT_VERSION);
|
||||
return next();
|
||||
}
|
||||
|
||||
// Validate the version parameter
|
||||
if (isValidApiVersion(versionParam)) {
|
||||
// Valid version - attach to request
|
||||
req.apiVersion = versionParam;
|
||||
req.versionDeprecation = getVersionDeprecation(versionParam);
|
||||
|
||||
log.debug({ apiVersion: versionParam }, 'API version detected from URL');
|
||||
return next();
|
||||
}
|
||||
|
||||
// Invalid version - log warning and return 404
|
||||
log.warn(
|
||||
{
|
||||
attemptedVersion: versionParam,
|
||||
supportedVersions: SUPPORTED_VERSIONS,
|
||||
path: req.path,
|
||||
method: req.method,
|
||||
ip: req.ip,
|
||||
},
|
||||
'Invalid API version requested',
|
||||
);
|
||||
|
||||
// Return 404 with UNSUPPORTED_VERSION error code
|
||||
// Using 404 because the versioned endpoint does not exist
|
||||
sendError(
|
||||
res,
|
||||
VERSION_ERROR_CODES.UNSUPPORTED_VERSION,
|
||||
`API version '${versionParam}' is not supported. Supported versions: ${SUPPORTED_VERSIONS.join(', ')}`,
|
||||
404,
|
||||
{
|
||||
requestedVersion: versionParam,
|
||||
supportedVersions: [...SUPPORTED_VERSIONS],
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracts the API version from the URL path pattern and attaches it to the request.
|
||||
*
|
||||
* Unlike `detectApiVersion`, this middleware parses the version from the URL path
|
||||
* directly using a regex pattern. This is useful when the middleware needs to run
|
||||
* before or independently of parameterized routing.
|
||||
*
|
||||
* Pattern matched: `/v{number}/...` at the beginning of the path
|
||||
* (e.g., `/v1/users`, `/v2/flyers/123`)
|
||||
*
|
||||
* If the version is valid, sets `req.apiVersion` and `req.versionDeprecation`.
|
||||
* If the version is invalid or not present, defaults to `DEFAULT_VERSION`.
|
||||
*
|
||||
* This middleware does NOT return errors for invalid versions - it's designed for
|
||||
* cases where version detection is informational rather than authoritative.
|
||||
*
|
||||
* @param req - Express request object
|
||||
* @param _res - Express response object (unused)
|
||||
* @param next - Express next function
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Applied early in middleware chain:
|
||||
* app.use('/api', extractApiVersionFromPath, apiRouter);
|
||||
*
|
||||
* // For path /api/v1/users:
|
||||
* // req.path = '/v1/users' (relative to /api mount point)
|
||||
* // req.apiVersion = 'v1'
|
||||
* ```
|
||||
*/
|
||||
export function extractApiVersionFromPath(req: Request, _res: Response, next: NextFunction): void {
|
||||
// Get the request-scoped logger if available, otherwise use module logger
|
||||
const log = req.log?.child({ middleware: 'extractApiVersionFromPath' }) ?? moduleLogger;
|
||||
|
||||
// Extract version from URL path using regex: /v{number}/
|
||||
// The path is relative to the router's mount point
|
||||
const pathMatch = req.path.match(/^\/v(\d+)\//);
|
||||
|
||||
if (pathMatch) {
|
||||
const versionString = `v${pathMatch[1]}` as string;
|
||||
|
||||
if (isValidApiVersion(versionString)) {
|
||||
req.apiVersion = versionString;
|
||||
req.versionDeprecation = getVersionDeprecation(versionString);
|
||||
log.debug({ apiVersion: versionString }, 'API version extracted from path');
|
||||
return next();
|
||||
}
|
||||
|
||||
// Version number in path but not in supported list - log and use default
|
||||
log.warn(
|
||||
{
|
||||
attemptedVersion: versionString,
|
||||
supportedVersions: SUPPORTED_VERSIONS,
|
||||
path: req.path,
|
||||
},
|
||||
'Unsupported API version in path, falling back to default',
|
||||
);
|
||||
}
|
||||
|
||||
// No version detected or invalid - use default
|
||||
req.apiVersion = DEFAULT_VERSION;
|
||||
req.versionDeprecation = getVersionDeprecation(DEFAULT_VERSION);
|
||||
log.debug({ apiVersion: DEFAULT_VERSION }, 'Using default API version');
|
||||
return next();
|
||||
}
|
||||
|
||||
/**
|
||||
* Type guard to check if a request has a valid API version attached.
|
||||
*
|
||||
* @param req - Express request object
|
||||
* @returns True if req.apiVersion is set to a valid ApiVersion
|
||||
*/
|
||||
export function hasApiVersion(req: Request): req is Request & { apiVersion: ApiVersion } {
|
||||
return req.apiVersion !== undefined && isValidApiVersion(req.apiVersion);
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets the API version from a request, with a fallback to the default version.
|
||||
*
|
||||
* @param req - Express request object
|
||||
* @returns The API version from the request, or DEFAULT_VERSION if not set
|
||||
*/
|
||||
export function getRequestApiVersion(req: Request): ApiVersion {
|
||||
if (req.apiVersion && isValidApiVersion(req.apiVersion)) {
|
||||
return req.apiVersion;
|
||||
}
|
||||
return DEFAULT_VERSION;
|
||||
}
|
||||
450
src/middleware/deprecation.middleware.test.ts
Normal file
450
src/middleware/deprecation.middleware.test.ts
Normal file
@@ -0,0 +1,450 @@
|
||||
// src/middleware/deprecation.middleware.test.ts
|
||||
/**
|
||||
* @file Unit tests for deprecation header middleware.
|
||||
* Tests RFC 8594 compliant header generation for deprecated API versions.
|
||||
*
|
||||
* @see ADR-008 for API versioning strategy
|
||||
* @see docs/architecture/api-versioning-infrastructure.md
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
|
||||
import type { Request, Response } from 'express';
|
||||
import {
|
||||
addDeprecationHeaders,
|
||||
addDeprecationHeadersFromRequest,
|
||||
DEPRECATION_HEADERS,
|
||||
} from './deprecation.middleware';
|
||||
import { VERSION_CONFIGS } from '../config/apiVersions';
|
||||
import { createMockRequest } from '../tests/utils/createMockRequest';
|
||||
|
||||
// Mock the logger to avoid actual logging during tests
|
||||
vi.mock('../services/logger.server', () => ({
|
||||
createScopedLogger: vi.fn(() => ({
|
||||
debug: vi.fn(),
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
})),
|
||||
logger: {
|
||||
debug: vi.fn(),
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
child: vi.fn().mockReturnThis(),
|
||||
},
|
||||
}));
|
||||
|
||||
describe('deprecation.middleware', () => {
|
||||
// Store original VERSION_CONFIGS to restore after tests
|
||||
let originalV1Config: typeof VERSION_CONFIGS.v1;
|
||||
let originalV2Config: typeof VERSION_CONFIGS.v2;
|
||||
|
||||
let mockRequest: Request;
|
||||
let mockResponse: Partial<Response>;
|
||||
|
||||
let mockNext: any;
|
||||
|
||||
let setHeaderSpy: any;
|
||||
|
||||
beforeEach(() => {
|
||||
// Save original configs
|
||||
originalV1Config = { ...VERSION_CONFIGS.v1 };
|
||||
originalV2Config = { ...VERSION_CONFIGS.v2 };
|
||||
|
||||
// Reset mocks
|
||||
setHeaderSpy = vi.fn();
|
||||
mockRequest = createMockRequest({
|
||||
method: 'GET',
|
||||
path: '/api/v1/flyers',
|
||||
get: vi.fn().mockReturnValue('TestUserAgent/1.0'),
|
||||
});
|
||||
mockResponse = {
|
||||
set: setHeaderSpy,
|
||||
setHeader: setHeaderSpy,
|
||||
};
|
||||
mockNext = vi.fn();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Restore original configs after each test
|
||||
VERSION_CONFIGS.v1 = originalV1Config;
|
||||
VERSION_CONFIGS.v2 = originalV2Config;
|
||||
});
|
||||
|
||||
describe('addDeprecationHeaders (factory function)', () => {
|
||||
describe('with active version', () => {
|
||||
it('should always set X-API-Version header', () => {
|
||||
// Arrange - v1 is active by default
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('should not add Deprecation header for active version', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
expect(setHeaderSpy).toHaveBeenCalledTimes(1); // Only X-API-Version
|
||||
});
|
||||
|
||||
it('should not add Sunset header for active version', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.SUNSET,
|
||||
expect.anything(),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not add Link header for active version', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.LINK, expect.anything());
|
||||
});
|
||||
|
||||
it('should not set versionDeprecation on request for active version', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockRequest.versionDeprecation).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('with deprecated version', () => {
|
||||
beforeEach(() => {
|
||||
// Mark v1 as deprecated for these tests
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
});
|
||||
|
||||
it('should add Deprecation: true header', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
});
|
||||
|
||||
it('should add Sunset header with ISO 8601 date', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.SUNSET,
|
||||
'2027-01-01T00:00:00Z',
|
||||
);
|
||||
});
|
||||
|
||||
it('should add Link header with successor-version relation', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.LINK,
|
||||
'</api/v2>; rel="successor-version"',
|
||||
);
|
||||
});
|
||||
|
||||
it('should add X-API-Deprecation-Notice header', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.DEPRECATION_NOTICE,
|
||||
expect.stringContaining('deprecated'),
|
||||
);
|
||||
});
|
||||
|
||||
it('should always set X-API-Version header', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
|
||||
});
|
||||
|
||||
it('should set versionDeprecation on request', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockRequest.versionDeprecation).toBeDefined();
|
||||
expect(mockRequest.versionDeprecation?.deprecated).toBe(true);
|
||||
expect(mockRequest.versionDeprecation?.sunsetDate).toBe('2027-01-01T00:00:00Z');
|
||||
expect(mockRequest.versionDeprecation?.successorVersion).toBe('v2');
|
||||
});
|
||||
|
||||
it('should call next() to continue middleware chain', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
expect(mockNext).toHaveBeenCalledWith();
|
||||
});
|
||||
|
||||
it('should add all RFC 8594 compliant headers in correct format', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert - verify all headers are set
|
||||
const headerCalls = setHeaderSpy.mock.calls;
|
||||
const headerNames = headerCalls.map((call: unknown[]) => call[0]);
|
||||
|
||||
expect(headerNames).toContain(DEPRECATION_HEADERS.API_VERSION);
|
||||
expect(headerNames).toContain(DEPRECATION_HEADERS.DEPRECATION);
|
||||
expect(headerNames).toContain(DEPRECATION_HEADERS.SUNSET);
|
||||
expect(headerNames).toContain(DEPRECATION_HEADERS.LINK);
|
||||
expect(headerNames).toContain(DEPRECATION_HEADERS.DEPRECATION_NOTICE);
|
||||
});
|
||||
});
|
||||
|
||||
describe('with deprecated version missing optional fields', () => {
|
||||
beforeEach(() => {
|
||||
// Mark v1 as deprecated without sunset date or successor
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
// No sunsetDate or successorVersion
|
||||
};
|
||||
});
|
||||
|
||||
it('should add Deprecation header even without sunset date', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
});
|
||||
|
||||
it('should not add Sunset header when sunsetDate is not configured', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.SUNSET,
|
||||
expect.anything(),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not add Link header when successorVersion is not configured', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.LINK, expect.anything());
|
||||
});
|
||||
});
|
||||
|
||||
describe('with v2 version', () => {
|
||||
it('should set X-API-Version: v2 header', () => {
|
||||
// Arrange
|
||||
const middleware = addDeprecationHeaders('v2');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v2');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('addDeprecationHeadersFromRequest', () => {
|
||||
describe('when apiVersion is set on request', () => {
|
||||
it('should add headers based on request apiVersion', () => {
|
||||
// Arrange
|
||||
mockRequest.apiVersion = 'v1';
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-06-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
|
||||
// Act
|
||||
addDeprecationHeadersFromRequest(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(
|
||||
DEPRECATION_HEADERS.SUNSET,
|
||||
'2027-06-01T00:00:00Z',
|
||||
);
|
||||
});
|
||||
|
||||
it('should not add deprecation headers for active version', () => {
|
||||
// Arrange
|
||||
mockRequest.apiVersion = 'v2';
|
||||
|
||||
// Act
|
||||
addDeprecationHeadersFromRequest(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v2');
|
||||
expect(setHeaderSpy).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('when apiVersion is not set on request', () => {
|
||||
it('should skip header processing and call next', () => {
|
||||
// Arrange
|
||||
mockRequest.apiVersion = undefined;
|
||||
|
||||
// Act
|
||||
addDeprecationHeadersFromRequest(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert
|
||||
expect(setHeaderSpy).not.toHaveBeenCalled();
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('DEPRECATION_HEADERS constants', () => {
|
||||
it('should have correct header names', () => {
|
||||
expect(DEPRECATION_HEADERS.DEPRECATION).toBe('Deprecation');
|
||||
expect(DEPRECATION_HEADERS.SUNSET).toBe('Sunset');
|
||||
expect(DEPRECATION_HEADERS.LINK).toBe('Link');
|
||||
expect(DEPRECATION_HEADERS.DEPRECATION_NOTICE).toBe('X-API-Deprecation-Notice');
|
||||
expect(DEPRECATION_HEADERS.API_VERSION).toBe('X-API-Version');
|
||||
});
|
||||
});
|
||||
|
||||
describe('edge cases', () => {
|
||||
it('should handle sunset version status', () => {
|
||||
// Arrange
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'sunset',
|
||||
sunsetDate: '2026-01-01T00:00:00Z',
|
||||
};
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert - sunset is different from deprecated, so no deprecation headers
|
||||
// Only X-API-Version should be set
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
|
||||
expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
});
|
||||
|
||||
it('should handle request with existing log object', () => {
|
||||
// Arrange
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
const mockLogWithBindings = {
|
||||
debug: vi.fn(),
|
||||
bindings: vi.fn().mockReturnValue({ request_id: 'test-request-id' }),
|
||||
};
|
||||
mockRequest.log = mockLogWithBindings as unknown as Request['log'];
|
||||
const middleware = addDeprecationHeaders('v1');
|
||||
|
||||
// Act
|
||||
middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert - should not throw and should complete
|
||||
expect(mockNext).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('should work with different versions in sequence', () => {
|
||||
// Arrange
|
||||
VERSION_CONFIGS.v1 = {
|
||||
version: 'v1',
|
||||
status: 'deprecated',
|
||||
sunsetDate: '2027-01-01T00:00:00Z',
|
||||
successorVersion: 'v2',
|
||||
};
|
||||
const v1Middleware = addDeprecationHeaders('v1');
|
||||
const v2Middleware = addDeprecationHeaders('v2');
|
||||
|
||||
// Act
|
||||
v1Middleware(mockRequest, mockResponse as Response, mockNext);
|
||||
|
||||
// Reset for v2
|
||||
setHeaderSpy.mockClear();
|
||||
mockNext.mockClear();
|
||||
const mockRequest2 = createMockRequest({
|
||||
method: 'GET',
|
||||
path: '/api/v2/flyers',
|
||||
});
|
||||
|
||||
v2Middleware(mockRequest2, mockResponse as Response, mockNext);
|
||||
|
||||
// Assert - v2 should only have API version header
|
||||
expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v2');
|
||||
expect(setHeaderSpy).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
});
|
||||
218
src/middleware/deprecation.middleware.ts
Normal file
218
src/middleware/deprecation.middleware.ts
Normal file
@@ -0,0 +1,218 @@
|
||||
// src/middleware/deprecation.middleware.ts
|
||||
/**
|
||||
* @file Deprecation Headers Middleware - RFC 8594 Compliant
|
||||
* Implements ADR-008 Phase 2: API Versioning Infrastructure.
|
||||
*
|
||||
* This middleware adds standard deprecation headers to API responses when
|
||||
* a deprecated API version is being accessed. It follows:
|
||||
* - RFC 8594: The "Sunset" HTTP Header Field
|
||||
* - draft-ietf-httpapi-deprecation-header: The "Deprecation" HTTP Header Field
|
||||
* - RFC 8288: Web Linking (for successor-version relation)
|
||||
*
|
||||
* Headers added for deprecated versions:
|
||||
* - `Deprecation: true` - Indicates the endpoint is deprecated
|
||||
* - `Sunset: <ISO 8601 date>` - When the endpoint will be removed
|
||||
* - `Link: </api/vX>; rel="successor-version"` - URL to the replacement version
|
||||
* - `X-API-Deprecation-Notice: <message>` - Human-readable deprecation message
|
||||
*
|
||||
* Always added (for all versions):
|
||||
* - `X-API-Version: <version>` - The API version being accessed
|
||||
*
|
||||
* @see docs/architecture/api-versioning-infrastructure.md
|
||||
* @see https://datatracker.ietf.org/doc/html/rfc8594
|
||||
*/
|
||||
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import { ApiVersion, VERSION_CONFIGS, getVersionDeprecation } from '../config/apiVersions';
|
||||
import { createScopedLogger } from '../services/logger.server';
|
||||
|
||||
// Create a module-scoped logger for deprecation tracking
|
||||
const deprecationLogger = createScopedLogger('deprecation-middleware');
|
||||
|
||||
/**
|
||||
* HTTP header names for deprecation signaling.
|
||||
* Using constants to ensure consistency and prevent typos.
|
||||
*/
|
||||
export const DEPRECATION_HEADERS = {
|
||||
/** RFC draft-ietf-httpapi-deprecation-header: Indicates deprecation status */
|
||||
DEPRECATION: 'Deprecation',
|
||||
/** RFC 8594: ISO 8601 date when the endpoint will be removed */
|
||||
SUNSET: 'Sunset',
|
||||
/** RFC 8288: Link to successor version with rel="successor-version" */
|
||||
LINK: 'Link',
|
||||
/** Custom header: Human-readable deprecation notice */
|
||||
DEPRECATION_NOTICE: 'X-API-Deprecation-Notice',
|
||||
/** Custom header: Current API version being accessed */
|
||||
API_VERSION: 'X-API-Version',
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Creates middleware that adds RFC 8594 compliant deprecation headers
|
||||
* to responses when a deprecated API version is accessed.
|
||||
*
|
||||
* This is a middleware factory function that takes a version parameter
|
||||
* and returns the configured middleware function. This pattern allows
|
||||
* different version routers to have their own deprecation configuration.
|
||||
*
|
||||
* @param version - The API version this middleware is handling
|
||||
* @returns Express middleware function that adds appropriate headers
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // In a versioned router factory:
|
||||
* const v1Router = Router();
|
||||
* v1Router.use(addDeprecationHeaders('v1'));
|
||||
*
|
||||
* // When v1 is deprecated, responses will include:
|
||||
* // Deprecation: true
|
||||
* // Sunset: 2027-01-01T00:00:00Z
|
||||
* // Link: </api/v2>; rel="successor-version"
|
||||
* // X-API-Deprecation-Notice: API v1 is deprecated...
|
||||
* // X-API-Version: v1
|
||||
* ```
|
||||
*/
|
||||
export function addDeprecationHeaders(version: ApiVersion) {
|
||||
// Pre-fetch configuration at middleware creation time for efficiency.
|
||||
// This avoids repeated lookups on every request.
|
||||
const config = VERSION_CONFIGS[version];
|
||||
const deprecationInfo = getVersionDeprecation(version);
|
||||
|
||||
return function deprecationHeadersMiddleware(
|
||||
req: Request,
|
||||
res: Response,
|
||||
next: NextFunction,
|
||||
): void {
|
||||
// Always set the API version header for transparency and debugging.
|
||||
// This helps clients know which version they're using, especially
|
||||
// useful when default version routing is in effect.
|
||||
res.set(DEPRECATION_HEADERS.API_VERSION, version);
|
||||
|
||||
// Only add deprecation headers if this version is actually deprecated.
|
||||
// Active versions should not have any deprecation headers.
|
||||
if (config.status === 'deprecated') {
|
||||
// RFC draft-ietf-httpapi-deprecation-header: Set to "true" to indicate deprecation
|
||||
res.set(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
|
||||
// RFC 8594: Sunset header with ISO 8601 date indicating removal date
|
||||
if (config.sunsetDate) {
|
||||
res.set(DEPRECATION_HEADERS.SUNSET, config.sunsetDate);
|
||||
}
|
||||
|
||||
// RFC 8288: Link header with successor-version relation
|
||||
// This tells clients where to migrate to
|
||||
if (config.successorVersion) {
|
||||
res.set(
|
||||
DEPRECATION_HEADERS.LINK,
|
||||
`</api/${config.successorVersion}>; rel="successor-version"`,
|
||||
);
|
||||
}
|
||||
|
||||
// Custom header: Human-readable message for developers
|
||||
// This provides context that may not be obvious from the standard headers
|
||||
if (deprecationInfo.message) {
|
||||
res.set(DEPRECATION_HEADERS.DEPRECATION_NOTICE, deprecationInfo.message);
|
||||
}
|
||||
|
||||
// Attach deprecation info to the request for use in route handlers.
|
||||
// This allows handlers to implement version-specific behavior or logging.
|
||||
req.versionDeprecation = deprecationInfo;
|
||||
|
||||
// Log deprecation access at debug level to avoid log spam.
|
||||
// This provides visibility into deprecated API usage without overwhelming logs.
|
||||
// Use debug level because high-traffic APIs could generate significant volume.
|
||||
// Production monitoring should use the access logs or metrics aggregation
|
||||
// to track deprecation usage patterns.
|
||||
deprecationLogger.debug(
|
||||
{
|
||||
apiVersion: version,
|
||||
method: req.method,
|
||||
path: req.path,
|
||||
sunsetDate: config.sunsetDate,
|
||||
successorVersion: config.successorVersion,
|
||||
userAgent: req.get('User-Agent'),
|
||||
// Include request ID if available from the request logger
|
||||
requestId: (req.log as { bindings?: () => { request_id?: string } })?.bindings?.()
|
||||
?.request_id,
|
||||
},
|
||||
'Deprecated API version accessed',
|
||||
);
|
||||
}
|
||||
|
||||
next();
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Standalone middleware for adding deprecation headers based on
|
||||
* the `apiVersion` property already set on the request.
|
||||
*
|
||||
* This middleware should be used after the version extraction middleware
|
||||
* has set `req.apiVersion`. It provides a more flexible approach when
|
||||
* the version is determined dynamically rather than statically.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // After version extraction middleware:
|
||||
* router.use(extractApiVersion);
|
||||
* router.use(addDeprecationHeadersFromRequest);
|
||||
* ```
|
||||
*/
|
||||
export function addDeprecationHeadersFromRequest(
|
||||
req: Request,
|
||||
res: Response,
|
||||
next: NextFunction,
|
||||
): void {
|
||||
const version = req.apiVersion;
|
||||
|
||||
// If no version is set on the request, skip deprecation handling.
|
||||
// This should not happen if the version extraction middleware ran first,
|
||||
// but we handle it gracefully for safety.
|
||||
if (!version) {
|
||||
next();
|
||||
return;
|
||||
}
|
||||
|
||||
const config = VERSION_CONFIGS[version];
|
||||
const deprecationInfo = getVersionDeprecation(version);
|
||||
|
||||
// Always set the API version header
|
||||
res.set(DEPRECATION_HEADERS.API_VERSION, version);
|
||||
|
||||
// Add deprecation headers if version is deprecated
|
||||
if (config.status === 'deprecated') {
|
||||
res.set(DEPRECATION_HEADERS.DEPRECATION, 'true');
|
||||
|
||||
if (config.sunsetDate) {
|
||||
res.set(DEPRECATION_HEADERS.SUNSET, config.sunsetDate);
|
||||
}
|
||||
|
||||
if (config.successorVersion) {
|
||||
res.set(
|
||||
DEPRECATION_HEADERS.LINK,
|
||||
`</api/${config.successorVersion}>; rel="successor-version"`,
|
||||
);
|
||||
}
|
||||
|
||||
if (deprecationInfo.message) {
|
||||
res.set(DEPRECATION_HEADERS.DEPRECATION_NOTICE, deprecationInfo.message);
|
||||
}
|
||||
|
||||
req.versionDeprecation = deprecationInfo;
|
||||
|
||||
deprecationLogger.debug(
|
||||
{
|
||||
apiVersion: version,
|
||||
method: req.method,
|
||||
path: req.path,
|
||||
sunsetDate: config.sunsetDate,
|
||||
successorVersion: config.successorVersion,
|
||||
userAgent: req.get('User-Agent'),
|
||||
requestId: (req.log as { bindings?: () => { request_id?: string } })?.bindings?.()
|
||||
?.request_id,
|
||||
},
|
||||
'Deprecated API version accessed',
|
||||
);
|
||||
}
|
||||
|
||||
next();
|
||||
}
|
||||
478
src/pages/DealsPage.test.tsx
Normal file
478
src/pages/DealsPage.test.tsx
Normal file
@@ -0,0 +1,478 @@
|
||||
// src/pages/DealsPage.test.tsx
|
||||
import React from 'react';
|
||||
import { render, screen } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
|
||||
import { DealsPage } from './DealsPage';
|
||||
import { useAuth } from '../hooks/useAuth';
|
||||
import { useWatchedItems } from '../hooks/useWatchedItems';
|
||||
import { useShoppingLists } from '../hooks/useShoppingLists';
|
||||
import {
|
||||
createMockUser,
|
||||
createMockUserProfile,
|
||||
createMockMasterGroceryItem,
|
||||
createMockShoppingList,
|
||||
resetMockIds,
|
||||
} from '../tests/utils/mockFactories';
|
||||
import type { MasterGroceryItem, ShoppingList } from '../types';
|
||||
|
||||
// Mock the hooks that DealsPage depends on
|
||||
vi.mock('../hooks/useAuth');
|
||||
vi.mock('../hooks/useWatchedItems');
|
||||
vi.mock('../hooks/useShoppingLists');
|
||||
|
||||
// Mock the child components to isolate DealsPage logic
|
||||
vi.mock('../features/shopping/WatchedItemsList', () => ({
|
||||
WatchedItemsList: vi.fn(({ items, user, activeListId }) => (
|
||||
<div data-testid="watched-items-list">
|
||||
<span data-testid="watched-items-count">{items?.length ?? 0} items</span>
|
||||
<span data-testid="watched-items-user">{user ? 'logged-in' : 'logged-out'}</span>
|
||||
<span data-testid="watched-items-active-list">{activeListId ?? 'none'}</span>
|
||||
</div>
|
||||
)),
|
||||
}));
|
||||
|
||||
vi.mock('../features/charts/PriceChart', () => ({
|
||||
PriceChart: vi.fn(({ unitSystem, user }) => (
|
||||
<div data-testid="price-chart">
|
||||
<span data-testid="price-chart-unit-system">{unitSystem}</span>
|
||||
<span data-testid="price-chart-user">{user ? 'logged-in' : 'logged-out'}</span>
|
||||
</div>
|
||||
)),
|
||||
}));
|
||||
|
||||
vi.mock('../features/charts/PriceHistoryChart', () => ({
|
||||
PriceHistoryChart: vi.fn(() => <div data-testid="price-history-chart">Price History Chart</div>),
|
||||
}));
|
||||
|
||||
// Cast the mocked hooks for type-safe assertions
|
||||
const mockedUseAuth = useAuth as Mock;
|
||||
const mockedUseWatchedItems = useWatchedItems as Mock;
|
||||
const mockedUseShoppingLists = useShoppingLists as Mock;
|
||||
|
||||
describe('DealsPage Component', () => {
|
||||
// Create mock data
|
||||
const mockUser = createMockUser({ user_id: 'user-123', email: 'test@example.com' });
|
||||
const mockUserProfile = createMockUserProfile({ user: mockUser });
|
||||
|
||||
const mockWatchedItems: MasterGroceryItem[] = [
|
||||
createMockMasterGroceryItem({ master_grocery_item_id: 1, name: 'Apples' }),
|
||||
createMockMasterGroceryItem({ master_grocery_item_id: 2, name: 'Bananas' }),
|
||||
];
|
||||
|
||||
const mockShoppingLists: ShoppingList[] = [
|
||||
createMockShoppingList({ shopping_list_id: 101, name: 'Weekly Groceries' }),
|
||||
createMockShoppingList({ shopping_list_id: 102, name: 'Party Shopping' }),
|
||||
];
|
||||
|
||||
// Mock function implementations
|
||||
const mockAddWatchedItem = vi.fn();
|
||||
const mockRemoveWatchedItem = vi.fn();
|
||||
const mockAddItemToList = vi.fn();
|
||||
const mockSetActiveListId = vi.fn();
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
resetMockIds();
|
||||
|
||||
// Set up default mock implementations for authenticated user with data
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: mockUserProfile,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
mockedUseWatchedItems.mockReturnValue({
|
||||
watchedItems: mockWatchedItems,
|
||||
addWatchedItem: mockAddWatchedItem,
|
||||
removeWatchedItem: mockRemoveWatchedItem,
|
||||
error: null,
|
||||
});
|
||||
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
shoppingLists: mockShoppingLists,
|
||||
activeListId: 101,
|
||||
setActiveListId: mockSetActiveListId,
|
||||
createList: vi.fn(),
|
||||
deleteList: vi.fn(),
|
||||
addItemToList: mockAddItemToList,
|
||||
updateItemInList: vi.fn(),
|
||||
removeItemFromList: vi.fn(),
|
||||
isCreatingList: false,
|
||||
isDeletingList: false,
|
||||
isAddingItem: false,
|
||||
isUpdatingItem: false,
|
||||
isRemovingItem: false,
|
||||
error: null,
|
||||
});
|
||||
});
|
||||
|
||||
describe('Page Rendering', () => {
|
||||
it('should render the page title', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(
|
||||
screen.getByRole('heading', { name: /my deals & watched items/i }),
|
||||
).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render all three main components', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('watched-items-list')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('price-chart')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('price-history-chart')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should apply correct layout classes for max width and spacing', () => {
|
||||
const { container } = render(<DealsPage />);
|
||||
|
||||
const mainContainer = container.firstChild as HTMLElement;
|
||||
expect(mainContainer).toHaveClass('max-w-4xl');
|
||||
expect(mainContainer).toHaveClass('mx-auto');
|
||||
expect(mainContainer).toHaveClass('p-4');
|
||||
expect(mainContainer).toHaveClass('space-y-6');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Props Passing to WatchedItemsList', () => {
|
||||
it('should pass watched items to WatchedItemsList', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('watched-items-count')).toHaveTextContent('2 items');
|
||||
});
|
||||
|
||||
it('should pass user to WatchedItemsList when authenticated', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('watched-items-user')).toHaveTextContent('logged-in');
|
||||
});
|
||||
|
||||
it('should pass null user to WatchedItemsList when not authenticated', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: null,
|
||||
authStatus: 'SIGNED_OUT',
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('watched-items-user')).toHaveTextContent('logged-out');
|
||||
});
|
||||
|
||||
it('should pass activeListId to WatchedItemsList', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('watched-items-active-list')).toHaveTextContent('101');
|
||||
});
|
||||
|
||||
it('should pass "none" when no active list is selected', () => {
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
...mockedUseShoppingLists(),
|
||||
activeListId: null,
|
||||
});
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('watched-items-active-list')).toHaveTextContent('none');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Props Passing to PriceChart', () => {
|
||||
it('should pass imperial unit system to PriceChart', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('price-chart-unit-system')).toHaveTextContent('imperial');
|
||||
});
|
||||
|
||||
it('should pass user to PriceChart when authenticated', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('price-chart-user')).toHaveTextContent('logged-in');
|
||||
});
|
||||
|
||||
it('should pass null user to PriceChart when not authenticated', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: null,
|
||||
authStatus: 'SIGNED_OUT',
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('price-chart-user')).toHaveTextContent('logged-out');
|
||||
});
|
||||
});
|
||||
|
||||
describe('User Authentication States', () => {
|
||||
it('should render correctly when user is authenticated', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
// Both components should receive the user
|
||||
expect(screen.getByTestId('watched-items-user')).toHaveTextContent('logged-in');
|
||||
expect(screen.getByTestId('price-chart-user')).toHaveTextContent('logged-in');
|
||||
});
|
||||
|
||||
it('should render correctly when user is not authenticated', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: null,
|
||||
authStatus: 'SIGNED_OUT',
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
// Both components should receive null user
|
||||
expect(screen.getByTestId('watched-items-user')).toHaveTextContent('logged-out');
|
||||
expect(screen.getByTestId('price-chart-user')).toHaveTextContent('logged-out');
|
||||
});
|
||||
|
||||
it('should handle undefined user within userProfile gracefully', () => {
|
||||
// Edge case where userProfile exists but user is undefined
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: { ...mockUserProfile, user: undefined },
|
||||
authStatus: 'AUTHENTICATED',
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
// Should treat undefined user as logged out
|
||||
expect(screen.getByTestId('watched-items-user')).toHaveTextContent('logged-out');
|
||||
expect(screen.getByTestId('price-chart-user')).toHaveTextContent('logged-out');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Watched Items Data States', () => {
|
||||
it('should render with empty watched items list', () => {
|
||||
mockedUseWatchedItems.mockReturnValue({
|
||||
watchedItems: [],
|
||||
addWatchedItem: mockAddWatchedItem,
|
||||
removeWatchedItem: mockRemoveWatchedItem,
|
||||
error: null,
|
||||
});
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('watched-items-count')).toHaveTextContent('0 items');
|
||||
});
|
||||
|
||||
it('should render with multiple watched items', () => {
|
||||
const manyItems = Array.from({ length: 10 }, (_, i) =>
|
||||
createMockMasterGroceryItem({
|
||||
master_grocery_item_id: i + 1,
|
||||
name: `Item ${i + 1}`,
|
||||
}),
|
||||
);
|
||||
|
||||
mockedUseWatchedItems.mockReturnValue({
|
||||
watchedItems: manyItems,
|
||||
addWatchedItem: mockAddWatchedItem,
|
||||
removeWatchedItem: mockRemoveWatchedItem,
|
||||
error: null,
|
||||
});
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('watched-items-count')).toHaveTextContent('10 items');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Shopping Lists Data States', () => {
|
||||
it('should render when no shopping lists exist', () => {
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
...mockedUseShoppingLists(),
|
||||
shoppingLists: [],
|
||||
activeListId: null,
|
||||
});
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('watched-items-active-list')).toHaveTextContent('none');
|
||||
});
|
||||
|
||||
it('should render when shopping lists exist but none is active', () => {
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
...mockedUseShoppingLists(),
|
||||
activeListId: null,
|
||||
});
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(screen.getByTestId('watched-items-active-list')).toHaveTextContent('none');
|
||||
});
|
||||
});
|
||||
|
||||
describe('handleAddItemFromWatchedList Function', () => {
|
||||
it('should call addItemToList with correct parameters when activeListId exists', async () => {
|
||||
// Import the mocked component to access its props
|
||||
const { WatchedItemsList } = await import('../features/shopping/WatchedItemsList');
|
||||
const MockedWatchedItemsList = vi.mocked(WatchedItemsList);
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
// Get the onAddItemToList prop passed to WatchedItemsList
|
||||
const lastCall =
|
||||
MockedWatchedItemsList.mock.calls[MockedWatchedItemsList.mock.calls.length - 1];
|
||||
const onAddItemToList = lastCall[0].onAddItemToList;
|
||||
|
||||
// Simulate calling the handler with a master item ID
|
||||
onAddItemToList(42);
|
||||
|
||||
// Verify addItemToList was called with the active list ID and master item ID
|
||||
expect(mockAddItemToList).toHaveBeenCalledTimes(1);
|
||||
expect(mockAddItemToList).toHaveBeenCalledWith(101, { masterItemId: 42 });
|
||||
});
|
||||
|
||||
it('should not call addItemToList when activeListId is null', async () => {
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
...mockedUseShoppingLists(),
|
||||
activeListId: null,
|
||||
addItemToList: mockAddItemToList,
|
||||
});
|
||||
|
||||
const { WatchedItemsList } = await import('../features/shopping/WatchedItemsList');
|
||||
const MockedWatchedItemsList = vi.mocked(WatchedItemsList);
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
// Get the onAddItemToList prop passed to WatchedItemsList
|
||||
const lastCall =
|
||||
MockedWatchedItemsList.mock.calls[MockedWatchedItemsList.mock.calls.length - 1];
|
||||
const onAddItemToList = lastCall[0].onAddItemToList;
|
||||
|
||||
// Simulate calling the handler with a master item ID
|
||||
onAddItemToList(42);
|
||||
|
||||
// Verify addItemToList was NOT called because there's no active list
|
||||
expect(mockAddItemToList).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Callback Props Verification', () => {
|
||||
it('should pass addWatchedItem function to WatchedItemsList', async () => {
|
||||
const { WatchedItemsList } = await import('../features/shopping/WatchedItemsList');
|
||||
const MockedWatchedItemsList = vi.mocked(WatchedItemsList);
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
const lastCall =
|
||||
MockedWatchedItemsList.mock.calls[MockedWatchedItemsList.mock.calls.length - 1];
|
||||
expect(lastCall[0].onAddItem).toBe(mockAddWatchedItem);
|
||||
});
|
||||
|
||||
it('should pass removeWatchedItem function to WatchedItemsList', async () => {
|
||||
const { WatchedItemsList } = await import('../features/shopping/WatchedItemsList');
|
||||
const MockedWatchedItemsList = vi.mocked(WatchedItemsList);
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
const lastCall =
|
||||
MockedWatchedItemsList.mock.calls[MockedWatchedItemsList.mock.calls.length - 1];
|
||||
expect(lastCall[0].onRemoveItem).toBe(mockRemoveWatchedItem);
|
||||
});
|
||||
});
|
||||
|
||||
describe('Component Structure', () => {
|
||||
it('should render components in the correct order', () => {
|
||||
const { container } = render(<DealsPage />);
|
||||
|
||||
const mainContainer = container.firstChild as HTMLElement;
|
||||
const children = Array.from(mainContainer.children);
|
||||
|
||||
// First child should be the heading
|
||||
expect(children[0].tagName).toBe('H1');
|
||||
expect(children[0]).toHaveTextContent(/my deals & watched items/i);
|
||||
|
||||
// Subsequent children are the three main components
|
||||
// (indices may vary based on actual DOM structure)
|
||||
expect(screen.getByTestId('watched-items-list')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('price-chart')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('price-history-chart')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should have proper heading styling', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
const heading = screen.getByRole('heading', { name: /my deals & watched items/i });
|
||||
expect(heading).toHaveClass('text-3xl');
|
||||
expect(heading).toHaveClass('font-bold');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Edge Cases', () => {
|
||||
it('should handle userProfile with null user property', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: { ...mockUserProfile, user: null } as unknown,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
render(<DealsPage />);
|
||||
|
||||
// Should render without crashing and treat user as null
|
||||
expect(screen.getByTestId('watched-items-list')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('watched-items-user')).toHaveTextContent('logged-out');
|
||||
});
|
||||
|
||||
it('should handle undefined watchedItems gracefully', () => {
|
||||
mockedUseWatchedItems.mockReturnValue({
|
||||
watchedItems: undefined,
|
||||
addWatchedItem: mockAddWatchedItem,
|
||||
removeWatchedItem: mockRemoveWatchedItem,
|
||||
error: null,
|
||||
});
|
||||
|
||||
// This should not throw an error - the component should handle undefined
|
||||
render(<DealsPage />);
|
||||
|
||||
// The mock will receive undefined and show "0 items" or handle it
|
||||
expect(screen.getByTestId('watched-items-list')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render PriceHistoryChart without any props', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
// PriceHistoryChart doesn't take props from DealsPage
|
||||
expect(screen.getByTestId('price-history-chart')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('price-history-chart')).toHaveTextContent('Price History Chart');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Hook Integration', () => {
|
||||
it('should call useAuth hook', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(mockedUseAuth).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should call useWatchedItems hook', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(mockedUseWatchedItems).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should call useShoppingLists hook', () => {
|
||||
render(<DealsPage />);
|
||||
|
||||
expect(mockedUseShoppingLists).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
});
|
||||
564
src/pages/FlyersPage.test.tsx
Normal file
564
src/pages/FlyersPage.test.tsx
Normal file
@@ -0,0 +1,564 @@
|
||||
// src/pages/FlyersPage.test.tsx
|
||||
import React from 'react';
|
||||
import { render, screen, fireEvent, within } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { MemoryRouter } from 'react-router-dom';
|
||||
import { FlyersPage } from './FlyersPage';
|
||||
import { createMockFlyer, createMockUserProfile, resetMockIds } from '../tests/utils/mockFactories';
|
||||
import type { Flyer, UserProfile } from '../types';
|
||||
|
||||
// Unmock the component to test the real implementation
|
||||
vi.unmock('./FlyersPage');
|
||||
|
||||
// Mock the hooks used by FlyersPage
|
||||
const mockUseAuth = vi.fn();
|
||||
const mockUseFlyers = vi.fn();
|
||||
const mockUseFlyerSelection = vi.fn();
|
||||
|
||||
vi.mock('../hooks/useAuth', () => ({
|
||||
useAuth: () => mockUseAuth(),
|
||||
}));
|
||||
|
||||
vi.mock('../hooks/useFlyers', () => ({
|
||||
useFlyers: () => mockUseFlyers(),
|
||||
}));
|
||||
|
||||
vi.mock('../hooks/useFlyerSelection', () => ({
|
||||
useFlyerSelection: (options: { flyers: Flyer[] }) => mockUseFlyerSelection(options),
|
||||
}));
|
||||
|
||||
// Mock child components to isolate the FlyersPage logic
|
||||
vi.mock('../features/flyer/FlyerList', async () => {
|
||||
const { MockFlyerList } = await import('../tests/utils/componentMocks');
|
||||
return { FlyerList: MockFlyerList };
|
||||
});
|
||||
|
||||
vi.mock('../features/flyer/FlyerUploader', async () => {
|
||||
const { MockFlyerUploader } = await import('../tests/utils/componentMocks');
|
||||
return { FlyerUploader: MockFlyerUploader };
|
||||
});
|
||||
|
||||
// Mock the logger to prevent console output during tests
|
||||
vi.mock('../services/logger.client', () => ({
|
||||
logger: {
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
debug: vi.fn(),
|
||||
},
|
||||
}));
|
||||
|
||||
describe('FlyersPage Component', () => {
|
||||
// Default mock implementations
|
||||
const mockRefetchFlyers = vi.fn();
|
||||
const mockHandleFlyerSelect = vi.fn();
|
||||
|
||||
const defaultAuthReturn = {
|
||||
userProfile: null as UserProfile | null,
|
||||
authStatus: 'SIGNED_OUT' as const,
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
};
|
||||
|
||||
const defaultFlyersReturn = {
|
||||
flyers: [] as Flyer[],
|
||||
isLoadingFlyers: false,
|
||||
flyersError: null,
|
||||
fetchNextFlyersPage: vi.fn(),
|
||||
hasNextFlyersPage: false,
|
||||
isRefetchingFlyers: false,
|
||||
refetchFlyers: mockRefetchFlyers,
|
||||
};
|
||||
|
||||
const defaultSelectionReturn = {
|
||||
selectedFlyer: null as Flyer | null,
|
||||
handleFlyerSelect: mockHandleFlyerSelect,
|
||||
flyerIdFromUrl: undefined,
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
resetMockIds();
|
||||
|
||||
// Set up default mock implementations
|
||||
mockUseAuth.mockReturnValue(defaultAuthReturn);
|
||||
mockUseFlyers.mockReturnValue(defaultFlyersReturn);
|
||||
mockUseFlyerSelection.mockReturnValue(defaultSelectionReturn);
|
||||
});
|
||||
|
||||
const renderPage = () => {
|
||||
return render(
|
||||
<MemoryRouter>
|
||||
<FlyersPage />
|
||||
</MemoryRouter>,
|
||||
);
|
||||
};
|
||||
|
||||
describe('Basic Rendering', () => {
|
||||
it('should render the page title', () => {
|
||||
renderPage();
|
||||
|
||||
expect(screen.getByRole('heading', { name: /flyers/i, level: 1 })).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render the FlyerList component', () => {
|
||||
renderPage();
|
||||
|
||||
expect(screen.getByTestId('flyer-list')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render the FlyerUploader component', () => {
|
||||
renderPage();
|
||||
|
||||
expect(screen.getByTestId('flyer-uploader')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should have the correct page structure with spacing', () => {
|
||||
const { container } = renderPage();
|
||||
|
||||
// Check for the main container with styling classes
|
||||
const mainDiv = container.querySelector('.max-w-4xl');
|
||||
expect(mainDiv).toBeInTheDocument();
|
||||
expect(mainDiv).toHaveClass('mx-auto', 'p-4', 'space-y-6');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Empty State (No Flyers)', () => {
|
||||
it('should show empty message when there are no flyers', () => {
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: [],
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
expect(flyerList).toHaveAttribute('data-flyer-count', '0');
|
||||
expect(screen.getByTestId('no-flyers-message')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('With Flyers Data', () => {
|
||||
const mockFlyers: Flyer[] = [
|
||||
createMockFlyer({
|
||||
flyer_id: 1,
|
||||
store: { store_id: 1, name: 'Safeway', created_at: '', updated_at: '' },
|
||||
item_count: 25,
|
||||
}),
|
||||
createMockFlyer({
|
||||
flyer_id: 2,
|
||||
store: { store_id: 2, name: 'Walmart', created_at: '', updated_at: '' },
|
||||
item_count: 40,
|
||||
}),
|
||||
createMockFlyer({
|
||||
flyer_id: 3,
|
||||
store: { store_id: 3, name: 'Costco', created_at: '', updated_at: '' },
|
||||
item_count: 60,
|
||||
}),
|
||||
];
|
||||
|
||||
it('should pass flyers to FlyerList component', () => {
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
expect(flyerList).toHaveAttribute('data-flyer-count', '3');
|
||||
});
|
||||
|
||||
it('should render all flyer items', () => {
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
expect(screen.getByTestId('flyer-item-1')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('flyer-item-2')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('flyer-item-3')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should display store names in flyer list', () => {
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
expect(screen.getByText(/Safeway - 25 items/)).toBeInTheDocument();
|
||||
expect(screen.getByText(/Walmart - 40 items/)).toBeInTheDocument();
|
||||
expect(screen.getByText(/Costco - 60 items/)).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Flyer Selection', () => {
|
||||
const mockFlyers: Flyer[] = [
|
||||
createMockFlyer({
|
||||
flyer_id: 1,
|
||||
store: { store_id: 1, name: 'Safeway', created_at: '', updated_at: '' },
|
||||
item_count: 25,
|
||||
}),
|
||||
createMockFlyer({
|
||||
flyer_id: 2,
|
||||
store: { store_id: 2, name: 'Walmart', created_at: '', updated_at: '' },
|
||||
item_count: 40,
|
||||
}),
|
||||
];
|
||||
|
||||
it('should pass selectedFlyerId to FlyerList when a flyer is selected', () => {
|
||||
const selectedFlyer = mockFlyers[0];
|
||||
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
mockUseFlyerSelection.mockReturnValue({
|
||||
...defaultSelectionReturn,
|
||||
selectedFlyer,
|
||||
handleFlyerSelect: mockHandleFlyerSelect,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
expect(flyerList).toHaveAttribute('data-selected-id', '1');
|
||||
});
|
||||
|
||||
it('should pass null selectedFlyerId when no flyer is selected', () => {
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
mockUseFlyerSelection.mockReturnValue({
|
||||
...defaultSelectionReturn,
|
||||
selectedFlyer: null,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
expect(flyerList).toHaveAttribute('data-selected-id', 'none');
|
||||
});
|
||||
|
||||
it('should call handleFlyerSelect when a flyer is clicked', () => {
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerItem = screen.getByTestId('flyer-item-1');
|
||||
const selectButton = within(flyerItem).getByRole('button');
|
||||
fireEvent.click(selectButton);
|
||||
|
||||
expect(mockHandleFlyerSelect).toHaveBeenCalledTimes(1);
|
||||
expect(mockHandleFlyerSelect).toHaveBeenCalledWith(mockFlyers[0]);
|
||||
});
|
||||
|
||||
it('should call useFlyerSelection with the correct flyers', () => {
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
expect(mockUseFlyerSelection).toHaveBeenCalledWith({ flyers: mockFlyers });
|
||||
});
|
||||
});
|
||||
|
||||
describe('User Authentication States', () => {
|
||||
const mockFlyers: Flyer[] = [
|
||||
createMockFlyer({
|
||||
flyer_id: 1,
|
||||
store: { store_id: 1, name: 'Safeway', created_at: '', updated_at: '' },
|
||||
item_count: 25,
|
||||
}),
|
||||
];
|
||||
|
||||
it('should pass null profile to FlyerList when user is not authenticated', () => {
|
||||
mockUseAuth.mockReturnValue({
|
||||
...defaultAuthReturn,
|
||||
userProfile: null,
|
||||
authStatus: 'SIGNED_OUT',
|
||||
});
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
expect(flyerList).toHaveAttribute('data-profile-role', 'none');
|
||||
});
|
||||
|
||||
it('should pass user profile to FlyerList when user is authenticated', () => {
|
||||
const userProfile = createMockUserProfile({ role: 'user' });
|
||||
|
||||
mockUseAuth.mockReturnValue({
|
||||
...defaultAuthReturn,
|
||||
userProfile,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
});
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
expect(flyerList).toHaveAttribute('data-profile-role', 'user');
|
||||
});
|
||||
|
||||
it('should pass admin profile to FlyerList when user is admin', () => {
|
||||
const adminProfile = createMockUserProfile({ role: 'admin' });
|
||||
|
||||
mockUseAuth.mockReturnValue({
|
||||
...defaultAuthReturn,
|
||||
userProfile: adminProfile,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
});
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
expect(flyerList).toHaveAttribute('data-profile-role', 'admin');
|
||||
});
|
||||
});
|
||||
|
||||
describe('FlyerUploader Integration', () => {
|
||||
it('should pass refetchFlyers to FlyerUploader as onProcessingComplete', () => {
|
||||
renderPage();
|
||||
|
||||
// Click the mock upload complete button
|
||||
const completeButton = screen.getByTestId('mock-upload-complete-btn');
|
||||
fireEvent.click(completeButton);
|
||||
|
||||
// Verify refetchFlyers was called
|
||||
expect(mockRefetchFlyers).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('should trigger data refresh when upload completes', () => {
|
||||
const mockFlyers: Flyer[] = [
|
||||
createMockFlyer({
|
||||
flyer_id: 1,
|
||||
store: { store_id: 1, name: 'Safeway', created_at: '', updated_at: '' },
|
||||
}),
|
||||
];
|
||||
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
// Simulate upload completion
|
||||
const completeButton = screen.getByTestId('mock-upload-complete-btn');
|
||||
fireEvent.click(completeButton);
|
||||
|
||||
expect(mockRefetchFlyers).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Hook Integration', () => {
|
||||
it('should call useAuth hook', () => {
|
||||
renderPage();
|
||||
|
||||
expect(mockUseAuth).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should call useFlyers hook', () => {
|
||||
renderPage();
|
||||
|
||||
expect(mockUseFlyers).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should call useFlyerSelection with flyers from useFlyers', () => {
|
||||
const mockFlyers: Flyer[] = [
|
||||
createMockFlyer({ flyer_id: 1 }),
|
||||
createMockFlyer({ flyer_id: 2 }),
|
||||
];
|
||||
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
expect(mockUseFlyerSelection).toHaveBeenCalledWith({ flyers: mockFlyers });
|
||||
});
|
||||
});
|
||||
|
||||
describe('Component Props Passing', () => {
|
||||
it('should pass all required props to FlyerList', () => {
|
||||
const mockFlyers: Flyer[] = [createMockFlyer({ flyer_id: 1 })];
|
||||
const selectedFlyer = mockFlyers[0];
|
||||
const userProfile = createMockUserProfile({ role: 'admin' });
|
||||
|
||||
mockUseAuth.mockReturnValue({
|
||||
...defaultAuthReturn,
|
||||
userProfile,
|
||||
});
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
mockUseFlyerSelection.mockReturnValue({
|
||||
selectedFlyer,
|
||||
handleFlyerSelect: mockHandleFlyerSelect,
|
||||
flyerIdFromUrl: undefined,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
|
||||
// Verify all props are passed correctly
|
||||
expect(flyerList).toHaveAttribute('data-flyer-count', '1');
|
||||
expect(flyerList).toHaveAttribute('data-selected-id', '1');
|
||||
expect(flyerList).toHaveAttribute('data-profile-role', 'admin');
|
||||
});
|
||||
|
||||
it('should handle selectedFlyer being null gracefully', () => {
|
||||
const mockFlyers: Flyer[] = [createMockFlyer({ flyer_id: 1 })];
|
||||
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
mockUseFlyerSelection.mockReturnValue({
|
||||
selectedFlyer: null,
|
||||
handleFlyerSelect: mockHandleFlyerSelect,
|
||||
flyerIdFromUrl: undefined,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
expect(flyerList).toHaveAttribute('data-selected-id', 'none');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Edge Cases', () => {
|
||||
it('should handle flyer with missing store gracefully', () => {
|
||||
const flyerWithoutStore = createMockFlyer({
|
||||
flyer_id: 1,
|
||||
item_count: 10,
|
||||
});
|
||||
// Remove the store to test fallback behavior
|
||||
(flyerWithoutStore as unknown as { store: undefined }).store = undefined;
|
||||
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: [flyerWithoutStore],
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
// Should show "Unknown Store" as fallback
|
||||
expect(screen.getByText(/Unknown Store - 10 items/)).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should handle undefined selectedFlyer flyer_id', () => {
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: [],
|
||||
});
|
||||
mockUseFlyerSelection.mockReturnValue({
|
||||
selectedFlyer: null,
|
||||
handleFlyerSelect: mockHandleFlyerSelect,
|
||||
flyerIdFromUrl: undefined,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
expect(flyerList).toHaveAttribute('data-selected-id', 'none');
|
||||
});
|
||||
|
||||
it('should handle multiple rapid flyer selections', () => {
|
||||
const mockFlyers: Flyer[] = [
|
||||
createMockFlyer({ flyer_id: 1 }),
|
||||
createMockFlyer({ flyer_id: 2 }),
|
||||
createMockFlyer({ flyer_id: 3 }),
|
||||
];
|
||||
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
// Rapidly click different flyers
|
||||
fireEvent.click(within(screen.getByTestId('flyer-item-1')).getByRole('button'));
|
||||
fireEvent.click(within(screen.getByTestId('flyer-item-2')).getByRole('button'));
|
||||
fireEvent.click(within(screen.getByTestId('flyer-item-3')).getByRole('button'));
|
||||
|
||||
expect(mockHandleFlyerSelect).toHaveBeenCalledTimes(3);
|
||||
expect(mockHandleFlyerSelect).toHaveBeenNthCalledWith(1, mockFlyers[0]);
|
||||
expect(mockHandleFlyerSelect).toHaveBeenNthCalledWith(2, mockFlyers[1]);
|
||||
expect(mockHandleFlyerSelect).toHaveBeenNthCalledWith(3, mockFlyers[2]);
|
||||
});
|
||||
|
||||
it('should handle large number of flyers', () => {
|
||||
const manyFlyers = Array.from({ length: 100 }, (_, i) =>
|
||||
createMockFlyer({
|
||||
flyer_id: i + 1,
|
||||
store: { store_id: i + 1, name: `Store ${i + 1}`, created_at: '', updated_at: '' },
|
||||
item_count: (i + 1) * 10,
|
||||
}),
|
||||
);
|
||||
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: manyFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
const flyerList = screen.getByTestId('flyer-list');
|
||||
expect(flyerList).toHaveAttribute('data-flyer-count', '100');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Accessibility', () => {
|
||||
it('should have a main heading for the page', () => {
|
||||
renderPage();
|
||||
|
||||
const heading = screen.getByRole('heading', { level: 1, name: /flyers/i });
|
||||
expect(heading).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render interactive elements as buttons', () => {
|
||||
const mockFlyers: Flyer[] = [createMockFlyer({ flyer_id: 1 })];
|
||||
|
||||
mockUseFlyers.mockReturnValue({
|
||||
...defaultFlyersReturn,
|
||||
flyers: mockFlyers,
|
||||
});
|
||||
|
||||
renderPage();
|
||||
|
||||
// Both flyer selection and upload complete should be accessible buttons
|
||||
const buttons = screen.getAllByRole('button');
|
||||
expect(buttons.length).toBeGreaterThanOrEqual(2);
|
||||
});
|
||||
});
|
||||
});
|
||||
469
src/pages/ShoppingListsPage.test.tsx
Normal file
469
src/pages/ShoppingListsPage.test.tsx
Normal file
@@ -0,0 +1,469 @@
|
||||
// src/pages/ShoppingListsPage.test.tsx
|
||||
import { render, screen, waitFor } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
|
||||
import { ShoppingListsPage } from './ShoppingListsPage';
|
||||
import { useAuth } from '../hooks/useAuth';
|
||||
import { useShoppingLists } from '../hooks/useShoppingLists';
|
||||
import type { ShoppingList, ShoppingListItem, User, UserProfile } from '../types';
|
||||
import {
|
||||
createMockUser,
|
||||
createMockUserProfile,
|
||||
createMockShoppingList,
|
||||
createMockShoppingListItem,
|
||||
} from '../tests/utils/mockFactories';
|
||||
|
||||
// Mock the hooks used by ShoppingListsPage
|
||||
vi.mock('../hooks/useAuth');
|
||||
vi.mock('../hooks/useShoppingLists');
|
||||
|
||||
// Mock the ShoppingListComponent to isolate ShoppingListsPage logic
|
||||
vi.mock('../features/shopping/ShoppingList', () => ({
|
||||
ShoppingListComponent: vi.fn(
|
||||
({
|
||||
user,
|
||||
lists,
|
||||
activeListId,
|
||||
onSelectList,
|
||||
onCreateList,
|
||||
onDeleteList,
|
||||
onAddItem,
|
||||
onUpdateItem,
|
||||
onRemoveItem,
|
||||
}: {
|
||||
user: User | null;
|
||||
lists: ShoppingList[];
|
||||
activeListId: number | null;
|
||||
onSelectList: (listId: number) => void;
|
||||
onCreateList: (name: string) => Promise<void>;
|
||||
onDeleteList: (listId: number) => Promise<void>;
|
||||
onAddItem: (item: { customItemName: string }) => Promise<void>;
|
||||
onUpdateItem: (itemId: number, updates: Partial<ShoppingListItem>) => Promise<void>;
|
||||
onRemoveItem: (itemId: number) => Promise<void>;
|
||||
}) => (
|
||||
<div data-testid="shopping-list-component">
|
||||
<span data-testid="user-status">{user ? 'authenticated' : 'not-authenticated'}</span>
|
||||
<span data-testid="lists-count">{lists.length}</span>
|
||||
<span data-testid="active-list-id">{activeListId ?? 'none'}</span>
|
||||
<button data-testid="select-list-btn" onClick={() => onSelectList(999)}>
|
||||
Select List
|
||||
</button>
|
||||
<button data-testid="create-list-btn" onClick={() => onCreateList('New List')}>
|
||||
Create List
|
||||
</button>
|
||||
<button data-testid="delete-list-btn" onClick={() => onDeleteList(1)}>
|
||||
Delete List
|
||||
</button>
|
||||
<button
|
||||
data-testid="add-item-btn"
|
||||
onClick={() => onAddItem({ customItemName: 'Test Item' })}
|
||||
>
|
||||
Add Item
|
||||
</button>
|
||||
<button
|
||||
data-testid="update-item-btn"
|
||||
onClick={() => onUpdateItem(10, { is_purchased: true })}
|
||||
>
|
||||
Update Item
|
||||
</button>
|
||||
<button data-testid="remove-item-btn" onClick={() => onRemoveItem(10)}>
|
||||
Remove Item
|
||||
</button>
|
||||
</div>
|
||||
),
|
||||
),
|
||||
}));
|
||||
|
||||
const mockedUseAuth = vi.mocked(useAuth);
|
||||
const mockedUseShoppingLists = vi.mocked(useShoppingLists);
|
||||
|
||||
describe('ShoppingListsPage', () => {
|
||||
const mockUser: User = createMockUser({ user_id: 'user-123', email: 'test@example.com' });
|
||||
const mockUserProfile: UserProfile = createMockUserProfile({ user: mockUser });
|
||||
|
||||
const mockShoppingLists: ShoppingList[] = [
|
||||
createMockShoppingList({
|
||||
shopping_list_id: 1,
|
||||
name: 'Groceries',
|
||||
user_id: 'user-123',
|
||||
items: [
|
||||
createMockShoppingListItem({
|
||||
shopping_list_item_id: 101,
|
||||
shopping_list_id: 1,
|
||||
custom_item_name: 'Apples',
|
||||
}),
|
||||
],
|
||||
}),
|
||||
createMockShoppingList({
|
||||
shopping_list_id: 2,
|
||||
name: 'Hardware',
|
||||
user_id: 'user-123',
|
||||
items: [],
|
||||
}),
|
||||
];
|
||||
|
||||
// Mock functions from useShoppingLists
|
||||
const mockSetActiveListId = vi.fn();
|
||||
const mockCreateList = vi.fn();
|
||||
const mockDeleteList = vi.fn();
|
||||
const mockAddItemToList = vi.fn();
|
||||
const mockUpdateItemInList = vi.fn();
|
||||
const mockRemoveItemFromList = vi.fn();
|
||||
|
||||
const defaultUseShoppingListsReturn = {
|
||||
shoppingLists: mockShoppingLists,
|
||||
activeListId: 1,
|
||||
setActiveListId: mockSetActiveListId,
|
||||
createList: mockCreateList,
|
||||
deleteList: mockDeleteList,
|
||||
addItemToList: mockAddItemToList,
|
||||
updateItemInList: mockUpdateItemInList,
|
||||
removeItemFromList: mockRemoveItemFromList,
|
||||
isCreatingList: false,
|
||||
isDeletingList: false,
|
||||
isAddingItem: false,
|
||||
isUpdatingItem: false,
|
||||
isRemovingItem: false,
|
||||
error: null,
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetAllMocks();
|
||||
|
||||
// Default authenticated user
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: mockUserProfile,
|
||||
authStatus: 'AUTHENTICATED',
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
// Default shopping lists state
|
||||
mockedUseShoppingLists.mockReturnValue(defaultUseShoppingListsReturn);
|
||||
});
|
||||
|
||||
describe('Rendering', () => {
|
||||
it('should render the page title', () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByRole('heading', { name: 'Shopping Lists' })).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render the ShoppingListComponent', () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('shopping-list-component')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should pass the correct user to ShoppingListComponent when authenticated', () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('user-status')).toHaveTextContent('authenticated');
|
||||
});
|
||||
|
||||
it('should pass null user to ShoppingListComponent when not authenticated', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: null,
|
||||
authStatus: 'SIGNED_OUT',
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('user-status')).toHaveTextContent('not-authenticated');
|
||||
});
|
||||
|
||||
it('should pass the shopping lists to ShoppingListComponent', () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('lists-count')).toHaveTextContent('2');
|
||||
});
|
||||
|
||||
it('should pass the active list ID to ShoppingListComponent', () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('active-list-id')).toHaveTextContent('1');
|
||||
});
|
||||
|
||||
it('should handle empty shopping lists', () => {
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
...defaultUseShoppingListsReturn,
|
||||
shoppingLists: [],
|
||||
activeListId: null,
|
||||
});
|
||||
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('lists-count')).toHaveTextContent('0');
|
||||
expect(screen.getByTestId('active-list-id')).toHaveTextContent('none');
|
||||
});
|
||||
});
|
||||
|
||||
describe('User State', () => {
|
||||
it('should extract user from userProfile when available', () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
// The component should pass the user object to ShoppingListComponent
|
||||
expect(screen.getByTestId('user-status')).toHaveTextContent('authenticated');
|
||||
});
|
||||
|
||||
it('should pass null user when userProfile is null', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: null,
|
||||
authStatus: 'SIGNED_OUT',
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('user-status')).toHaveTextContent('not-authenticated');
|
||||
});
|
||||
|
||||
it('should pass null user when userProfile has no user property', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: { ...mockUserProfile, user: undefined as unknown as User },
|
||||
authStatus: 'AUTHENTICATED',
|
||||
isLoading: false,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
// When userProfile.user is undefined, the nullish coalescing should return null
|
||||
expect(screen.getByTestId('user-status')).toHaveTextContent('not-authenticated');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Callback Props', () => {
|
||||
it('should pass setActiveListId to ShoppingListComponent', async () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
const selectButton = screen.getByTestId('select-list-btn');
|
||||
selectButton.click();
|
||||
|
||||
expect(mockSetActiveListId).toHaveBeenCalledWith(999);
|
||||
});
|
||||
|
||||
it('should pass createList to ShoppingListComponent', async () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
const createButton = screen.getByTestId('create-list-btn');
|
||||
createButton.click();
|
||||
|
||||
expect(mockCreateList).toHaveBeenCalledWith('New List');
|
||||
});
|
||||
|
||||
it('should pass deleteList to ShoppingListComponent', async () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
const deleteButton = screen.getByTestId('delete-list-btn');
|
||||
deleteButton.click();
|
||||
|
||||
expect(mockDeleteList).toHaveBeenCalledWith(1);
|
||||
});
|
||||
|
||||
it('should pass updateItemInList to ShoppingListComponent', async () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
const updateButton = screen.getByTestId('update-item-btn');
|
||||
updateButton.click();
|
||||
|
||||
expect(mockUpdateItemInList).toHaveBeenCalledWith(10, { is_purchased: true });
|
||||
});
|
||||
|
||||
it('should pass removeItemFromList to ShoppingListComponent', async () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
const removeButton = screen.getByTestId('remove-item-btn');
|
||||
removeButton.click();
|
||||
|
||||
expect(mockRemoveItemFromList).toHaveBeenCalledWith(10);
|
||||
});
|
||||
});
|
||||
|
||||
describe('handleAddItemToShoppingList', () => {
|
||||
it('should call addItemToList with activeListId when adding an item', async () => {
|
||||
mockAddItemToList.mockResolvedValue(undefined);
|
||||
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
const addButton = screen.getByTestId('add-item-btn');
|
||||
addButton.click();
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockAddItemToList).toHaveBeenCalledWith(1, { customItemName: 'Test Item' });
|
||||
});
|
||||
});
|
||||
|
||||
it('should not call addItemToList when activeListId is null', async () => {
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
...defaultUseShoppingListsReturn,
|
||||
activeListId: null,
|
||||
});
|
||||
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
const addButton = screen.getByTestId('add-item-btn');
|
||||
addButton.click();
|
||||
|
||||
// Wait a tick to ensure any async operations would have completed
|
||||
await waitFor(() => {
|
||||
expect(mockAddItemToList).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
it('should handle addItemToList with masterItemId', async () => {
|
||||
// Re-mock ShoppingListComponent to test with masterItemId
|
||||
const ShoppingListComponent = vi.mocked(
|
||||
await import('../features/shopping/ShoppingList'),
|
||||
).ShoppingListComponent;
|
||||
|
||||
// Get the onAddItem prop from the last render call
|
||||
const lastCallProps = (ShoppingListComponent as unknown as Mock).mock.calls[0]?.[0];
|
||||
|
||||
if (lastCallProps?.onAddItem) {
|
||||
await lastCallProps.onAddItem({ masterItemId: 42 });
|
||||
|
||||
expect(mockAddItemToList).toHaveBeenCalledWith(1, { masterItemId: 42 });
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('Integration with useShoppingLists', () => {
|
||||
it('should use the correct hooks', () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
expect(mockedUseAuth).toHaveBeenCalled();
|
||||
expect(mockedUseShoppingLists).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should reflect changes when shoppingLists updates', () => {
|
||||
const { rerender } = render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('lists-count')).toHaveTextContent('2');
|
||||
|
||||
// Simulate adding a new list
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
...defaultUseShoppingListsReturn,
|
||||
shoppingLists: [
|
||||
...mockShoppingLists,
|
||||
createMockShoppingList({
|
||||
shopping_list_id: 3,
|
||||
name: 'New List',
|
||||
user_id: 'user-123',
|
||||
}),
|
||||
],
|
||||
});
|
||||
|
||||
rerender(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('lists-count')).toHaveTextContent('3');
|
||||
});
|
||||
|
||||
it('should reflect changes when activeListId updates', () => {
|
||||
const { rerender } = render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('active-list-id')).toHaveTextContent('1');
|
||||
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
...defaultUseShoppingListsReturn,
|
||||
activeListId: 2,
|
||||
});
|
||||
|
||||
rerender(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('active-list-id')).toHaveTextContent('2');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Page Structure', () => {
|
||||
it('should have correct CSS classes for layout', () => {
|
||||
const { container } = render(<ShoppingListsPage />);
|
||||
|
||||
const pageContainer = container.firstChild as HTMLElement;
|
||||
expect(pageContainer).toHaveClass('max-w-4xl', 'mx-auto', 'p-4', 'space-y-6');
|
||||
});
|
||||
|
||||
it('should have correctly styled heading', () => {
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
const heading = screen.getByRole('heading', { name: 'Shopping Lists' });
|
||||
expect(heading).toHaveClass('text-3xl', 'font-bold', 'text-gray-900');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Edge Cases', () => {
|
||||
it('should handle auth loading state gracefully', () => {
|
||||
mockedUseAuth.mockReturnValue({
|
||||
userProfile: null,
|
||||
authStatus: 'Determining...',
|
||||
isLoading: true,
|
||||
login: vi.fn(),
|
||||
logout: vi.fn(),
|
||||
updateProfile: vi.fn(),
|
||||
});
|
||||
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
// Page should still render even during auth loading
|
||||
expect(screen.getByRole('heading', { name: 'Shopping Lists' })).toBeInTheDocument();
|
||||
expect(screen.getByTestId('user-status')).toHaveTextContent('not-authenticated');
|
||||
});
|
||||
|
||||
it('should handle shopping lists with items correctly', () => {
|
||||
const listsWithItems = [
|
||||
createMockShoppingList({
|
||||
shopping_list_id: 1,
|
||||
name: 'With Items',
|
||||
items: [
|
||||
createMockShoppingListItem({
|
||||
shopping_list_item_id: 1,
|
||||
custom_item_name: 'Item 1',
|
||||
is_purchased: false,
|
||||
}),
|
||||
createMockShoppingListItem({
|
||||
shopping_list_item_id: 2,
|
||||
custom_item_name: 'Item 2',
|
||||
is_purchased: true,
|
||||
}),
|
||||
],
|
||||
}),
|
||||
];
|
||||
|
||||
mockedUseShoppingLists.mockReturnValue({
|
||||
...defaultUseShoppingListsReturn,
|
||||
shoppingLists: listsWithItems,
|
||||
});
|
||||
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
expect(screen.getByTestId('lists-count')).toHaveTextContent('1');
|
||||
});
|
||||
|
||||
it('should handle async callback errors gracefully', async () => {
|
||||
// The useShoppingLists hook catches errors internally and logs them,
|
||||
// so we mock it to resolve (the real error handling is tested in useShoppingLists.test.tsx)
|
||||
mockAddItemToList.mockResolvedValue(undefined);
|
||||
|
||||
render(<ShoppingListsPage />);
|
||||
|
||||
const addButton = screen.getByTestId('add-item-btn');
|
||||
|
||||
// Should not throw when clicked
|
||||
expect(() => addButton.click()).not.toThrow();
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockAddItemToList).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
78
src/pages/admin/AdminStoresPage.test.tsx
Normal file
78
src/pages/admin/AdminStoresPage.test.tsx
Normal file
@@ -0,0 +1,78 @@
|
||||
// src/pages/admin/AdminStoresPage.test.tsx
|
||||
import React from 'react';
|
||||
import { render, screen } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { MemoryRouter } from 'react-router-dom';
|
||||
import { AdminStoresPage } from './AdminStoresPage';
|
||||
import { QueryWrapper } from '../../tests/utils/renderWithProviders';
|
||||
|
||||
// Mock the AdminStoreManager child component to isolate the test
|
||||
vi.mock('./components/AdminStoreManager', () => ({
|
||||
AdminStoreManager: () => <div data-testid="admin-store-manager-mock">Admin Store Manager</div>,
|
||||
}));
|
||||
|
||||
// Mock the logger to prevent console output during tests
|
||||
vi.mock('../../services/logger', () => ({
|
||||
logger: {
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
debug: vi.fn(),
|
||||
},
|
||||
}));
|
||||
|
||||
// Helper function to render the component within router and query contexts
|
||||
const renderWithRouter = () => {
|
||||
return render(
|
||||
<QueryWrapper>
|
||||
<MemoryRouter>
|
||||
<AdminStoresPage />
|
||||
</MemoryRouter>
|
||||
</QueryWrapper>,
|
||||
);
|
||||
};
|
||||
|
||||
describe('AdminStoresPage', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it('should render the main heading and description', () => {
|
||||
renderWithRouter();
|
||||
|
||||
expect(screen.getByRole('heading', { name: /store management/i })).toBeInTheDocument();
|
||||
expect(screen.getByText('Manage stores and their locations.')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should render a link back to the admin dashboard', () => {
|
||||
renderWithRouter();
|
||||
|
||||
const link = screen.getByRole('link', { name: /back to admin dashboard/i });
|
||||
expect(link).toBeInTheDocument();
|
||||
expect(link).toHaveAttribute('href', '/admin');
|
||||
});
|
||||
|
||||
it('should render the AdminStoreManager component', () => {
|
||||
renderWithRouter();
|
||||
|
||||
expect(screen.getByTestId('admin-store-manager-mock')).toBeInTheDocument();
|
||||
expect(screen.getByText('Admin Store Manager')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('should have proper page layout structure', () => {
|
||||
const { container } = renderWithRouter();
|
||||
|
||||
// Check for the main container with expected classes
|
||||
const mainContainer = container.querySelector('.max-w-6xl');
|
||||
expect(mainContainer).toBeInTheDocument();
|
||||
expect(mainContainer).toHaveClass('mx-auto', 'py-8', 'px-4');
|
||||
});
|
||||
|
||||
it('should render the back link with the left arrow entity', () => {
|
||||
renderWithRouter();
|
||||
|
||||
// The back link should contain the larr HTML entity (left arrow)
|
||||
const link = screen.getByRole('link', { name: /back to admin dashboard/i });
|
||||
expect(link.textContent).toContain('\u2190'); // Unicode for ←
|
||||
});
|
||||
});
|
||||
672
src/pages/admin/components/AdminStoreManager.test.tsx
Normal file
672
src/pages/admin/components/AdminStoreManager.test.tsx
Normal file
@@ -0,0 +1,672 @@
|
||||
// src/pages/admin/components/AdminStoreManager.test.tsx
|
||||
import React from 'react';
|
||||
import { screen, fireEvent, waitFor, within } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import toast from 'react-hot-toast';
|
||||
import { AdminStoreManager } from './AdminStoreManager';
|
||||
import * as apiClient from '../../../services/apiClient';
|
||||
import { createMockStoreWithLocations } from '../../../tests/utils/mockFactories';
|
||||
import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
|
||||
import type { StoreWithLocations } from '../../../types';
|
||||
|
||||
// Must explicitly call vi.mock() for apiClient
|
||||
vi.mock('../../../services/apiClient');
|
||||
|
||||
// Mock react-hot-toast
|
||||
vi.mock('react-hot-toast', () => ({
|
||||
default: {
|
||||
loading: vi.fn(),
|
||||
success: vi.fn(),
|
||||
error: vi.fn(),
|
||||
},
|
||||
}));
|
||||
|
||||
// Mock the StoreForm component to isolate AdminStoreManager testing
|
||||
vi.mock('./StoreForm', () => ({
|
||||
StoreForm: ({
|
||||
store,
|
||||
onSuccess,
|
||||
onCancel,
|
||||
}: {
|
||||
store?: StoreWithLocations;
|
||||
onSuccess: () => void;
|
||||
onCancel: () => void;
|
||||
}) => (
|
||||
<div data-testid="store-form-mock">
|
||||
<span data-testid="store-form-mode">{store ? 'edit' : 'create'}</span>
|
||||
{store && <span data-testid="store-form-store-id">{store.store_id}</span>}
|
||||
<button onClick={onSuccess} data-testid="store-form-success">
|
||||
Submit
|
||||
</button>
|
||||
<button onClick={onCancel} data-testid="store-form-cancel">
|
||||
Cancel
|
||||
</button>
|
||||
</div>
|
||||
),
|
||||
}));
|
||||
|
||||
// Mock the ErrorDisplay component
|
||||
vi.mock('../../../components/ErrorDisplay', () => ({
|
||||
ErrorDisplay: ({ message }: { message: string }) => (
|
||||
<div data-testid="error-display">{message}</div>
|
||||
),
|
||||
}));
|
||||
|
||||
// Mock the logger to prevent console output during tests
|
||||
vi.mock('../../../services/logger.client', () => ({
|
||||
logger: {
|
||||
info: vi.fn(),
|
||||
warn: vi.fn(),
|
||||
error: vi.fn(),
|
||||
debug: vi.fn(),
|
||||
},
|
||||
}));
|
||||
|
||||
const mockedApiClient = vi.mocked(apiClient);
|
||||
const mockedToast = vi.mocked(toast, true);
|
||||
|
||||
const mockStores: StoreWithLocations[] = [
|
||||
createMockStoreWithLocations({
|
||||
store_id: 1,
|
||||
name: 'Loblaws',
|
||||
logo_url: 'https://example.com/loblaws.png',
|
||||
locations: [
|
||||
{ address: { address_line_1: '123 Main St', city: 'Toronto' } },
|
||||
{ address: { address_line_1: '456 Oak Ave', city: 'Mississauga' } },
|
||||
],
|
||||
}),
|
||||
createMockStoreWithLocations({
|
||||
store_id: 2,
|
||||
name: 'No Frills',
|
||||
logo_url: null,
|
||||
locations: [],
|
||||
}),
|
||||
createMockStoreWithLocations({
|
||||
store_id: 3,
|
||||
name: 'Walmart',
|
||||
logo_url: 'https://example.com/walmart.png',
|
||||
locations: [{ address: { address_line_1: '789 Pine St', city: 'Vancouver' } }],
|
||||
}),
|
||||
];
|
||||
|
||||
// Helper to create a successful API response
|
||||
const createSuccessResponse = (data: unknown) =>
|
||||
new Response(JSON.stringify({ data }), {
|
||||
status: 200,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
});
|
||||
|
||||
// Helper to create a failed API response
|
||||
const createErrorResponse = (status: number, body?: string) => new Response(body || '', { status });
|
||||
|
||||
describe('AdminStoreManager', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
|
||||
// Default mock: successful response with stores
|
||||
mockedApiClient.getStores.mockResolvedValue(createSuccessResponse(mockStores));
|
||||
mockedApiClient.deleteStore.mockResolvedValue(createSuccessResponse({}));
|
||||
|
||||
// Reset window.confirm mock
|
||||
vi.spyOn(window, 'confirm').mockReturnValue(true);
|
||||
});
|
||||
|
||||
describe('Loading State', () => {
|
||||
it('should render a loading state while fetching stores', async () => {
|
||||
// Make getStores hang indefinitely for this test
|
||||
mockedApiClient.getStores.mockImplementation(
|
||||
() => new Promise(() => {}), // Never resolves
|
||||
);
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
expect(screen.getByText('Loading stores...')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Error State', () => {
|
||||
it('should display an error message if fetching stores fails', async () => {
|
||||
mockedApiClient.getStores.mockResolvedValue(
|
||||
createErrorResponse(500, 'Internal Server Error'),
|
||||
);
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByTestId('error-display')).toBeInTheDocument();
|
||||
expect(screen.getByText(/Failed to load stores/i)).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
it('should display a generic error message for network failures', async () => {
|
||||
mockedApiClient.getStores.mockRejectedValue(new Error('Network Error'));
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByTestId('error-display')).toBeInTheDocument();
|
||||
expect(screen.getByText(/Failed to load stores: Network Error/i)).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Success State - Store List', () => {
|
||||
it('should render the list of stores when data is fetched successfully', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByRole('heading', { name: /store management/i })).toBeInTheDocument();
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
expect(screen.getByText('No Frills')).toBeInTheDocument();
|
||||
expect(screen.getByText('Walmart')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
it('should display store logos when available', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
const loblawsLogo = screen.getByAltText('Loblaws logo');
|
||||
expect(loblawsLogo).toHaveAttribute('src', 'https://example.com/loblaws.png');
|
||||
|
||||
const walmartLogo = screen.getByAltText('Walmart logo');
|
||||
expect(walmartLogo).toHaveAttribute('src', 'https://example.com/walmart.png');
|
||||
});
|
||||
});
|
||||
|
||||
it('should display "No Logo" placeholder when logo_url is null', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// No Frills has no logo
|
||||
const noLogoElements = screen.getAllByText('No Logo');
|
||||
expect(noLogoElements.length).toBeGreaterThanOrEqual(1);
|
||||
});
|
||||
|
||||
it('should display location count and first address for stores with locations', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
// Loblaws has 2 locations
|
||||
expect(screen.getByText('2 location(s)')).toBeInTheDocument();
|
||||
expect(screen.getByText('123 Main St, Toronto')).toBeInTheDocument();
|
||||
expect(screen.getByText('+ 1 more')).toBeInTheDocument();
|
||||
|
||||
// Walmart has 1 location
|
||||
expect(screen.getByText('1 location(s)')).toBeInTheDocument();
|
||||
expect(screen.getByText('789 Pine St, Vancouver')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
it('should display "No locations" for stores without locations', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('No locations')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
it('should render Edit and Delete buttons for each store', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
// There are 3 stores, so should have 3 Edit and 3 Delete buttons
|
||||
const editButtons = screen.getAllByRole('button', { name: /edit/i });
|
||||
const deleteButtons = screen.getAllByRole('button', { name: /delete/i });
|
||||
|
||||
expect(editButtons).toHaveLength(3);
|
||||
expect(deleteButtons).toHaveLength(3);
|
||||
});
|
||||
});
|
||||
|
||||
it('should render "Create Store" button', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByRole('button', { name: /create store/i })).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
it('should render an empty state message when no stores exist', async () => {
|
||||
mockedApiClient.getStores.mockResolvedValue(createSuccessResponse([]));
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('No stores found. Create one to get started!')).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Table Structure', () => {
|
||||
it('should render a table with correct column headers', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByRole('columnheader', { name: /logo/i })).toBeInTheDocument();
|
||||
expect(screen.getByRole('columnheader', { name: /store name/i })).toBeInTheDocument();
|
||||
expect(screen.getByRole('columnheader', { name: /locations/i })).toBeInTheDocument();
|
||||
expect(screen.getByRole('columnheader', { name: /actions/i })).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
it('should render one row per store plus the header row', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
// 1 header row + 3 data rows
|
||||
const rows = screen.getAllByRole('row');
|
||||
expect(rows).toHaveLength(4);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Create Store Modal', () => {
|
||||
it('should open the create modal when "Create Store" button is clicked', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
fireEvent.click(screen.getByRole('button', { name: /create store/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Create New Store')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('store-form-mock')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('store-form-mode')).toHaveTextContent('create');
|
||||
});
|
||||
});
|
||||
|
||||
it('should close the create modal when cancel is clicked', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Open modal
|
||||
fireEvent.click(screen.getByRole('button', { name: /create store/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Create New Store')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Click cancel
|
||||
fireEvent.click(screen.getByTestId('store-form-cancel'));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.queryByText('Create New Store')).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
it('should close the create modal and refresh data when form submission succeeds', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Open modal
|
||||
fireEvent.click(screen.getByRole('button', { name: /create store/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByTestId('store-form-mock')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Submit the form (triggers onSuccess)
|
||||
fireEvent.click(screen.getByTestId('store-form-success'));
|
||||
|
||||
await waitFor(() => {
|
||||
// Modal should be closed
|
||||
expect(screen.queryByText('Create New Store')).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Edit Store Modal', () => {
|
||||
it('should open the edit modal when "Edit" button is clicked', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Find the Loblaws row and click its Edit button
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
const editButton = within(loblawsRow!).getByRole('button', { name: /edit/i });
|
||||
fireEvent.click(editButton);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Edit Store')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('store-form-mock')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('store-form-mode')).toHaveTextContent('edit');
|
||||
expect(screen.getByTestId('store-form-store-id')).toHaveTextContent('1');
|
||||
});
|
||||
});
|
||||
|
||||
it('should pass the correct store to the form in edit mode', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Walmart')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Click Edit on Walmart (store_id: 3)
|
||||
const walmartRow = screen.getByText('Walmart').closest('tr');
|
||||
const editButton = within(walmartRow!).getByRole('button', { name: /edit/i });
|
||||
fireEvent.click(editButton);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByTestId('store-form-store-id')).toHaveTextContent('3');
|
||||
});
|
||||
});
|
||||
|
||||
it('should close the edit modal when cancel is clicked', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Open edit modal
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /edit/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Edit Store')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Click cancel
|
||||
fireEvent.click(screen.getByTestId('store-form-cancel'));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.queryByText('Edit Store')).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
|
||||
it('should close the edit modal and refresh data when form submission succeeds', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Open edit modal
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /edit/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByTestId('store-form-mock')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Submit form
|
||||
fireEvent.click(screen.getByTestId('store-form-success'));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.queryByText('Edit Store')).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Delete Store', () => {
|
||||
it('should show a confirmation dialog before deleting', async () => {
|
||||
const confirmSpy = vi.spyOn(window, 'confirm').mockReturnValue(false);
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
expect(confirmSpy).toHaveBeenCalledWith(
|
||||
expect.stringContaining('Are you sure you want to delete "Loblaws"'),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not delete if user cancels the confirmation', async () => {
|
||||
vi.spyOn(window, 'confirm').mockReturnValue(false);
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
// API should not be called
|
||||
expect(mockedApiClient.deleteStore).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should call deleteStore API when user confirms deletion', async () => {
|
||||
vi.spyOn(window, 'confirm').mockReturnValue(true);
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockedApiClient.deleteStore).toHaveBeenCalledWith(1);
|
||||
});
|
||||
});
|
||||
|
||||
it('should show a loading toast while deleting', async () => {
|
||||
vi.spyOn(window, 'confirm').mockReturnValue(true);
|
||||
mockedToast.loading.mockReturnValue('delete-toast-id');
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockedToast.loading).toHaveBeenCalledWith('Deleting store...');
|
||||
});
|
||||
});
|
||||
|
||||
it('should show success toast after successful deletion', async () => {
|
||||
vi.spyOn(window, 'confirm').mockReturnValue(true);
|
||||
mockedToast.loading.mockReturnValue('delete-toast-id');
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockedToast.success).toHaveBeenCalledWith('Store deleted successfully!', {
|
||||
id: 'delete-toast-id',
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
it('should show error toast when deletion fails with response body', async () => {
|
||||
vi.spyOn(window, 'confirm').mockReturnValue(true);
|
||||
mockedToast.loading.mockReturnValue('delete-toast-id');
|
||||
mockedApiClient.deleteStore.mockResolvedValue(
|
||||
createErrorResponse(400, 'Store has active flyers'),
|
||||
);
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockedToast.error).toHaveBeenCalledWith('Delete failed: Store has active flyers', {
|
||||
id: 'delete-toast-id',
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
it('should show error toast with status code when response body is empty', async () => {
|
||||
vi.spyOn(window, 'confirm').mockReturnValue(true);
|
||||
mockedToast.loading.mockReturnValue('delete-toast-id');
|
||||
mockedApiClient.deleteStore.mockResolvedValue(createErrorResponse(500));
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockedToast.error).toHaveBeenCalledWith(
|
||||
'Delete failed: Delete failed with status 500',
|
||||
{ id: 'delete-toast-id' },
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
it('should show error toast when API call throws an exception', async () => {
|
||||
vi.spyOn(window, 'confirm').mockReturnValue(true);
|
||||
mockedToast.loading.mockReturnValue('delete-toast-id');
|
||||
mockedApiClient.deleteStore.mockRejectedValue(new Error('Network error'));
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockedToast.error).toHaveBeenCalledWith('Delete failed: Network error', {
|
||||
id: 'delete-toast-id',
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
it('should handle non-Error objects thrown during deletion', async () => {
|
||||
vi.spyOn(window, 'confirm').mockReturnValue(true);
|
||||
mockedToast.loading.mockReturnValue('delete-toast-id');
|
||||
mockedApiClient.deleteStore.mockRejectedValue('A string error');
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockedToast.error).toHaveBeenCalledWith('Delete failed: A string error', {
|
||||
id: 'delete-toast-id',
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
it('should include correct warning message in confirmation dialog about locations and linked data', async () => {
|
||||
const confirmSpy = vi.spyOn(window, 'confirm').mockReturnValue(false);
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('No Frills')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
const noFrillsRow = screen.getByText('No Frills').closest('tr');
|
||||
fireEvent.click(within(noFrillsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
expect(confirmSpy).toHaveBeenCalledWith(
|
||||
expect.stringContaining('delete all associated locations'),
|
||||
);
|
||||
expect(confirmSpy).toHaveBeenCalledWith(
|
||||
expect.stringContaining('may affect flyers/receipts'),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('API Calls', () => {
|
||||
it('should call getStores with includeLocations=true on mount', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockedApiClient.getStores).toHaveBeenCalledWith(true);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Query Invalidation', () => {
|
||||
it('should refetch stores after successful store deletion', async () => {
|
||||
vi.spyOn(window, 'confirm').mockReturnValue(true);
|
||||
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByText('Loblaws')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// Initial call
|
||||
expect(mockedApiClient.getStores).toHaveBeenCalledTimes(1);
|
||||
|
||||
const loblawsRow = screen.getByText('Loblaws').closest('tr');
|
||||
fireEvent.click(within(loblawsRow!).getByRole('button', { name: /delete/i }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(mockedToast.success).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
// Should have been called again due to query invalidation
|
||||
await waitFor(() => {
|
||||
expect(mockedApiClient.getStores).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Accessibility', () => {
|
||||
it('should have accessible table structure', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByRole('table')).toBeInTheDocument();
|
||||
// There should be 2 rowgroups: thead and tbody
|
||||
const rowgroups = screen.getAllByRole('rowgroup');
|
||||
expect(rowgroups).toHaveLength(2);
|
||||
});
|
||||
});
|
||||
|
||||
it('should have proper scope attribute on column headers', async () => {
|
||||
renderWithProviders(<AdminStoreManager />);
|
||||
|
||||
await waitFor(() => {
|
||||
const headers = screen.getAllByRole('columnheader');
|
||||
headers.forEach((header) => {
|
||||
expect(header).toHaveAttribute('scope', 'col');
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user