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

```bash

# 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

```bash

# 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

```bash

# 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.



```python

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.



```python

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.



```python

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).

```python

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.

```python

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.

```python

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

```json

{

  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",

  "token_type": "bearer"

}

```

### Agent Execution Response

```json

{

  "execution_id": "exec_abc123",

  "agent_id": "agent_xyz",

  "status": "completed",

  "response": {

    "message": "Task completed successfully"

  }

}

```

### Workflow Execution Response

```json

{

  "execution_id": "wf_exec_456",

  "workflow_id": "workflow_789",

  "status": "running",

  "started_at": "2026-03-24T14:30:00Z"

}

```

## Example API Calls

### Login

```bash

curl -X POST http://localhost:8000/api/auth/login \

  -H "Content-Type: application/json" \

  -d '{

    "username": "test@example.com",

    "password": "password"

  }'

```

### Execute Agent

```bash

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

```bash

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

```bash

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

```python

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:

```bash

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:

```python

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

```python

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:

```bash

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

```

### Stop on First Failure

```bash

pytest backend/tests/mobile_api/ -v -x

```

### Run Failed Tests Only

```bash

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

```bash

# 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

```yaml

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](../../docs/API_DOCUMENTATION.md)
- [Agent Governance System](../../docs/AGENT_GOVERNANCE_SYSTEM.md)
- [Device Capabilities](../../docs/DEVICE_CAPABILITIES.md)
- [Testing Best Practices](../../docs/CODE_QUALITY_STANDARDS.md)

## 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.