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

{
  "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

# 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

# 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.