Project Setup

Learn about how to set up your project to use the Gatling gRPC protocol

Under the hood, Gatling uses gRPC-Java to implement its protocol support.

License and limitations

The Gatling gRPC component is distributed under the Gatling Enterprise Component License.

The Gatling gRPC protocol can be used with both the Open Source and Enterprise versions of Gatling.

Its usage is unlimited when running on Gatling Enterprise. When used with Gatling Open Source, usage is limited to:

5 users max
5 minute duration tests

Limits after which the test will stop.

Getting started with the demo project

A demo project is available with most combinations of currently supported languages and build tools:

It also contains a demo server that you can use if you want to run the example scenarios over a working server.

Adding the Gatling gRPC dependency

The Gatling gRPC plugin is not included with Gatling by default. Add the Gatling gRPC dependency, in addition to the usual Gatling dependencies.

For Java or Kotlin:

<dependencies>
  <dependency>
    <groupId>io.gatling</groupId>
    <artifactId>gatling-grpc-java</artifactId>
    <version>${gatling-grpc.version}</version>
    <scope>test</scope>
  </dependency>
</dependencies>

Base Gatling setup for Maven is documented here.

dependencies {
  gatlingImplementation("io.gatling:gatling-grpc-java:$gatlingGrpcVersion")
}

Base Gatling setup for Gradle is documented here.

For Scala:

<dependencies>
  <dependency>
    <groupId>io.gatling</groupId>
    <artifactId>gatling-grpc</artifactId>
    <version>${gatling-grpc.version}</version>
    <scope>test</scope>
  </dependency>
</dependencies>

Base Gatling setup for Maven is documented here.

dependencies {
  gatlingImplementation("io.gatling:gatling-grpc:$gatlingGrpcVersion")
}

Base Gatling setup for Gradle is documented here.

libraryDependencies += "io.gatling" % "gatling-grpc" % gatlingGrpcVersion % "test,it"

Base Gatling setup for sbt is documented here.

Configuring Protobuf code generation

By default, gRPC uses Protocol Buffers (protobuf) to serialize messages, so we also show typical configurations to generate your gRPC method descriptors and data access classes from proto files. Note that if your gRPC service uses something else (e.g. JSON messages), you will need to use appropriate configurations for your use case instead.

Protobuf for Java

For a project running Java with either Maven or Gradle:

<build>
  <extensions>
    <extension>
      <groupId>kr.motd.maven</groupId>
      <artifactId>os-maven-plugin</artifactId>
      <version>${os-maven-plugin.version}</version>
    </extension>
  </extensions>
  <plugins>
    <plugin>
      <groupId>org.xolstice.maven.plugins</groupId>
      <artifactId>protobuf-maven-plugin</artifactId>
      <version>${protobuf-maven-plugin.version}</version>
      <executions>
        <execution>
          <id>compile</id>
          <goals>
            <goal>test-compile</goal>
            <goal>test-compile-custom</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <pluginId>grpc-java</pluginId>
        <pluginArtifact>io.grpc:protoc-gen-grpc-java:${protoc-gen-grpc-java.version}:exe:${os.detected.classifier}</pluginArtifact>
        <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
      </configuration>
    </plugin>
  </plugins>
</build>

With the following properties:

<properties>
  <protobuf.version>3.25.2</protobuf.version>
  <protobuf-maven-plugin.version>0.6.1</protobuf-maven-plugin.version>
  <protoc-gen-grpc-java.version>1.61.0</protoc-gen-grpc-java.version>
  <os-maven-plugin.version>1.7.1</os-maven-plugin.version>
</properties>

Add your proto files in the src/test/proto directory.

Check the demo project for a full example: Gatling gRPC Java demo with Maven.

plugins {
  id("idea")
  id("java")
  id("com.google.protobuf") version "0.9.4"
}

protobuf {
  protoc {
    artifact = "com.google.protobuf:protoc:3.25.2"
  }
  plugins {
    grpc {
      artifact = "io.grpc:protoc-gen-grpc-java:1.61.0"
    }
  }
  generateProtoTasks {
    ofSourceSet("gatling").forEach { task ->
      compileGatlingJava.dependsOn(task)
      task.plugins {
        grpc {}
      }
    }
  }
}

You will also need to add the generated files to the idea module and Gatling source sets:

var generatedSources = [
  file("${protobuf.generatedFilesBaseDir}/gatling/java"),
  file("${protobuf.generatedFilesBaseDir}/gatling/grpc")
]

idea {
  module {
    generatedSources.forEach { generatedSourceDirs += it }
  }
}

sourceSets {
  gatling {
    java {
      generatedSources.forEach { srcDirs += it }
    }
  }
}

Add your proto files in the src/gatling/proto directory.

Check the demo project for a full example: Gatling gRPC Java demo with Gradle.

Protobuf for Kotlin

For a project running Kotlin with either Maven or Gradle:

<build>
  <extensions>
    <extension>
      <groupId>kr.motd.maven</groupId>
      <artifactId>os-maven-plugin</artifactId>
      <version>${os-maven-plugin.version}</version>
    </extension>
  </extensions>
  <plugins>
    <plugin>
      <groupId>org.xolstice.maven.plugins</groupId>
      <artifactId>protobuf-maven-plugin</artifactId>
      <version>${protobuf-maven-plugin.version}</version>
      <executions>
        <execution>
          <id>compile</id>
          <goals>
            <goal>test-compile</goal>
            <goal>test-compile-custom</goal>
          </goals>
          <configuration>
            <pluginId>grpc-java</pluginId>
            <pluginArtifact>io.grpc:protoc-gen-grpc-java:${protoc-gen-grpc-java.version}:exe:${os.detected.classifier}</pluginArtifact>
            <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

With the following properties:

<properties>
  <kotlin.version>1.9.10</kotlin.version>
  <protobuf.version>3.25.2</protobuf.version>
  <protobuf-maven-plugin.version>0.6.1</protobuf-maven-plugin.version>
  <protoc-gen-grpc-java.version>1.61.0</protoc-gen-grpc-java.version>
  <os-maven-plugin.version>1.7.1</os-maven-plugin.version>
</properties>

Add your proto files in the src/test/proto directory.

Check the demo project for a full example: Gatling gRPC Kotlin demo with Maven.

plugins {
  idea
  kotlin("jvm")
  kotlin("plugin.allopen")

  id("com.google.protobuf") version "0.9.4"
}

dependencies {
  gatlingApi("com.google.protobuf:protobuf-kotlin:3.25.2")
}

protobuf {
  protoc {
    artifact = "com.google.protobuf:protoc:3.25.2"
  }
  plugins {
    create("grpc") {
      artifact = "io.grpc:protoc-gen-grpc-java:1.61.0"
    }
  }
  generateProtoTasks {
    ofSourceSet("gatling").forEach { task ->
      tasks.getByName("compileGatlingKotlin").dependsOn(task)
      task.builtins {
        maybeCreate("java") // Used by kotlin and already defined by default
        create("kotlin")
      }
      task.plugins {
        create("grpc")
      }
    }
  }
}

You will also need to add the generated files to the idea module and Gatling source sets:

var generatedSources = arrayOf(
  file("${protobuf.generatedFilesBaseDir}/gatling/java"),
  file("${protobuf.generatedFilesBaseDir}/gatling/kotlin"),
  file("${protobuf.generatedFilesBaseDir}/gatling/grpc")
)

idea {
  module {
    generatedSourceDirs.plusAssign(generatedSources)
  }
}

sourceSets.getByName("gatling") {
  java.srcDirs(generatedSources)
  kotlin.srcDirs(generatedSources)
}

Add your proto files in the src/gatling/proto directory.

Check the demo project for a full example: Gatling gRPC Kotlin demo with Gradle.

Protobuf for Scala

For an sbt project running Scala, add the ScalaPB plugin in project/plugins.sbt:

addSbtPlugin("com.thesamet" % "sbt-protoc" % "1.0.6")

libraryDependencies ++= Seq(
  "com.thesamet.scalapb" %% "compilerplugin" % "0.11.14"
)

And configure it in your project settings (build.sbt):

val commons = Seq(
  PB.protocVersion := "3.25.2" // scalapb.compiler.Version.protobufVersion may point to an older version
)

val scalaSettings: Seq[Def.Setting[_]] = commons ++ Seq(
  Test / PB.targets := Seq(
    scalapb.gen() -> (Test / sourceManaged).value
  ),
  libraryDependencies ++= Seq(
    "com.thesamet.scalapb" %% "scalapb-runtime"      % scalapb.compiler.Version.scalapbVersion % "protobuf",
    "com.thesamet.scalapb" %% "scalapb-runtime-grpc" % scalapb.compiler.Version.scalapbVersion % "test"
  )
)

scalaSettings

Use javaSettings instead if you would rather use POJOs instead of objects generated by ScalaPB:

val javaSettings: Seq[Def.Setting[_]] = commons ++ Seq(
  Test / PB.targets := Seq(
    PB.gens.java -> (Test / sourceManaged).value,
    PB.gens.plugin("grpc-java") -> (Test / sourceManaged).value
  ),
  libraryDependencies ++= Seq(
    ("io.grpc" % "protoc-gen-grpc-java" % scalapb.compiler.Version.grpcJavaVersion).asProtocPlugin()
  )
)

javaSettings

Add your proto files to the src/test/protobuf directory.

Check the demo project for a full example: Gatling gRPC Scala demo with sbt.

Edit this page on GitHub

Project Setup

License and limitations#

Getting started with the demo project#

Adding the Gatling gRPC dependency#

Configuring Protobuf code generation#

Protobuf for Java#

Protobuf for Kotlin#

Protobuf for Scala#