AutoMeter

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.

Prerequisites

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).

Install

npm install -g autometer

Usage

$ autometer --help
    
    Usage: autometer <command>
    
    Options:
    --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]
    
    Examples:
    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
```

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;

test.jmx - Your jmeter test file, make sure test name matches with autometer config testName variable.
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

FAQs

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_VERSION 3.1
ENV JMETER_PLUGINS_VERSION=1.4.0
ENV JMETER_HOME=/usr/local/apache-jmeter-${JMETER_VERSION}
ENV PATH=${JMETER_HOME}/bin:${PATH}

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 .

Note:
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)

Contribute

See DEVELOPER.md for the instructions

Support

autometer.npm@gmail.com

intuit/autometer