# HyperTest Docs

# Intro

HyperTest is a cloud native solution for software testing. Using Hypertest, you'll eliminate the need to write or maintain tests.

# Prerequisites

Your system should have the following installed:

  • Docker (>= 20.10.6)
  • Docker-compose(>= 1.29.1) should be present on the platform.

# Installing Docker

Check if you have docker installed already by

docker -v

If you don’t have docker, install using the following command

curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh

If you have an older version (< 18.09.7), remove it and reinstall the latest version using above command

Add the current user to the docker group

sudo usermod -aG docker $USER

Test the installation using the following command

docker run hello-world

# Installing Docker Compose

Check if you have docker-compose installed already by

docker-compose -v

If you don’t have docker-compose, install using the following command

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose && sudo chmod +x /usr/local/bin/docker-compose && sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Replace 1.29.1 with the latest version

If you have an older version (< 1.29.1), remove it and reinstall the latest version using above command

Check if docker-compose installed successfully by this

docker-compose -v

# Getting Started

# Step 1 - download Hypertest

Create a new directory

mkdir -p /opt/hypertest_<name of your service>
cd /opt/hypertest_<name of your service>

Download Hypertest

wget -O ht-cli.tar.xz https://hypertest-binaries-1.s3.ap-south-1.amazonaws.com/ht-cli/ht-cli-latest.tar.xz
tar xvf ht-cli.tar.xz

# Step 2 - start Hypertest

# Start Hypertest and follow on-screen instructions

./hypertest start

# Set up a cron job to start Hypertest on reboot

  1. Open the file /etc/crontab using a text editor.

  2. Edit the path to hypertest binary and add the following entry to a new line.

    @reboot /opt/path/to/hypertest/binary bg-start >> /tmp/ht-cron-error.log 2>&1

# Open dashboard

Hypertest dashboard would be running on the port specified by you just now.

Open up your browser and go to http://your-ip/your-hostname:dashboard-port

# Step 3 - mirror traffic to Hypertest

# Using Nginx:

Mirror the traffic from your reverse proxy to Hypertest. For NGINX (>= 1.13.4), add the following in you site configuration

Sample nginx.conf
## copy this ##
upstream hypertest-service-logger {
    server <hypertest-vm-ip>:<hypertest-logger-port>;
## to this ##

server {
  ## listen 8000;
      location / {
        ## copy from this ##
        mirror /mirror;
        mirror_request_body on;
        ## to this ##
        ## proxy_pass http://localhost:3000;
    ## copy this ##
    location   = /mirror {
      if ($http_fromhypertest) {
          return 400 'mirror loop';
      proxy_connect_timeout 500ms;
      proxy_read_timeout 500ms;
      proxy_pass http://hypertest-service-logger$request_uri;
      proxy_set_header x-real-host $http_host;
      proxy_set_header x-forwarded-for $proxy_add_x_forwarded_for;
    ## to this

# Using GoReplay:

Download goreplay

wget -O gor.tar.gz https://github.com/buger/goreplay/releases/download/v0.16.1/gor_0.16.1_x64.tar.gz
tar xvf gor.tar.gz
sudo mv ./goreplay /usr/local/bin

To avoid typing in the absolute path to run the goreplay binary, copy it to /usr/local/bin. This document assumes the same.

You should run goreplay as a service using systemctl, monit, pm2 etc so that it restarts on boot or failures

# Run goreplay as a service using systemctl

  1. Create a bash script goreplay-<SERVICE_NAME>.sh, copy the following into it. Update the script as specified in the script itself.
#! /bin/sh

# Change these variables according to your deployment

process_count=$(pgrep -a -f -c ".--input-raw :$APPLICATION_PORT --output-http $HT_VM_IP:$HT_LOGGER_PORT")
process_names=$(pgrep -a -f ".--input-raw :$APPLICATION_PORT --output-http $HT_VM_IP:$HT_LOGGER_PORT")

if [ "$process_count" -gt 0 ]
    echo "At least one instance of same goreplay mirror is already working. Please verify if the custom instance works or kill it and the run script again."
    for process in "$process_names"; do
      echo "$process"
  echo "starting goreplay..."
  sudo goreplay --input-raw :$APPLICATION_PORT --output-http $HT_VM_IP:$HT_LOGGER_PORT --http-disallow-header "fromhypertest: y"
  1. Create a file /etc/systemd/system/goreplay-{SERVICE_NAME}.service

  2. Copy the following and paste it into the goreplay-{SERVICE_NAME} file created in step 2. Add the absolute path of the bash script you created in step 1.

Sample service file


  1. Save the file and run

    systemctl daemon-reload systemctl enable-<SERVICE_NAME> goreplay --now

# Using containers directly (via goreplay)

Update your application's Dockerfile as per below example or create a new one

Example Dockerfile
FROM node:10-alpine
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .
#CMD ["npm", "start"]

## copy this ##
# add next line only for alpine-based images
RUN apk add --no-cache ca-certificates openssl
RUN wget https://github.com/buger/goreplay/releases/download/v0.16.1/gor_0.16.1_x64.tar.gz -O gor.tar.gz
RUN tar xzf gor.tar.gz
CMD [ "sh", "-c", "./goreplay --input-raw :<your-application-port> --output-http <hypertest-vm-ip>:<hypertest-logger-port> & npm start" ]
## to this

# Using Apache

If you're receiving SSL traffic on apache, configure a new virtual host. Your original port would now be used to terminate SSL and forward traffic to the new virtual host. We can now mirror traffic from the new Virtual Host using goreplay.

If unencrypted traffic is being received, directly use goreplay.

Use the example below to create a new virtual host on NEW_NON_SSL_PORT, which you can use to mirror traffic to Hypertest.

Old Apache Config:


<VirtualHost *:OLD_SSL_PORT>
    ## ssl related config ##
    ProxyPreserveHost On

    ProxyPass / http://localhost:OLD_APP_PORT>
    ProxyPassReverse / http://localhost:OLD_APP_PORT>

New Apache Config:


<VirtualHost *:OLD_SSL_PORT>
    ## ssl related config ##
    ProxyPreserveHost On

    ProxyPass / http://localhost:NEW_NON_SSL_PORT>
    ProxyPassReverse / http://localhost:NEW_NON_SSL_PORT>

<VirtualHost *:NEW_NON_SSL_PORT>
    ProxyPreserveHost On

    ProxyPass / http://localhost:OLD_APP_PORT>
    ProxyPassReverse / http://localhost:OLD_APP_PORT>


# Using HAproxy:

Coming soon...

# Using Envoy:

Coming soon...