Testing Guide

This guide covers testing practices and methodologies used in Tessera development.

Test Structure

The test suite is organized into three main categories:

tests/
├── fixtures/       # Shared test fixtures and utilities
├── integration/    # End-to-end and integration tests
└── unit/          # Unit tests for individual components

Testing Tools

Tessera uses these testing tools:

• pytest: Main testing framework

• pytest-cov: Code coverage reporting

• pytest-asyncio: Async test support

• hypothesis: Property-based testing

Running Tests

Basic Usage:

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/unit/test_state.py

# Run specific test function
pytest tests/unit/test_state.py::test_state_transition

Coverage Reports:

# Generate coverage report
pytest --cov=jam

# Generate HTML report
pytest --cov=jam --cov-report=html

# View report in browser
open htmlcov/index.html

Writing Tests

1. Unit Tests:

   # tests/unit/test_feature.py
   import pytest
   from jam.feature import Feature
   
   def test_feature_behavior():
       # Arrange
       feature = Feature()
   
       # Act
       result = feature.process()
   
       # Assert
       assert result == expected
   

2. Integration Tests:

   # tests/integration/test_workflow.py
   import pytest
   from jam.workflow import Workflow
   
   @pytest.mark.asyncio
   async def test_end_to_end():
       # Setup
       workflow = Workflow()
   
       # Execute
       result = await workflow.run()
   
       # Verify
       assert result.status == "success"
   

Using Fixtures

1. Create Fixtures:

   # tests/fixtures/conftest.py
   import pytest
   
   @pytest.fixture
   def test_data():
       return {
           "key": "value"
       }
   
   @pytest.fixture
   async def async_resource():
       resource = await setup_resource()
       yield resource
       await cleanup_resource()
   

2. Use Fixtures:

   # tests/unit/test_feature.py
   def test_with_fixture(test_data):
       assert process(test_data) == expected
   
   @pytest.mark.asyncio
   async def test_async(async_resource):
       result = await async_resource.query()
       assert result
   

Property-Based Testing

Using Hypothesis:

from hypothesis import given, strategies as st

@given(st.integers(), st.integers())
def test_addition_properties(x, y):
    result = add(x, y)
    assert result == add(y, x)  # Commutative
    assert add(result, 0) == result  # Identity

Mocking

Using pytest-mock:

def test_with_mock(mocker):
    # Create mock
    mock_db = mocker.patch('jam.database.Database')
    mock_db.query.return_value = expected_result

    # Use mock
    result = process_data()

    # Verify
    mock_db.query.assert_called_once()
    assert result == expected_result

Best Practices

1. Test Organization: * One test file per module * Clear test names describing behavior * Group related tests in classes

2. Test Design: * Follow Arrange-Act-Assert pattern * Test edge cases and error conditions * Keep tests focused and isolated

3. Fixtures: * Use fixtures for common setup * Clean up resources properly * Share fixtures via conftest.py

4. Coverage: * Aim for high test coverage * Focus on critical paths * Don’t sacrifice quality for coverage

5. Performance: * Keep tests fast * Use async testing where appropriate * Minimize external dependencies