github.com/kubeshop/testkube@v1.17.23/contrib/executor/jmeter/README.md (about)

     1  ![Testkube Logo](https://raw.githubusercontent.com/kubeshop/testkube/main/assets/testkube-color-gray.png)
     2  
     3  [![Go Report Card](https://goreportcard.com/badge/github.com/kubeshop/testkube-executor-jmeter)](https://goreportcard.com/report/github.com/kubeshop/testkube-executor-jmeter)
     4  [![Go Reference](https://pkg.go.dev/badge/github.com/kubeshop/testkube-executor-jmeter.svg)](https://pkg.go.dev/github.com/kubeshop/testkube-executor-jmeter)
     5  [![License](https://img.shields.io/github/license/kubeshop/testkube-executor-jmeter)]()
     6  
     7  # JMeter Executor
     8  
     9  ## What is an Executor?
    10  
    11  Executor is nothing more than a program wrapped into Docker container which gets JSON (testube.Execution) OpenAPI based document as an input and returns a stream of JSON output lines (testkube.ExecutorOutput),
    12  where each output line is simply wrapped in this JSON, similar to the structured logging idea.
    13  
    14  ## Intro
    15  
    16  It's basic JMeter executor able to run simple JMeter scenarios writer in JMX format.
    17  Please define your JMeter file as file (string, or git file). 
    18  
    19  Project directory is not implemented yet.
    20  
    21  ## Plugins
    22  
    23  The following plugins are installed by default:
    24  * [JMeter Plugins Common Classes 0.6](https://javadoc.io/doc/kg.apc/jmeter-plugins-cmn-jmeter/latest/index.html)
    25  * [JMeter Plugins Manager 1.3](https://jmeter-plugins.org/wiki/PluginsManager/)
    26  * [Custom JMeter Functions 2.1](https://jmeter-plugins.org/wiki/Functions/)
    27  
    28  You can add more JMeter plugins either when creating or executing a JMeter test by leveraging Testkube's [copy files](https://docs.testkube.io/articles/running-tests#mapping-local-files) functionality.
    29  
    30  JMeter Plugin JAR files need to be copied to the `uploads` directory in the Executor container.
    31  
    32  Example:
    33  ```shell
    34  kubectl testkube create test \
    35            --file test.jmx    \
    36            --copy-files "/source/path/to/jmeter-plugins-functions-2.1.jar:plugins/jmeter-plugins-functions-2.1.jar" \
    37            --name jmeter-test \
    38            --type jmeter/test
    39  ```
    40  
    41  ## Local development
    42  
    43  ### Prerequisites
    44  
    45  Make sure the following tools are installed on your machine and available in your PATH:
    46  * [JMeter](https://jmeter.apache.org/download_jmeter.cgi) - pure Java application designed to load test functional behavior and measure performance
    47  
    48  ### Setup
    49  1. Create a directory called `data/` where JMeter will run and store results (best practice is to create it in the project root because it is git-ignored)
    50  2. Create a JMeter XML project file and save it as a file named `test-content` in the newly created `data/` directory
    51  3. Create an execution JSON file and save it as a file named `execution.json` based on the template below (best practice is to save it in the `temp/` folder in the project root because it is git-ignored)
    52      ```json
    53      {
    54        "id": "jmeter-test",
    55        "args": [],
    56        "variables": {},
    57        "content": {
    58          "type": "string"
    59        }
    60      }
    61      ```
    62  4. You need to provide the `RUNNER_SCRAPPERENABLED`, `RUNNER_SSL` and `RUNNER_DATADIR` environment variables and run the Executor using the `make run run_args="-f|--file <path>"` make command where `-f|--file <path>` argument is the path to the `execution.json` file you created in step 3.
    63      ```bash
    64      RUNNER_SCRAPPERENABLED=false RUNNER_SSL=false RUNNER_DATADIR="./data" make run run_args="-f temp/execution.json"
    65      ```
    66  
    67  #### Execution JSON
    68  
    69  Execution JSON stores information required for an Executor to run the configured tests.
    70  
    71  Breakdown of the Execution JSON:
    72  ```json
    73  {
    74     "args": ["-n", "-t", "test.jmx"],
    75     "variables": {
    76        "example": {
    77           "type": "basic", 
    78           "name": "example", 
    79           "value": "some-value"
    80       }
    81     },
    82     "content": {
    83        "type": "string"
    84     }
    85  }
    86  ```
    87  * **args** - array of strings which will be passed to JMeter as arguments
    88    * example: `["-n", "-t", "test.jmx"]`
    89  * **variables** - map of variables which will be passed to JMeter as arguments
    90    * example: `{"example": {"type": "basic", "name": "example", "value": "some-value"}}` 
    91  * **content.type** - used to specify that JMeter XML is provided as a text file
    92  
    93  #### Environment Variables
    94  ```bash
    95  RUNNER_SSL=false                  # used if storage backend is behind HTTPS, should be set to false for local development
    96  RUNNER_SCRAPPERENABLED=false      # used to enable/disable scrapper, should be set to false for local development
    97  RUNNER_DATADIR=<path-to-data-dir> # path to the data/ directory where JMeter will run and store results
    98  ```
    99  
   100  ## Testing in Kubernetes
   101  
   102  ### Prerequisites
   103  * Kubernetes cluster with Testkube installed (best practice is to install it in the `testkube` namespace)
   104  
   105  ### Guide
   106  
   107  After validating locally that the Executor changes work as expected, next step is to test whether Testkube can successfully schedule a Test using the new Executor image.
   108  
   109  NOTE: The following commands assume that Testkube is installed in the `testkube` namespace, if you have it installed in a different namespace, please adjust the `--namespace` flag accordingly.
   110  
   111  The following steps need to be executed in order for Testkube to use the new Executor image:
   112  1. Build the new Executor image using the `make docker-build-local` command. By default, the image will be tagged as `kubeshop/testkube-executor-jmeter:999.0.0` unless a `LOCAL_TAG` environment variable is provided before the command.
   113  2. Now you need to make the image accessible in Kubernetes, there are a couple of approaches:
   114     * *kind* - `kind load docker-image <image-name> --name <kind cluster name>` (e.g. `kind load docker-image testkube-executor-jmeter:999.0.0 --name testkube-k8s-cluster`)
   115     * *minikube* - `minikube image load <image-name> --profile <minikube profile>` (e.g. `minikube image load testkube-executor-jmeter:999.0.0 --profile k8s-cluster-test`)
   116     * *Docker Desktop* - just by building the image locally, it becomes accessible in the Docker Desktop Kubernetes cluster
   117     * *other* - you can push the image to a registry and then Testkube will pull it in Kubernetes (assuming it has credentials for it if needed)
   118  3. Edit the Job Template and change the `imagePullPolicy` to `IfNotPresent`
   119     * Edit the ConfigMap `testkube-api-server` either by running `kubectl edit configmap testkube-api-server --namespace testkube` or by using a tool like Monokle
   120     * Find the `job-template.yml` key and change the `imagePullPolicy` field in the `containers` section to `IfNotPresent`
   121  4. Edit the Executors configuration and change the base image to use the newly created image:
   122     * Edit the ConfigMap `testkube-api-server` either by running `kubectl edit configmap testkube-api-server --namespace testkube` or by using a tool like Monokle
   123     * Find the `executors.json` key and change the `executor.image` field to use the newly created image for the JMeter Executor (`name` field is `jmeter-executor`)
   124  5. Restart the API Server by running `kubectl rollout restart deployment testkube-api-server --namespace testkube`
   125  
   126  Testkube should now use the new image for the Executor and you can schedule a Test with your preferred method.