attune/tests/QUICK_START.md

E2E Testing Quick Start Guide

Last Updated: 2026-01-22
Status: ✅ Infrastructure Ready - Quick Test Passing (3/3)

---

Prerequisites

• Attune API service running on http://localhost:8080 (or set ATTUNE_API_URL)
• Python 3.8+ installed
• Internet connection (for downloading test dependencies)

---

Quick Validation (No Setup Required)

Test basic connectivity without installing dependencies:

cd tests
python3 quick_test.py

Expected Output:

============================================================
Attune E2E Quick Test
============================================================
API URL: http://localhost:8080

Testing /health endpoint...
✓ Health check passed: {'status': 'ok'}

Testing authentication...
  Attempting registration...
  ⚠ Registration returned: 200
  Attempting login...
  ✓ Login successful, got token: eyJ0eXAiOiJKV1QiLCJh...
  ✓ Authenticated as: test@attune.local

Testing pack endpoints...
  Fetching pack list...
  ✓ Pack list retrieved: 0 packs found

============================================================
Test Summary
============================================================
✓ PASS   Health Check
✓ PASS   Authentication
✓ PASS   Pack Endpoints
------------------------------------------------------------
Total: 3/3 passed
============================================================

✓ All tests passed! E2E environment is ready.

---

Full Test Suite

1. Setup (First Time Only)

cd tests
./run_e2e_tests.sh --setup

This will:

• Create a Python virtual environment at tests/venvs/e2e
• Install all test dependencies (pytest, requests, etc.)
• Verify dependencies are installed correctly

2. Run Tests

Basic run:

./run_e2e_tests.sh

Verbose output (recommended):

./run_e2e_tests.sh -v

Run specific test:

./run_e2e_tests.sh -k "test_api_health"

Stop on first failure:

./run_e2e_tests.sh -s

With coverage report:

./run_e2e_tests.sh --coverage

All options:

./run_e2e_tests.sh -h

3. Cleanup

./run_e2e_tests.sh --teardown

This removes:

• Test artifacts
• Log files
• Pytest cache
• Coverage reports

---

Manual Test Execution (Advanced)

If you prefer to run pytest directly:

# Activate virtual environment
source tests/venvs/e2e/bin/activate

# Run tests
cd tests
pytest test_e2e_basic.py -v

# Deactivate when done
deactivate

---

Environment Variables

Configure test behavior via environment variables:

# API endpoint (default: http://localhost:8080)
export ATTUNE_API_URL="http://localhost:8080"

# Test timeout in seconds (default: 60)
export TEST_TIMEOUT="60"

# Then run tests
./run_e2e_tests.sh -v

---

Troubleshooting

API Service Not Running

Error:

✗ API service is not reachable at http://localhost:8080

Solution:

# Start API service
cd crates/api
cargo run --release

Authentication Fails

Error:

✗ Login failed: 422 Client Error: Unprocessable Entity

Common Causes:

1. Wrong field names: Must use "login" not "username"
2. Password too short: Minimum 8 characters required
3. Missing fields: Both login and password are required

Test credentials:

• Login: test@attune.local
• Password: TestPass123! (min 8 chars)

Import Errors

Error:

ModuleNotFoundError: No module named 'pytest'

Solution:

# Run setup first
./run_e2e_tests.sh --setup

# Or manually install dependencies
pip install -r tests/requirements.txt

Pack Registration Fails

Error:

FileNotFoundError: [Errno 2] No such file or directory: 'tests/fixtures/packs/test_pack'

Solution:

# Verify you're in the project root
pwd  # Should end with /attune

# Check test pack exists
ls -la tests/fixtures/packs/test_pack/

# If missing, the repository may be incomplete

---

Test Scenarios

Currently Implemented

1. ✅ Health Check - Validates API is responding
2. ✅ Authentication - User registration and login
3. ✅ Pack Registration - Register test pack from local directory
4. ✅ Action Creation - Create simple echo action
5. ✅ Timer Trigger Flow - Create trigger, action, and rule (infrastructure only)
6. 🔄 Manual Execution - Direct action execution (pending endpoint)

Planned (Phase 3)

• Timer automation flow (sensor → event → rule → execution)
• Workflow execution (3-task sequential workflow)
• FIFO queue ordering (concurrency limits)
• Inquiry (human-in-the-loop) flows
• Secret management across services
• Error handling and retry logic
• WebSocket notifications
• Dependency isolation (per-pack venvs)

---

API Endpoint Reference

Health Endpoints (No Auth)

• GET /health - Basic health check
• GET /health/detailed - Health with database status
• GET /health/ready - Readiness probe
• GET /health/live - Liveness probe

Authentication Endpoints (No Auth)

• POST /auth/register - Register new user
• POST /auth/login - Login and get JWT token
• POST /auth/refresh - Refresh access token

Protected Endpoints (Auth Required)

• GET /auth/me - Get current user info
• POST /auth/change-password - Change password
• GET /api/v1/packs - List packs
• POST /api/v1/packs/register - Register pack
• GET /api/v1/actions - List actions
• POST /api/v1/actions - Create action
• And all other /api/v1/* endpoints...

---

Authentication Schema

Register Request

{
  "login": "newuser@example.com",   // Min 3 chars (NOT "username")
  "password": "SecurePass123!",     // Min 8 chars, max 128
  "display_name": "New User"        // Optional (NOT "full_name")
}

Login Request

{
  "login": "user@example.com",      // NOT "username"
  "password": "SecurePass123!"      // Min 8 chars
}

Login Response

{
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJh...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJh...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": {
      "id": 1,
      "login": "user@example.com",
      "display_name": "User Name"
    }
  }
}

---

CI/CD Integration

GitHub Actions Example

name: E2E Tests

on: [push, pull_request]

jobs:
  e2e-tests:
    runs-on: ubuntu-latest
    
    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
      
      rabbitmq:
        image: rabbitmq:3.12-management
        options: >-
          --health-cmd "rabbitmq-diagnostics ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      
      - name: Start API Service
        run: |
          cd crates/api
          cargo run --release &
          sleep 5
      
      - name: Run E2E Tests
        run: |
          ./tests/run_e2e_tests.sh --setup -v
      
      - name: Upload Test Reports
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: e2e-test-reports
          path: tests/htmlcov/

---

Getting Help

• Documentation: See tests/README.md for detailed test scenarios
• Work Summary: work-summary/2026-01-22-e2e-testing-phase2.md
• Issues: Check service logs in tests/logs/ (if running via scripts)
• Quick Test: Use python3 tests/quick_test.py to isolate API connectivity issues

---

Status Summary

Component	Status	Notes
Test Infrastructure	✅ Complete	AttuneClient, fixtures, runner
Quick Test	✅ Passing	3/3 tests passing
Basic Tests	🔄 Partial	5 scenarios implemented
Advanced Tests	📋 Planned	Timer flow, workflows, FIFO
CI/CD Integration	📋 Planned	GitHub Actions workflow

Last Validation: 2026-01-22 - Quick test confirmed: health ✓, auth ✓, pack endpoints ✓

---

Ready to test? Start here: ./tests/run_e2e_tests.sh --setup -v