https://github.com/christian-draeger/k6-kotlin
Run k6 load and performance testing scenarios from your JVM project on an out-of-the box but configurable k6 infra spin-up by the use of Docker.
https://github.com/christian-draeger/k6-kotlin
docker dsl k6 kotlin kotlin-library library load-test load-tester load-testing performance-testing testcontainers
Last synced: 7 months ago
JSON representation
Run k6 load and performance testing scenarios from your JVM project on an out-of-the box but configurable k6 infra spin-up by the use of Docker.
- Host: GitHub
- URL: https://github.com/christian-draeger/k6-kotlin
- Owner: christian-draeger
- License: mit
- Created: 2020-10-18T20:03:33.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2023-03-08T09:32:51.000Z (over 2 years ago)
- Last Synced: 2025-03-18T15:12:42.467Z (7 months ago)
- Topics: docker, dsl, k6, kotlin, kotlin-library, library, load-test, load-tester, load-testing, performance-testing, testcontainers
- Language: Kotlin
- Homepage:
- Size: 11.7 MB
- Stars: 14
- Watchers: 2
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# k6-kotlin
> Embedding k6 test-infrastructure into your JVM projects.
## TL;DR
This project wires everything you need to run load tests done by [k6](https://k6.io) from you JVM project,
e.g., as a jUnit test during you gradle or maven build or triggered programmatically from anywhere in your codebase.
It automatically spins-up everything you need to run a load test using k6 (like an influxDB, grafana as an UI for your results, as well as k6 itself) via docker.
Therefore, it is mandatory to have a running [docker installation](https://docs.docker.com/engine/install/) on your system.
## Setup
**important: It's mandatory to have a running Docker installation to use this library.**
### Add the dependency to your project:
```kotlin
implementation("io.github.christian-draeger:k6-kotlin:0.1.0")
```
## Usage
### Scenario / Test definitions
> **important:** This library currently just exists to do all the runner setup and result visualization setup for you.
> The test scenarios are usually k6 tests. Please check the [official k6 docs](https://k6.io/docs/using-k6/) to learn how to write them.
> In the future this library will possibly evolve to abstract writing scenarios in kotlin or inject postman collections.
To run k6 tests from your jvm project just place as many valid k6 load test scenarios under `resources/k6-tests` in your project.
K6 test scenarios are written in Javascript. For in depth documentation please see the [official k6 docs](https://k6.io/docs/), especially the ["Using k6" section](https://k6.io/docs/using-k6/).
### Test Execution
Start the k6 infrastructure and run all the test scenarios that have been placed in `resources/k6-tests`:
```kotlin
// info: you could call it from wherever you want, even your production code. it doesn't necessarily gets called inside a test
@Test
fun `run load test with default infra settings`() {
val defaultK6Infra = k6
defaultK6Infra.start
}
```
### Result output
#### Console
The result of the k6 runner will be piped to STDOUT (updated in real time):
#### Grafana
Since the setup will spin-up a grafana that is preconfigured to connect to the influxDB where the k6 runner results are stored it is possible to watch the results via grafana during a running k6 load test scenario (by default the current results will be updated every 5 seconds):
To automatically open the grafana results dashboard in chrome browser during a k6 load test starts just set the following property:
```kotlin
k6 {
grafana {
autoOpen = true
}
}
```
### Customize Setup
It is possible to customize most of the crucial config parameters that are used to spin-up a working k6 test environment.
```kotlin
// info: you could call it from wherever you want, even your production code. it doesn't necessarily gets called inside a test
@Test
internal fun `run load test with custom inbfra settings`() {
k6 {
influxDB {
image = "influxdb" // the docker image that will be used
version = "1.8.4-alpine" // the docker images version
dbName = "fancy-name"
networkAlias = "influx" // service alias inside the docker network
internalPort = 8086 // port used inside of the docker network
// external port is dynamically allocated and will be some free port
}
grafana {
image = "grafana/grafana" // the docker image that will be used
version = "latest" // the docker images version
internalPort = 3000 // port used inside of the docker network
networkAlias = "grafana" // service alias inside the docker network
autoOpen = true // will automatically open grafana dashboard with realtime results in chrome browser
}
runner {
image = "loadimpact/k6" // the docker image that will be used
version = "0.28.0" // the docker images version
networkAlias = "k6" // service alias inside the docker network
resourcePath = "./k6-tests" // location of the test scenarios relative to the src/(main|test)/resources folder
}
}
}
```
## Why [k6](https://k6.io)?
k6 is a developer-centric, free and open-source load testing tool built for making performance testing a productive and enjoyable experience.
Using k6, you'll be able to catch performance regression and problems earlier, allowing you to build resilient systems and robust applications.
### Use cases
[k6](https://k6.io) users are typically Developers, QA Engineers, and DevOps. They use k6 for testing the performance of APIs, microservices, and websites. Common k6 use cases are:
#### Load testing
[k6](https://k6.io) is optimized for minimal consumption of system resources. It’s a high-performance tool designed for running tests with high load (spike, stress, soak tests) in pre-production and QA environments.
#### Performance monitoring
[k6](https://k6.io) provides great primitives for performance testing automation. You could run tests with a small amount of load to continuously monitor the performance of your production environment.
## Development
bump dependencies:
./gradlew dependencyUpdates
bump gradle version:
./gradlew wrapper --gradle-version 7.0.2
run tests with k6 result output visible:
./gradlew clean build -i
publish to local maven repository
./gradlew publishToMavenLocal
## License
[MIT](./LICENSE)