github.com/containers/libpod@v1.9.4-0.20220419124438-4284fd425507/test/apiv2/README.md (about) 1 API v2 tests 2 ============ 3 4 This directory contains tests for the podman version 2 API (HTTP). 5 6 Tests themselves are in files of the form 'NN-NAME.at' where NN is a 7 two-digit number, NAME is a descriptive name, and '.at' is just 8 an extension I picked. 9 10 Running Tests 11 ============= 12 13 The main test runner is `test-apiv2`. Usage is: 14 15 $ sudo ./test-apiv2 [NAME [...]] 16 17 ...where NAME is one or more optional test names, e.g. 'image' or 'pod' 18 or both. By default, `test-apiv2` will invoke all `*.at` tests. 19 20 `test-apiv2` connects to *localhost only* and *via TCP*. There is 21 no support here for remote hosts or for UNIX sockets. This is a 22 framework for testing the API, not all possible protocols. 23 24 `test-apiv2` will start the service if it isn't already running. 25 26 27 Writing Tests 28 ============= 29 30 The main test function is `t`. It runs `curl` against the server, 31 with POST parameters if present, and compares return status and 32 (optionally) string results from the server: 33 34 t GET /_ping 200 OK 35 ^^^ ^^^^^^ ^^^ ^^ 36 | | | +--- expected string result 37 | | +------- expected return code 38 | +-------------- endpoint to access 39 +------------------ method (GET, POST, DELETE, HEAD) 40 41 42 t POST libpod/volumes/create name=foo 201 .ID~[0-9a-f]\\{12\\} 43 ^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^ ^^^ ^^^^^^^^^^^^^^^^^^^^ 44 | | | JSON '.ID': expect 12-char hex 45 | | +-- expected code 46 | +----------- POST params 47 +--------------------------------- note the missing slash 48 49 Notes: 50 51 * If the endpoint has a leading slash (`/_ping`), `t` leaves it unchanged. 52 If there's no leading slash, `t` prepends `/v1.40`. This is a simple 53 convenience for simplicity of writing tests. 54 55 * When method is POST, the argument after the endpoint must be a series 56 of POST arguments in the form 'key=value', separated by commas. `t` will 57 convert those to JSON form for passing to the server. 58 59 * The final arguments are one or more expected string results. If an 60 argument starts with a dot, `t` will invoke `jq` on the output to 61 fetch that field, and will compare it to the right-hand side of 62 the argument. If the separator is `=` (equals), `t` will require 63 an exact match; if `~` (tilde), `t` will use `expr` to compare.