DAOS-18304 ddb: Add Go unit tests for ddb command layer

Add Go unit test coverage for the ddb command layer, made possible by
the DdbAPI interface introduced in the previous patch.

New files:
- test_helpers.go: DdbContextStub implementing DdbAPI for use in tests
  without a live VOS environment; captureStdout, runCmdToStdout,
  runMainFlow and isArgEqual test utilities.
- ddb_commands_test.go:
  - TestHelpCmds: verifies help output for the ls and open commands.
  - TestCmds: argument and option parsing for ls (path, --recursive,
    --details) and open (--vos_path, --db_path, --write_mode).
  - TestManPage: man page output to stdout and to file.
- main_test.go:
  - TestParseOpts: general help, unknown commands with --help, default
    option values, flag parsing (--debug, --write, --vos_path,
    --db_path, --version) and error cases (conflicting --cmd /
    --cmd_file, missing --vos_path when --db_path is set).
  - TestRun: version output, unknown command detection, auto-open
    behaviour with --vos_path and --db_path, command-line and
    command-file execution modes.
  - TestStrToLogLevels: all supported log level string conversions.

Features: recovery
Signed-off-by: Cedric Koch-Hofer <cedric.koch-hofer@hpe.com>

Author: kanard38

src/control/cmd/ddb/command_completers_test.go

@@ -1,3 +1,9 @@
+//
+// (C) Copyright 2026 Hewlett Packard Enterprise Development LP
+//
+// SPDX-License-Identifier: BSD-2-Clause-Patent
+//
+
 package main
 
 import (
@@ -18,7 +24,7 @@ func createFile(t *testing.T, filePath string) {
 
 	fd, err := os.Create(filePath)
 	if err != nil {
-		t.Fatalf("Failed to create test vos file %s: %v", filePath, err)
+		t.Fatalf("failed to create test vos file %s: %v", filePath, err)
 	}
 	fd.Close()
 }
@@ -27,14 +33,14 @@ func createDirAll(t *testing.T, dirPath string) {
 	t.Helper()
 
 	if err := os.MkdirAll(dirPath, 0755); err != nil {
-		t.Fatalf("Failed to create test pool directory %s: %v", dirPath, err)
+		t.Fatalf("failed to create test pool directory %s: %v", dirPath, err)
 	}
 }
 
-func testSetup(t *testing.T) (tmpDir string, teardown func()) {
+func testSetup(t *testing.T) string {
 	t.Helper()
 
-	tmpDir, teardown = test.CreateTestDir(t)
+	tmpDir := t.TempDir()
 
 	for _, dir := range testPoolDirs {
 		createDirAll(t, filepath.Join(tmpDir, dir))
@@ -51,12 +57,11 @@ func testSetup(t *testing.T) (tmpDir string, teardown func()) {
 	createDirAll(t, filepath.Join(tmpDir, "bar", "baz"))
 	createFile(t, filepath.Join(tmpDir, "bar", "baz", "no_vos"))
 
-	return
+	return tmpDir
 }
 
 func TestListVosFiles(t *testing.T) {
-	tmpDir, teardown := testSetup(t)
-	t.Cleanup(teardown)
+	tmpDir := testSetup(t)
 
 	for name, tc := range map[string]struct {
 		args   string
@@ -118,7 +123,7 @@ func TestListVosFiles(t *testing.T) {
 	} {
 		t.Run(name, func(t *testing.T) {
 			results := listVosFiles(tc.args)
-			test.AssertStringsEqual(t, tc.expRes, results, "listDirVos results do not match expected")
+			test.AssertStringsEqual(t, tc.expRes, results, "unexpected listVosFiles results")
 		})
 	}
 }
@@ -169,7 +174,7 @@ func TestFilterSuggestions(t *testing.T) {
 	} {
 		t.Run(name, func(t *testing.T) {
 			results := filterSuggestions(tc.prefix, initialSuggestions, additionalSuggestions)
-			test.AssertStringsEqual(t, tc.expRes, results, "filterSuggestions results do not match expected")
+			test.AssertStringsEqual(t, tc.expRes, results, "unexpected filterSuggestions results")
 		})
 	}
 }

src/control/cmd/ddb/ddb_commands_test.go

@@ -0,0 +1,278 @@
+//
+// (C) Copyright 2026 Hewlett Packard Enterprise Development LP
+//
+// SPDX-License-Identifier: BSD-2-Clause-Patent
+//
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/daos-stack/daos/src/control/common/test"
+)
+
+func runHelpCmd(t *testing.T, cmdStr string, helpSubStr string) {
+	t.Helper()
+
+	var ctx DdbContextStub
+
+	// Create a temporary config file with the help command
+	tmpCfgDir := t.TempDir()
+	tmpCfgFile := path.Join(tmpCfgDir, "ddb-cmd_file.txt")
+	if err := os.WriteFile(tmpCfgFile, []byte(fmt.Sprintf("%s --help", cmdStr)), 0644); err != nil {
+		t.Fatalf("failed to write temp config file: %v", err)
+	}
+
+	// Run the help command with a command file
+	args := test.JoinArgs(nil, "--cmd_file="+tmpCfgFile)
+	stdoutCmdFile, err := runMainFlow(&ctx, args)
+	if err != nil {
+		t.Fatalf("unexpected error when running '%s --help' via command file: want nil, got %v", cmdStr, err)
+	}
+	test.AssertTrue(t, strings.Contains(stdoutCmdFile, helpSubStr),
+		fmt.Sprintf("expected stdout to contain %q: got\n%s", helpSubStr, stdoutCmdFile))
+
+	// Run the help command with a command line
+	args = test.JoinArgs(nil, cmdStr, "--help")
+	stdoutCmdLine, err := runMainFlow(&ctx, args)
+	if err != nil {
+		t.Fatalf("unexpected error when running '%s --help' via command line: want nil, got %v", cmdStr, err)
+	}
+	test.AssertTrue(t, strings.Contains(stdoutCmdLine, helpSubStr),
+		fmt.Sprintf("expected stdout to contain %q: got\n%s", helpSubStr, stdoutCmdLine))
+
+	// Compare command line and command file outputs
+	test.AssertEqual(t, stdoutCmdFile, stdoutCmdLine,
+		fmt.Sprintf("unexpected help output mismatch between command file and command line for '%s'", cmdStr))
+}
+
+func TestHelpCmds(t *testing.T) {
+	for name, tc := range map[string]struct {
+		cmdStr     string
+		helpSubStr string
+	}{
+		"help for 'ls' command": {
+			cmdStr:     "ls",
+			helpSubStr: "Usage:\n  ls [flags] [path]\n",
+		},
+		"help for 'open' command": {
+			cmdStr:     "open",
+			helpSubStr: "Usage:\n  open [flags] path\n",
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			runHelpCmd(t, tc.cmdStr, tc.helpSubStr)
+		})
+	}
+}
+
+func TestCmds(t *testing.T) {
+	for name, tc := range map[string]struct {
+		args      []string
+		expCalls  func(ctx *DdbContextStub)
+		expStdout []string
+		expErr    error
+	}{
+		"ls invalid options": {
+			args:   []string{"ls", "--bar"},
+			expErr: ddbTestErr("invalid flag: --bar"),
+		},
+		"ls default": {
+			args: []string{"ls"},
+			expCalls: func(ctx *DdbContextStub) {
+				ctx.ls = func(path string, recursive bool, details bool) error {
+					fmt.Println("ls called")
+					if err := isArgEqual("", path, "path"); err != nil {
+						return err
+					}
+					if err := isArgEqual(false, recursive, "recursive"); err != nil {
+						return err
+					}
+					if err := isArgEqual(false, details, "details"); err != nil {
+						return err
+					}
+					return nil
+				}
+			},
+			expStdout: []string{"ls called"},
+		},
+		"ls path": {
+			args: []string{"ls", "/[0]"},
+			expCalls: func(ctx *DdbContextStub) {
+				ctx.ls = func(path string, recursive bool, details bool) error {
+					fmt.Println("ls called")
+					if err := isArgEqual("/[0]", path, "path"); err != nil {
+						return err
+					}
+					if err := isArgEqual(false, recursive, "recursive"); err != nil {
+						return err
+					}
+					if err := isArgEqual(false, details, "details"); err != nil {
+						return err
+					}
+					return nil
+				}
+			},
+			expStdout: []string{"ls called"},
+		},
+		"ls long recursive opt": {
+			args: []string{"ls", "--recursive"},
+			expCalls: func(ctx *DdbContextStub) {
+				ctx.ls = func(path string, recursive bool, details bool) error {
+					fmt.Println("ls called")
+					if err := isArgEqual("", path, "path"); err != nil {
+						return err
+					}
+					if err := isArgEqual(true, recursive, "recursive"); err != nil {
+						return err
+					}
+					if err := isArgEqual(false, details, "details"); err != nil {
+						return err
+					}
+					return nil
+				}
+			},
+			expStdout: []string{"ls called"},
+		},
+		"ls short details opt": {
+			args: []string{"ls", "-d"},
+			expCalls: func(ctx *DdbContextStub) {
+				ctx.ls = func(path string, recursive bool, details bool) error {
+					fmt.Println("ls called")
+					if err := isArgEqual("", path, "path"); err != nil {
+						return err
+					}
+					if err := isArgEqual(false, recursive, "recursive"); err != nil {
+						return err
+					}
+					if err := isArgEqual(true, details, "details"); err != nil {
+						return err
+					}
+					return nil
+				}
+			},
+			expStdout: []string{"ls called"},
+		},
+		"ls details long opt": {
+			args: []string{"ls", "--details"},
+			expCalls: func(ctx *DdbContextStub) {
+				ctx.ls = func(path string, recursive bool, details bool) error {
+					fmt.Println("ls called")
+					if err := isArgEqual("", path, "path"); err != nil {
+						return err
+					}
+					if err := isArgEqual(false, recursive, "recursive"); err != nil {
+						return err
+					}
+					if err := isArgEqual(true, details, "details"); err != nil {
+						return err
+					}
+					return nil
+				}
+			},
+			expStdout: []string{"ls called"},
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			checkCmd := func(t *testing.T, stdout string, err error) {
+				t.Helper()
+				test.CmpErr(t, tc.expErr, err)
+				if tc.expErr != nil {
+					return
+				}
+				for _, msg := range tc.expStdout {
+					test.AssertTrue(t, strings.Contains(stdout, msg),
+						fmt.Sprintf("expected stdout to contain %q: got\n%s", msg, stdout))
+				}
+			}
+
+			t.Run("command-line", func(t *testing.T) {
+				var ctx DdbContextStub
+				if tc.expCalls != nil {
+					tc.expCalls(&ctx)
+				}
+				stdout, err := runMainFlow(&ctx, tc.args)
+				checkCmd(t, stdout, err)
+			})
+
+			t.Run("command-file", func(t *testing.T) {
+				tmpDir := t.TempDir()
+				cmdFile := filepath.Join(tmpDir, "cmds.txt")
+				cmdLine := strings.Join(tc.args, " ")
+				if err := os.WriteFile(cmdFile, []byte(cmdLine), 0644); err != nil {
+					t.Fatalf("failed to write command file: %v", err)
+				}
+				var ctx DdbContextStub
+				if tc.expCalls != nil {
+					tc.expCalls(&ctx)
+				}
+				stdout, err := runMainFlow(&ctx, []string{"--cmd_file=" + cmdFile})
+				checkCmd(t, stdout, err)
+			})
+		})
+	}
+}
+
+func TestManPage(t *testing.T) {
+	for name, tc := range map[string]struct {
+		args      []string
+		expStdout []string
+		expErr    error
+	}{
+		"manpage to stdout contains sections and commands": {
+			args: []string{"manpage"},
+			expStdout: []string{
+				manArgsHeader,
+				manCmdsHeader,
+				manPathSection[:20],
+				manMdOnSsdSection[:20],
+				manLoggingSection[:20],
+				// Known commands must appear in the listing
+				".B ls\n",
+				".B open\n",
+			},
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			var ctx DdbContextStub
+			stdout, err := runMainFlow(&ctx, tc.args)
+			test.CmpErr(t, tc.expErr, err)
+			if tc.expErr != nil {
+				return
+			}
+			for _, msg := range tc.expStdout {
+				test.AssertTrue(t, strings.Contains(stdout, msg),
+					fmt.Sprintf("expected stdout to contain %q: got\n%s", msg, stdout))
+			}
+		})
+	}
+
+	// Test --output flag: man page is written to a file, stdout is empty.
+	t.Run("manpage to file", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		outFile := filepath.Join(tmpDir, "ddb.groff")
+
+		var ctx DdbContextStub
+		stdout, err := runMainFlow(&ctx, []string{"manpage", "--output=" + outFile})
+		if err != nil {
+			t.Fatalf("unexpected error when running 'manpage --output': want nil, got %v", err)
+		}
+		test.AssertTrue(t, stdout == "",
+			fmt.Sprintf("expected empty stdout when --output is set: got\n%s", stdout))
+
+		content, err := os.ReadFile(outFile)
+		if err != nil {
+			t.Fatalf("failed to read output file: %v", err)
+		}
+		for _, section := range []string{manArgsHeader, manCmdsHeader, manLoggingSection[:20]} {
+			test.AssertTrue(t, strings.Contains(string(content), section),
+				fmt.Sprintf("expected file to contain %q: got\n%s", section, string(content)))
+		}
+	})
+}