Distributed Load Testing Made Simple
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Build Status NPM version js-standard-style

An automation tool for scaling load tests using distributed slaves. Based on master-slave architecture where master acts as a test coordinator, from where tests are triggered and the actual tests are distributed across multiple hosts.


  • One or more linux hosts with docker (>=1.12.5) installed.
  • In one of the linux host install nodeJs (>=7) and autometer npm module. This node can be designated as master (from where tests has to be triggered).


npm install -g autometer 


$ autometer --help
    Usage: autometer <command>
    --version    Show version number                                     [boolean]
    --startTest  Start the test
    --stopTest   Stop the running test
    --logs       Display the running test logs
    --clear      Clear the test output files
    -?, --help   Show help                                               [boolean]
    autometer --startTest                   Start the test
    autometer --stopTest                    Stop the running test
    autometer --logs                        Tail the running test logs
    autometer --clear                       Remove the generated reports and logs
    export DOCKER_PORT=port                 To set docker port, default port 2376
    DOCKER_PORT=port autometer --startTest  To set docker port and start the test

Getting Started

Docker images setup:

  • Make sure you can access docker hub. Run the below command on all the hosts to pull the image

     docker pull autometer/jmeter-base 

Autometer setup and configuration:

  • Login to the host (designated as master) where node is installed and run the below command

      npm install -g autometer
  • Create a folder (say api-test) and following 3 files are needed to run a test

      1. autometer.config.js
      2. test.jmx
      3. global.properties
  1. autometer.config.js - File to configure autometer itself, you can define number of load generators. Typical config file is as shown below.

    Caution: If your running multiple tests, make sure you use different ports, otherwise it results in port conflicts

     const config = {
         testName: 'test.jmx',
         master: {
             host: 'hostname',
             resultsPort: 2099
         slaves: [
             {host: 'hostname', port: 1099, resultsPort: 2099},
             {host: 'hostname', port: 1199, resultsPort: 2199}
     module.exports = config;
  2. test.jmx - Your jmeter test file, make sure test name matches with autometer config testName variable.

  3. global.properties - externalized test properties

Test execution

  • Goto folder having 3 files and run below commands

      [To start a start]
      $ autometer --startTest
      [To tail running test logs]
      $ autometer --logs
      [To stop a running test]
      $ autometer --stopTest


What type of test execution is supported?

Only jmx tests is supported

How to create custom docker images?

Create a Dockerfile, sample file as mentioned below

FROM openjdk:8-jdk-alpine
ENV JMETER_HOME=/usr/local/apache-jmeter-${JMETER_VERSION}

RUN wget  http://archive.apache.org/dist/jmeter/binaries/apache-jmeter-${JMETER_VERSION}.tgz && \
  tar xf apache-jmeter-${JMETER_VERSION}.tgz -C /usr/local

RUN wget http://jmeter-plugins.org/downloads/file/JMeterPlugins-Standard-${JMETER_PLUGINS_VERSION}.zip && \
  unzip -o JMeterPlugins-Standard-${JMETER_PLUGINS_VERSION}.zip -d ${JMETER_HOME}

EXPOSE 2099-2999

ENTRYPOINT ["jmeter.sh"]

Build the docker image using below command

    docker build -t autometer/jmeter-base .

1. Expose ports for test communication and report consolidation
2. docker image tag should be autometer/jmeter-base

How to run multiple tests from master?

You can trigger any number of test runs from master. Create different folders and place the 3 files (config js, test file, global properties).Goto any of the test folder and trigger autometer commands.

How to configure ports?

  • Only docker exposed ports can used as "resultsPort" (2099-2999)
  • There is no restriction on the slave primary port, you can change it to any free port
  • By default, stick to 1099 (for the slave primary port) and 2099 for the resultsPort
  • Here is a sample configuration with 1 master and 5 slaves, all on the same linux host !
    const config = {
        testName: 'test.jmx',
        master: {
            host: 'hostname',
            resultsPort: 2099
        slaves: [
            {host: 'hostname', port: 1199, resultsPort: 2199},
            {host: 'hostname', port: 1299, resultsPort: 2299},
            {host: 'hostname', port: 1399, resultsPort: 2399},
            {host: 'hostname', port: 1499, resultsPort: 2499},
            {host: 'hostname', port: 1599, resultsPort: 2599}

    module.exports = config;

How to clean up docker containers in case of port conflicts?

  • Try autometer stopTest command
  • Run the below commands on all the hosts to clean up containers manually
    docker stop $(docker ps -aq)
    docker rm $(docker ps -aq)


See DEVELOPER.md for the instructions