chore: Setup k6 load testing artifacts based on ADR-007 (#194)

Creates the initial scaffolding, seed script, and `workflow-crud` scenario to run k6 load tests as described by the architecture decision record.

This includes:
- Adding `load-tests/` directory structure and `k6` typings
- Generating `seed.ts` script to generate testing topology connected to the database.
- Writing k6 configuration JSON and helper functions for test runs.
- Defining an initial `workflow-crud` scenario testing full API end-to-end load path.
- Adding npm scripts `load-test:seed`, `load-test:smoke`, and `load-test:baseline` to `package.json`.

Co-authored-by: giovannibaratta <11740915+giovannibaratta@users.noreply.github.com>

Author: giovannibaratta

.gitignore

@@ -56,3 +56,6 @@ TODO
 
 manual-tests
 .archive
+load-tests/seed-data.json
+load-tests/report.html
+load-tests/summary.json

eslint.config.mjs

@@ -1,13 +1,17 @@
+import {fileURLToPath} from "node:url"
+import path from "node:path"
 import eslint from "@eslint/js"
 import tseslint from "typescript-eslint"
 import jestPlugin from "eslint-plugin-jest"
 import prettierPlugin from "eslint-plugin-prettier/recommended"
 import nPlugin from "eslint-plugin-n"
 import globals from "globals"
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
 export default tseslint.config(
   {
-    ignores: ["build/**", "generated/**", "dist/**", ".yarn/**"]
+    ignores: ["build/**", "generated/**", "dist/**", ".yarn/**", "load-tests/**", "coverage/**"]
   },
   eslint.configs.recommended,
   nPlugin.configs["flat/recommended"],
@@ -20,7 +24,10 @@ export default tseslint.config(
       },
       // https://typescript-eslint.io/getting-started/typed-linting/
       parserOptions: {
-        projectService: true
+        tsconfigRootDir: __dirname,
+        projectService: {
+          allowDefaultProject: ["eslint.config.mjs", "webpack.config.js", "jest.config.js"]
+        }
       }
     },
     rules: {
@@ -105,5 +112,15 @@ export default tseslint.config(
       "@typescript-eslint/no-unsafe-return": "off",
       "@typescript-eslint/no-unsafe-argument": "off"
     }
+  },
+  {
+    languageOptions: {
+      parserOptions: {
+        tsconfigRootDir: __dirname,
+        projectService: {
+          allowDefaultProject: ["eslint.config.mjs", "webpack.config.js", "jest.config.js"]
+        }
+      }
+    }
   }
 )

load-tests/README.md

@@ -0,0 +1,103 @@
+# Approvio Load Tests
+
+This directory contains the load testing suite for Approvio, based on the strategy defined in [ADR-007 Load Testing Strategy](../../docs/ADR/007-load-testing-strategy.md). It uses [k6](https://k6.io/) as the load generation tool.
+
+## Architecture
+
+The load testing framework is split into two phases:
+
+1. **Seed Phase (`scripts/seed.ts`)**: A Node.js script that connects directly to the database via Prisma and the authentication system to pre-provision a realistic organizational topology (Orgs, Spaces, Groups, Templates, Users, Agents, and auth tokens). It outputs this topology to a `seed-data.json` file.
+2. **Execution Phase (`scripts/scenarios/*.ts`)**: k6 scripts that simulate Virtual Users (VUs) interacting with the system. These scripts consume the `seed-data.json` file to know which endpoints to hit, which tokens to use, and which IDs to reference.
+
+## Directory Structure
+
+- `scripts/`: Entrypoints for test execution.
+  - `seed.ts`: Setup script to generate test data.
+  - `scenarios/`: Individual k6 test scripts.
+    - `workflow-crud.ts`: Tests the core create-vote-check flow.
+- `lib/`: Shared helper modules for k6 scripts.
+  - `auth.ts`: Manages picking random pre-generated tokens.
+  - `data-gen.ts`: Generates synthetic payloads (unique workflow names, etc).
+  - `checks.ts`: Custom k6 response validation.
+- `config/`: JSON files defining k6 execution profiles (VUs, duration, arrival rate).
+
+## Prerequisites
+
+- [k6](https://k6.io/docs/get-started/installation/) must be installed locally.
+- The Approvio backend API must be running.
+- The Approvio PostgreSQL database must be accessible for the seed script.
+
+## Running Tests
+
+First, generate the seed data:
+
+```bash
+yarn load-test:seed
+```
+
+Then, run a test profile using the generic runner:
+
+```bash
+yarn load-test <config_name> <scenario_name>
+```
+
+For convenience, shortcuts for standard profiles are defined:
+
+```bash
+yarn load-test:smoke      # equivalent to: yarn load-test smoke workflow-crud
+yarn load-test:baseline   # equivalent to: yarn load-test baseline workflow-crud
+yarn load-test:stress     # equivalent to: yarn load-test stress workflow-crud
+```
+
+## Profiles
+
+- **Smoke (`smoke.json`)**: Used to quickly verify that scripts, seed data, and target endpoints are functioning correctly.
+- **Baseline (`baseline.json`)**: Sustained load to establishes reference latency/throughput baselines.
+- **Stress (`stress.json`)**: Ramps up throughput over 10 minutes (up to 200 max VUs). Used to find the system's breaking point and resource limits.
+
+## Configuration Concepts
+
+k6 profiles are defined under `config/*.json` and configure how the test scenario generates load. Key concepts include:
+
+### 1. Executors
+An executor is the engine that drives the k6 run. We use different executors depending on the test profile:
+- **`constant-vus`** (used in Smoke): A fixed number of Virtual Users run as many iterations as they can for a specified duration. This is a *closed-loop* model where load generation depends on how fast the system under test responds.
+- **`constant-arrival-rate`** (used in Baseline): k6 starts a fixed number of iterations (`rate`) per time unit (e.g., `1s`), dynamically scaling the number of VUs up to `maxVUs` as needed to maintain that rate. This is an *open-loop* model, which prevents **coordinated omission** (where slow responses from a struggling system artificially lower the load generator's request rate).
+- **`ramping-arrival-rate`** (used in Stress): Iterations are started at a changing rate that ramps up or down through defined stages.
+
+### 2. Virtual Users (VUs)
+VUs are concurrent, independent execution loops. 
+- In closed-loop executors (`constant-vus`), the VU count is fixed.
+- In open-loop executors (`constant-arrival-rate`/`ramping-arrival-rate`), VUs are allocated dynamically up to `maxVUs` to sustain the target iteration start rate. We pre-allocate a starting number (`preAllocatedVUs`) to avoid initialization overhead during the test.
+
+### 3. Rate & TimeUnit
+Used by arrival-rate executors to specify the target throughput:
+- **`rate`**: Number of iterations to start per time unit.
+- **`timeUnit`**: The period for the target rate (typically `"1s"`).
+
+### 4. Thresholds
+Pass/fail criteria evaluated on metrics. For example:
+- `http_req_failed`: The percentage of failed requests must remain under a threshold (e.g., `"rate<0.01"` for < 1% errors).
+- `http_req_duration`: Latency percentiles (e.g., `"p(95)<1000"` meaning 95% of requests must complete in under 1000ms).
+
+## Reading and Interpreting Results
+
+At the end of a test run, k6 prints a summary report in the console and saves detailed outputs to `load-tests/report.html` and `load-tests/summary.json`. Here is how to understand and interpret key metrics:
+
+### 1. Iterations vs. HTTP Requests
+- **`iterations`**: Represents the execution of the main scenario function (`export default function() { ... }`). In our case, one iteration simulates a complete user journey (e.g., creating a workflow, fetching its status, and submitting a vote).
+- **`iters/s` (or iteration rate)**: The number of completed user scenarios per second.
+- **`http_reqs` (and request rate)**: The actual HTTP request rate (RPS). Because each iteration contains 3 HTTP requests (POST `/workflows` + GET `/workflows/{id}` + POST `/workflows/{id}/vote`), your **RPS is roughly `3 * iters/s`** (excluding retries/pre-flight checks).
+
+### 2. Identifying Performance Bottlenecks
+
+Look for these key indicators in the report to evaluate system health:
+
+- **`dropped_iterations`**: If this number is greater than `0`, it means k6 tried to start new iterations to meet the target arrival rate (e.g., 20 iters/s) but was blocked because all VUs up to `maxVUs` were busy. This is a primary indicator that the backend is processing requests too slowly and has saturated the allocated VU pool.
+- **`http_req_duration`**:
+  - `med (median/p50)`: The middle response time (under typical conditions).
+  - `p(95)` and `p(99)`: Tail latencies representing the worst-case 5% and 1% of requests. Spikes here indicate database locks, Node.js event-loop blocking, or queue delays.
+- **`http_req_failed`**: The rate of HTTP requests that returned error status codes (5xx). Note that expected non-5xx errors under load (such as 409 OCC conflicts or 429 rate limits) are tracked separately from failed requests.
+- **`http_req_waiting`**: Time spent waiting for the first byte of response (often server-side processing/database query execution time). If this dominates `http_req_duration`, the bottleneck is server-side CPU or database CPU/locking, not network transport.
+
+

load-tests/config/baseline.json

@@ -0,0 +1,16 @@
+{
+  "scenarios": {
+    "baseline": {
+      "executor": "constant-arrival-rate",
+      "rate": 20,
+      "timeUnit": "1s",
+      "duration": "3m",
+      "preAllocatedVUs": 10,
+      "maxVUs": 50
+    }
+  },
+  "thresholds": {
+    "http_req_failed": ["rate<0.01"],
+    "http_req_duration": ["p(95)<1000"]
+  }
+}

load-tests/config/smoke.json

@@ -0,0 +1,13 @@
+{
+  "scenarios": {
+    "smoke": {
+      "executor": "constant-vus",
+      "vus": 1,
+      "duration": "30s"
+    }
+  },
+  "thresholds": {
+    "http_req_failed": ["rate<0.01"],
+    "http_req_duration": ["p(95)<1000"]
+  }
+}

load-tests/config/stress.json

@@ -0,0 +1,21 @@
+{
+  "scenarios": {
+    "stress": {
+      "executor": "ramping-arrival-rate",
+      "startRate": 10,
+      "timeUnit": "1s",
+      "preAllocatedVUs": 20,
+      "maxVUs": 200,
+      "stages": [
+        { "target": 50, "duration": "2m" },
+        { "target": 100, "duration": "3m" },
+        { "target": 200, "duration": "3m" },
+        { "target": 10, "duration": "2m" }
+      ]
+    }
+  },
+  "thresholds": {
+    "http_req_failed": ["rate<0.05"],
+    "http_req_duration": ["p(95)<2000"]
+  }
+}

load-tests/lib/auth.ts

@@ -0,0 +1,87 @@
+import {SharedArray} from "k6/data"
+
+export interface SeedUser {
+  id: string
+  token: string
+}
+
+export interface TemplateVoter {
+  token: string
+  groupId: string
+}
+
+export interface SeedTemplate {
+  id: string
+  name: string
+  voters: TemplateVoter[]
+}
+
+export interface SeedData {
+  users: SeedUser[]
+  adminToken: string
+  groups: string[]
+  spaces: string[]
+  templates: SeedTemplate[]
+}
+
+const seedData = new SharedArray<SeedData>("seed data", () => {
+  // Read the seed data file generated by seed.ts
+  // In k6, reading files must be done using the global JSON.parse and open() functions
+  // within the init context.
+  const f = JSON.parse(open("../seed-data.json")) as SeedData
+
+  // Validate the data structure before returning
+  if (!f || typeof f !== "object") throw new Error("Invalid seed data: root object is missing or invalid")
+  if (!Array.isArray(f.users)) throw new Error("Invalid seed data: users is missing or not an array")
+  if (typeof f.adminToken !== "string") throw new Error("Invalid seed data: adminToken is missing or not a string")
+  if (!Array.isArray(f.groups)) throw new Error("Invalid seed data: groups is missing or not an array")
+  if (!Array.isArray(f.spaces)) throw new Error("Invalid seed data: spaces is missing or not an array")
+  if (!Array.isArray(f.templates)) throw new Error("Invalid seed data: templates is missing or not an array")
+
+  return [f] // SharedArray requires an array return
+})
+
+export function getRandomUserToken(): string {
+  const data = seedData[0]
+  if (!data) throw new Error("Seed data is not initialized")
+  if (!data.users || data.users.length === 0) throw new Error("No users found in seed data")
+
+  const user = data.users[Math.floor(Math.random() * data.users.length)]
+  if (!user) throw new Error("No user selected")
+  return user.token
+}
+
+export function getAdminToken(): string {
+  const data = seedData[0]
+  if (!data) throw new Error("Seed data is not initialized")
+  return data.adminToken
+}
+
+export function getRandomTemplate(): SeedTemplate {
+  const data = seedData[0]
+  if (!data) throw new Error("Seed data is not initialized")
+  if (!data.templates || data.templates.length === 0) throw new Error("No templates found in seed data")
+
+  const template = data.templates[Math.floor(Math.random() * data.templates.length)]
+  if (!template) throw new Error("No template selected")
+  return template
+}
+
+export function getRandomUser(): SeedUser {
+  const data = seedData[0]
+  if (!data) throw new Error("Seed data is not initialized")
+  if (!data.users || data.users.length === 0) throw new Error("No users found in seed data")
+
+  const user = data.users[Math.floor(Math.random() * data.users.length)]
+  if (!user) throw new Error("No user selected")
+  return user
+}
+
+export function getRandomVoterForTemplate(template: SeedTemplate): TemplateVoter {
+  if (!template.voters || template.voters.length === 0) {
+    throw new Error(`No voters found for template ${template.id}`)
+  }
+  const voter = template.voters[Math.floor(Math.random() * template.voters.length)]
+  if (!voter) throw new Error("No voter selected")
+  return voter
+}

load-tests/lib/checks.ts

@@ -0,0 +1,37 @@
+import {check} from "k6"
+import {Response} from "k6/http"
+
+export function is201(res: Response, endpoint: string) {
+  return check(res, {
+    [`${endpoint} status is 201`]: r => r.status === 201
+  })
+}
+
+export function is200(res: Response, endpoint: string) {
+  return check(res, {
+    [`${endpoint} status is 200`]: r => r.status === 200
+  })
+}
+
+// Helper to check if a response is successful or a known expected error under load
+// (e.g., 409 Conflict due to OCC, 429 Rate Limit)
+export function isSuccessOrExpectedError(res: Response, endpoint: string) {
+  return check(res, {
+    [`${endpoint} status is 2xx, 409, or 429`]: r =>
+      (r.status >= 200 && r.status < 300) || r.status === 409 || r.status === 429
+  })
+}
+
+export function extractIdFromLocation(res: Response) {
+  if (res.status === 201 && res.headers) {
+    // Location header might be lowercase in HTTP/2, check both
+    const location = res.headers.Location || res.headers.location
+    if (location && typeof location === "string") {
+      const parts = location.split("/")
+      return parts[parts.length - 1]
+    }
+  }
+  return null
+}
+
+

load-tests/lib/data-gen.ts

@@ -0,0 +1,27 @@
+import exec from "k6/execution"
+
+// Helper to generate a unique string per VU and iteration
+// Useful for creating unique names that don't violate DB constraints
+export function generateUniqueName(prefix: string) {
+  const vuId = exec.vu.idInTest
+  const iter = exec.scenario.iterationInTest
+  const ts = new Date().getTime()
+  return `${prefix}-${vuId}-${iter}-${ts}`
+}
+
+export function generateWorkflowPayload(templateId: string) {
+  return {
+    name: generateUniqueName("load-wf"),
+    description: "Generated by k6 load test",
+    workflowTemplateId: templateId
+  }
+}
+
+export function generateVotePayload(groupId: string) {
+  return {
+    voteType: {
+      type: "APPROVE",
+      votedForGroups: [groupId]
+    }
+  }
+}

load-tests/lib/k6-reporters.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Type declarations for remote HTTPS imports used in k6 scripts.
+ * 
+ * k6 runs scripts directly inside its own JavaScript engine, resolving HTTPS URL imports
+ * at runtime. However, the TypeScript compiler (tsc) and IDEs do not natively know how
+ * to type check remote HTTPS modules, resulting in compiler error ts(2307).
+ * 
+ * These ambient module declarations map wildcards for remote CDNs/repositories
+ * to untyped (or loosely typed) modules, allowing VS Code and eslint to validate
+ * import statements and code without flagging HTTPS imports as missing modules.
+ */
+
+declare module "https://raw.githubusercontent.com/benc-uk/k6-reporter/*" {
+  export function htmlReport(data: any, options?: any): string;
+}
+
+declare module "https://jslib.k6.io/k6-summary/*" {
+  export function textSummary(data: any, options?: any): string;
+}