Apisix Test Setup

I run into some challenges setting up the APISIX test. Documenting it here for my furture self.

The overall step looks like this,

# get source
$ git clone git@github.com:apache/incubator-apisix.git
$ cd incubator-apisix

# prepare runtime and start apisix process
$ etcd --enable-v2=true &
$ make init # create config files
$ make deps
$ make run

# install required test-nginx repo to sibling file path
$ git clone https://github.com/openresty/test-nginx.git ../test-nginx
# invoke the test in incurbator-apisix using `prove`
$ TEST_NGINX_BINARY=`which openresty` \
prove  -I./ -I../test-nginx/lib -I../test-nginx/inc -r ./t

Read further if you want more detais.

Some confusion comes from the test toolchian.
The project is a lua project, but the testing framework is written in a different language: perl.
The perl test framework is called prove. I have no idea how to use it.
This is beginner unfriendly because this adds a surprising component to the project. All I want to do is to start the test, but before I can do that I have to learn how to use perl, both the testing command and also the package management system.

Some confusion comes from the project strucutre.
The test toolchain, unlike other projects, is not included in the git repo itself. User needs to download a new git repo(test-nginx) to set the ground for running the test.
This is confusing because setting up test framework is not automated, require one extra chance for making mistake.
For projects from other programmng language(Python, C++), test framwork is part of the project source tree. To run the test, user only needs to invoke a command, no need to break out of the context and download a test driver.

Nontheless, with some effort I was able to run the test, after solving the following puzzles. My workflow is to run make test and read through both issue 862 and error output to make progress.

Plan

Start the process to be tested
Run the test framework against the subject
Check the result

Software Versions

# Perl version
$ perl --version  
This is perl 5, version 32, subversion 0 (v5.32.0)

# OS version
$ uname -a
Linux 2d-pc 5.3.0-62-generic #56~18.04.1-Ubuntu SMP \
Wed Jun 24 16:17:03 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux

# Perl package manager version
$ cpan -v
Loading internal logger. Log::Log4perl recommended for better logging
>(info): /home/linuxbrew/.linuxbrew/bin/cpan script version 1.675, CPAN.pm version 2.27

Prelude: start the subject being tested

# start the etcd db in compatible mode
$ etcd --enable-v2=true & # !NOTE1

# init local nginx.conf and other things
$ make init
# start apisix process
$ make run

NOTE1: Using v2(not v3) is documented at install deps. Which is very easy to overlook. Also remember to always start this first because init needs to talk to etcd!

Up to this point, we should have the subject up and running. Let us check that this is indeed the case.

First, curl a request to the process,

curl "http://127.0.0.1:9080/apisix/admin/services/" \
    -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' | jq

We will get this as the response: apisix-running

TODO: access dashboard UI needs to clone incubator-apisix-dashboard repo and will need additional setup.

Run Test

Since we have verified that the apisix process is running, we can run test against it by

$ make test #!NOTE2

TEST_NGINX_BINARY=`which openresty` \
    prove -I../test-nginx/lib -I../test-nginx/inc -I./ -r -s t/

... very long text output on test results...

NOTE2: need to add -I../test-nginx/inc to the make script otherwise would run into missing Test::Base error.

Contents

Plan

Prelude: start the subject being tested

Run Test