qstash-test

name: qstash-test description: | Run qstash-stress test suites against real QStash with proper setup. Use when user asks to: (1) run QStash tests, (2) test against real QStash, (3) run a specific test suite, (4) run tests with --serve mode, (5) generate test reports, (6) filter tests by tags. Triggers: "run tests", "test qstash", "run basic suite", "test with serve", "run test-suites".

Run qstash-stress YAML test suites against real QStash.

Prerequisites

Build the CLI:
```
go build -o qstash-stress .
```

Set environment variables:

export QSTASH_TOKEN="your-token"
export QSTASH_CURRENT_SIGNING_KEY="sig_..."
export QSTASH_NEXT_SIGNING_KEY="sig_..."

Start ngrok tunnel:

ngrok http 8080
# Copy the https URL
export RECEIVER_BASE_URL="https://xxx.ngrok.io"

Run Tests

Basic Usage (Recommended)

Run with --serve to start receiver in same process:

./qstash-stress run test-suites/basic.yaml --serve --port 8080

Run Specific Suite

./qstash-stress run test-suites/retry.yaml --serve --port 8080
./qstash-stress run test-suites/queue.yaml --serve --port 8080
./qstash-stress run test-suites/callback.yaml --serve --port 8080

Run Multiple Suites

./qstash-stress run test-suites/*.yaml --serve --port 8080

Filter by Tags

# Only run tests tagged "basic"
./qstash-stress run test-suites/*.yaml --tags basic --serve

# Exclude tests tagged "slow"
./qstash-stress run test-suites/*.yaml --exclude-tags slow --serve

Generate Reports

# Markdown report
./qstash-stress run test-suites/basic.yaml --serve --format markdown -o report.md

# JSON report
./qstash-stress run test-suites/basic.yaml --serve --format json -o report.json

Available Test Suites

Suite	Tests	Runnable	What It Tests
basic.yaml	9	9	HTTP methods, payloads, headers
timing.yaml	4	4	Delays, scheduled delivery
dedup.yaml	4	4	ID and content-based deduplication
retry.yaml	8	7	Retry count, delays, Retry-After
callback.yaml	5	2	Success/failure callbacks
queue.yaml	8	6	FIFO ordering, parallelism
urlgroup.yaml	4	1	URL group fanout
batch.yaml	4	2	Batch publishing
dlq.yaml	4	2	Dead letter queue
edge-cases.yaml	4	3	Large payloads

Skipped suites (require multi-step workflow):

schedule.yaml (9 tests) - Cron scheduling
flowcontrol.yaml (6 tests) - Rate limiting

Troubleshooting

Tests timeout:

Ensure --serve flag is used
Check ngrok tunnel is active
Verify RECEIVER_BASE_URL matches ngrok URL

Signature verification failed:

Check signing keys match QStash console
Both current and next keys required

Message not delivered:

Check QStash console for message status
Run with verbose logging: ./qstash-stress -v run ...

Load Testing

For sustained load tests:

./qstash-stress load \
  --profile constant \
  --rate 10 \
  --duration 5m \
  --destination "${RECEIVER_BASE_URL}/message"

Profiles: constant, ramping, burst, spike, soak