dss/.dss/TEST_STRATEGY.md

# Comprehensive Test Strategy: Phases 6-8 & Figma Integration

**Date**: 2025-12-05
**Purpose**: Test complete flow from Figma → DSS → Storybook with self-referential design system
**Status**: PLANNING

---

## Architecture Overview: Self-Referential Design System

```
Figma Design File (Source of Truth)
    ↓
DSS Figma Extractor (Phase 7)
    ↓
Token/Asset Database
    ↓
DSS Component Library (Built using own tokens)
    ↓
Storybook (Stories showcase DSS using DSS tokens)
    ↓
Output Formats (CSS, JSON, TS, etc.)
    ↓
Integration Tests (Verify full loop)
```

**Key Challenge**: DSS components consume tokens that came from Figma, which were designed to match DSS components. This is intentional (eating your own dogfood).

---

## Test Layers Strategy

### Layer 1: Unit Tests (Individual Modules)
- Config loader initialization
- Component registry management
- Audit logging functionality
- Workflow persistence snapshots
- Route guard validation
- Error recovery mechanisms

### Layer 2: Integration Tests
- Config → Component Registry flow
- Figma extraction → Token sync
- Error handling with recovery points
- Permission checks with logging
- State persistence and restoration

### Layer 3: Figma API Tests
- Real Figma file connection
- Variable extraction from DSS file
- Component definition extraction
- Style and asset extraction
- Token format conversion

### Layer 4: End-to-End Tests
- Complete Figma → DSS → Storybook workflow
- Token sync across all formats
- Error recovery in full flow
- Multi-format export validation

### Layer 5: Visual Regression Tests
- Storybook stories using DSS tokens
- Component rendering with real tokens
- Theme switching with token variables
- Chromatic visual testing

### Layer 6: Snapshot Tests
- Token export format stability
- Component rendering consistency
- Output format preservation

---

## Testing Tools & Setup

### Required Dependencies
```json
{
  "devDependencies": {
    "jest": "^29.0.0",
    "jest-environment-jsdom": "^29.0.0",
    "@testing-library/react": "^14.0.0",
    "@testing-library/jest-dom": "^6.0.0",
    "pytest": "^7.0.0",
    "pytest-asyncio": "^0.21.0",
    "@storybook/test-runner": "^0.13.0",
    "@chromatic-com/storybook": "^1.0.0"
  }
}
```

### Test File Structure
```
project/
├── admin-ui/js/core/__tests__/
│   ├── config-loader.test.js
│   ├── component-config.test.js
│   ├── workflow-persistence.test.js
│   ├── audit-logger.test.js
│   ├── route-guards.test.js
│   ├── error-recovery.test.js
│   ├── config-component-integration.test.js
│   └── phase8-integration.test.js
│
├── admin-ui/__tests__/
│   ├── e2e-full-workflow.test.js
│   └── __snapshots__/
│
├── dss-mvp1/src/__tests__/
│   ├── component-rendering.test.jsx
│   └── __snapshots__/
│
├── dss-mvp1/.storybook/
│   └── test-setup.js
│
└── tools/api/tests/
    ├── test_figma_integration.py
    ├── test_token_formats.py
    ├── test_token_snapshots.py
    └── __snapshots__/
```

---

## Test Execution Matrix

### Environment Variables Required
```bash
# Figma Integration
export FIGMA_API_KEY="figd_xxxxxxxxxxxx"
export DSS_FIGMA_FILE_KEY="xxxxxxxxxxxx"  # Main DSS design file
export DSS_TEST_FIGMA_FILE="yyyyyyyyyyyy" # Disposable test file

# DSS Configuration
export DSS_HOST="dss.overbits.luz.uy"
export DSS_PORT="3456"
export STORYBOOK_PORT="6006"

# Test Configuration
export TEST_ENV="test"
export VERBOSE_TESTS="true"
```

### Test Commands
```bash
# Run all tests
npm run test

# Unit tests only
npm run test:unit

# Integration tests
npm run test:integration

# Figma real-file tests (requires API key)
npm run test:figma

# E2E tests (requires running server)
npm run test:e2e

# Visual regression tests (Storybook)
npm run test:visual

# With coverage report
npm run test -- --coverage

# Watch mode for development
npm run test -- --watch

# Single test file
npm run test -- config-loader.test.js
```

---

## Implementation Phases

### Phase 1: Unit Tests (This Week)
Create test files for:
1. config-loader.js
2. component-config.js
3. All Phase 8 modules

Target: 80%+ coverage

### Phase 2: Figma Integration (Next Week)
1. Test real Figma file connection
2. Test token extraction
3. Test component extraction
4. Create token export modules

Target: Full workflow validation

### Phase 3: Storybook Setup (Week After)
1. Configure Storybook with DSS tokens
2. Create component stories using tokens
3. Setup visual regression testing
4. Chromatic integration

Target: Visual consistency

### Phase 4: CI/CD (Final Week)
1. GitHub Actions workflow
2. Automated test runs on push
3. Coverage reporting
4. Visual regression tracking

Target: Automated quality gates

---

## Success Criteria

| Layer | Coverage | Pass Rate | Requirement |
|-------|----------|-----------|-------------|
| Unit | >80% | 100% | All modules |
| Integration | >70% | 100% | All interactions |
| Figma API | N/A | 100% | Real extraction |
| E2E | >60% | 100% | Full workflow |
| Visual | >90% | 100% | Component rendering |
| **Overall** | **>75%** | **100%** | Production ready |

---

## Key Test Scenarios

### Scenario 1: Blank State → Full Import
- Load app (config not cached)
- Connect to Figma
- Extract all tokens, components, styles
- Import into database
- Verify all formats work

### Scenario 2: Crash & Recovery
- Create recovery point
- Simulate error
- Verify error logged
- Restore from recovery point
- Resume operation

### Scenario 3: Figma Update → DSS Sync
- Get latest Figma file
- Extract changed tokens only
- Sync to DSS
- Update Storybook
- Verify visual changes

### Scenario 4: Multi-Format Export
- Extract from Figma
- Export as CSS variables
- Export as JSON
- Export as TypeScript
- Verify all formats match

### Scenario 5: Permission Enforcement
- Attempt unauthorized action
- Verify guard blocks access
- Check audit log
- Verify error recovery

---

## Next Immediate Actions

1. ✅ Create test strategy document (this file)
2. 🔄 Create unit test files for all modules
3. 🔄 Setup Figma test environment
4. 🔄 Create token format exporters
5. 🔄 Setup Storybook with DSS tokens
6. 🔄 Create end-to-end tests

All test files will be provided next in this session.