github.com/containers/podman/v5@v5.1.0-rc1/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  Never, ever, ever, seriously _EVER_ `exit` from a test. Just don't.
    50  That skips cleanup, and leaves the system in a broken state.
    51  
    52  Notes:
    53  
    54  * If the endpoint has a leading slash (`/_ping`), `t` leaves it unchanged.
    55  If there's no leading slash, `t` prepends `/v1.40`. This is a simple
    56  convenience for simplicity of writing tests.
    57  
    58  * When method is POST, the argument(s) after the endpoint may be a series
    59  of POST parameters in the form 'key=value', separated by spaces:
    60       t POST myentrypoint 200                                 ! no params
    61       t POST myentrypoint id=$id 200                          ! just one
    62       t POST myentrypoint id=$id filter='{"foo":"bar"}' 200   ! two, with json
    63       t POST myentrypoint name=$name badparam='["foo","bar"]' 500  ! etc...
    64  `t` will convert the param list to JSON form for passing to the server.
    65  A numeric status code terminates processing of POST parameters.
    66  ** As a special case, when one POST argument is a string ending in `.tar`,
    67  `.yaml`, or `.json`, `t` will invoke `curl` with `--data-binary @PATH` and
    68  set `Content-type` as appropriate. This is useful for `build` endpoints.
    69  (To override `Content-type`, simply pass along an extra string argument
    70  matching `application/*`):
    71        t POST myentrypoint /mytmpdir/myfile.tar application/foo 400
    72  ** Like above, when using PUT, `t` does `--upload-time` instead of
    73  `--data-binary`
    74  
    75  * The final arguments are one or more expected string results. If an
    76  argument starts with a dot, `t` will invoke `jq` on the output to
    77  fetch that field, and will compare it to the right-hand side of
    78  the argument. If the separator is `=` (equals), `t` will require
    79  an exact match; if `~` (tilde), `t` will use `expr` to compare.
    80  
    81  * If your test expects `curl` to time out:
    82       APIV2_TEST_EXPECT_TIMEOUT=5 t POST /foo 999