/~\
  ______       C oo
  | ___ \      _( ^)
  | |_/ /__  _/__ ~\ __   ___
  |  __/ _ \| '_ \ / _` |/ _ \
  | | | (_) | | | | (_| | (_) |
  \_|  \___/|_| |_|\__, |\___/
                    __/ |
                   |___/

Usage: pongo action [options...] [--] [action options...]

Options:
  --no-cassandra     do not start cassandra db
  --no-postgres      do not start postgres db
  --redis            do start redis db

Actions:
  up            start required dependency containers for testing

  build         build the Kong test image

  run           run spec files, accepts Busted options and spec files/folders
                as arguments, see: 'pongo run -- --help'

  tail          starts a tail on the specified file. Default file is
                ./servroot/logs/error.log, an alternate file can be specified

  shell         get a shell directly on a kong container

  down          remove all dependency containers

  clean         removes the dependency containers and deletes all test images

  update        update embedded artifacts for building test images

Environment variables:
  KONG_VERSION  the specific Kong version to use when building the test image

  KONG_IMAGE    the base Kong Docker image to use when building the test image

  KONG_LICENSE_DATA
                set this variable with the Kong Enterprise license data

  POSTGRES      the version of the Postgres dependency to use (default 9.5)
  CASSANDRA     the version of the Cassandra dependency to use (default 3.9)
  REDIS         the version of the Redis dependency to use (default 5.0.4)

Example usage:
  pongo run
  KONG_VERSION=0.36-1 pongo run -v -o gtest ./spec/02-access_spec.lua
  POSTGRES=9.4 KONG_IMAGE=kong-ee pongo run
  pongo down

Pongo provides a simple way of testing Kong plugins

Set up the following when testing against Kong Enterprise:

• Have the Kong Enterprise license key, and set it in KONG_LICENSE_DATA.
• Have a docker image of Kong Enterprise, and set the image name in the environment variable KONG_IMAGE, or alternatively log in to Bintray before running Pongo.

Clone the repository and install Pongo:

PATH=$PATH:~/.local/bin
git clone [email protected]:Kong/kong-pongo.git
mkdir -p ~/.local/bin
ln -s $(realpath kong-pongo/pongo.sh) ~/.local/bin/pongo

Notes:

• you need ~/.local/bin on your $PATH
• for MacOS you need the coreutils to be installed. This is easiest via the Homebrew package manager by doing:

  brew install coreutils
  

Get a shell into your plugin repository, and run pongo, for example:

git clone [email protected]:Kong/kong-plugin.git
cd kong-plugin

# auto pull and build the test images
pongo run ./spec

# Run against a specific version of Kong (log into bintray first!) and pass
# a number of Busted options
KONG_VERSION=0.36-1 pongo run -v -o gtest ./spec

# Run against a local image of Kong
KONG_IMAGE=kong-ee pongo run ./spec

The above command (pongo run) will automatically build the test image and start the test environment. When done, the test environment can be torn down by:

pongo down

When running the tests, the Kong prefix (or working directory) will be set to ./servroot.

To track the error log (where any print or ngx.log statements will go) you can use the tail command

pongo tail

The above would be identical to:

tail -F ./servroot/logs/error.log

By default when the test container is started, it will look for a .rockspec file, if it find one, then it will install that rockspec file with the --deps-only flag. Meaning it will not install that rock itself, but if it depends on any external libraries, those rocks will be installed.

For example; the Kong plugin session relies on the lua-resty-session rock. So by default it will install that dependency before starting the tests.

An alternate way is to provide a .pongo-setup.sh file. If that file is present then that file will be executed (using source), instead of the default behaviour.

For example, the following .pongo-setup.sh file will install a specific development branch of lua-resty-session instead of the one specified in the rockspec:

# remove any existing version if installed
luarocks remove lua-resty-session --force

git clone https://github.com/Tieske/lua-resty-session
cd lua-resty-session

# now checkout and install the development branch
git checkout redis-ssl
luarocks make

cd ..
rm -rf lua-resty-session

When new Kong versions are released, the test artifacts contained within this repository must be updated. Do so as follows:

1. clone this repo and checkout a new branch:

   git clone http:https://github.com/Kong/kong-pongo.git
   cd kong-pongo
   git checkout -b newrelease

2. update assets/set_variables.sh and add the new versions
3. commit the change with message:

   feat(version) added <Enterprise|open source> version <x.x>

4. update the artifacts

   pongo update

5. commit the change with message:

   chore(version) added <Enterprise|open source> version <x.x> artifacts

   git add kong-versions/
   git commit

6. test the changes:

   git clone http:https://github.com/Kong/kong-plugin.git
   cd kong-plugin
   KONG_VERSION=<x.x> pongo run
   rm -rf kong-plugin

7. push the branch and create a PR.