> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praeto.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Guide

> Run the Praeto Dispatcher PowerShell test suite.

# Testing Guide

This project includes PowerShell test scripts that exercise the production-like Worker deployment.

Most tests assume these environment variables are set:

```powershell theme={null}
$env:PRAETO_API_KEY = "praeto_live_..."
$env:PRAETO_ADMIN_API_KEY = "your-admin-key"
```

***

## Recommended test order

Run tests in this order after a fresh deploy.

### 1. End-to-end test

```powershell theme={null}
.\tests\Test-PraetoDispatcher-EndToEnd.ps1 -CreateApiKey -AdminApiKey $env:PRAETO_ADMIN_API_KEY
```

This verifies:

* health check
* schema check
* tenant creation
* API key creation
* unauthorized request failure
* endpoint creation
* event creation
* idempotency behavior

***

### 2. Idempotency

```powershell theme={null}
.\tests\Web-Request-TestIdempotency.ps1
```

Expected:

* first request succeeds
* same request reuses the original event
* same key with different payload fails with `409`

***

### 3. SSRF protection

```powershell theme={null}
.\tests\Web-Request-TestSSRFProtection.ps1
```

Expected:

* localhost/private/metadata URLs rejected
* URLs with embedded credentials rejected
* non-HTTP protocols rejected

***

### 4. Endpoint health

```powershell theme={null}
.\tests\Web-Request-GetEndpointHealth.ps1 -EndpointId "YOUR_ENDPOINT_ID"
```

Use a real endpoint ID returned from endpoint creation.

***

### 5. Metrics summary

```powershell theme={null}
.\tests\Web-Request-GetMetricsSummary.ps1
```

Expected fields:

* deliveries by status
* attempts by status code
* DLQ count
* retry count
* endpoint counts
* queue age approximation

***

### 6. Current usage

```powershell theme={null}
.\tests\Web-Request-GetCurrentUsage.ps1
```

Expected fields:

* events
* deliveries
* billable attempts
* retry attempts
* payload storage estimate
* endpoint count

***

### 7. Usage limits

```powershell theme={null}
.\tests\Web-Request-GetUsageLimits.ps1
```

***

### 8. Safety limits

```powershell theme={null}
.\tests\Web-Request-GetSafetyLimits.ps1
```

***

### 9. Event rate limit

```powershell theme={null}
.\tests\Web-Request-TestEventRateLimit.ps1
```

Default config:

```text theme={null}
events_per_minute = 60
```

Expected:

```text theme={null}
Attempts 1-60 succeed
Attempt 61 fails with rate limit exceeded
```

***

### 10. Endpoint create rate limit

```powershell theme={null}
.\tests\Web-Request-TestEndpointCreateRateLimit.ps1
```

Default config:

```text theme={null}
endpoint_creates_per_hour = 30
```

Expected:

```text theme={null}
Attempts 1-30 succeed
Attempt 31 fails with rate limit exceeded
```

***

### 11. Event deliveries

```powershell theme={null}
.\tests\Web-Request-GetEventDeliveries.ps1 -EventId "YOUR_EVENT_ID"
```

Use a real event ID from an event creation response.

***

### 12. Delivery attempts

```powershell theme={null}
.\tests\Web-Request-GetDeliveryAttempts.ps1 -DeliveryId "YOUR_DELIVERY_ID"
```

Use a real delivery ID from an event creation response.

***

### 13. Delivery replay

```powershell theme={null}
.\tests\Web-Request-ReplayDelivery.ps1 -DeliveryId "YOUR_DELIVERY_ID"
```

***

### 14. DLQ list

```powershell theme={null}
.\tests\Web-Request-ListDLQ.ps1
```

If all endpoints are healthy, an empty DLQ is expected.

***

### 15. Secret rotation overlap

```powershell theme={null}
.\tests\Web-Request-RotateEndpointSecretOverlap.ps1 -EndpointId "YOUR_ENDPOINT_ID"
```

Expected:

* new signing secret returned
* previous secret expiry returned
* overlap days returned
* previous signing secret active flag true

***

### 16. Retention cleanup dry-run

```powershell theme={null}
.\tests\Web-Request-RunRetentionCleanup.ps1
```

Expected:

* does not delete rows
* reports what would be deleted

***

### 17. Retention cleanup apply

Only run this after dry-run looks safe.

```powershell theme={null}
.\tests\Web-Request-RunRetentionCleanup.ps1 -Apply
```

***

## Common test mistakes

### Using placeholders

This will fail:

```powershell theme={null}
.\tests\Web-Request-GetEventDeliveries.ps1 -EventId "YOUR_EVENT_ID"
```

Use a real ID from test output.

***

### Using admin key as tenant key

This will fail:

```powershell theme={null}
$env:PRAETO_API_KEY = $env:PRAETO_ADMIN_API_KEY
```

Admin keys and tenant API keys are different.

***

### Forgetting required SQL migrations

Some phases require new tables or columns. If you see:

```text theme={null}
relation "rate_limit_counters" does not exist
```

then Phase 8 SQL was not applied.

***

### Not redeploying after changing Worker vars/secrets

After changing `wrangler.jsonc` or Worker secrets:

```powershell theme={null}
npx wrangler deploy
```

***

## Clean test environment recommendation

Because tests create endpoints and events, dev databases can get noisy.

Recommended cleanup approach:

1. Use short retention values in dev.
2. Run retention dry-run.
3. Run retention apply.
4. Avoid using production tenant IDs during aggressive test loops.