mirror of
https://github.com/containers/podman.git
synced 2026-03-17 22:28:22 -04:00
0a2eb7b185
Some months ago, apiv2 tests got added that needed new functionality: passing a tarball to the remote server. There was no mechanism to do so in the 't' helper, so these tests used complicated (and actually not-really- working) curl commands. This PR introduces and documents a new usage of 't', in which passing an argument ending in '.tar' adds the right magic syntax (--data-binary @PATH) to the existing curl. This lets us use all standard 't' checks, making for simpler tests and in the process fixing some bugs. Also: drive-by fix of a typo bug in the networks test. Also: set CONTAINERS_REGISTRIES_CONF when starting server and when running direct podman, to avoid docker.io throttling. Signed-off-by: Ed Santiago <santiago@redhat.com>
75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
API v2 tests
|
|
============
|
|
|
|
This directory contains tests for the podman version 2 API (HTTP).
|
|
|
|
Tests themselves are in files of the form 'NN-NAME.at' where NN is a
|
|
two-digit number, NAME is a descriptive name, and '.at' is just
|
|
an extension I picked.
|
|
|
|
Running Tests
|
|
=============
|
|
|
|
The main test runner is `test-apiv2`. Usage is:
|
|
|
|
$ sudo ./test-apiv2 [NAME [...]]
|
|
|
|
...where NAME is one or more optional test names, e.g. 'image' or 'pod'
|
|
or both. By default, `test-apiv2` will invoke all `*.at` tests.
|
|
|
|
`test-apiv2` connects to *localhost only* and *via TCP*. There is
|
|
no support here for remote hosts or for UNIX sockets. This is a
|
|
framework for testing the API, not all possible protocols.
|
|
|
|
`test-apiv2` will start the service if it isn't already running.
|
|
|
|
|
|
Writing Tests
|
|
=============
|
|
|
|
The main test function is `t`. It runs `curl` against the server,
|
|
with POST parameters if present, and compares return status and
|
|
(optionally) string results from the server:
|
|
|
|
t GET /_ping 200 OK
|
|
^^^ ^^^^^^ ^^^ ^^
|
|
| | | +--- expected string result
|
|
| | +------- expected return code
|
|
| +-------------- endpoint to access
|
|
+------------------ method (GET, POST, DELETE, HEAD)
|
|
|
|
|
|
t POST libpod/volumes/create name=foo 201 .ID~[0-9a-f]\\{12\\}
|
|
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^ ^^^ ^^^^^^^^^^^^^^^^^^^^
|
|
| | | JSON '.ID': expect 12-char hex
|
|
| | +-- expected code
|
|
| +----------- POST params
|
|
+--------------------------------- note the missing slash
|
|
|
|
Notes:
|
|
|
|
* If the endpoint has a leading slash (`/_ping`), `t` leaves it unchanged.
|
|
If there's no leading slash, `t` prepends `/v1.40`. This is a simple
|
|
convenience for simplicity of writing tests.
|
|
|
|
* When method is POST, the argument(s) after the endpoint may be a series
|
|
of POST parameters in the form 'key=value', separated by spaces:
|
|
t POST myentrypoint 200 ! no params
|
|
t POST myentrypoint id=$id 200 ! just one
|
|
t POST myentrypoint id=$id filter='{"foo":"bar"}' 200 ! two, with json
|
|
t POST myentrypoint name=$name badparam='["foo","bar"]' 500 ! etc...
|
|
`t` will convert the param list to JSON form for passing to the server.
|
|
A numeric status code terminates processing of POST parameters.
|
|
** As a special case, when one POST argument is a string ending in `.tar`,
|
|
`t` will invoke `curl` with `--data-binary @PATH` and
|
|
set `Content-type: application/x-tar`. This is useful for `build` endpoints.
|
|
(To override `Content-type`, simply pass along an extra string argument
|
|
matching `application/*`):
|
|
t POST myentrypoint /mytmpdir/myfile.tar application/foo 400
|
|
|
|
* The final arguments are one or more expected string results. If an
|
|
argument starts with a dot, `t` will invoke `jq` on the output to
|
|
fetch that field, and will compare it to the right-hand side of
|
|
the argument. If the separator is `=` (equals), `t` will require
|
|
an exact match; if `~` (tilde), `t` will use `expr` to compare.
|