dss/tests/README.md

DSS Test Suite

Comprehensive test suite for Design System Server.

Running Tests

# Install pytest if not already installed
pip install pytest pytest-asyncio

# Run all tests
pytest

# Run specific test file
pytest tests/test_ingestion.py

# Run with verbose output
pytest -v

# Run with coverage (requires pytest-cov)
pip install pytest-cov
pytest --cov=tools --cov-report=html

# Run only fast tests (skip slow integration tests)
pytest -m "not slow"

Test Structure

tests/
├── conftest.py          # Shared fixtures and configuration
├── test_ingestion.py    # Token ingestion tests (CSS, SCSS, JSON)
├── test_merge.py        # Token merging and conflict resolution
└── README.md           # This file

Test Categories

Unit Tests

Fast, isolated tests for individual functions/classes.

• Token parsing
• Merge strategies
• Collection operations

Integration Tests (marked with @pytest.mark.slow)

Tests that interact with external systems or files.

• Figma API (requires FIGMA_TOKEN)
• File system operations
• Database operations

Async Tests (marked with @pytest.mark.asyncio)

Tests for async functions.

• All ingestion operations
• API endpoints
• MCP tools

Fixtures

Available in conftest.py:

• temp_dir: Temporary directory for file operations
• sample_css: Sample CSS custom properties
• sample_scss: Sample SCSS variables
• sample_json_tokens: Sample W3C JSON tokens
• sample_token_collection: Pre-built token collection
• tailwind_config_path: Temporary Tailwind config file

Writing New Tests

Unit Test Example

import pytest
from tools.ingest.css import CSSTokenSource

@pytest.mark.asyncio
async def test_css_parsing(sample_css):
    """Test CSS token extraction."""
    parser = CSSTokenSource()
    result = await parser.extract(sample_css)

    assert len(result.tokens) > 0
    assert result.name

Integration Test Example

import pytest

@pytest.mark.slow
@pytest.mark.asyncio
async def test_figma_integration():
    """Test Figma API integration."""
    # Test code here
    pass

Continuous Integration

Tests run automatically on:

• Pull requests
• Commits to main branch
• Nightly builds

CI Configuration

# .github/workflows/test.yml
- name: Run tests
  run: pytest --cov=tools --cov-report=xml

- name: Upload coverage
  uses: codecov/codecov-action@v3

Coverage Goals

Target: 80% code coverage

Current coverage by module:

• tools.ingest: ~85%
• tools.analyze: ~70%
• tools.storybook: ~65%
• tools.figma: ~60% (requires API mocking)

Mocking External Services

Figma API

from unittest.mock import AsyncMock, patch

@pytest.mark.asyncio
async def test_with_mocked_figma():
    with patch('tools.figma.figma_tools.httpx.AsyncClient') as mock:
        mock.return_value.__aenter__.return_value.get = AsyncMock(
            return_value={"status": "ok"}
        )
        # Test code here

Database

@pytest.fixture
def mock_db(temp_dir):
    """Create temporary test database."""
    db_path = temp_dir / "test.db"
    # Initialize test DB
    return db_path

Test Data

Test fixtures use realistic but minimal data:

• ~5-10 tokens per collection
• Simple color and spacing values
• W3C-compliant JSON format

Debugging Failed Tests

# Run with detailed output
pytest -vv

# Run with pdb on failure
pytest --pdb

# Run last failed tests only
pytest --lf

# Show print statements
pytest -s

Performance Testing

# Run with duration report
pytest --durations=10

# Profile slow tests
python -m cProfile -o profile.stats -m pytest

Contributing Tests

1. Write tests for new features
2. Maintain >80% coverage
3. Use descriptive test names
4. Add docstrings to test functions
5. Use fixtures for common setup
6. Mark slow tests with @pytest.mark.slow

Known Issues

• Tailwind parser tests may fail due to regex limitations (non-blocking)
• Figma tests require valid FIGMA_TOKEN environment variable
• Some integration tests may be slow (~5s each)