# 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 v1

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 v1 version. v2 is not supported as of now.

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

# Set up a cron job to start Hypertest on reboot

  1. run sudo crontab -e

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

    @reboot cd /opt/hypertest_<name of your service> && ./hypertest bg-start >> /tmp/ht-cron-error.log 2>&1

# Start Hypertest and follow on-screen instructions

./hypertest start

# 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 {
      internal;
      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.
`goreplay-{SERVICE_NAME}.sh`
#! /bin/sh

# Change these variables according to your deployment
APPLICATION_PORT=8001
HT_VM_IP=localhost
HT_LOGGER_PORT=10005

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 ]
  then
    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"
    done
else
  echo "starting goreplay..."
  sudo goreplay --input-raw :$APPLICATION_PORT --output-http $HT_VM_IP:$HT_LOGGER_PORT --http-disallow-header "fromhypertest: y"
fi
  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
    [Unit]
    Description=goreplay
    After=network.target
    StartLimitIntervalSec=0

    [Service]
    Type=simple
    Restart=always
    RestartSec=1
    ExecStart=<ABSOLUTE_PATH_OF_THE_BASH_SCRIPT>

    [Install]
    WantedBy=multi-user.target
  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 . .
ENV HYPER_TEST_BRANCH candidate
EXPOSE 3001
#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:
Listen OLD_SSL_PORT

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

    ProxyPass / http://localhost:OLD_APP_PORT>
    ProxyPassReverse / http://localhost:OLD_APP_PORT>
</VirtualHost>
New Apache Config:
Listen OLD_SSL_PORT
Listen NEW_NON_SSL_PORT

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

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

<VirtualHost *:NEW_NON_SSL_PORT>
    ProxyPreserveHost On

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

</VirtualHost>

# Using HAproxy:

Coming soon...

# Using Envoy:

Coming soon...

# Step 4 - CI integration

Hypertest CLI can also be used to start a test from your CI plugin.

simply load the cli Note: you should add this as a cachable step in you CI tool.

# Download hypertest CLI (same as done in step 1)

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

# set env variable HT_BASE_URL in your CI job

HT_BASE_URL=http://hypertest-ip-or-hostname:dashboard-port

HT_BASE_URL is the location of your hypertest dashboard. You can also export HT_BASE_URL directly in the command as well. Example: HT_BASE_URL=http://1.2.3.4:5678 ./hypertest can-run-test

# Check if hypertest can run a test (optional)

HT_BASE_URL=http://1.2.3.4:5678 ./hypertest can-run-test

# start a new test

HT_BASE_URL=http://1.2.3.4:5678 ./hypertest start-new-test --wait-for-result

# cli options

help can be shown for all commands with the -h option

./hypertest can-run-test --help
./hypertest can-run-test --help

Usage: hypertest can-run-test [options]

checks if a new test can be started on hypertest. Using --poll will check until a new test can be started

Options:
--poll                                       polls hypertest until a new test can be started (default: false)
--interval <interval>                        poll interval in seconds (default 60) (default: 60)
--time-limit <time-limit-in-seconds>         max duration to wait for execution (default 3600) (default: 3600)
--git-dir <path/conatinting/.git/directory>  useful to obtain branch name. (Default = current working directory)
-h, --help                                   display help for command
./hypertest start-new-test --help
./hypertest start-new-test --help

Usage: hypertest start-new-test [options]

starts a new test on hypertest

Options:
-d, --delay <delay-time-in-seconds>          delay in seconds to wait before starting a new test (default: 0)
-p, --primary <primary-base-url>             base url for stable(primary) version
-c, --candidate <candidate-base-url>         base url for test(candidate) version
-i, --initial-timestamp <initial-timestamp>  traffic would be considered from here. (calculated from test_window by default) (Should be parsable by new Date(val) in javascript)
-f, --final-timestamp <final-timestamp>      traffic would be considered until here. (current time by default) (Should be parsable by new Date(val) in javascript)
--no-stop-running-tests                      dont start a suite if one is already running. (default: terminates old and starts new)
--stop-on-first-failure                      stops test execution on first failure (default: complete entire test execution) (default: false)
--smoke-only                                 only run test cases saved as smoke tests (default: false)
--saved-only                                 only run saved test cases (default: false)
--play-duplicate-requests                    run duplicate requests within a session (default: false)
--play-duplicate-sessions                    run duplicate sessions (default: false)
--description <description>                  test case description
--interval <interval>                        poll interval in seconds (default 60) (default: 60)
--skip-wait-for-old-tests                    does not wait for old running tests to complete. Running tests terminated by default or program fails if --no-stop-running-tests is passed
(default: false)
--wait-for-result                            wait for test to complete (just starts the test by default) (default: false)
--git-dir <path/conatinting/.git/directory>  useful to obtain branch name. (Default = current working directory)
--time-limit <time-limit-in-seconds>         max duration to wait for execution (default 3600) (default: 3600)
-h, --help                                   display help for command