testutils: Document and enforce @func callback retvals for virTestMain()

When a test has a wrapper over main() (e.g. because it's
preloading some mock libraries). the main() is renamed to
something else (usually mymain()), and main() is generated by
calling one of VIR_TEST_MAIN() or VIR_TEST_MAIN_PRELOAD() macros.

This has a neat side effect - if mymain() returns an error a
short summary is printed, e.g.:

  Some tests failed. Run them using:
  VIR_TEST_DEBUG=1 VIR_TEST_RANGE=5-6 ./virtest

However, this detection only works if EXIT_FAILURE is returned by
mymain(). Document and enforce this limitation.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>

tests/testutils.c

@@ -838,6 +838,19 @@ int virTestMain(int argc,
             fprintf(stderr, "%*s", 40 - (int)(testCounter % 40), "");
         fprintf(stderr, " %-3zu %s\n", testCounter, ret == 0 ? "OK" : "FAIL");
     }
+
+    switch (ret) {
+    case EXIT_FAILURE:
+    case EXIT_SUCCESS:
+    case EXIT_AM_SKIP:
+    case EXIT_AM_HARDFAIL:
+        break;
+    default:
+        fprintf(stderr, "Test callback returned invalid value: %d\n", ret);
+        ret = EXIT_AM_HARDFAIL;
+        break;
+    }
+
     if (ret == EXIT_FAILURE && !virBitmapIsAllClear(failedTests)) {
         g_autofree char *failed = virBitmapFormat(failedTests);
         fprintf(stderr, "Some tests failed. Run them using:\n");

tests/testutils.h

@@ -98,6 +98,10 @@ void virTestQuiesceLibvirtErrors(bool always);
 void virTestCounterReset(const char *prefix);
 const char *virTestCounterNext(void);
 
+/**
+ * The @func shall return  EXIT_FAILURE or EXIT_SUCCESS or
+ * EXIT_AM_SKIP or EXIT_AM_HARDFAIL.
+ */
 int virTestMain(int argc,
                 char **argv,
                 int (*func)(void),