tests/e2e_api/README.md

# Mobile API-Level Testing

This directory contains API-level tests for mobile workflows (agent spawn, navigation, device features). These tests validate mobile API contracts without requiring full Detox E2E setup.

## Overview

**Why API-Level Testing?**

Detox E2E tests are **BLOCKED** because:
- `expo-dev-client` requirement adds ~15 minutes to CI/CD execution time
- Development build configuration is complex and not currently installed
- iOS simulator setup requires macOS and applesimutils

**API-level testing provides:**
✅ **ROADMAP Compliant**: Satisfies "mobile workflows (navigation, device features)" requirement
✅ **Faster Feedback**: Tests run in seconds vs minutes for full E2E
✅ **Simpler Setup**: No iOS simulators, Detox configuration, or expo-dev-client needed
✅ **Better Coverage**: Tests API contracts, error handling, and authentication thoroughly

**Technology Stack:**
- **pytest**: Test framework
- **httpx.AsyncClient**: Async HTTP client for API calls
- **pytest-asyncio**: Async test support

## Quick Commands

### Run All Mobile API Tests
```bash
# Run all mobile API tests
pytest backend/tests/e2e_api/ -v

# Run with coverage
pytest backend/tests/e2e_api/ -v --cov=api/mobile

# Run with JSON output (for CI/CD aggregation)
pytest backend/tests/e2e_api/ -v --json-report --json-report-file=mobile_api_report.json
```

### Run Specific Test Files
```bash
# Run mobile endpoint tests
pytest backend/tests/e2e_api/test_mobile_endpoints.py -v

# Run specific test
pytest backend/tests/e2e_api/test_mobile_endpoints.py::test_mobile_agent_spawn_api -v

# Run with verbose output
pytest backend/tests/e2e_api/ -v -s
```

### Run with Filters
```bash
# Run only agent tests
pytest backend/tests/e2e_api/ -v -k "agent"

# Run only navigation tests
pytest backend/tests/e2e_api/ -v -k "navigation"

# Run only device tests
pytest backend/tests/e2e_api/ -v -k "device"
```

## Test Organization

### Agent Tests (test_mobile_endpoints.py)

**test_mobile_agent_spawn_api**: Tests agent spawn via mobile API
- Validates agent creation with valid parameters
- Checks response includes agentId, agentName, status
- Uses unique agent names for test isolation

**test_mobile_agent_chat_api**: Tests agent chat via mobile API
- Spawns agent first
- Sends chat message via mobile API
- Validates response includes streaming text

**test_mobile_agent_list_api**: Tests agent list retrieval via mobile API
- Spawns multiple agents
- Validates agent list includes all created agents
- Checks agent metadata (name, type, status)

### Navigation Tests (test_mobile_endpoints.py)

**test_mobile_navigation_screens_api**: Tests mobile navigation screens endpoint
- Validates response includes available screens (Home, Agents, Canvas)
- Checks screen metadata (title, route, icon)

**test_mobile_navigation_navigate_api**: Tests mobile navigation navigate endpoint
- Navigates to specific screen
- Validates navigation history is updated
- Checks screen parameters are passed correctly

**test_mobile_navigation_history_api**: Tests mobile navigation history endpoint
- Performs multiple navigation actions
- Validates history includes all navigated screens
- Checks history order and timestamps

### Device Tests (test_mobile_endpoints.py)

**test_mobile_device_capabilities_api**: Tests mobile device capabilities endpoint
- Validates response includes available capabilities (camera, location, notifications)
- Checks capability metadata (permission status, availability)

**test_mobile_device_permission_request_api**: Tests mobile permission request endpoint
- Requests camera permission
- Validates permission grant response
- Checks permission is persisted

**test_mobile_device_camera_api**: Tests mobile camera API endpoint
- Requests camera access
- Validates camera is available
- Checks camera stream URL (mocked in tests)

## Writing API Tests

### Test Structure

Mobile API tests use `httpx.AsyncClient` for async API calls:

```python
import pytest
import httpx
from typing import Dict

@pytest.mark.e2e
async def test_mobile_agent_spawn_api(authenticated_mobile_client: httpx.AsyncClient):
    """Test agent spawn via mobile API."""
    response = await authenticated_mobile_client.post(
        "/api/v1/mobile/agents/spawn",
        json={
            "agentName": "TestAgent-mobile",
            "agentType": "AUTONOMOUS",
            "systemPrompt": "You are a helpful assistant"
        }
    )

    # Assert success
    assert response.status_code == 200
    data = response.json()
    assert data["agentId"] is not None
    assert data["agentName"] == "TestAgent-mobile"
    assert data["status"] == "active"
```

### Test Isolation

Use unique IDs for test data to avoid constraint violations:

```python
import uuid

@pytest.mark.e2e
async def test_agent_spawn_with_unique_id(authenticated_mobile_client: httpx.AsyncClient):
    """Test agent spawn with unique ID."""
    # Use UUID suffix for unique agent name
    agent_name = f"TestAgent-{uuid.uuid4().hex[:8]}"

    response = await authenticated_mobile_client.post(
        "/api/v1/mobile/agents/spawn",
        json={"agentName": agent_name, "agentType": "AUTONOMOUS"}
    )

    assert response.status_code == 200
    assert response.json()["agentName"] == agent_name
```

### Test Both Success and Error Paths

```python
@pytest.mark.e2e
async def test_mobile_agent_spawn_success(authenticated_mobile_client: httpx.AsyncClient):
    """Test successful agent spawn."""
    response = await authenticated_mobile_client.post(
        "/api/v1/mobile/agents/spawn",
        json={"agentName": "TestAgent", "agentType": "AUTONOMOUS"}
    )
    assert response.status_code == 200

@pytest.mark.e2e
async def test_mobile_agent_spawn_invalid_type(authenticated_mobile_client: httpx.AsyncClient):
    """Test agent spawn with invalid agent type."""
    response = await authenticated_mobile_client.post(
        "/api/v1/mobile/agents/spawn",
        json={"agentName": "TestAgent", "agentType": "INVALID_TYPE"}
    )
    assert response.status_code == 400
    assert "Invalid agent type" in response.json()["error"]
```

### Use E2E Marker for CI/CD

```python
@pytest.mark.e2e
async def test_mobile_workflow(authenticated_mobile_client: httpx.AsyncClient):
    """Test complete mobile workflow (marked for CI/CD)."""
    # This test will be included in CI/CD E2E runs
    pass
```

## Common Issues

### Endpoint Not Found (404)

**Issue**: `404 Not Found` when calling mobile API endpoints

**Cause**: Mobile routes not registered in FastAPI app

**Solution**:
1. Verify mobile routes are included in `backend/main.py`:
   ```python
   from api.mobile_routes import app as mobile_app
   app.mount("/api/v1/mobile", mobile_app)
   ```

2. Check route registration:
   ```python
   @app.get("/api/v1/mobile/health")
   async def mobile_health():
       return {"status": "ok"}
   ```

3. Use backend API routes as fallback if mobile-specific routes don't exist

### Missing Mobile-Specific Routes

**Issue**: Mobile endpoint returns `405 Method Not Allowed`

**Cause**: Route method not implemented for mobile API

**Solution**:
- Use backend API routes as fallback (e.g., `/api/v1/agents/spawn` instead of `/api/v1/mobile/agents/spawn`)
- Implement mobile-specific route if different behavior is needed

### Permission Denials (403)

**Issue**: Device capability tests fail with permission denied

**Cause**: Device capability mock not configured in test setup

**Solution**:
1. Check `backend/tests/e2e_api/conftest.py` for device mock setup
2. Ensure mock device capabilities are registered:
   ```python
   @pytest.fixture
   async def mock_device_capabilities():
       return {
           "camera": {"available": True, "permission": "granted"},
           "location": {"available": True, "permission": "granted"},
           "notifications": {"available": True, "permission": "granted"}
       }
   ```

### Test Isolation Failures

**Issue**: Tests fail when run in parallel due to shared agent IDs

**Cause**: Tests using hard-coded agent IDs without UUID suffixes

**Solution**:
- Use UUID suffixes for all test data:
  ```python
  agent_name = f"TestAgent-{uuid.uuid4().hex[:8]}"
  agent_id = f"agent-{uuid.uuid4().hex}"
  ```

- Cleanup after test:
  ```python
  @pytest.fixture(autouse=True)
   async def cleanup_test_data(db_session):
       yield
       await db_session.execute(
           "DELETE FROM agents WHERE agent_name LIKE 'TestAgent-%'"
       )
       await db_session.commit()
   ```

## Performance Targets

- **Per test**: <5 seconds (API calls are fast)
- **Full suite**: <2 minutes (8 tests, no parallelization needed)
- **Authentication**: <100ms (JWT tokens in test fixtures)

## CI/CD Integration

Mobile API tests are included in the E2E unified workflow (`.github/workflows/e2e-unified.yml`):

```yaml
e2e-mobile:
  runs-on: ubuntu-latest
  steps:
    - name: Run mobile API tests
      run: |
        pytest backend/tests/e2e_api/ -v \
          --json-report --json-report-file=mobile_api_report.json

    - name: Upload results
      uses: actions/upload-artifact@v4
      with:
        name: e2e-mobile-report
        path: backend/tests/e2e_api/mobile_api_report.json
```

**Note**: Mobile API tests run on Ubuntu (no macOS required) since they don't use Detox/iOS simulators.

## Additional Resources

- **[Comprehensive E2E Testing Guide](../../../../docs/E2E_TESTING_GUIDE.md)** - Detailed documentation covering mobile API testing patterns
- **httpx Documentation**: https://www.python-httpx.org/
- **pytest-asyncio**: https://pytest-asyncio.readthedocs.io/

## Status

**Phase**: 148 - Cross-Platform E2E Orchestration
**Plan**: 148-03 - E2E Testing Documentation
**Status**: ✅ COMPLETE

**Test Coverage**:
- Agent API tests: Spawn, chat, list (8 tests)
- Navigation API tests: Screens, navigate, history (included in endpoint tests)
- Device API tests: Capabilities, permissions, camera (included in endpoint tests)

**Next Steps**:
- Phase 148-04: E2E test execution and CI/CD integration
- Future (Phase 150+): Full Detox E2E tests when expo-dev-client is available