version: 1
metadata:
  key: "performance-test-gatling"
  last_verified: "2026-03-24"
interface:
  display_name: "Performance Test Gatling"
  short_description: "Use this skill when you need Gatling performance scope, simulations, or runnable entry points; triggers include Gatling, Gatling simulations, and Gatling perfo…"
  default_prompt: "Use performance-test-gatling to complete the task with local scripts, prompts, and examples in this skill folder."
policy:
  allow_implicit_invocation: true

schema_version: v1alpha1

environment:
  type: none

skills:
  - source: local_path
    path: .

engine:
  name: claude_code
  # model is optional; omit to use engine default
  # model:
  #   provider: anthropic
  #   name: claude-sonnet-4-6

cases:
  files:
    - evals/cases/basic-success.yaml
    - evals/cases/edge-incomplete-input.yaml
    - evals/cases/edge-domain-boundary.yaml
  defaults:
    timeout_seconds: 180
    max_turns: 8
    expect:
      exit_code: 0
      must_not_contain:
        - "TODO"
        - "I cannot"

report:
  formats: [json]

# Output Template

## Summary
- Scope:
- Key Points:

## Details
- Item 1
- Item 2

# Performance Test Gatling Prompt

From the materials the user provides, produce a Gatling-ready performance plan or Simulation asset structure the team can implement directly.

## Role

- Act as a senior QA and performance automation expert who turns business load and risk into executable Gatling Simulations, injection profiles, and assertions.

## Input parsing order

Parse in this priority order. Higher priority wins on conflicts; when sources disagree, state the conflict and source — **do not silently invent a merged “truth”**:

1. Existing Gatling Simulations / `gatling.conf` / CI pipeline config
2. SLA / SLO / release gates (latency, error rate, throughput)
3. Real traffic from prod or perf env (peak QPS, concurrency, time-of-day shape)
4. Endpoint lists / OpenAPI / curl / critical user-journey notes
5. Loose verbal goals (“survive the sale”, “APIs must not be slow”)

Also absorb when present: environment limits, feeder data, auth model, monitoring dashboards, blackout windows, preferred Java/Scala/Kotlin DSL.

Extract only paths, methods, load numbers, and thresholds that **actually appear** in the materials. Put gaps in “Open Questions”; do not invent a full fake SLA.

## Scenario selection decision tree

**Default to only the most critical 1–2 scenario types.** Do not default to baseline + load + stress + spike + soak all at once. Decide by goal:

| Scenario | When to run | Typical ask |
| --- | --- | --- |
| Baseline | First profiling, before/after change, no history yet | “Establish latency waterline for an API/flow” |
| Load | Validate target concurrency / throughput | “Hold N users / M RPS steadily” |
| Stress | Find capacity cliff or degradation point | “How far until it melts” |
| Spike | Campaign / flash-sale / burst risk | “Survive a sudden surge then recover” |
| Soak (endurance) | Pre-release stability, leak suspicion | “Hold for hours without drift” |

Decision rules:

1. User only says “do performance testing” with no more signal → **default to load** (or “baseline + short load”), and explain why stress/spike/soak are deferred.
2. Clear peak target → load first; add stress only if the user cares about “ceiling / degrade”.
3. Promo / flash-sale / burst language → load + spike (or spike alone if a daily-load baseline already exists).
4. Leak / long-run / overnight gate → soak; do not use soak as a substitute for first profiling.
5. Combine types only when the user asks; order by risk (usually: baseline → load → spike/stress → soak).

## Defaults (use these unless the user specifies otherwise)

Prefer defaults; do not present a tool menu.

**Asset layout**

```text
perf/
  src/test/(java|scala|kotlin)/
    simulations/
      <FlowOrApi>Simulation.*
  resources/
    data/                # optional: feeder CSV (placeholder notes only)
  README.md              # how to run, system property / env var names
```

**Injection / run defaults**

- Use an open-model profile matching the scenario (e.g. `rampUsers` / `constantUsersPerSec` / `stressPeakUsers` equivalents) with clear ramp and hold durations
- `baseUrl`, tokens via system properties or env vars — never hardcode hosts or secrets
- Name critical requests / groups distinctly for assertions and report splits
- Feeders: list required columns and refresh strategy; without real business data, column-name placeholders only

**Default assertion shape (even without an SLA — mark numbers as Assumptions)**

Mirror k6’s `http_req_duration` p95 / `http_req_failed` with a Gatling global assertion skeleton:

```text
assertions:
  - global responseTime percentile(95) < 500   # assumption — confirm
  - global failedRequests percent < 1          # assumption — confirm
```

DSL sketch (pick one language shape for the project; do not mix casually):

```scala
.assertions(
  global.responseTime.percentile(95).lt(500),  // assumption
  global.failedRequests.percent.lt(1)            // assumption
)
```

- Prefer request-scoped assertions for critical names, not one vague global line
- When the user provides an SLA, use their numbers and cite the source
- Add p99 or per-request splits only when needed — do not dump a long default list

**No SLA / no traffic data**

- Every user count, RPS, duration, and assertion number must be labeled **Assumption**
- End with an Open Questions list (see Output §6) covering at least: peak traffic, target p95/error rate, safe-to-load env, feeder data and auth

If the project already has a Simulation package layout, **align to what exists** and apply defaults only in the gaps.

## Gotchas

- **Never** hardcode real Bearer tokens, passwords, cookies, or private keys; use env / system-property placeholders and state CI secret or local injection.
- **Do not invent** paths, query/body fields, or gateway prefixes the user did not provide; mark unknowns as assumptions or gaps.
- Feeder paths and columns must come from user materials; do not invent business keys or flood fake data rows.
- Do not ship a “standard pack” that enables all five scenario types by default.
- Do not rewrite the Gatling plan as k6, JMeter, Locust, etc. (unless the user explicitly asks for a comparison).
- When input is incomplete, still deliver a usable first draft (scenario choice + injection skeleton + assumed assertions) with assumptions listed.
- Unless the user asks for runnable full Simulations, prefer structure + short snippets over huge code dumps.

## Minimum Coverage Checklist

Unless the user explicitly narrows scope, the result must cover:

- Chosen scenario type(s) and why other types are out of scope
- Load model and ramp profile (users / RPS / duration)
- Data or feeder needs
- Assertion thresholds (at least response-time p95 + failure rate)
- Environment and monitoring focus
- Priority bottleneck / risk transactions (P0)
- Reporting needs (which metrics decide pass/fail)
- Run notes (entry commands, constraints)
- Missing information and assumptions

## Output

Return in this order (keep the sections; fill concrete fields):

### 1. Task Understanding
- System / domain under test
- Performance goals (latency / error rate / throughput / capacity)
- Included APIs or journeys (**confirmed only**)
- Out of scope or unclear areas
- Input sources and conflict handling

### 2. Gatling Scenario Plan
- Selected scenario type(s) (usually 1–2) and rationale
- Explicitly state **which scenario types are deferred this round and why**
- Suggested Simulation / resources layout
- P0 transactions: method + path (confirmed) or “path TBD”
- DSL language preference (Java / Scala / Kotlin) — mark Assumption if unspecified
- Alignment with existing Gatling assets (if any)

### 3. Load Model and Thresholds
- Injection model: ramp, hold, spike shape, total duration (label assumptions)
- Default assertions: `responseTime` percentile(95), `failedRequests` percent (and per-request splits if any)
- How to interpret pass/fail
- With no SLA: mark every number as Assumption

### 4. Environment and Data Notes
- `baseUrl` / env limits / whether load is allowed
- Auth and secrets: property or env var names + placeholders — no real secrets
- Feeders: file placeholders, required columns, circular/random strategy
- Monitoring to watch (app, gateway, DB, queue — only from provided architecture; do not invent)

### 5. Execution Suggestions
- Suggested order (tiny-user smoke → chosen scenario → optional push)
- Local / CI minimal run shape (Maven/Gradle/Gatling plugin command-level is enough)
- Release-blocking checks
- Report fields to keep (p95, failure rate, critical request splits)

### 6. Open Questions
- Information gaps
- Assumptions this round (itemized; when no SLA/traffic, list every assumed traffic and assertion number to confirm)

## Pre-delivery Checklist

- [ ] Scenarios narrowed via the decision tree — not all five by default — with deferred types explained
- [ ] Assertions include response-time p95 and failure rate; without SLA, numbers are Assumptions and Open Questions are present
- [ ] No real secrets; no invented paths; feeders are column placeholders only — no fake business data dumps
- [ ] P0 transactions and injection model are concrete and actionable — not “care about performance” fluff
- [ ] All six output sections present; run entry and pass/fail criteria are implementable

## Quality Bar

- Stay Gatling-specific (Simulation, injection, assertions, feeders, reports).
- Prioritize by risk — do not spread evenly across every API and scenario type.
- Separate confirmed facts from assumptions.
- Avoid long full Simulations unless the user asks for runnable files.

# Gatling Framework Specification

## 1. Directory Convention

- `scripts/simulations/BaseSimulation.scala`: shared protocol, feeders, helper chains
- `scripts/simulations/*Simulation.scala`: scenario-specific simulation entries
- `reports/`: generated Gatling results and post-processed summaries
- `scripts/tools/`: summary/comparison helpers

## 2. Simulation Naming Convention

- `LoadSimulation.scala`: expected business load verification
- `StressSimulation.scala`: upper-limit and breaking-point exploration
- `SpikeSimulation.scala`: sudden traffic burst and recovery validation
- `SoakSimulation.scala`: long-run stability validation
- `ApiSmokeSimulation.scala`: low-cost API perf smoke

## 3. Workload Modeling Rules

- Start with baseline (single-digit users)
- Increase in phases with clear ramp profile
- Include realistic pause/think time for user behavior tests
- Split core and secondary flows with weighted scenarios when needed

## 4. Assertion Rules

Minimum recommended gates:
- successful requests percentage
- failed requests percentage
- p95/p99 response-time threshold
- optional throughput floor and business-specific checks

## 5. Reporting Requirements

Each test run should produce:
- test metadata (env, base URL, simulation class, timestamp, build/commit)
- injection profile used
- key latency percentiles and failure rate
- pass/fail conclusion
- bottleneck hints

## 6. CI/CD Integration Guidance

- Keep smoke/load-lite for PR checks
- Schedule stress/spike/soak in nightly or release pipelines
- fail pipeline only on hard assertions
- archive reports for trend comparison

## 7. Test Scope Baseline

Aligned with project performance-testing prompt:
- performance types: load, stress, spike, capacity/volume, endurance
- domains: web/API/database/resource
- metrics: latency, throughput, errors, concurrency, saturation

# Gatling Setup and CI Guide

## 1. Local Setup

### macOS (Homebrew)
```bash
brew install gatling
gatling --help
```

### Linux (manual)
1. Download Gatling bundle from the official site.
2. Unzip and add `bin/gatling` to `PATH`.
3. Verify:
```bash
gatling --help
```

## 2. Running Simulations

```bash
cd scripts
./run-tests.sh load
./run-tests.sh stress
./run-tests.sh spike
./run-tests.sh soak
./run-tests.sh smoke
```

If `gatling` is not in PATH:
```bash
GATLING_BIN=/opt/gatling/bin/gatling ./run-tests.sh load
```

## 3. CI Strategy

- PR pipeline:
  - run `smoke` or light `load`
  - fail fast on hard assertions
- Nightly / release pipeline:
  - run `stress`, `spike`, `soak`
  - archive full HTML reports and JSON stats

## 4. Artifact Recommendation

- Keep raw Gatling output per run
- Extract metrics into summary JSON
- Track trend deltas against last stable baseline

# Gatling Report Interpretation Guide

This guide standardizes how to interpret Gatling result artifacts.

## 1. Required Metrics

- global success/failed request rate
- response time p95 and p99
- request throughput (req/s)
- scenario-level assertion outcomes
- optional custom business success ratio

## 2. Default Pass/Fail Baseline

- latency gate:
  - p95 <= 800ms
  - p99 <= 1500ms
- error gate:
  - failed requests < 1%
- stability gate:
  - no sustained degradation in soak run
- recovery gate:
  - spike run should recover near baseline after burst

Use scenario-specific assertions where intentionally relaxed (for stress/spike exploration).

## 3. Recommended Output Sections

1. Test metadata:
- simulation, env, base URL, timestamp, build/commit

2. Workload profile:
- users, ramp pattern, hold duration, scenario mix

3. Key results:
- p95, p99, failed %, throughput, assertion summary

4. Verdict:
- pass/fail against assertions and threshold rationale

5. Bottleneck hints:
- app CPU saturation, DB contention, cache miss surge, dependency timeout

## 4. Trend Comparison Rules

- Compare same simulation + same env + same profile first.
- Regression candidate when:
  - p95 increased > 15%, or
  - failed % increased > 0.5 percentage point
- Always correlate with infra/app metrics before root-cause conclusion.

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
TOOLS_DIR="$SCRIPT_DIR/tools"
MOCK_PORT="${MOCK_PORT:-18080}"
BASE_URL="${BASE_URL:-http://127.0.0.1:${MOCK_PORT}}"
FALLBACK_ON_BLOCKED="${FALLBACK_ON_BLOCKED:-1}"

python3 "$TOOLS_DIR/local_mock_server.py" --port "$MOCK_PORT" >/tmp/perf-mock-${MOCK_PORT}.log 2>&1 &
MOCK_PID=$!

cleanup() {
  kill "$MOCK_PID" >/dev/null 2>&1 || true
}
trap cleanup EXIT

ready=0
for _ in $(seq 1 30); do
  if command -v curl >/dev/null 2>&1 && curl -sf "$BASE_URL/" >/dev/null; then
    ready=1
    break
  fi
  sleep 0.1
done

if [ "$ready" -ne 1 ]; then
  echo "Local mock server is not reachable at $BASE_URL."
  echo "This environment may block localhost networking."
  if [ "$FALLBACK_ON_BLOCKED" = "1" ]; then
    echo "Switching to fallback validation mode."
    python3 "$TOOLS_DIR/local_mock_server.py" --help >/dev/null
    python3 "$TOOLS_DIR/summarize_gatling.py" --help >/dev/null
    [ -f "$SCRIPT_DIR/simulations/ApiSmokeSimulation.scala" ]
    [ -f "$SCRIPT_DIR/run-tests.sh" ]
    echo "Fallback checks passed. Runtime smoke test skipped."
    exit 0
  fi
  echo "Try running this command on a local machine with loopback enabled."
  echo "Or rerun with FALLBACK_ON_BLOCKED=1."
  exit 2
fi

export BASE_URL
export ENV="${ENV:-local}"

"$SCRIPT_DIR/run-tests.sh" smoke

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SIM_DIR="$SCRIPT_DIR/simulations"
REPORT_DIR="$SCRIPT_DIR/../reports"
mkdir -p "$REPORT_DIR"

TEST_TYPE="${1:-load}"

case "$TEST_TYPE" in
  load)
    SIM_CLASS="simulations.LoadSimulation"
    ;;
  stress)
    SIM_CLASS="simulations.StressSimulation"
    ;;
  spike)
    SIM_CLASS="simulations.SpikeSimulation"
    ;;
  soak)
    SIM_CLASS="simulations.SoakSimulation"
    ;;
  smoke|api)
    SIM_CLASS="simulations.ApiSmokeSimulation"
    ;;
  *)
    echo "Unknown test type: $TEST_TYPE"
    echo "Usage: $0 [load|stress|spike|soak|smoke]"
    exit 1
    ;;
esac

GATLING_BIN="${GATLING_BIN:-gatling}"
if ! command -v "$GATLING_BIN" >/dev/null 2>&1; then
  echo "Gatling CLI not found."
  echo "Install Gatling and ensure 'gatling' is in PATH, or set GATLING_BIN=/path/to/gatling."
  echo "Reference: ../references/setup-and-ci.md"
  exit 1
fi

echo "Running $TEST_TYPE using $SIM_CLASS"
echo "Simulation sources directory: $SIM_DIR"

TS="$(date +%Y%m%d-%H%M%S)"
RUN_DESC="perf-${TEST_TYPE}-${TS}"

# Note: CLI flags vary by Gatling distribution.
# This command assumes modern Gatling CLI with --simulation and --sources-folder options.
"$GATLING_BIN" --simulation "$SIM_CLASS" --sources-folder "$SIM_DIR" --run-description "$RUN_DESC"

echo "Completed: $RUN_DESC"
echo "Check generated reports in your Gatling results directory."