{"id":20840362,"url":"https://github.com/kong/kong-pongo","last_synced_at":"2025-04-12T21:31:30.476Z","repository":{"id":37759317,"uuid":"204032943","full_name":"Kong/kong-pongo","owner":"Kong","description":"Tooling to run plugin tests with Kong and Kong Enterprise","archived":false,"fork":false,"pushed_at":"2025-04-11T06:28:05.000Z","size":5596,"stargazers_count":160,"open_issues_count":21,"forks_count":57,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-04-11T08:31:56.152Z","etag":null,"topics":["kong","kong-enterprise","kong-plugin"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kong.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-08-23T16:20:07.000Z","updated_at":"2025-04-11T06:28:09.000Z","dependencies_parsed_at":"2023-02-02T04:31:33.748Z","dependency_job_id":"d74332ec-7f60-4d57-9b68-43b461c85c19","html_url":"https://github.com/Kong/kong-pongo","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Fkong-pongo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Fkong-pongo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Fkong-pongo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Fkong-pongo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kong","download_url":"https://codeload.github.com/Kong/kong-pongo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248634974,"owners_count":21137152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kong","kong-enterprise","kong-plugin"],"created_at":"2024-11-18T01:16:05.409Z","updated_at":"2025-04-12T21:31:25.460Z","avatar_url":"https://github.com/Kong.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Unix Tests](https://img.shields.io/github/actions/workflow/status/Kong/kong-pongo/test.yml?branch=master\u0026label=Unix%20tests\u0026logo=linux)](https://github.com/Kong/kong-pongo/actions/workflows/test.yml)\n[![Docker Tests](https://img.shields.io/github/actions/workflow/status/Kong/kong-pongo/test.yml?branch=master\u0026label=Docker%20tests\u0026logo=docker)](https://github.com/Kong/kong-pongo/actions/workflows/docker.yml)\n[![Lint](https://github.com/Kong/kong-pongo/workflows/Lint/badge.svg)](https://github.com/Kong/kong-pongo/actions/workflows/lint.yml)\n[![SemVer](https://img.shields.io/github/v/tag/Kong/kong-pongo?color=brightgreen\u0026label=SemVer\u0026logo=semver\u0026sort=semver)](CHANGELOG.md)\n\n# pongo\n\nPongo provides a simple way of testing Kong plugins. For a complete walkthrough\ncheck [this blogpost on the Kong website](https://konghq.com/blog/custom-lua-plugin-kong-gateway).\n\n\n```\n                /~\\\n  ______       C oo\n  | ___ \\      _( ^)\n  | |_/ /__  _/__ ~\\ __   ___\n  |  __/ _ \\| '_ \\ / _ `|/ _ \\\n  | | | (_) | | | | (_| | (_) |\n  \\_|  \\___/|_| |_|\\__, |\\___/\n                    __/ |\n                   |___/  v2.16.0\n\nUsage: pongo action [options...] [--] [action options...]\n\nOptions (can also be added to '.pongo/pongorc'):\n  --no-postgres      do not start postgres db\n  --cassandra        do start cassandra db\n  --grpcbin          do start grpcbin (see readme for info)\n  --redis            do start redis db (see readme for info)\n  --squid            do start squid forward-proxy (see readme for info)\n\nProject actions:\n  init          initializes the current plugin directory with some default\n                configuration files if not already there (not required)\n\n  lint          will run the LuaCheck linter\n\n  pack          will pack all '*.rockspec' files into '*.rock' files for\n                distribution (see LuaRocks package manager docs)\n\n  run           run spec files, accepts Busted options and spec files/folders\n                as arguments, see: 'pongo run -- --help'\n\n  shell         get a shell directly on a kong container\n\n  tail          starts a tail on the specified file. Default file is\n                ./servroot/logs/error.log, an alternate file can be specified\n\nEnvironment actions:\n  build         build the Kong test image, add '--force' to rebuild images\n\n  clean / nuke  removes the dependency containers and deletes all test images\n\n  docs          will generate and open the test-helper documentation\n\n  down          remove all dependency containers\n\n  expose        expose the internal ports for access from the host\n\n  logs          show docker-compose logs of the Pongo environment\n\n  restart       shortcut, a combination of; down + up\n\n  status        show status of the Pongo network, images, and containers\n\n  up            start required dependency containers for testing\n\nMaintenance actions:\n  update        update embedded artifacts for building test images\n\n\nEnvironment variables:\n  KONG_VERSION  the specific Kong version to use when building the test image\n                (note that the patch-version can be 'x' to use latest)\n\n  KONG_IMAGE    the base Kong Docker image to use when building the test image\n\n  KONG_LICENSE_DATA\n                set this variable with the Kong Enterprise license data\n\n  POSTGRES      the version of the Postgres dependency to use (default 9.5)\n  CASSANDRA     the version of the Cassandra dependency to use (default 3.11)\n  REDIS         the version of the Redis dependency to use (default 6.2.6)\n\nExample usage:\n  pongo run\n  KONG_VERSION=3.3.x pongo run -v -o gtest ./spec/02-access_spec.lua\n  POSTGRES=10 KONG_IMAGE=kong-ee pongo run\n  pongo down\n```\n\n## Table of contents\n\n - [Requirements](#requirements)\n - [Installation](#installation)\n - [Update](#update)\n - [Configuration](#configuration)\n - [Do a test run](#do-a-test-run)\n - [Pongo on Windows](#pongo-on-windows)\n - [Test dependencies](#test-dependencies)\n    - Postgres (Kong datastore)\n    - Cassandra (Kong datastore)\n    - grpcbin (mock grpc backend)\n    - Redis (key-value store)\n    - Squid (forward-proxy)\n    - [Dependency defaults](#dependency-defaults)\n    - [Dependency troubleshooting](#dependency-troubleshooting)\n    - [Custom local dependencies](#custom-local-dependencies)\n - [Debugging](#debugging)\n     - [Accessing the logs](#accessing-the-logs)\n     - [Direct access to service ports](#direct-access-to-service-ports)\n - [Test initialization](#test-initialization)\n - [Test coverage](#test-coverage)\n - [Setting up CI](#setting-up-ci)\n - [Running Pongo in Docker](#running-pongo-in-docker)\n - [Releasing new Kong versions](#releasing-new-kong-versions)\n - [Changelog](CHANGELOG.md)\n\n## Requirements\n\nTools Pongo needs to run:\n* `docker-compose` (and hence `docker`)\n* `curl`\n* `realpath`, for older MacOS versions you need the [`coreutils`](https://www.gnu.org/software/coreutils/coreutils.html)\n  to be installed. This is easiest via the [Homebrew package manager](https://brew.sh/) by doing:\n  ```\n  brew install coreutils\n  ```\n* depending on your environment you should set some [environment variables](#configuration).\n\n[Back to ToC](#table-of-contents)\n\n## Installation\n\nClone the repository and install Pongo:\n```shell\nPATH=$PATH:~/.local/bin\ngit clone https://github.com/Kong/kong-pongo.git\nmkdir -p ~/.local/bin\nln -s $(realpath kong-pongo/pongo.sh) ~/.local/bin/pongo\n```\n### Proxies\n\nWhen Pongo builds images, it might fail when it is behind proxies and cannot verify the certificates. See [configuration](#configuration)\non how to disable verification.\n\n## Update\n\nSince the Pongo script is symbolic linked to `~/.local/bin/pongo`, in order to update Pongo, all you have to do is to fetch latest changes from the Pongo repo:\n\n```\ncd \u003ccloned Pongo repo\u003e\ngit pull\n\n# checkout the latest version tag (checkout 'master' for bleeding edge)\ngit checkout $(git tag | sort --version-sort | tail -n 1)\n```\n\n[Back to ToC](#table-of-contents)\n\n## Configuration\n\nSeveral environment variables are available for configuration:\n\n* Docker credentials; `DOCKER_USERNAME` and `DOCKER_PASSWORD` to prevent rate-\n  limits when pulling images.\n* Kong license; set `KONG_LICENSE_DATA` with the Enterprise license to enable\n  Enterprise features.\n* Specify a custom image; set the image name/tag in `KONG_IMAGE` and make sure\n  the image is locally available\n* When the variable `PONGO_INSECURE` is set to anything else than `'false'`, it\n  will configure curl and git (during the build) to switch off ssl verification.\n  Please ensure you understand the security consequences when using this option!\n  See also `pongo build --help`.\n\nFor Kong-internal use there are some additional variables:\n\n* `GITHUB_TOKEN` the Github token to get access to the Kong Enterprise source\n  code. This is only required for development builds, not for released\n  versions of Kong.\n\n[Back to ToC](#table-of-contents)\n\n## Do a test run\n\nGet a shell into your plugin repository, and run `pongo`, for example:\n\n```shell\ngit clone https://github.com/Kong/kong-plugin.git\ncd kong-plugin\n\n# auto pull and build the test images\npongo run\n```\n\nSome more elaborate examples:\n\n```shell\n# Run against a specific version of Kong and pass\n# a number of Busted options\nKONG_VERSION=3.2.2 pongo run -- -v -o gtest ./spec\n\n# Run against the latest patch version of a Kong release using '.x'\nKONG_VERSION=3.4.x pongo run\n\n# Run against the latest stable version, using special label 'stable'\n# (available labels are: 'stable', 'stable-ee', 'dev', and 'dev-ee')\nKONG_VERSION=stable pongo run\n\n# Run against a local image of Kong\nKONG_IMAGE=kong-ee pongo run ./spec\n```\n\nThe above command (`pongo run`) will automatically build the test image and\nstart the test environment. When done, the test environment can be torn down by:\n\n```shell\npongo down\n```\n\n[Back to ToC](#table-of-contents)\n\n## Pongo on Windows\n\nPongo should run in Git-BASH if you have [Git for Windows](https://gitforwindows.org/)\ninstalled (and Docker for Windows).\n\n### using WSL2\n\nAn alternative to run Pongo on Windows is [WSL2](https://docs.microsoft.com/windows/wsl/)\n(Windows Subsystem for Linux).\n\n* install WSL2\n* install Docker for Windows\n* from the Microsoft Store install Debian (search for `Debian`)\n* start Debian (should be in your start menu)\n* now from the prompt install Pongo and some dependencies;\n\n      sudo apt update\n      sudo apt install git curl coreutils\n\n      cd ~\n      git clone https://github.com/Kong/kong-pongo.git\n      mkdir -p ~/.local/bin\n      ln -s $(realpath kong-pongo/pongo.sh) ~/.local/bin/pongo\n      PATH=$PATH:~/.local/bin\n\n* Open Docker for Windows and open the settings\n* under \"General\" enable using the WSL2 engine\n* under \"Resources - WSL integration\" enable integration with the Debian package\n\nYou can now edit your code with your favorite Windows IDE or editor and then run\nthe tests with Pongo.\n\nTo give this a try using the template plugin;\n\n* download or clone `https://github.com/Kong/kong-plugin.git` (assuming this to\n  land in `C:\\users\\tieske\\code\\kong-plugin`)\n* start Debian and at the prompt do:\n\n      cd /mnt/c/users/tieske/code/kong-plugin\n      pongo run\n\n\n[Back to ToC](#table-of-contents)\n\n## Test dependencies\n\nPongo can use a set of test dependencies that can be used to test against. Each\ncan be enabled/disabled by respectively specifying `--[dependency_name]` or\n`--no-[dependency-name]` as options for the `pongo up`, `pongo restart`, and\n`pongo run` commands. The alternate way of specifying the dependencies is\nby adding them to the `.pongo/pongorc` file (see below).\n\nThe available dependencies are:\n\n* **Postgres** Kong datastore (started by default)\n  - Disable it with `--no-postgres`\n  - The Postgres version is controlled by the `POSTGRES` environment variable\n\n* **Cassandra** Kong datastore\n  - Enable it with `--cassandra`\n  - The Cassandra version is controlled by the `CASSANDRA` environment variable\n\n* **grpcbin** mock grpc backend\n  - Enable it with `--grpcbin`\n  - The engine is [moul/grpcbin](https://github.com/moul/grpcbin)\n  - From within the environment it is available at:\n      * `grpcbin:9000` grpc over http\n      * `grpcbin:9001` grpc over http+tls\n\n* **Redis** key-value store\n  - Enable it with `--redis`\n  - The Redis version is controlled by the `REDIS` environment variable\n  - From within the environment the Redis instance is available at `redis:6379`,\n    but from the test specs it should be accessed by using the `helpers.redis_host`\n    field, and port `6379`, to keep it portable to other test environments. Example:\n    ```shell\n    local helpers = require \"spec.helpers\"\n    local redis_host = helpers.redis_host\n    local redis_port = 6379\n    ```\n\n* **Squid** (forward-proxy)\n  - Enable it with `--squid`\n  - The Squid version is controlled by the `SQUID` environment variable\n  - From within the environment the Squid instance is available at `squid:3128`.\n    Essentially it would be configured as these standard environment variables:\n\n    - `http_proxy=http://squid:3128/`\n    - `https_proxy=http://squid:3128/`\n\n    The configuration comes with basic-auth configuration, and a single user:\n\n    - username: `kong`\n    - password: `king`\n\n    All access is to be authenticated by the proxy, except for the domain `.mockbin.org`,\n    which is white-listed.\n\n    Some test instructions to play with the proxy:\n    ```shell\n    # clean environment, start with squid and create a shell\n    pongo down\n    pongo up --squid --no-postgres\n    pongo shell\n\n    # connect to httpbin (http), while authenticating\n    http --proxy=http:http://kong:king@squid:3128 --proxy=https:http://kong:king@squid:3128 http://httpbin.org/anything\n\n    # https also works\n    http --proxy=http:http://kong:king@squid:3128 --proxy=https:http://kong:king@squid:3128 https://httpbin.org/anything\n\n    # connect unauthenticated to the whitelisted mockbin.org (http)\n    http --proxy=http:http://squid:3128 --proxy=https:http://squid:3128 http://mockbin.org/request\n\n    # and here https also works\n    http --proxy=http:http://squid:3128 --proxy=https:http://squid:3128 https://mockbin.org/request\n    ```\n\n[Back to ToC](#table-of-contents)\n\n### Dependency defaults\n\nThe defaults do not make sense for every type of plugin and some dependencies\n(Cassandra for example) can slow down the tests. So to override the defaults on\na per project/plugin basis, a `.pongo/pongorc` file can be added\nto the project.\n\nThe format of the file is very simple; each line contains 1 commandline option, eg.\na `.pongo/pongorc` file for a plugin that only needs Postgres and Redis:\n\n  ```shell\n  --no-cassandra\n  --redis\n  ```\n\n[Back to ToC](#table-of-contents)\n\n### Disable Service Health Checks\n\nWhen unable to leverage container health checks, they can be disabled setting the environment variable `HEALTH_TIMEOUT=0`.\nThis will set the variable `SERVICE_DISABLE_HEALTHCHECK=true`, which can be used to disable the service health checks for\nthe Pongo services in the docker composer files.\n\nFor example:\n```\n    healthcheck:\n      test:\n      - CMD\n      - pg_isready\n      - --dbname=kong_tests\n      - --username=kong\n      disable: ${SERVICE_DISABLE_HEALTHCHECK:-false}\n```\nTo wait for the environment and run the tests one could run\n```\nexport HEALTH_TIMEOUT=0\npongo up \u0026\u0026 sleep 10 \u0026\u0026 pongo run\n```\n\n### Dependency troubleshooting\n\nWhen dependency containers are causing trouble, the logs can be accessed using\nthe `pongo logs` command. This command is the same as `docker-compose logs` except\nthat it operates on the Pongo environment specifically. Any additional options\nspecified to the command will be passed to the underlying `docker-compose logs`\ncommand.\n\nSome examples:\n```shell\n# show latest logs\npongo logs\n\n# tail latest logs\npongo logs -f\n\n# tail latest logs for the postgres dependency\npongo logs -f postgres\n```\n\n[Back to ToC](#table-of-contents)\n\n### Custom local dependencies\n\nIf the included dependencies are not enough for testing a plugin, then Pongo allows\nyou to specify your own dependencies.\nTo create a custom local dependency you must add its name to the `.pongo/pongorc` file\nAn example defining 2 extra dependencies; `zipkin`, and `myservice`:\n\n  ```shell\n  --no-cassandra\n  --redis\n  --zipkin\n  --no-myservice\n  ```\n\nThis defines both services, with `zipkin` being started by default and `myservice`\nonly when specifying it like this;\n\n  ```\n  pongo up --myservice\n  ```\n\nThis only defines the dependency, but it also needs a configuration. The\nconfiguration is a `docker-compose` file specific for each dependency. So taking\nthe above `zipkin` example we create a file named `.pongo/zipkin.yml`.\n\n  ```yml\n  version: '3.5'\n\n  services:\n    zipkin:\n      image: openzipkin/zipkin:${ZIPKIN:-2.19}\n      healthcheck:\n        interval: 5s\n        retries: 10\n        test:\n        - CMD\n        - wget\n        - localhost:9411/health\n        timeout: 10s\n        disable: ${SERVICE_DISABLE_HEALTHCHECK:-false}\n      restart: on-failure\n      stop_signal: SIGKILL\n      networks:\n        - ${NETWORK_NAME}\n  ```\n\nThe components of the file:\n\n  - file name: based on the dependency name; `./pongo/\u003cdep-name\u003e.yml`\n  - service name: this must be the dependency name as defined, in this case `zipkin`\n  - `image` is required, the environment variable `ZIPKIN` to override the default\n    version `2.19` is optional\n  - `healthcheck` if available then Pongo uses the health-status to determine\n    whether a dependency is ready and the test run can be started.\n  - `networks` should be included and left as-is to include the dependency in the\n    network with the other containers.\n\nSome helpfull examples:\n  - Dependencies requiring configuration files: see `squid` in the main [Pongo\n    docker-compose file](https://github.com/Kong/kong-pongo/blob/master/assets/docker-compose.yml).\n  - A custom dependency example: see the [Zipkin plugin](https://github.com/Kong/kong-plugin-zipkin)\n\n[Back to ToC](#table-of-contents)\n\n## Debugging\n\nThis section is about debugging plugin code. If you have trouble with the Pongo\nenvironment then check [Dependency troubleshooting](#dependency-troubleshooting).\n\n### Accessing the logs\n\nWhen running the tests, the Kong prefix (or working directory) will be set to\n`./servroot`.\n\nTo track the error log (where any `print` or `ngx.log` statements will go) you\ncan use the tail command\n\n```shell\npongo tail\n```\n\nThe above would be identical to:\n\n```shell\ntail -F ./servroot/logs/error.log\n```\n\nThe above does not work in a CI environment. So how to get access to the logs in\nthat case?\n\nFrom the default `.travis.yml` (see [chapter on CI](#setting-up-ci)), change the\nbasic lines to run the commands as follows, from;\n\n    script:\n    - \"../kong-pongo/pongo.sh lint\"\n    - \"../kong-pongo/pongo.sh run\"\n\nto;\n\n    script:\n    - \"../kong-pongo/pongo.sh lint\"\n    - \"KONG_TEST_DONT_CLEAN=true ../kong-pongo/pongo.sh run\"\n    - \"cat servroot/logs/error.log\"\n\nSetting the `KONG_TEST_DONT_CLEAN` variable will instruct Kong to not clean up\nthe working directory in between tests. And the final `cat` command will output\nthe log to the Travis console.\n\n[Back to ToC](#table-of-contents)\n\n### Direct access to service ports\n\nTo directly access Kong from the host, or the datastores, the `pongo expose`\ncommand can be used to expose the internal ports to the host.\n\nThis allows for example to connect to Postgres on port `5432` to validate\nthe contents of the database. Or when running `pongo shell` to manually\nstart Kong, you can access all the regular Kong ports from the host, including\nthe GUI's.\n\nThis has been implemented as a separate container that opens all those ports and\nrelays them on the docker network to the actual service containers (the reason\nfor this is that regular Pongo runs do not interfere with ports already in use\non the host, only if `expose` is used there is a risk of failure because ports\nare already in use on the host)\n\nSince it is technically a \"dependency\" it can be specified as a dependency as\nwell.\n\nso\n```shell\npongo up\npongo expose\n```\nis equivalent to\n```shell\npongo up --expose\n```\n\nSee `pongo expose --help` for the ports.\n\n[Back to ToC](#table-of-contents)\n\n\n## Test initialization\n\nBy default when the test container is started, it will look for a `.rockspec`\nfile, if it finds one, then it will install that rockspec file with the\n`--deps-only` flag. Meaning it will not install that rock itself, but if it\ndepends on any external libraries, those rocks will be installed. If the rock\nis already installed in the image, it will be uninstalled first.\n\nFor example; the Kong plugin `session` relies on the `lua-resty-session` rock.\nSo by default it will install that dependency before starting the tests.\n\nTo modify the default behaviour there are 2 scripts that can be hooked up:\n\n* `.pongo/pongo-setup-host.sh` this script will be executed (not sourced) right\n  before the Kong test container is started. Hence this script runs **on the host**.\n  The interpreter can be set using the regular shebang.\n\n* `.pongo/pongo-setup.sh` is ran upon container start **inside** the Kong\n  container. It will not be executed but sourced, and will run on `/bin/bash` as\n  interpreter.\n\nBoth scripts will have an environment variable `PONGO_COMMAND` that will have\nthe current command being executed, for example `shell` or `run`.\n\nBelow an example using both files. On the host it clones a dependency if it\nisn't available already. This prevents pulling it on each run, but makes sure it\nis available in CI. Then on each run it will install the dependency in the\ncontainer first and then it will do the default action of installing all\nrockspecs found.\n\nExample `.pongo/pongo-setup-host.sh`:\n```shell\n#!/usr/bin/env bash\n\n# this runs on the host, before the Kong container is started\nif [ ! -d \"my_dependency\" ]; then\n  git clone https://github.com/memyselfandi/my_dependency.git\nfi\n```\n\nExample `.pongo/pongo-setup.sh`:\n```shell\n#!/usr/bin/env bash\n\n# this runs in the test container upon starting it\ncd /kong-plugin/my_dependency\nmake install\n\n# additionally run the default action of installing rockspec dependencies\n/pongo/default-pongo-setup.sh\n```\n\n[Back to ToC](#table-of-contents)\n\n## Test coverage\n\nPongo has support for the LuaCov code coverage tool. But this is rather limited.\nLuaCov is not able to run in OpenResty, hence it will not report on integration\ntests, only on unit tests.\n\nTo enable LuaCov, run `pongo init` to create the `.luacov` configuration file, and\nthen run the tests using the Busted `--coverage` option like this:\n\n```shell\npongo run -- --coverage\n```\n\nAfter the test run the output files `luacov.*.out` files should be available.\n\n[Back to ToC](#table-of-contents)\n\n## Setting up CI\n\nPongo is easily added to a CI setup. The examples below will assume Github Actions, but\ncan be easily converted to other engines.\n\n* For Github the best option is to use [the Pongo Github Action](https://github.com/Kong/kong-pongo-action)\n* if your engine of preference runs itself in Docker, then checkout [Pongo in Docker](#running-pongo-in-docker).\n* to test against development images add a job with `KONG_VERSION=dev`,\n\n**Note:** there is also a \"`dev-ee`\" for Kong Enterprise. But this requires a GitHub access token to\nfetch the Kong Enterprise source code, and must be specified as a `GITHUB_TOKEN` environment variable.\n\nHere's a base setup for a plugin that will test against multiple Kong versions:\n```yaml\n# .github/workflows/test.yml\n\nname: \"Test\"\n\nconcurrency:\n  group: ${{ github.workflow }} ${{ github.ref }}\n  cancel-in-progress: ${{ github.event_name == 'pull_request' }}\n\non:\n  pull_request: {}\n  push:\n    branches:\n    - master\n  schedule:\n  - cron: '0 0 * * *'  # every day at midnight, to test against development\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n\n    strategy:\n      fail-fast: false\n      matrix:\n        kongVersion:\n        - \"2.8.x\"\n        - \"3.5.x\"\n        - \"dev\"\n        - \"3.5.x.x\"\n        #- \"dev-ee\"    # Kong internal only, requires access to source code\n\n    steps:\n    - uses: actions/checkout@v3\n\n    - uses: Kong/kong-pongo-action@v1\n      with:\n        pongo_version: master\n        kong_version: ${{ matrix.kongVersion }}\n        # Kong internal users can use the Kong/kong-license action to get the license\n        license: ${{ secrets.KONG_LICENSE_DATA }}\n\n    - run: pongo run\n\n```\n\n[Back to ToC](#table-of-contents)\n\n\n## Running Pongo in Docker\n\nPongo relies on Docker and Docker-compose to recreate environments and test\nsetups. So what if your environment is running Pongo itself in a Docker\ncontainer?\n\n[Docker-in-Docker has some serious issues when used in CI](http://jpetazzo.github.io/2015/09/03/do-not-use-docker-in-docker-for-ci/)\n(as it was intended for Docker development only).\nThe proposed solution in that blog post actually works with Pongo. By starting\nthe container running Pongo with the\n\n    -v /var/run/docker.sock:/var/run/docker.sock\n\noption, the container will get control over the Docker deamon on the host. The\nmeans that the test environment spun up by Pongo will not run inside the Pongo\ncontainer (as children) but along side the Pongo container (as siblings).\nTo share the plugin code and tests with the (sibling) test container Pongo will\nneed a shared working directory on the host. This working directory must be\nmapped to `/pongo_wd` on the container running Pongo.\n\nAdditionally the container id must be made available to the Pongo container. It must\nbe in a file `.containerid` in the same working directory.\n\n_**WARNING**: make sure to read up on the security consequences of sharing `docker.sock`! You are allowing a Docker container to control the Docker deamon on the host!_\n\nFor a working example see [the Pongo repo](https://github.com/Kong/kong-pongo/tree/master/assets/docker).\n\n[Back to ToC](#table-of-contents)\n\n## Releasing (new Kong versions)\n\nWhen new Kong versions are released, the test artifacts contained within this\nPongo repository must be updated.\n\nTo do so there are some pre-requisites;\n\n- have [gh](https://cli.github.com/) installed and configured\n- have access to the `kong-pongo` (push) and `kong-ee` (read/clone) repositories on Github\n\nUpdate the version as follows:\n\n```shell\n# The code-base (1st argument) is either \"EE\" (Enterprise) or \"CE\" (Opensource)\n# 2nd argument is the version to add.\n# 3rd argument makes it a test run if given\n\nassets/add_version.sh \"EE\" \"1.2.3\" \"test\"\n```\n\nHere's an all-in-one command, edit the parameters as needed;\n```\ngit clone --single-branch https://github.com/Kong/kong-pongo $TMPDIR/kong-pongo \u0026\u0026 $TMPDIR/kong-pongo/assets/add_version.sh \"EE\" \"1.2.3\" \"test\"; rm -rf $TMPDIR/kong-pongo\n```\n\nThe result should be a new PR on the Pongo repo.\n\n[Back to ToC](#table-of-contents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkong%2Fkong-pongo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkong%2Fkong-pongo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkong%2Fkong-pongo/lists"}