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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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**:
  ```python
  class TestStoreProductAPI:      # Store product endpoints
  class TestAdminUserAPI:          # Admin user endpoints
  class TestPublicCatalogAPI:      # Public catalog endpoints
  ```

### Test Functions

- **Pattern**: `test_<action>_<scenario>`
- **Examples**:
  ```python
  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:

```python
# 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:

```python
# 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:

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

### 5. Test Both Success and Failure

Cover all scenarios:

```python
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](store-api-testing.md) 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

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

```python
# 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
```

```bash
# 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](store-api-testing.md) - Comprehensive store testing documentation
- [Testing Guide](testing-guide.md) - Overall testing strategy
- [Test Maintenance](test-maintenance.md) - Maintaining test quality