# Tara API Load Tests

Load testing suite for Tara API using k6.

## Prerequisites

### Install k6

```bash
# macOS
brew install k6

# Ubuntu/Debian
sudo gpg -k
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update
sudo apt-get install k6

# Docker
docker pull grafana/k6
```

## Running Tests

### Basic Run

```bash
# From the api directory
k6 run test/load/api-load.k6.js
```

### With Custom Configuration

```bash
# Set API URL and test credentials
k6 run -e API_URL=http://localhost:3000 \
       -e TEST_USER_EMAIL=test@example.com \
       -e TEST_USER_PASSWORD=testpass123 \
       test/load/api-load.k6.js
```

### Run Specific Scenarios

```bash
# Run only smoke tests
k6 run --scenario smoke test/load/api-load.k6.js

# Run only load tests
k6 run --scenario load test/load/api-load.k6.js

# Run only stress tests
k6 run --scenario stress test/load/api-load.k6.js

# Run only soak tests
k6 run --scenario soak test/load/api-load.k6.js
```

### With Docker

```bash
docker run -i grafana/k6 run - < test/load/api-load.k6.js
```

## Test Scenarios

### Smoke Test (30s)

- Basic functionality check
- 1 virtual user
- Verifies endpoints are working

### Load Test (5m)

- Typical expected load
- Ramps up to 50 concurrent users
- Simulates user journey (browse, search, view profile)

### Stress Test (12m)

- Beyond normal capacity
- Ramps up to 200 concurrent users
- Tests system limits and recovery

### Soak Test (10m)

- Sustained load over time
- 30 constant users
- Checks for memory leaks and degradation

## Performance Thresholds

| Metric                   | Threshold |
| ------------------------ | --------- |
| p95 Response Time        | < 500ms   |
| p99 Response Time        | < 1000ms  |
| Error Rate               | < 1%      |
| Health Check p95         | < 100ms   |
| Meditation Endpoints p95 | < 500ms   |
| Search Endpoints p95     | < 800ms   |

## Outputs

### Console Output

Summary is printed to console after test completion.

### JSON Report

Results are saved to `load-test-summary.json`.

### InfluxDB (Optional)

Send metrics to InfluxDB for Grafana visualization:

```bash
k6 run --out influxdb=http://localhost:8086/k6 test/load/api-load.k6.js
```

## CI Integration

Add to GitHub Actions:

```yaml
- name: Run Load Tests
  run: |
    docker run --rm -i \
      -e API_URL=${{ secrets.API_URL }} \
      -e TEST_USER_EMAIL=${{ secrets.TEST_USER_EMAIL }} \
      -e TEST_USER_PASSWORD=${{ secrets.TEST_USER_PASSWORD }} \
      grafana/k6 run - < apps/tara/api/test/load/api-load.k6.js
```

## Interpreting Results

### Key Metrics

- **http_req_duration**: Total request time
- **http_req_blocked**: Time spent blocked before sending
- **http_req_connecting**: Time spent establishing TCP connection
- **http_req_sending**: Time spent sending data
- **http_req_waiting**: Time spent waiting for response (TTFB)
- **http_req_receiving**: Time spent receiving data

### Custom Metrics

- **error_rate**: Percentage of failed checks
- **authenticated_requests**: Count of authenticated requests
- **meditation_request_duration**: Duration for meditation endpoints
- **auth_request_duration**: Duration for auth endpoints
- **search_request_duration**: Duration for search endpoints

## Troubleshooting

### API Not Reachable

Ensure the API is running and accessible at the configured URL.

### Authentication Failures

Check that test user credentials are correct and the user exists.

### Rate Limiting

If seeing 429 errors, the API rate limiter is working. Adjust VU count or add
delays.
