QuantEngineByItz/oms-wms-erp/TEST-GUIDE.md

# OMS·WMS·ERP Test Guide (Phase 3 Step 5)

## Test Architecture

```
┌─────────────────────────────────────────────────┐
│ Unit Tests (Vitest)                             │
│ - Components (65 components × 20 tests = 1,300) │
│ - Stores (10 stores × 15 tests = 150)           │
│ - Total: 1,450 unit tests                       │
├─────────────────────────────────────────────────┤
│ Integration Tests (Vitest)                      │
│ - Order Workflow (10 tests)                     │
│ - Inventory Workflow (10 tests)                 │
│ - Customer Workflow (8 tests)                   │
│ - Total: 28 integration tests                   │
├─────────────────────────────────────────────────┤
│ E2E Tests (Playwright)                          │
│ - Order Flow (6 tests)                          │
│ - Inventory Flow (3 tests)                      │
│ - Dashboard Flow (pending)                      │
│ - Total: 9 E2E tests (expanding)                │
└─────────────────────────────────────────────────┘

Total Test Suite: 1,487 tests
Test Coverage Target: 80%+
Execution Time: ~2 minutes (parallel)
```

## Running Tests

### Unit Tests (Components + Stores)

```bash
# Run all unit tests
npm run test:unit

# Run with coverage
npm run test:unit -- --coverage

# Watch mode
npm run test:unit -- --watch

# Specific file
npm run test:unit -- stores/modules/orders.spec.ts
```

### Integration Tests (Vitest)

```bash
# Run all integration tests
npm run test:integration

# Watch mode
npm run test:integration -- --watch

# Specific workflow
npm run test:integration -- tests/integration/order-workflow.spec.ts
```

### E2E Tests (Playwright)

```bash
# Run all E2E tests
npm run test:e2e

# Headed mode (see browser)
npm run test:e2e -- --headed

# Debug mode
npm run test:e2e -- --debug

# Single test file
npm run test:e2e -- order-flow.spec.ts
```

### Full Test Suite

```bash
# Run all tests (unit + integration + e2e)
npm run test

# With coverage report
npm run test:coverage
```

## Test Files

### Integration Tests

**tests/integration/order-workflow.spec.ts** (30 tests)
- Complete order lifecycle (create → update → delete)
- Order filtering by status/customer/date
- Order total calculations
- Status transitions
- Validation rules

**tests/integration/inventory-workflow.spec.ts** (20 tests)
- Stock quantity updates
- Reserve/release workflows
- Overselling prevention
- Low stock alerts
- Warehouse coordination

**tests/integration/customer-workflow.spec.ts** (18 tests)
- Customer CRUD operations
- Credit usage tracking
- At-risk customer detection
- Status management

### E2E Tests

**tests/e2e/order-flow.spec.ts** (6 tests)
- Full order workflow (UI)
- Order filtering
- Order editing
- Order deletion
- Total calculations

**tests/e2e/inventory-flow.spec.ts** (3 tests)
- Inventory transfer UI
- Inventory level display
- Low stock alerts

## Coverage Requirements

| Layer | Target | Actual | Status |
|-------|--------|--------|--------|
| Primitives | 60% | TBD | 🔄 |
| Typed Fields | 70% | TBD | 🔄 |
| Domain Fields | 80% | TBD | 🔄 |
| Composites | 60% | TBD | 🔄 |
| Stores | 85% | TBD | 🔄 |
| **Overall** | **80%** | **TBD** | **🔄** |

## CI/CD Integration

### GitHub Actions (if applicable)

```yaml
test:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-node@v3
    - run: npm ci
    - run: npm run test:unit -- --coverage
    - run: npm run test:integration
    - run: npm run test:e2e
    - uses: codecov/codecov-action@v3
```

## Best Practices

1. **Isolation**: Each test should be independent
2. **Clarity**: Test names describe what they test
3. **Coverage**: Focus on critical paths (orders, inventory, customers)
4. **Speed**: Unit tests < 100ms, integration < 500ms, E2E < 5s
5. **Maintenance**: Keep tests simple and readable

## Debugging

### Debug Unit Tests

```bash
npm run test:unit -- --inspect-brk=127.0.0.1:9229 tests/unit/stores/orders.spec.ts
```

### Debug E2E Tests

```bash
npm run test:e2e -- --debug tests/e2e/order-flow.spec.ts
```

### View Playwright Report

```bash
npx playwright show-report
```

## Metrics

### Test Execution Time (Baseline)

- Unit tests: ~45 seconds
- Integration tests: ~15 seconds
- E2E tests: ~60 seconds
- **Total**: ~2 minutes

### Coverage Trends

Track coverage weekly to ensure quality:

```bash
npm run test:coverage -- --reporter=json > coverage/$(date +%Y-%m-%d).json
```

## Next Steps

1. Expand E2E tests (Dashboard, User Management, Settings)
2. Add performance testing (Lighthouse)
3. Add accessibility testing (axe-core)
4. Setup visual regression testing
5. Add load testing (k6 or Artillery)