Gatlin/docs/2026-04-30-gatling-setup-plan.md

Implementation Plan: Gatling Setup for Kubernetes Cluster Testing

Date: 2026-04-30
Branch: feat/NCS-57
Stack: Scala 3.5.1, Gradle, Gatling 3.x (Scala DSL)

---

Decisions

Concern	Decision
Build tool	Gradle
Language	Scala 3.5.1
Gatling API	Scala DSL (Gatling 3.x)
Authentication	Bearer token via env var GATLING_AUTH_TOKEN
Target base URL	Injected at runtime via Gradle project property -PbaseUrl=...

---

Steps

Step 1 — build.gradle + settings.gradle

Create settings.gradle:

• Set root project name to gatlin

Create build.gradle:

• Apply io.gatling.gradle plugin (3.x)
• Set scalaVersion = '3.5.1'
• Configure gatlingRun task to pass baseUrl and authToken as JVM system properties so simulations can read them via sys.props

Run command:

./gradlew gatlingRun -PbaseUrl=http://<cluster-service> -PauthToken=<token>

---

Step 2 — Gradle wrapper

Generate gradlew / gradlew.bat and gradle/wrapper/gradle-wrapper.properties (Gradle 8.x).
This ensures reproducible builds without a local Gradle installation.

---

Step 3 — Source layout

Create the standard Gatling + Gradle directory structure:

src/
  gatling/
    scala/
      simulations/       ← concrete simulation classes
      base/              ← BaseSimulation.scala (shared protocol + auth)
    resources/
      gatling.conf       ← timeout / connection overrides
      data/              ← CSV feeders (added per test as needed)
      bodies/            ← request body templates (added per test as needed)

Update .idea/Gatlin.iml source roots to include src/gatling/scala.

---

Step 4 — BaseSimulation.scala

src/gatling/scala/base/BaseSimulation.scala:

• Reads target.baseUrl from sys.props (set by Gradle from -PbaseUrl)
• Reads gatling.authToken from sys.props (set by Gradle from -PauthToken or env GATLING_AUTH_TOKEN)
• Defines a shared HttpProtocolBuilder:
  • base URL
  • Authorization: Bearer <token> header on every request
  • Accept: application/json
  • connection keep-alive
• Abstract class — concrete simulations extend it and inherit the protocol

---

Step 5 — SmokeTestSimulation.scala

src/gatling/scala/simulations/SmokeTestSimulation.scala:

• Extends BaseSimulation
• Single virtual user, one GET /healthz request
• Asserts: HTTP 200, response time < 2 000 ms
• Purpose: verify end-to-end connectivity and auth before writing heavier tests

This serves as the reference example for future simulations.

---

Step 6 — gatling.conf

src/gatling/resources/gatling.conf:

gatling {
  http {
    enableGA = false
  }
}

Keeps telemetry off. Other defaults (timeouts, max connections) are left to Gatling's built-in values and can be overridden per-simulation in code.

---

Step 7 — .gitignore updates

Add to .gitignore:

build/
.gradle/
results/

---

Step 8 — README.md update

Document:

1. Prerequisites (Gradle wrapper handles everything — no local installs needed beyond a JVM)
2. How to run: ./gradlew gatlingRun -PbaseUrl=... -PauthToken=...
3. How to add a new simulation (extend BaseSimulation, place in simulations/)
4. Where reports are generated (build/reports/gatling/)

---

File Checklist

File	Action
settings.gradle	Create
build.gradle	Create
gradle/wrapper/gradle-wrapper.properties	Generate
gradlew / gradlew.bat	Generate
src/gatling/scala/base/BaseSimulation.scala	Create
src/gatling/scala/simulations/SmokeTestSimulation.scala	Create
src/gatling/resources/gatling.conf	Create
.gitignore	Update
README.md	Update
.idea/Gatlin.iml	Update source roots