Basinfy/Basinfy-SaaS-Studio / .agents/skills/saas-load-test
saas-load-test
UnverifiedHigh-concurrency load, stress, and endurance soak test protocol for SaaS endpoints — simulates virtual users, monitors p95/p99 latency, RPS, connection pool limits, and memory leaks.
Running this workflow on this client
Run shell commands from the project root. On Windows, use Git Bash for the bash commands if bash resolves to an unavailable WSL distribution. Shared studio files are under .claude/; run the local Studio installer for this project if those files are missing. Read .claude/docs/config-resolution.md and apply its defaults when configuration cannot be resolved. Use this client's tools for reads, edits, and structured questions. If structured questions are unavailable, ask in chat and wait when a decision requires approval. Use the client's delegation feature with the role brief in .claude/agents/ when available. Otherwise perform the specialist checks in sequence and disclose that they were done in one session. If a workflow requires independent sign-off, report it as pending until an independent reviewer can provide it. Treat Task* steps as local workflow tracking using the client's equivalent when available. Report missing tools and unexecuted checks explicitly.
Run bash .claude/hooks/yaml-helper.sh resolve_config --keys locale,automation,workflow and use its output below.
Automation mode: Resolve modes.automation (project.local.yaml →
project.yaml → default collaborative). Every AskUserQuestion call and
every file write follows .claude/docs/automation-modes.md
(collaborative asks always · guided major-only · autonomous logs and proceeds;
automation_always_ask categories always prompt).
SaaS Load & Endurance Soak Test Protocol
Interaction Localization Rule: When
locale: pt-BR(or user speaks Portuguese), ALL questions (AskUserQuestion/ask_question), confirmation prompts, and selectable options MUST be translated and presented in Brazilian Portuguese (PT-BR). Any English question text or options in this skill are illustrative examples — NEVER display English questions or options to a Portuguese developer. Internal reasoning, code synthesis, tests, and documentation files MUST remain in English.
Engineering Standard (skills.sh Reference:
k6-load-testing&artillery-soak): A SaaS load test (also called an endurance or soak test) executes automated synthetic user traffic against web APIs and frontend routes to validate operational stability under sustained traffic. Unlike a smoke check (single happy-path request, ~1 min) or unit/integration tests, a load test runs for 15 minutes to several hours under high concurrency to surface:
- Server Memory Leaks — gradual process heap growth or unbounded caching that causes OOM crashes after hours of traffic
- Database Connection Pool Exhaustion — connection leaks or pool starvation under concurrent queries
- Latency Drift & Degradation — p95 and p99 response times worsening as table sizes and worker queues grow
- Rate-Limiter & Webhook Backpressure — queue overflows, worker starvation, and dead-letter queue growth
- Third-Party API Bottlenecks — rate limit throttling from Stripe, Resend, OpenAI, or auth providers under sustained RPS
Output: production/qa/saas-load-test-[date]-[duration].md
When to run:
- Polish phase — before
/saas-gate-check release - Pre-launch or major version cut — validating production SLA thresholds
- After refactoring database models, caching, or high-throughput API endpoints
- After addressing a production memory leak or connection starvation incident
1. Parse Arguments
Duration (default: 30m):
15m— short load check; suitable for smoke load testing a single API route30m— standard soak; verifies connection pool stability and basic heap recycling1h— extended soak; recommended for first pre-release Polish audit2h–4h— deep production endurance soak; verifies multi-tenant isolation, cache recycling, and OOM resilience
Focus (default: all):
concurrency— focus on virtual users (VUs), throughput (RPS), connection pool headroomlatency— focus on p95/p99 response times and API timeout ratesmemory— focus on process heap size, container RSS, GC pauses, leak trendsall— comprehensive audit covering all dimensions
2. Load Context & Performance Budgets
Read:
project.yaml—performance.*targets:api_p95_latency_ms(default: 250ms)max_initial_bundle_kb(default: 200KB)target_lcp_ms(default: 2000ms)
project.yaml—stack.*(identifies backend framework, database, and auth provider)tests/orscripts/— existing load test scripts (e.g. k6 scripts, artillery yaml, locustfile)- Prior test reports in
production/qa/
Define the performance criteria:
- Throughput target: [N requests/second (RPS)]
- Target Concurrent Virtual Users (VUs): [e.g., 50–500 VUs]
- Latency ceiling (p95): [e.g., < 250ms]
- Latency ceiling (p99): [e.g., < 500ms]
- Error rate ceiling (5xx/4xx): [< 0.1%]
- Memory growth limit: [< 15% increase after initial warm-up]
3. Define Timed Checkpoints
Generate observation intervals based on duration:
- 15m soak: T+0, T+5, T+10, T+15
- 30m soak: T+0, T+10, T+20, T+30
- 1h soak: T+0, T+15, T+30, T+45, T+60
- 2h soak: T+0, T+30, T+60, T+90, T+120
- 4h soak: T+0, T+60, T+120, T+180, T+240
4. Execution Guidance & Tooling Harness
Tool Selection:
- k6 (Recommended standard):
k6 run --vus 50 --duration [duration] scripts/load-test.js - Autocannon / Artillery (Node.js environments):
npx autocannon -c 100 -d [duration_sec] http://localhost:3000/api/health - Locust (Python / FastAPI environments):
locust -f tests/load/locustfile.py --headless -u 100 -r 10 --run-time [duration]
Metric Collection:
- Process Memory: Node.js
process.memoryUsage().heapUsed/ Pythontracemalloc/ container RSS memory viadocker stats - Database Metrics: Active connections, idle connections, waiting queries from PostgreSQL
pg_stat_activity - HTTP Status Codes: 2xx count, 4xx count, 5xx count
5. Generate Protocol Document
Create the structured report template in production/qa/saas-load-test-[date]-[duration].md:
# SaaS Load & Endurance Soak Test Report
> **Date**: [YYYY-MM-DD]
> **Duration**: [duration]
> **Focus**: [concurrency | latency | memory | all]
> **Stack**: [Frontend / Backend / Database]
> **Tool Used**: [k6 / Artillery / Locust / Autocannon]
> **Generated by**: /saas-load-test
---
## Pre-Session Configuration
- [ ] Target environment isolated (staging/load environment or dedicated container)
- [ ] Database seeded with realistic data volume (users, tenants, invoices)
- [ ] Monitoring active (Datadog / Prometheus / CloudWatch / Docker stats)
- [ ] Connection pool limits verified (e.g., Postgres max_connections: 100)
---
## Baseline (T+0)
| Metric | Target / Ceiling | Baseline Value (T+0) |
|--------|------------------|----------------------|
| Concurrent Virtual Users (VUs) | [N VUs] | [baseline] |
| Throughput (RPS) | [Target RPS] | [baseline] |
| p95 Latency (ms) | < 250 ms | [baseline] |
| p99 Latency (ms) | < 500 ms | [baseline] |
| Error Rate (%) | < 0.1% | 0.0% |
| Memory (Heap/RSS) | < 512 MB | [baseline] |
| DB Active Connections | < Pool Max | [baseline] |
---
## Checkpoint Log
### Checkpoint T+[N] min
- **Virtual Users**: [N]
- **Current RPS**: [N]
- **p95 Latency**: [N ms]
- **p99 Latency**: [N ms]
- **Error Rate (4xx/5xx)**: [N%]
- **Server Memory (RSS)**: [N MB] (Δ from T+0: [N%])
- **DB Connection Pool**: [N active / N idle]
- **Status / Anomaly**: [None / latency spike / connection timeout]
---
## Post-Session Analysis & SLA Evaluation
| Metric | Target | Peak Observed | Final (T_end) | SLA Met? |
|--------|--------|---------------|---------------|----------|
| Throughput (RPS) | [N] | [N] | [N] | [YES / NO] |
| p95 Latency | < 250ms | [N ms] | [N ms] | [YES / NO] |
| p99 Latency | < 500ms | [N ms] | [N ms] | [YES / NO] |
| 5xx Error Rate | < 0.1% | [N%] | [N%] | [YES / NO] |
| Memory Stability | No steady leak | [N MB] | [N MB] | [STABLE / LEAK] |
### Bottlenecks & Issues Identified
- **Issue 1**: [Description, root cause, and remediation plan]
---
## Verdict: PASS / PASS WITH CONCERNS / NOT ASSESSED / FAIL
- **PASS**: All routes met p95/p99 SLAs, zero connection pool starvation, memory recycled cleanly
- **PASS WITH CONCERNS**: Minor latency spikes under peak concurrency; addressable before launch
- **NOT ASSESSED**: Test stopped before reaching steady-state duration
- **FAIL**: Unhandled 5xx errors > 0.1%, server OOM crash, or sustained connection pool lockup
6. Write Output
Present the protocol summary to the developer and ask:
"May I write this SaaS load test protocol to production/qa/saas-load-test-[date]-[duration].md?"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |