k6 Performance Testing Suite

End-to-end performance testing suite covering five test types — smoke, load, stress, spike, and soak — with custom metrics, threshold-based pass/fail gates, and CI integration.

Target API: test-api.k6.io (k6's official testbed — no rate limits).

---

What's Inside

Test Type	Purpose	Duration	VUs
Smoke	Verify the system handles minimal load without errors. Run on every PR.	~1 min	1
Load	Confirm the system performs well under expected production load.	~10 min	50 → 50
Stress	Find the breaking point — push beyond normal capacity.	~16 min	0 → 300
Spike	Validate behavior under sudden traffic surges.	~3 min	0 → 500 → 0
Soak	Detect memory leaks and resource exhaustion over time.	~30 min	100 (sustained)

---

Quick Start

Prerequisites

• k6 installed locally

Run a test

# Smoke test - fast, catches obvious breakage
k6 run tests/smoke/crocodiles-smoke.js

# Load test
k6 run tests/load/crocodiles-load.js

# Stress test
k6 run tests/stress/crocodiles-stress.js

# Spike test
k6 run tests/spike/crocodiles-spike.js

# Soak test (long-running!)
k6 run tests/soak/crocodiles-soak.js

Output to JSON / HTML

k6 run --out json=results.json tests/load/crocodiles-load.js

---

Project Structure

.
├── .github/workflows/
│   └── k6-smoke.yml          # CI - runs smoke tests on every PR
├── tests/
│   ├── smoke/                # Minimal load, fast feedback
│   ├── load/                 # Sustained expected load
│   ├── stress/               # Push beyond capacity
│   ├── spike/                # Sudden traffic surge
│   └── soak/                 # Long-duration stability
├── lib/
│   ├── auth.js               # Reusable login / token helpers
│   ├── checks.js             # Common response validators
│   └── helpers.js            # Sleep, random data, etc.
├── config/
│   └── thresholds.js         # Shared SLA thresholds
└── README.md

---

Thresholds & SLAs

Every test enforces SLA thresholds. If they fail, k6 exits non-zero — which fails the CI build.

// config/thresholds.js
export const defaultThresholds = {
  'http_req_duration': ['p(95)<500', 'p(99)<1000'],
  'http_req_failed':   ['rate<0.01'],
  'checks':            ['rate>0.99'],
};

Metric	Threshold	Why
http_req_duration p(95)	< 500ms	95% of requests must respond within 500ms
http_req_duration p(99)	< 1000ms	99% within 1s — catches tail latency
http_req_failed	rate < 1%	Error budget
checks	rate > 99%	Functional correctness under load

---

Custom Metrics

The suite tracks domain-specific metrics in addition to k6's built-ins:

Metric	Type	Tracks
crocodiles_list_duration	Trend	Time to fetch crocodile list
login_failures	Counter	Failed authentication attempts
auth_success_rate	Rate	% of successful logins

---

CI Integration

GitHub Actions runs the smoke test on every push and PR — keeps performance regressions out of main.

- name: Run smoke test
  uses: grafana/k6-action@v0.3.1
  with:
    filename: tests/smoke/crocodiles-smoke.js

Heavier tests (load, stress, spike, soak) are run manually or on a nightly schedule to save CI minutes.

---

Reading Results

After a run, k6 prints a summary like:

checks.........................: 100.00% ✓ 600      ✗ 0
http_req_duration..............: avg=87.4ms  min=42ms p(95)=215ms p(99)=412ms
http_req_failed................: 0.00%   ✓ 0        ✗ 600
iterations.....................: 300     50/s
vus............................: 50      min=50  max=50

What to look for:

• http_req_duration p(95) exceeding threshold = latency degradation
• http_req_failed > 1% = errors under load
• checks < 99% = functional bugs surfacing under stress

---

What This Demonstrates

• Understanding of 5 distinct performance test types and when to use each
• Threshold-based pass/fail gating in CI (not just generating reports)
• Custom metrics for domain-specific observability
• Reusable helpers to avoid duplication across scenarios
• Realistic scenarios (ramping load, soak duration, spike shapes)

---

License

MIT