Introducing APISIX’s testing framework

    If you want to test the CLI behavior of APISIX (), you need to write a shell script in the t/cli directory to test it. You can refer to the existing test scripts for more details.

    If you want to test the others, you need to write test code based on the framework.

    Here, we briefly describe how to do simple testing based on this framework.

    you need to write test cases in the t/ directory, in a corresponding .t file. Note that a single test file should not exceed 800 lines, and if it is too long, it needs to be divided by a suffix. For example:

    Both consumers.t and consumers2.t contain tests for consumers in the Admin API.

    Some of the test files start with this paragraph:

    1. add_block_preprocessor(sub {    my ($block) = @_;
    2.     if (! $block->no_error_log && ! $block->error_log) {        $block->set_value("no_error_log", "[error]\n[alert]");    }});

    It means that all tests in this test file that do not define request are set to GET /t. The same is true for error_log.

    Preparing the configuration

    When testing a behavior, we need to prepare the configuration.

    If the configuration is from etcd: We can set up specific configurations through the Admin API.

    1. === TEST 7: refer to empty nodes upstream--- config    location /t {        content_by_lua_block {            local core = require("apisix.core")            local t = require("lib.test_admin").test            local code, message = t('/apisix/admin/routes/1',                ngx.HTTP_PUT,                [[{                    "methods": ["GET"],                    "upstream_id": "1",                    "uri": "/index.html"                }]]                )
    2.             if code >= 300 then                ngx.status = code                ngx.print(message)                return            end
    3.             ngx.say(message)        }    }--- requestGET /t--- response_bodypassed

    We can initiate a request with request and set the request headers with more_headers.

    For example.

    Lua code can be used to send multiple requests.

    One request after another:

    1.     location /t {        content_by_lua_block {            local http = require "resty.http"            local uri = "http://127.0.0.1:" ... ngx.var.server_port                        ... "/server_port"
    2.             local ports_count = {}            for i = 1, 12 do                local httpc = http.new()                local res, err = httpc:request_uri(uri, {method = "GET"})                if not res then                    ngx.say(err)                    return                end                ports_count[res.body] = (ports_count[res.body] or 0) + 1            end

    Sending multiple requests concurrently:

    1.     location /t {        content_by_lua_block {            local http = require "resty.http"            local uri = "http://127.0.0.1:" ... ngx.var.server_port                        ... "/server_port?var=2&var2="
    3.             local t = {}            local ports_count = {}            for i = 1, 180 do                local th = assert(ngx.thread.spawn(function(i)                    local httpc = http.new()                    local res, err = httpc:request_uri(uri..i, {method = "GET"})                    if not res then                        ngx.log(ngx.ERR, err)                        return                    end                    ports_count[res.body] = (ports_count[res.body] or 0) + 1                end, i))                table.insert(t, th)            end            for i, th in ipairs(t) do                ngx.thread.wait(th)            end

    Assertions

    The following assertions are commonly used.

    Check status (if not set, the framework will check if the request has 200 status code).

      Check response headers.

      Check response body.

      1. --- response_body[{"count":12, "port": "1982"}]
      1. --- grep_error_log evalqr/hash_on: header|chash_key: "custom-one"/--- grep_error_log_outhash_on: headerchash_key: "custom-one"hash_on: headerchash_key: "custom-one"hash_on: headerchash_key: "custom-one"hash_on: headerchash_key: "custom-one"

      The default log level is info, but you can get the debug level log with -- log_level: debug.

      The test framework listens to multiple ports when it is started.

      • 1980/1981/1982/5044: HTTP upstream port
      • 1983: HTTPS upstream port
      • 1984: APISIX HTTP port. Can be used to verify HTTP related gateway logic, such as concurrent access to an API.
      • 1994: APISIX HTTPS port. Can be used to verify HTTPS related gateway logic, such as testing certificate matching logic.

      The methods in are executed when accessing the upstream port. _M.go is the entry point for this file. When the request accesses the upstream /xxx, the _M.xxx method is executed. For example, a request for /hello will execute _M.hello. This allows us to write methods inside t/lib/server.lua to emulate specific upstream logic, such as sending special responses.

      Note that before adding new methods to t/lib/server.lua, make sure that you can reuse existing methods.

      Run the test

      Assume your current work directory is the root of the apisix source code.

      1. Install our fork of to ../test-nginx.
      2. Run the test: prove -I. -I../test-nginx/inc -I../test-nginx/lib -r t/path/to/file.t.

      The Nginx configuration and logs generated by the test cases are located in the t/servroot directory. The Nginx configuration template for testing is located in t/APISIX.pm.

      Running only some test cases

      Three notes can be used to control which parts of the tests are executed.

      FIRST & LAST:

      1. === TEST 1: vars rule with ! (set)--- FIRST--- config...--- response_bodypassed

      ONLY: