feat(deployment): show command output on failure (#43)

This change adds an additional helper utility to run commands silently
unless there is a failure, and adjusts the keycloak deployment script to
use this when running a couple helm install and ugprade commands to help
aid in troubleshooting setup problems.

Assisted-By: Cursor Desktop

rh-pre-commit.version: 2.3.2
rh-pre-commit.check-secrets: ENABLED

Author: gashcrumb

docs/overlay/reference/troubleshooting.md

@@ -123,9 +123,10 @@ oc login --token=<token> --server=<server>
 
 ### "Keycloak deployment failed"
 
-**Problem:** Keycloak fails to deploy.
+**Problem:** Keycloak fails to deploy (e.g. during global setup or when using `auth: "keycloak"`).
 
 **Solutions:**
+- **Check the build log for command output.** When the Keycloak deployment step fails, the test framework prints the failed command's stdout and stderr to the log. Look for **`[command stdout]:`** and **`[command stderr]:`** in the output — that shows the actual Helm (or other) command output and is the first place to look for the failure reason.
 - Check Keycloak namespace for errors:
   ```bash
   oc get pods -n rhdh-keycloak

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@red-hat-developer-hub/e2e-test-utils",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "description": "Test utilities for RHDH E2E tests",
   "license": "Apache-2.0",
   "repository": {

src/deployment/keycloak/deployment.ts

@@ -1,6 +1,6 @@
 import KeycloakAdminClient from "@keycloak/keycloak-admin-client";
 import { KubernetesClientHelper } from "../../utils/kubernetes-client.js";
-import { $ } from "../../utils/bash.js";
+import { $, runQuietUnlessFailure } from "../../utils/bash.js";
 import {
   DEFAULT_KEYCLOAK_CONFIG,
   BITNAMI_CHART_REPO,
@@ -380,11 +380,11 @@ export class KeycloakHelper {
 
   private async _deployWithHelm(): Promise<void> {
     await $`helm repo add bitnami ${BITNAMI_CHART_REPO} || true`;
-    await $`helm repo update > /dev/null 2>&1`;
+    await runQuietUnlessFailure`helm repo update`;
 
-    await $`helm upgrade --install ${this.deploymentConfig.releaseName} ${BITNAMI_CHART_NAME} \
+    await runQuietUnlessFailure`helm upgrade --install ${this.deploymentConfig.releaseName} ${BITNAMI_CHART_NAME} \
       --namespace ${this.deploymentConfig.namespace} \
-      --values ${this.deploymentConfig.valuesFile} > /dev/null 2>&1`;
+      --values ${this.deploymentConfig.valuesFile}`;
 
     await this.waitUntilReady();
   }

src/utils/bash.ts

@@ -3,4 +3,44 @@ import { $ } from "zx";
 $.quiet = true;
 $.stdio = ["inherit", "inherit", "inherit"];
 
+/** Shape of zx ProcessOutput used when checking command result. */
+interface ProcessResult {
+  exitCode: number;
+  stdout?: string;
+  stderr?: string;
+}
+
+/**
+ * Runs a shell command with stdout/stderr captured. On success, output is not printed.
+ * On non-zero exit, stdout and stderr are written to console.error and an error is thrown.
+ * Use for noisy commands that should stay quiet on success but show output when they fail.
+ */
+export async function runQuietUnlessFailure(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): Promise<void> {
+  const runWithPipe = $({
+    stdio: ["pipe", "pipe", "pipe"],
+    nothrow: true,
+  });
+  const result = (await (
+    runWithPipe as (
+      strings: TemplateStringsArray,
+      ...values: unknown[]
+    ) => ReturnType<typeof $>
+  )(strings, ...values)) as ProcessResult;
+
+  if (result.exitCode !== 0) {
+    if (result.stdout?.trim()) {
+      console.error("[command stdout]:", result.stdout.trim());
+    }
+    if (result.stderr?.trim()) {
+      console.error("[command stderr]:", result.stderr.trim());
+    }
+    throw new Error(
+      `Command failed with exit code ${result.exitCode}. Output above.`,
+    );
+  }
+}
+
 export { $ };

src/utils/index.ts

@@ -1,5 +1,5 @@
 export { envsubst } from "./common.js";
-export { $ } from "./bash.js";
+export { $, runQuietUnlessFailure } from "./bash.js";
 export {
   mergeYamlFiles,
   mergeYamlFilesIfExists,