orion/docs/testing/test-structure.md

Test Structure

Overview

The integration test suite is organized to mirror the API code structure, providing clear mapping between code and tests for better maintainability, discoverability, and team collaboration.

Directory Structure

tests/integration/api/v1/
├── admin/                           # Admin API tests
│   ├── __init__.py
│   └── README.md
├── store/                          # Store API tests
│   ├── __init__.py
│   ├── README.md
│   ├── test_authentication.py      # Authentication tests
│   └── test_dashboard.py           # Dashboard tests
├── public/                          # Public API tests
│   ├── __init__.py
│   └── README.md
└── shared/                          # Shared/common tests
    ├── __init__.py
    └── README.md

Structure Mapping

The test structure directly mirrors the API code structure:

app/api/v1/admin/     →  tests/integration/api/v1/admin/
app/api/v1/store/    →  tests/integration/api/v1/store/
app/api/v1/platform/    →  tests/integration/api/v1/platform/
app/api/v1/shared/    →  tests/integration/api/v1/shared/

Benefits

1. Easy Discoverability

Finding tests is straightforward:

# Looking for store product tests?
ls tests/integration/api/v1/store/test_products.py

# Looking for admin user tests?
ls tests/integration/api/v1/admin/test_users.py

2. Clear Code-to-Test Mapping

Code change:    app/api/v1/store/products.py
Test location:  tests/integration/api/v1/store/test_products.py
                ↑ 1:1 mapping!

3. Faster Testing

Run tests for specific areas without complex filters:

# Test only store endpoints
pytest tests/integration/api/v1/store/ -v

# Test only admin endpoints
pytest tests/integration/api/v1/admin/ -v

4. Better Code Reviews

Changes are grouped logically:

Pull Request:
  Changed files:
    app/api/v1/store/products.py                      # Code
    tests/integration/api/v1/store/test_products.py  # Test
                                                       ↑ Easy to verify

5. Team Collaboration

Different teams can work in parallel with fewer conflicts:

Admin Team:   works in tests/integration/api/v1/admin/
Store Team:  works in tests/integration/api/v1/store/
Public Team:  works in tests/integration/api/v1/platform/

Running Tests

By Area

# All store tests
pytest tests/integration/api/v1/store/ -v

# All admin tests
pytest tests/integration/api/v1/admin/ -v

# All public tests
pytest tests/integration/api/v1/platform/ -v

# All shared tests
pytest tests/integration/api/v1/shared/ -v

Specific Test Files

# Run specific test file
pytest tests/integration/api/v1/store/test_authentication.py -v

# Run specific test class
pytest tests/integration/api/v1/store/test_authentication.py::TestStoreAPIAuthentication -v

# Run specific test
pytest tests/integration/api/v1/store/test_authentication.py::TestStoreAPIAuthentication::test_store_auth_me_success -v

With Coverage

# Store API coverage
pytest tests/integration/api/v1/store/ \
  --cov=app/api/v1/store \
  --cov-report=html

# View coverage report
open htmlcov/index.html

Using Markers

All tests use pytest markers for flexible filtering:

# All store tests
pytest -m store -v

# Store API tests only
pytest -m "store and api" -v

# Store authentication tests
pytest -m "store and auth" -v

Naming Conventions

Test Files

• Pattern: test_<endpoint_name>.py
• Examples:
  • test_products.py - Tests for products endpoints
  • test_authentication.py - Tests for authentication
  • test_dashboard.py - Tests for dashboard endpoints

Test Classes

• Pattern: Test<Area><Feature>API
• Examples:

  class TestStoreProductAPI:      # Store product endpoints
  class TestAdminUserAPI:          # Admin user endpoints
  class TestPublicCatalogAPI:      # Public catalog endpoints
  

Test Functions

• Pattern: test_<action>_<scenario>
• Examples:

  def test_list_products_success(self):
  def test_create_product_without_auth(self):
  def test_update_product_invalid_data(self):
  def test_delete_product_not_found(self):
  

Best Practices

1. Mirror API Structure

Always create test files that mirror the API code structure:

# API Code
app/api/v1/store/products.py

# Test File
tests/integration/api/v1/store/test_products.py

2. One Test File Per API Module

Keep tests focused:

• Each API module gets its own test file
• Easy to find and maintain
• Clear responsibility

3. Descriptive Test Names

Use clear, descriptive names:

# Good ✅
class TestStoreProductAPI:
    def test_list_products_success(self):
    def test_create_product_without_auth(self):
    def test_update_product_with_invalid_data(self):

# Avoid ❌
class TestProducts:
    def test_api(self):
    def test_endpoint(self):

4. Appropriate Markers

Mark tests appropriately:

@pytest.mark.integration
@pytest.mark.api
@pytest.mark.store
class TestStoreProductAPI:
    pass

5. Test Both Success and Failure

Cover all scenarios:

class TestStoreProductAPI:
    # Success cases
    def test_list_products_success(self):
    def test_create_product_success(self):

    # Failure cases
    def test_list_products_without_auth(self):
    def test_create_product_invalid_data(self):
    def test_create_product_as_admin_user(self):

Test Areas

Admin Tests (admin/)

Tests for admin-only endpoints at /api/v1/admin/*:

• User management
• System configuration
• Analytics and reporting
• Store approval workflows

Requirements:

• Admin user authentication
• Admin-specific permissions
• Cross-store data access

Store Tests (store/)

Tests for store endpoints at /api/v1/store/*:

• Product management
• Order processing
• Customer management
• Analytics and stats
• Team management

Requirements:

• Store user authentication
• Store context isolation
• StoreUser associations

See Store API Testing Guide for details.

Public Tests (public/)

Tests for public endpoints at /api/v1/platform/*:

• Product catalog browsing
• Public store profiles
• Search functionality

Requirements:

• No authentication required
• Rate limiting tests
• Public data only

Shared Tests (shared/)

Tests for shared/common functionality:

• Authentication endpoints
• Pagination utilities
• Filtering utilities
• Common error handling

Requirements:

• Work across all user types
• Consistent behavior
• Proper error handling

Migration Status

Completed ✅

Area	Files	Tests	Status
Store Authentication	store/test_authentication.py	30+	✅ Complete
Store Dashboard	store/test_dashboard.py	12	✅ Complete

Pending ⚠️

Legacy File	New Location	Priority
test_store_endpoints.py	Split into store/test_*.py	High
test_admin_endpoints.py	Split into admin/test_*.py	High
test_auth_endpoints.py	shared/test_auth.py	Medium
test_marketplace_*.py	store/test_marketplace_*.py	Medium
test_inventory_endpoints.py	store/test_inventory.py	Medium

Adding New Tests

When adding new integration tests:

1. Identify the API area (admin/store/public/shared)
2. Create test file in appropriate folder
3. Follow naming conventions
4. Add appropriate markers
5. Test both success and failure cases
6. Update coverage reports

Example: Adding Store Products Tests

# 1. Create test file
touch tests/integration/api/v1/store/test_products.py

# 2. Write tests following conventions
import pytest

@pytest.mark.integration
@pytest.mark.api
@pytest.mark.store
class TestStoreProductAPI:
    """Tests for store product management endpoints"""

    def test_list_products_success(self, client, store_user_headers):
        """Test listing products with authentication"""
        response = client.get(
            "/api/v1/store/products",
            headers=store_user_headers
        )
        assert response.status_code == 200
        data = response.json()
        assert "products" in data
        assert "total" in data

    def test_list_products_without_auth(self, client):
        """Test listing products requires authentication"""
        response = client.get("/api/v1/store/products")
        assert response.status_code == 401

    def test_create_product_success(self, client, store_user_headers):
        """Test creating product with valid data"""
        response = client.post(
            "/api/v1/store/products",
            headers=store_user_headers,
            json={
                "name": "Test Product",
                "price": 29.99,
                "description": "Test description"
            }
        )
        assert response.status_code == 201

# 3. Run tests
pytest tests/integration/api/v1/store/test_products.py -v

# 4. Check coverage
pytest tests/integration/api/v1/store/test_products.py \
  --cov=app/api/v1/store/products \
  --cov-report=html

Troubleshooting

Tests Not Discovered

Problem: pytest doesn't find tests

Solutions:

• Ensure __init__.py exists in test directory
• Check file naming: test_*.py or *_test.py
• Verify test functions start with test_
• Check pytest collection with: pytest --collect-only

Import Errors

Problem: Fixtures not found

Solutions:

• Check pytest_plugins in tests/conftest.py
• Use absolute imports: from tests.fixtures.auth_fixtures import ...
• Verify fixture files are in correct location

Coverage Not Working

Problem: Coverage report shows 0%

Solutions:

• Specify correct source path: --cov=app/api/v1/store
• Check test actually exercises the code
• Verify coverage config in pyproject.toml or .coveragerc

See Also

• Store API Testing Guide - Comprehensive store testing documentation
• Testing Guide - Overall testing strategy
• Test Maintenance - Maintaining test quality