gatling-picatinny

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

gatling-picatinny

★ 12 Open GitHub ↗

Gatling DSL extensions — feeders, profile management, transactions, assertions, Redis integration, and utility functions

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Gatling Picatinny

[![CI](https://github.com/galax-io/gatling-picatinny/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/galax-io/gatling-picatinny/actions/workflows/ci.yml)
[![Tests](https://img.shields.io/github/actions/workflow/status/galax-io/gatling-picatinny/ci.yml?branch=main&label=tests)](https://github.com/galax-io/gatling-picatinny/actions/workflows/ci.yml)
[![Maven Central](https://img.shields.io/maven-central/v/org.galaxio/gatling-picatinny_2.13.svg?color=success)](https://search.maven.org/search?q=org.galaxio.gatling-picatinny)
[![codecov](https://codecov.io/gh/galax-io/gatling-picatinny/branch/main/graph/badge.svg)](https://codecov.io/gh/galax-io/gatling-picatinny)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![Scala Steward badge](https://img.shields.io/badge/Scala_Steward-helping-blue.svg?style=flat&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAQCAMAAAARSr4IAAAAVFBMVEUAAACHjojlOy5NWlrKzcYRKjGFjIbp293YycuLa3pYY2LSqql4f3pCUFTgSjNodYRmcXUsPD/NTTbjRS+2jomhgnzNc223cGvZS0HaSD0XLjbaSjElhIr+AAAAAXRSTlMAQObYZgAAAHlJREFUCNdNyosOwyAIhWHAQS1Vt7a77/3fcxxdmv0xwmckutAR1nkm4ggbyEcg/wWmlGLDAA3oL50xi6fk5ffZ3E2E3QfZDCcCN2YtbEWZt+Drc6u6rlqv7Uk0LdKqqr5rk2UCRXOk0vmQKGfc94nOJyQjouF9H/wCc9gECEYfONoAAAAASUVORK5CYII=)](https://scala-steward.org)

Gatling DSL extensions library — production-ready utilities for feeders, transactions, assertions, templates, config management, JWT generation, Redis integration, and more. Build faster, more reliable performance tests.

---

## Contents

- [What & why](#what--why) · [Start here](#start-here) · [Compatibility](#compatibility) · [Installation](#installation) · [Quickstart](#quickstart)
- **Key features**: [Configuration](#configuration) · [Feeders](#feeders) · [JWT](#jwt) · [Transactions](#transactions) · [Logging & secret masking](#logging--secret-masking)
- **Full docs**: [Configuration](docs/configuration.md) · [Feeders](docs/feeders.md) · [Logging](docs/logging.md) · [Profile](docs/profile.md) · [Redis](docs/redis.md) · [Templates](docs/templates.md) · [JWT](docs/jwt.md) · [Assertions](docs/assertions.md) · [Transactions](docs/transactions.md) · [Examples](docs/examples.md) · [Migration](docs/migration.md)
- [Documentation catalog](#documentation) · [Contributing](#contributing) · [License](#license)

---

## What & why

Gatling Picatinny is best for teams that write Gatling load tests and need production-grade helpers on top of the core DSL: structured config, realistic data feeders, signed JWTs, Redis-backed scenarios, reusable transaction blocks, and response-time assertions — without writing all of that from scratch. It is a `Test`-scoped library that plugs into the standard Gatling DSL; you keep writing normal simulations and reach for Picatinny where the core DSL leaves a gap.

## Start here

### Step 1 — Add the dependency

Pick the snippet for your build tool in [Installation](#installation), then come back here.

### Step 2 — Open an example project

The `examples/` folder contains source overlays for all three languages. Each overlay is applied on top of a project generated by the galaxio CLI — none of them are standalone runnable on their own. Generate a project with the CLI first, then open the `Debug` simulation as your entry point. See [Examples & Testing](docs/examples.md) for the full table.

### Step 3 — Find the feature you need

| I want to… | Go to |
|---|---|
| Share `baseUrl`, intensity, and custom vars across scenarios | [Configuration](docs/configuration.md) |
| Generate realistic test data (names, phones, UUIDs, CSV rows) | [Feeders](docs/feeders.md) |
| Wrap request groups into named transactions with latency stats | [Transactions](docs/transactions.md) |
| Attach a signed JWT to every request | [JWT](docs/jwt.md) |
| Share state between virtual users via Redis | [Redis](docs/redis.md) |
| Assert response-time percentiles after a run | [Assertions](docs/assertions.md) |
| Render dynamic request bodies from JSON/XML DSL + file templates (Gatling EL) | [Templates](docs/templates.md) |
| Tame logs / mask secrets / configure the startup banner | [Logging & Secret Masking](docs/logging.md) |

---

## Compatibility

| Picatinny version | Gatling | Scala | Java | Branch |
|---|---|---|---|---|
| since 1.12.0 — latest ([Releases][releases] · [Maven Central][maven]) | 3.13.x | 2.13 | 17+ | `main` |
| 0.16.0 – 0.18.2 (archived) | 3.11.x | 2.13 | 17+ | — |

`main` always tracks the newest stable Gatling; 3.13.x has been supported since 1.12.0.

> **Which version should I use?**
> - **Gatling 3.13 (current)** — use the latest release from `main` (see [Releases][releases]). 3.13.x supported since 1.12.0.
> - **Gatling 3.11 (legacy)** — use `0.18.2`; that line is no longer actively developed.

[releases]: https://github.com/galax-io/gatling-picatinny/releases
[maven]: https://search.maven.org/search?q=org.galaxio.gatling-picatinny

> **Branch strategy:** `main` tracks the latest stable Gatling release (currently 3.13.x). There is no separate long-term branch for older Gatling lines.

## Installation

> Replace `VERSION` with the latest — see the **Maven Central** badge at the top or the [Releases][releases] page.

### Scala (sbt) — Gatling 3.13

```scala
libraryDependencies += "org.galaxio" %% "gatling-picatinny" % "VERSION" % Test
```

### Java / Kotlin (Gradle Kotlin DSL) — Gatling 3.13

```kotlin
gatling("org.galaxio:gatling-picatinny_2.13:VERSION")
```

### Maven — Gatling 3.13

```xml
<dependency>
  <groupId>org.galaxio</groupId>
  <artifactId>gatling-picatinny_2.13</artifactId>
  <version>VERSION</version>
  <scope>test</scope>
</dependency>
```

### Legacy — Gatling 3.11

**sbt:**

```scala
libraryDependencies += "org.galaxio" %% "gatling-picatinny" % "0.18.2" % Test
```

**Gradle (Kotlin DSL):**

```kotlin
gatling("org.galaxio:gatling-picatinny_2.13:0.18.2")
```

**Maven:**

```xml
<dependency>
  <groupId>org.galaxio</groupId>
  <artifactId>gatling-picatinny_2.13</artifactId>
  <version>0.18.2</version>
  <scope>test</scope>
</dependency>
```

## Quickstart

A minimal simulation wiring Picatinny `SimulationConfig` (shared `baseUrl`/`intensity`/durations) and the startup banner into the standard Gatling DSL:

```scala
import io.gatling.core.Predef._
import io.gatling.http.Predef._
import org.galaxio.gatling.config.SimulationConfig._
import org.galaxio.gatling.utils.Utility

class Quickstart extends Simulation {
  val httpProtocol = http.baseUrl(baseUrl)

val scn = scenario("Quickstart").exec(http("home").get("/"))

val injection = (
    rampUsersPerSec(0).to(intensity).during(rampDuration),
    constantUsersPerSec(intensity).during(stageDuration),
  )

Utility.banner(injection) // workload banner, emitted via SLF4J

setUp(scn.inject(injection._1, injection._2)).protocols(httpProtocol)
}
```

`simulation.conf` (under `src/test/resources`):

```hocon
baseUrl = "http://localhost"
intensity = "60 rpm"
rampDuration = 1 minute
stageDuration = 5 minutes
```

Run it, overriding any value with `-D`:

```bash
sbt Gatling/test -DbaseUrl=https://test.example.org -Dintensity="120 rpm"
```

> The banner and all config/diagnostic output go through **SLF4J**; Picatinny ships no `logback.xml`. Add the recommended config so output renders the way you expect — see [Logging & Secret Masking](docs/logging.md).

## Key features

Short tour of the most-used pieces. Full per-feature docs are in the [Documentation](#documentation) catalog below.

### Configuration

`SimulationConfig` shares `baseUrl`, `intensity`, ramp/stage/test durations and your own params across scenarios, with
`-D` overrides and validation on first read. Values are masked when logged (see [secret masking](#logging--secret-masking)).

```scala
import org.galaxio.gatling.config.SimulationConfig._

http.baseUrl(baseUrl)                       // shared HTTP base
val region = getStringParam("region")       // custom param from simulation.conf or -Dregion=eu
rampUsersPerSec(0).to(intensity).during(rampDuration)
```

Full reference → [docs/configuration.md](docs/configuration.md).

### Feeders

Composable **Faker API** generators (domain-oriented: names, phones, finance, RU docs) plus legacy `Random*Feeder`
one-liners, HC Vault, CSV/`SeparatedValuesFeeder` and phone feeders — all produce standard Gatling feeders.

```scala
import org.galaxio.gatling.feeders.faker.Predef._
import org.galaxio.gatling.feeders.faker._

val users = GeneratedFeeder(
  "email"  -> Faker.internet.email(),
  "phone"  -> Faker.phone.mobile(Country.RU, PhoneFormatMode.E164),
  "amount" -> Faker.finance.amount(BigDecimal(100), BigDecimal(5000)),
)
```

Full reference → [docs/feeders.md](docs/feeders.md) · Faker API → [docs/faker-api.md](docs/faker-api.md).

### JWT

Generate HMAC (HS*) or RSA/EC (RS*/ES*) JWTs, with a standard-claims DSL, EL placeholders for per-user claims, PEM key
loading, and a bearer-token helper. Tokens land in the session for signing requests.

```scala
import org.galaxio.gatling.utils.jwt._

val gen = jwt("HS256", "my-secret")
exec(_.setJwtAsBearer(gen))                 // adds Authorization: Bearer <token>
// or store it: .exec(_.setJwt(gen, "jwtToken"))
```

Full reference → [docs/jwt.md](docs/jwt.md).

### Transactions

Group request chains into named transactions with their own latency/throughput stats. The simulation extends
`SimulationWithTransactions`.

```scala
import org.galaxio.gatling.transactions.Predef._

exec(Actions.createEntity())
  .startTransaction("checkout")
  .exec(Actions.insertTest()).pause(2).exec(Actions.selectTest)
  .endTransaction("checkout")
```

Full reference → [docs/transactions.md](docs/transactions.md).

### Logging & secret masking

> These behaviors arrive in **1.23.0** (current `main`, not yet released). On the latest published release they behave as before — see the [1.23.0 migration notes](docs/logging.md#migration--upgrading-to-1230).

Output goes through SLF4J; the library ships **no** `logback.xml` (you stay in control). Secrets are redacted at every
log/print/exception sink — keys whose last segment is a sensitive term (`password`, `secret`, `token`, `apiKey`,
`bearer`, `credentials`, … and separator-less forms like `dbpassword`) become `******`; benign ones (`roleId`,
`tokenBucketSize`) stay visible. Add your own terms; toggle the banner with the enable flags.

```hocon
picatinny.redaction.additionalSensitiveKeys = ["tenantRef"]   # extend masking
picatinny.startup.banner.enabled = true                       # the on/off knob
```

Full reference + recommended `logback.xml` + [1.23.0 migration](docs/logging.md#migration--upgrading-to-1230) →
[docs/logging.md](docs/logging.md).

## Documentation

| Topic | What it covers |
|---|---|
| [Configuration](docs/configuration.md) | `SimulationConfig`: `baseUrl`/`intensity`/durations, custom vars, validation, secret masking at read time |
| [Feeders](docs/feeders.md) | Faker API ([full reference](docs/faker-api.md)), legacy `Random*Feeder`, HC Vault, `SeparatedValuesFeeder`, phone feeders |
| [Logging & Secret Masking](docs/logging.md) | SLF4J setup, recommended `logback.xml`, startup banner & diagnostics, secret redaction, **1.23.0 migration notes** |
| [Profile](docs/profile.md) | Profile DSL: load HTTP/custom profiles from HOCON/YAML |
| [Redis](docs/redis.md) | Redis commands as Gatling scenario actions |
| [Templates](docs/templates.md) | JSON/XML body DSL + file-based template loading |
| [JWT](docs/jwt.md) | JWT generation: HMAC/RSA/EC, claims DSL, bearer helper |
| [Assertions](docs/assertions.md) | NFR assertions from YAML (percentiles, error rate) |
| [Transactions](docs/transactions.md) | `startTransaction`/`endTransaction` with pause-inclusive latency |
| [Examples & Testing](docs/examples.md) | Scala / Java / Kotlin example overlays and how to run them |
| [Migration Guide](docs/migration.md) | Per-version upgrade matrix + before/after code for spec-kit releases (1.16.0+) |

## Contributing

```bash
# Build
sbt compile

# Run unit tests
sbt test

# Run integration tests
sbt IntegrationTest/test

# Check formatting
sbt scalafmtCheckAll

# Format code
sbt scalafmtAll
```

## License

Apache License 2.0. See [LICENSE](LICENSE) for details.

gatling-picatinny

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README