tests/mobile_api/README.md

Mobile API Testing

Overview

Mobile API testing provides API-level test coverage for mobile app functionality without the overhead of UI automation. Tests use FastAPI's TestClient for in-memory API testing, making them 10-100x faster than browser-based tests.

Key Benefits

• API-First Approach: Direct API calls (no browser or mobile device needed)
• Fast Execution: <10ms per request with TestClient (no network overhead)
• Consistency: Response structure matches web API for cross-platform compatibility
• Governance: Tests verify agent maturity and permission enforcement
• CI/CD Friendly: Graceful skip when device hardware not available

Prerequisites

• Python 3.11+
• FastAPI TestClient (included with FastAPI)
• Test database (SQLite or PostgreSQL)
• Authentication fixtures (from mobile_api.fixtures.mobile_fixtures)

Running Tests

Run All Mobile API Tests

# From project root
pytest backend/tests/mobile_api/ -v

# With coverage
pytest backend/tests/mobile_api/ --cov=backend/api --cov-report=html

# With detailed output
pytest backend/tests/mobile_api/ -v -s

Run Specific Test Files

# Authentication tests
pytest backend/tests/mobile_api/test_mobile_auth.py -v

# Agent execution tests
pytest backend/tests/mobile_api/test_mobile_agent_execution.py -v

# Workflow execution tests
pytest backend/tests/mobile_api/test_mobile_workflow_execution.py -v

# Device features tests
pytest backend/tests/mobile_api/test_mobile_device_features.py -v

Run Specific Test Classes or Tests

# Run specific test class
pytest backend/tests/mobile_api/test_mobile_auth.py::TestMobileLogin -v

# Run specific test
pytest backend/tests/mobile_api/test_mobile_auth.py::TestMobileLogin::test_mobile_login_success -v

# Run tests matching pattern
pytest backend/tests/mobile_api/ -k "login" -v

Test Categories

1. Authentication Tests (test_mobile_auth.py)

Tests for authentication endpoints:

• Login Success: Valid credentials return access token
• Login Failure: Invalid credentials return 401 error
• Token Refresh: Returns new access token
• Token Validation: /api/auth/me returns user data
• Logout: Invalidates token (client-side)

Coverage:

• POST /api/auth/login
• POST /api/auth/refresh
• GET /api/auth/me
• POST /api/auth/logout

2. Agent Execution Tests (test_mobile_agent_execution.py)

Tests for agent execution endpoints:

• Agent Execute: Sync execution with query
• Agent Execute with Params: Custom parameters passed correctly
• Agent Stream: Streaming execution via WebSocket
• Agent Governance: Maturity level enforcement (STUDENT/INTERN/SUPERVISED/AUTONOMOUS)
• Agent History: Execution history listing

Coverage:

• GET /api/v1/agents
• POST /api/v1/agents/{agent_id}/execute
• POST /api/atom-agent/chat
• POST /api/atom-agent/chat/stream
• GET /api/v1/agents/executions

3. Workflow Execution Tests (test_mobile_workflow_execution.py)

Tests for workflow execution endpoints:

• Workflow Create: Create new workflow
• Workflow Add Skill: Add skills to workflow
• Workflow Execute: Run workflow with input
• Workflow DAG Validation: Detect cyclic dependencies
• Workflow History: Execution history with pagination

Coverage:

• GET /api/v1/workflows
• POST /api/v1/workflows
• POST /api/v1/workflows/{workflow_id}/skills
• POST /api/v1/workflows/{workflow_id}/execute
• POST /api/v1/workflows/validate
• GET /api/v1/workflows/executions

4. Device Features Tests (test_mobile_device_features.py)

Tests for device hardware access:

• Camera Capture: Image capture with quality settings
• Location: GPS coordinates with accuracy
• Notifications: Push notifications
• Device Capabilities: List available features
• Device Permissions: Permission status (granted/denied)
• Screen Recording: Start/stop recording (SUPERVISED+ required)

Coverage:

• POST /api/v1/device/capture
• GET /api/v1/device/location
• POST /api/v1/device/notifications
• GET /api/v1/device/capabilities
• GET /api/v1/device/permissions
• POST /api/v1/device/screen-record/start
• POST /api/v1/device/screen-record/stop

Fixtures

Mobile API tests use these fixtures from mobile_api.fixtures.mobile_fixtures:

mobile_test_user

Creates a test user with UUID v4 email for uniqueness.

def test_with_user(mobile_test_user):
    assert mobile_test_user.email.endswith("@example.com")
    assert mobile_test_user.status == "active"

mobile_auth_token

Returns JWT access token for authenticated requests.

def test_with_token(mobile_auth_token):
    headers = {"Authorization": f"Bearer {mobile_auth_token}"}
    # Make authenticated request

mobile_auth_headers

Returns Authorization headers dict with Bearer token.

def test_authenticated(mobile_api_client, mobile_auth_headers):
    response = mobile_api_client.get("/api/v1/agents", headers=mobile_auth_headers)
    assert response.status_code == 200

mobile_api_client

FastAPI TestClient for in-memory API testing (no server startup).

def test_api_call(mobile_api_client):
    response = mobile_api_client.post("/api/auth/login", json={
        "username": "test@example.com",
        "password": "password"
    })
    assert response.status_code == 200

mobile_authenticated_client

Helper function that makes authenticated requests automatically.

def test_auth_call(mobile_authenticated_client):
    response = mobile_authenticated_client("GET", "/api/v1/agents")
    assert response.status_code == 200

mobile_admin_user

Creates admin user with superuser privileges.

def test_admin_endpoint(mobile_admin_user):
    admin, token = mobile_admin_user
    assert admin.role == "super_admin"

Consistency with Web API

Mobile API responses match web API responses for consistency:

Authentication Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Agent Execution Response

{
  "execution_id": "exec_abc123",
  "agent_id": "agent_xyz",
  "status": "completed",
  "response": {
    "message": "Task completed successfully"
  }
}

Workflow Execution Response

{
  "execution_id": "wf_exec_456",
  "workflow_id": "workflow_789",
  "status": "running",
  "started_at": "2026-03-24T14:30:00Z"
}

Example API Calls

Login

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test@example.com",
    "password": "password"
  }'

Execute Agent

curl -X POST http://localhost:8000/api/v1/agents/agent_id/execute \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Create a workflow for daily reports"
  }'

Create Workflow

curl -X POST http://localhost:8000/api/v1/workflows \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Reports",
    "description": "Generate daily reports",
    "category": "automation"
  }'

Get Location

curl -X GET http://localhost:8000/api/v1/device/location \
  -H "Authorization: Bearer YOUR_TOKEN"

Governance Enforcement

Mobile API tests verify governance enforcement:

Agent Maturity Levels

• STUDENT: Cannot execute automated triggers (blocked)
• INTERN: Can execute with proposal approval
• SUPERVISED: Executes under real-time supervision
• AUTONOMOUS: Full execution without oversight

Device Feature Permissions

• Camera: INTERN+ maturity required
• Location: INTERN+ maturity required
• Notifications: INTERN+ maturity required
• Screen Recording: SUPERVISED+ maturity required
• Command Execution: AUTONOMOUS only

Example Governance Test

def test_mobile_device_camera_governance(mobile_api_client, mobile_auth_headers):
    response = mobile_api_client.post(
        "/api/v1/device/capture",
        headers=mobile_auth_headers,
        json={"type": "image", "quality": "high"}
    )

    # Should enforce governance (not succeed silently)
    if response.status_code == 403:
        # Governance blocked - verify error message
        assert "detail" in response.json()

Troubleshooting

Common Issues

1. Import Errors

ImportError: No module named 'core.models'

Solution: Ensure backend directory is in PYTHONPATH:

export PYTHONPATH=/Users/rushiparikh/projects/atom/backend:$PYTHONPATH

2. Database Session Missing

fixture 'mobile_test_user' not found

Solution: Ensure db_session fixture is available from parent conftest:

# In backend/tests/mobile_api/conftest.py
from fixtures.database_fixtures import db_session

3. Authentication Failures

AssertionError: 401 != 200

Solution: Verify auth token is correctly set in headers:

headers = {"Authorization": f"Bearer {token}"}

4. Endpoint Not Available

pytest.skip: Endpoint not implemented

Solution: This is expected behavior. Tests gracefully skip when endpoints are not available.

5. Device Hardware Not Available

pytest.skip: Camera not available in test environment

Solution: Expected in CI/CD. Tests use graceful skip when hardware unavailable.

Debug Mode

Run tests with verbose output and print statements:

pytest backend/tests/mobile_api/ -v -s --tb=short

Stop on First Failure

pytest backend/tests/mobile_api/ -v -x

Run Failed Tests Only

pytest backend/tests/mobile_api/ -v --lf

Performance

TestClient vs Real HTTP

Method	Latency	Use Case
TestClient (in-memory)	<10ms	Unit tests, CI/CD
Real HTTP (localhost)	~50ms	Integration tests
Real HTTP (remote)	~200ms	End-to-end tests

Optimization Tips

1. Use TestClient: Fastest option for API testing
2. Reuse Fixtures: Fixtures cache expensive operations
3. Parallel Execution: Use pytest-xdist for parallel tests
4. Skip Slow Tests: Use markers for slow integration tests

# Run tests in parallel
pytest backend/tests/mobile_api/ -n auto

# Skip slow tests
pytest backend/tests/mobile_api/ -v -m "not slow"

Integration with CI/CD

GitHub Actions Example

name: Mobile API Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest pytest-cov
      - name: Run mobile API tests
        run: |
          pytest backend/tests/mobile_api/ -v --cov=backend/api
      - name: Upload coverage
        uses: codecov/codecov-action@v3

Further Reading

• Backend API Documentation
• Agent Governance System
• Device Capabilities
• Testing Best Practices

Contributing

When adding new mobile API tests:

1. Use API-first approach (TestClient, no browser)
2. Follow existing test structure (classes and test names)
3. Add graceful skip for missing endpoints/hardware
4. Verify response structure matches web API
5. Test both success and failure cases
6. Include governance tests where applicable

License

Internal testing framework for Atom platform.