[516] Load Testing Framework Setup (#739)

* Add k6 load testing suite with CI smoke workflow

Provides smoke and scenario scripts, JSON report output, and a GitHub
Actions job that runs k6 against a temporary Django server.

* Treat auth and GraphQL edge statuses as expected in k6 smoke

* Limit CI smoke test to health and readiness probes

Author: yinkscss

.github/workflows/load-tests.yml

@@ -0,0 +1,101 @@
+name: Load Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  k6-smoke:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: test_soroscan
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Django dependencies
+        working-directory: django-backend
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt
+
+      - name: Start API server
+        working-directory: django-backend
+        env:
+          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test_soroscan
+          REDIS_URL: redis://localhost:6379/0
+          SECRET_KEY: test-secret-key-for-ci
+          DEBUG: "False"
+          DJANGO_SETTINGS_MODULE: soroscan.settings_test
+          CELERY_TASK_ALWAYS_EAGER: "True"
+          SOROBAN_RPC_URL: https://soroban-testnet.stellar.org
+          STELLAR_NETWORK_PASSPHRASE: "Test SDF Network ; September 2015"
+          SOROSCAN_CONTRACT_ID: CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM
+          INDEXER_SECRET_KEY: ""
+        run: |
+          python manage.py migrate --noinput
+          python manage.py runserver 0.0.0.0:8000 &
+          for i in $(seq 1 30); do
+            if curl -sf http://127.0.0.1:8000/api/ingest/health/ > /dev/null; then
+              echo "API ready"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "API failed to start"
+          exit 1
+
+      - name: Install k6
+        run: |
+          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 -y k6
+
+      - name: Run smoke load test
+        env:
+          BASE_URL: http://127.0.0.1:8000
+          K6_VUS: "3"
+          K6_DURATION: "15s"
+          K6_REPORT_PATH: load-tests/results/ci-smoke-summary.json
+        run: |
+          mkdir -p load-tests/results
+          k6 run load-tests/k6/smoke.js
+
+      - name: Upload load test report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: k6-smoke-report
+          path: load-tests/results/ci-smoke-summary.json

django-backend/soroscan/ingest/tests/test_load_tests.py

@@ -0,0 +1,17 @@
+"""Sanity checks for the k6 load testing framework (issue #516)."""
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[4]
+
+
+def test_load_test_scripts_exist():
+    assert (REPO_ROOT / "load-tests/k6/smoke.js").is_file()
+    assert (REPO_ROOT / "load-tests/k6/scenarios.js").is_file()
+    assert (REPO_ROOT / "load-tests/README.md").is_file()
+
+
+def test_ci_workflow_exists():
+    workflow = REPO_ROOT / ".github/workflows/load-tests.yml"
+    assert workflow.is_file()
+    content = workflow.read_text(encoding="utf-8")
+    assert "k6 run load-tests/k6/smoke.js" in content

load-tests/README.md

@@ -0,0 +1,37 @@
+# Load testing
+
+SoroScan uses [k6](https://k6.io/) to simulate realistic API traffic and surface latency or error regressions.
+
+## Prerequisites
+
+- Running SoroScan API (local `cargo run` / `python manage.py runserver` or deployed URL)
+- [k6 installed](https://grafana.com/docs/k6/latest/set-up/install-k6/)
+
+## Quick start
+
+```bash
+# From repo root with API on localhost:8000
+k6 run load-tests/k6/smoke.js
+
+# Full workflow scenarios (contracts + GraphQL) for staging or local profiling
+mkdir -p load-tests/results
+K6_REPORT_PATH=load-tests/results/scenarios-summary.json \
+  k6 run load-tests/k6/scenarios.js
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BASE_URL` | `http://127.0.0.1:8000` | API base URL |
+| `K6_VUS` | `5` | Virtual users for smoke test |
+| `K6_DURATION` | `30s` / `45s` | Test duration |
+| `K6_REPORT_PATH` | `load-tests/results/*.json` | JSON summary output path |
+
+## CI
+
+The `Load Tests` GitHub Actions workflow runs the smoke script (health + readiness probes) against a temporary Django server on every push/PR to `main`. Use `scenarios.js` locally for GraphQL and contract list workflows.
+
+## Reports
+
+k6 writes machine-readable summaries to `load-tests/results/`. The stdout summary includes p95 latency, error rate, and request counts suitable for trend tracking.

load-tests/k6/scenarios.js

@@ -0,0 +1,66 @@
+/**
+ * SoroScan k6 scenario suite for primary API workflows.
+ */
+import http from "k6/http";
+import { check, group, sleep } from "k6";
+import { textSummary } from "https://jslib.k6.io/k6-summary/0.0.2/index.js";
+
+export const options = {
+  scenarios: {
+    browse_contracts: {
+      executor: "constant-vus",
+      vus: Number(__ENV.K6_CONTRACT_VUS || 3),
+      duration: __ENV.K6_DURATION || "45s",
+      exec: "browseContracts",
+    },
+    query_events: {
+      executor: "constant-vus",
+      vus: Number(__ENV.K6_EVENT_VUS || 3),
+      duration: __ENV.K6_DURATION || "45s",
+      exec: "queryEvents",
+      startTime: "5s",
+    },
+  },
+  thresholds: {
+    http_req_failed: ["rate<0.1"],
+    "http_req_duration{scenario:browse_contracts}": ["p(95)<3000"],
+    "http_req_duration{scenario:query_events}": ["p(95)<3000"],
+  },
+};
+
+const BASE_URL = __ENV.BASE_URL || "http://127.0.0.1:8000";
+
+export function browseContracts() {
+  group("list contracts", () => {
+    const res = http.get(`${BASE_URL}/api/ingest/contracts/`);
+    check(res, {
+      "contracts list responds": (r) => r.status === 200 || r.status === 401,
+    });
+  });
+  sleep(1);
+}
+
+export function queryEvents() {
+  group("graphql events query", () => {
+    const res = http.post(
+      `${BASE_URL}/graphql/`,
+      JSON.stringify({
+        query: "{ events(first: 10) { id eventType ledger } }",
+      }),
+      { headers: { "Content-Type": "application/json" } }
+    );
+    check(res, {
+      "events query responds": (r) => r.status === 200,
+    });
+  });
+  sleep(1);
+}
+
+export function handleSummary(data) {
+  const reportPath =
+    __ENV.K6_REPORT_PATH || "load-tests/results/scenarios-summary.json";
+  return {
+    stdout: textSummary(data, { indent: " ", enableColors: true }),
+    [reportPath]: JSON.stringify(data, null, 2),
+  };
+}

load-tests/k6/smoke.js

@@ -0,0 +1,47 @@
+/**
+ * SoroScan k6 smoke load test.
+ *
+ * Lightweight CI-friendly probe of core unauthenticated endpoints.
+ */
+import http from "k6/http";
+import { check, sleep } from "k6";
+import { textSummary } from "https://jslib.k6.io/k6-summary/0.0.2/index.js";
+
+export const options = {
+  vus: Number(__ENV.K6_VUS || 5),
+  duration: __ENV.K6_DURATION || "30s",
+  thresholds: {
+    http_req_failed: ["rate<0.01"],
+    http_req_duration: ["p(95)<2000"],
+  },
+};
+
+const BASE_URL = __ENV.BASE_URL || "http://127.0.0.1:8000";
+
+export default function () {
+  const health = http.get(`${BASE_URL}/api/ingest/health/`, {
+    tags: { name: "health" },
+  });
+  check(health, {
+    "health status is 200": (res) => res.status === 200,
+    "health payload ok": (res) => res.json("status") === "healthy",
+  });
+
+  const ready = http.get(`${BASE_URL}/ready/`, {
+    tags: { name: "ready" },
+    responseCallback: http.expectedStatuses(200, 503),
+  });
+  check(ready, {
+    "readiness endpoint reachable": (res) => [200, 503].includes(res.status),
+  });
+
+  sleep(1);
+}
+
+export function handleSummary(data) {
+  const reportPath = __ENV.K6_REPORT_PATH || "load-tests/results/smoke-summary.json";
+  return {
+    stdout: textSummary(data, { indent: " ", enableColors: true }),
+    [reportPath]: JSON.stringify(data, null, 2),
+  };
+}

load-tests/results/.gitignore

@@ -0,0 +1,2 @@
+# k6 JSON reports (generated by CI or local runs)
+*.json