From 3dc106e10a2bfb7c4bed091221b4d8654f18de20 Mon Sep 17 00:00:00 2001
From: Debarshi Ray <rishi@fedoraproject.org>
Date: Wed, 11 Oct 2023 12:36:04 +0200
Subject: [PATCH] test/system: Clarify misleading 'toolbox --help' test

Commit 5e63e9ec9bc420da added a 'help' command to show the toolbox(1)
manual or a manual page for a specific command, and made the --help flag
identical to it.  Therefore it's misleading to say that the --help flag
should show the usage screen.  The usage screen is a brief listing of
the commands and options, which isn't the same thing as the more
detailed manuals.

Later, after this test was written, commit 40fc1689a3d90f77 added a
fallback for host operating systems without man(1), like Fedora CoreOS,
that would show a very brief usage screen with only the most common
commands.

To make it more confusing, the test was checking for a string that's
common to both the toolbox(1) manual and the fallback brief usage screen
that might be shown by 'toolbox --help'.  This meant that it was neither
able to distinguish between the code paths nor ensure that they were
working as intended.

This was resolved by adapting the existing 'toolbox --help' test to
strictly ensure that it's showing the toolbox(1) manual when man(1) is
present, and by adding a new test to strictly ensure that it's showing
the fallback brief usage screen when man(1) is absent.

Until Bats 1.10.0, 'run --keep-empty-lines' had a bug where it counted
the trailing newline on the last line as a separate line [1].  However,
Bats 1.10.0 is only available in Fedora >= 39 and is absent from Fedoras
37 and 38.

Fallout from b27795a03ec8ae3139e2dad93b4efca13e96fb01

[1] Bats commit 6648e2143bffb933
    https://github.com/bats-core/bats-core/commit/6648e2143bffb933
    https://github.com/bats-core/bats-core/issues/708

https://github.com/containers/toolbox/pull/1386
---
 test/system/002-help.bats | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/test/system/002-help.bats b/test/system/002-help.bats
index 4c47651..6ed31aa 100644
--- a/test/system/002-help.bats
+++ b/test/system/002-help.bats
@@ -62,11 +62,42 @@ setup() {
   assert_line --index 7 "Go to https://github.com/containers/toolbox for further information."
 }
 
-@test "help: Use flag '--help' (it should show usage screen)" {
+@test "help: Use flag '--help'" {
+  if ! command -v man 2>/dev/null; then
+    skip "not found man(1)"
+  fi
+
   run --keep-empty-lines "$TOOLBOX" --help
 
   assert_success
-  assert_output --partial "toolbox - Tool for containerized command line environments on Linux"
+  assert_line --index 0 --partial "toolbox(1)"
+  assert_line --index 0 --partial "General Commands Manual"
+  assert_line --index 3 --partial "toolbox - Tool for containerized command line environments on Linux"
+}
+
+@test "help: Use flag '--help' with man(1) absent" {
+  if command -v man 2>/dev/null; then
+    skip "found man(1)"
+  fi
+
+  run --keep-empty-lines --separate-stderr "$TOOLBOX" --help
+
+  assert_success
+  assert_line --index 0 "toolbox - Tool for containerized command line environments on Linux"
+  assert_line --index 2 "Common commands are:"
+  assert_line --index 3 "create    Create a new toolbox container"
+  assert_line --index 4 "enter     Enter an existing toolbox container"
+  assert_line --index 5 "list      List all existing toolbox containers and images"
+  assert_line --index 7 "Go to https://github.com/containers/toolbox for further information."
+
+  if check_bats_version 1.10.0; then
+    assert [ ${#lines[@]} -eq 8 ]
+  else
+    assert [ ${#lines[@]} -eq 9 ]
+  fi
+
+  # shellcheck disable=SC2154
+  assert [ ${#stderr_lines[@]} -eq 0 ]
 }
 
 @test "help: Try to run toolbox with non-existent command (shows usage screen)" {