Implement review feedback

- document a recommended convention for fail-fast tests

- document the requirement for jq. (And, add a fail-fast
  test for its presence; remove the duplicated checks
  in subtests)

- add further sanity checks to 'help' test. Add missing
  documentation. Remove a no-longer-needed workaround for
  usage-message bug fixed in #2486

- add a documented TEMPLATE

- and, since we're at 1.1, enable 'Remote API' check in
  version test

- better diagnostics in setup/teardown; add vim filetype hint;
  better formatting of actual-vs-expect errors

- new pod-top, logs, build tests

- improve error messages

- add $IMAGE alias for ridiculous $PODMAN_TEST_IMAGE_FQN

- final cleanup, in prep for merge

Signed-off-by: Ed Santiago <santiago@redhat.com>

1 files changed, 114 insertions, 0 deletions

diff --git a/test/system/000-TEMPLATE b/test/system/000-TEMPLATE
new file mode 100644
index 000000000..296ed4d58
--- /dev/null
+++ b/test/system/000-TEMPLATE
@@ -0,0 +1,114 @@
+#!/usr/bin/env bats   -*- bats -*-
+#
+# FIXME: short description of the purpose of this module
+#
+# FIXME: copy this file to 'NNN-yourtestname.bats' and edit as needed.
+#
+
+load helpers
+
+@test "podman subcmd - description of this particular test" {
+    args="some sort of argument list"
+    run_podman subcmd $args
+    is "$output"   "what we expect"   "output from 'podman subcmd $args'"
+}
+
+# vim: filetype=sh
+
+###############################################################################
+#
+# FIXME FIXME FIXME: Most of the time you can cut from here on down.
+# FIXME FIXME FIXME: The above template is probably enough for many tests.
+# FIXME FIXME FIXME:
+# FIXME FIXME FIXME: If you need anything more complicated, read on.
+#
+# FIXME: This is a bloated test template. It provides mostly stuff for you
+# FIXME: to remove, plus stuff for you to base your tests on.
+# FIXME:
+# FIXME: copy this file to 'NNN-yourtestname.bats' and edit as needed.
+# FIXME: Read all FIXMEs, act on them as needed, then remove them.
+# FIXME: test w/ $ PODMAN=./bin/podman bats test/system/NNN-yourtestname.bats
+#
+
+load helpers
+
+# FIXME: DELETE THESE LINES UNLESS YOU ABSOLUTELY NEED THEM.
+# FIXME: Most tests will not need a custom setup/teardown: they are
+# FIXME: provided by helpers.bash.
+# FIXME: But if you have to do anything special, these give you the
+# FIXME: names of the standard setup/teardown so you can call them
+# FIXME: before or after your own additions.
+function setup() {
+    basic_setup
+    # FIXME: you almost certainly want to do your own setup _after_ basic.
+}
+function teardown() {
+    # FIXME: you almost certainly want to do your own teardown _before_ basic.
+    basic_teardown
+}
+
+
+# FIXME: very basic one-pass example
+@test "podman FOO - description of test" {
+    # FIXME: please try to remove this line; that is, try to write tests
+    # that will pass as both root and rootless.
+    skip_if_rootless
+
+    # FIXME: template for run commands. Always use 'run_podman'!
+    # FIXME: The '?' means 'ignore exit status'; use a number if you
+    # FIXME:    expect a precise nonzero code, or omit for 0 (usual case).
+    # FIXME: NEVER EVER RUN 'podman' DIRECTLY. See helpers.bash for why.
+    run_podman '?' run -d $IMAGE sh -c 'prep..; echo READY'
+    cid="$output"
+    wait_for_ready $cid
+
+    run_podman logs $cid
+    # FIXME: example of dprint. This will trigger if PODMAN_TEST_DEBUG=FOO
+    # FIXME:  ...or anything that matches the name assigned in the @test line.
+    dprint "podman logs $cid -> '$output'"
+    is "$output" "what are we expecting?" "description of this check"
+
+    # Clean up
+    run_podman rm $cid
+}
+
+
+# FIXME: another example, this time with a test table loop
+@test "podman FOO - json - template for playing with json output" {
+    # FIXME: Define a multiline string in tabular form, using '|' as separator.
+    # FIXME: Each row defines one test. Each column (there may be as many as
+    # FIXME: you want) is one field. In the case below we have two, a
+    # FIXME: json field descriptor and an expected value.
+    tests="
+id        | [0-9a-f]\\\{64\\\}
+created   | [0-9-]\\\+T[0-9:]\\\+\\\.[0-9]\\\+Z
+size      | -\\\?[0-9]\\\+
+"
+
+    # FIXME: Run a basic podman command. We'll check $output multiple times
+    # FIXME: in the while loop below.
+    run_podman history --format json $IMAGE
+
+    # FIXME: parse_table is what does all the work, giving us test cases.
+    parse_table "$tests" | while read field expect; do
+        # FIXME: this shows a drawback of BATS and bash: we can't include '|'
+        # FIXME: in the table, but we need to because some images don't
+        # FIXME: have a CID. So, yeah, this is ugly -- but rare.
+        if [ "$field" = "id" ]; then expect="$expect\|<missing>";fi
+
+        # output is an array of dicts; check each one
+        count=$(echo "$output" | jq '. | length')
+        i=0
+        while [ $i -lt $count ]; do
+            actual=$(echo "$output" | jq -r ".[$i].$field")
+            # FIXME: please be sure to note the third field!
+            # FIXME: that's the test name. Make it something useful! Include
+            # FIXME: loop variables whenever possible. Don't just say "my test"
+            is "$actual"    "$expect\$"    "jq .[$i].$field"
+            i=$(expr $i + 1)
+        done
+    done
+}
+
+
+# vim: filetype=sh