# Traffic Cop 🚓🚦
![](https://github.com/walterscarborough/traffic-cop/workflows/Run%20All%20Tests/badge.svg)
![](https://img.shields.io/docker/cloud/build/walterscarborough/traffic-cop.svg)
## Overview
This application provides a RESTful interface to the [gatling](https://gatling.io/open-source) load testing library to help easily run load tests in cloud environments.
It was inspired by the work done on the `gatling-runner` tool that <NAME> and I worked on together: https://github.com/poprygun/gatling-runner. 
This new redesign/rewrite is fully tested and allows you to easily change load test configuration without the need to recompile anything.
## Design
This application follows [App Continuum](https://www.appcontinuum.io/) design methodology, and has been designed as a component based monolithic single application.
## Usage
Load tests can be easily configured and run by a HTTP request.
 
Load test traffic can be set to run at a constant number of users per second, a ramped number of users per second (i.e. an increasing number of users per second over time), or as a combination of both.
## Project Dependencies
* JDK 8 or above
* `shellcheck` for running bash linter (`brew install shellcheck`)
## Starting Traffic-Cop
Although traffic-cop can be built into a jar, it will need to be unpacked in order to run.
Some cloud providers such as Cloud Foundry will automatically unzip the jar, but you may need unzip it yourself if your target environment doesn't do that or if you want to run it locally.
Here's what that would look like:
```bash
./gradlew clean build
cd application/build/libs
# unpack the jar
jar xf traffic-cop.jar
# start traffic-cop
java -cp . org.springframework.boot.loader.JarLauncher
```
## Running With Docker
There is a multistage `Dockerfile` included in this repository that will build traffic-cop and then package it into a small image.
```bash
# build
docker build -t traffic-cop .
# run from docker with the traffic-cop api port mapped to localhost:8080, and the report directory mapped to localhost /tmp/traffic-cop-reports
docker run -it -p 8080:8080 -v /tmp/traffic-cop-reports:/traffic-cop/reports traffic-cop
```
At this point, you can send commands as usual (e.g. to `localhost:8080`, and then go see the output report in `/tmp/traffic-cop-reports/<report-name>`
### Example Command: Run Load Test
```bash
curl 'http://localhost:8080/run-load-test' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"baseUrl":"http://localhost:52616","endpoint":"/chachkies","httpMethod":"PUT","payload":"{\"name\": \"<NAME>\"}","constantUsersPerSecond":1,"constantUsersPerSecondDuration":5,"rampUsersPerSecondMinimum":1,"rampUsersPerSecondMaximum":5,"rampUsersPerSecondDuration":5}'
```
In this example, a load test with 1 "user" (aka request) per second will run for 5 seconds. The target server is located at `http://localhost:52616`, using the endpoint `/chachkies`. All requests for this load test will be issued as `PUT` requests with a request body of `{"name": "<NAME>"}`.
It is important to note that the request body json has to be escaped since it is included as the `payload` value in our load test request json.
### Example Command: Read Reports
In your browser, go to: 
```
http://localhost:8080/reports
```
All reports will be listed in chronological order. 
Click on the report that you're interested in to browse it.
Documentation on gatling report details is available from the gatling project: https://gatling.io/docs/current/general/reports/. 
### Run Tests
```
./scripts/run-tests.sh
```
### Run End to End Tests
```
./scripts/run-end-to-end-tests.sh
```
### Build
```
./scripts/build-artifact.sh
```
## Future Ideas
* Allowing custom headers to be injected into load test requests.
* Bundling autogenerated Spring Rest Docs into the jar.
* Allowing gatling reports to be downloaded as zip files.
* Any other suggestions?
## License
MIT