# 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:
```bash
./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 |