fix(integ-runner): assembly execution errors don't provide meaningful information (#716)

This PR improves error formatting in the `integ-runner` including the
actual cause of a command line execution failure and improving
readability through colors and indentation.

Relates to #715

### Before

<img width="1197" height="99" alt="image"
src="https://github.com/user-attachments/assets/2abdb7d6-39a8-4109-a025-5002547c71ad"
/>

Note that the original error can be extracted from double verbose logs
(running with `-vv`). But it's hidden within a wall of text:

<img width="1197" height="158" alt="image"
src="https://github.com/user-attachments/assets/d5cfe578-e49b-408e-90d0-e21000685ed1"
/>


### After
<img width="1197" height="121" alt="image"
src="https://github.com/user-attachments/assets/10331faa-05d1-4bc8-a26b-226331ee359c"
/>




---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

Author: mrgrain

packages/@aws-cdk/integ-runner/lib/workers/common.ts

@@ -286,30 +286,37 @@ export function printResults(diagnostic: Diagnostic): void {
       logger.success('  UNCHANGED  %s %s', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`));
       break;
     case DiagnosticReason.TEST_SUCCESS:
-      logger.success('  SUCCESS    %s %s\n      ', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`), diagnostic.message);
+      logger.success('  SUCCESS    %s %s\n      ', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`));
       break;
     case DiagnosticReason.NO_SNAPSHOT:
       logger.error('  NEW        %s %s', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`));
       break;
     case DiagnosticReason.SNAPSHOT_FAILED:
-      logger.error('  CHANGED    %s %s\n      %s', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`), diagnostic.message);
+      logger.error('  CHANGED    %s %s\n%s', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`), indentLines(diagnostic.message, 6));
       break;
     case DiagnosticReason.SNAPSHOT_ERROR:
     case DiagnosticReason.TEST_ERROR:
-      logger.error('  ERROR      %s %s\n      %s', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`), diagnostic.message);
+      logger.error('  ERROR      %s %s\n%s', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`), indentLines(diagnostic.message, 6));
       break;
     case DiagnosticReason.TEST_FAILED:
-      logger.error('  FAILED     %s %s\n      %s', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`), diagnostic.message);
+      logger.error('  FAILED     %s %s\n%s', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`), indentLines(diagnostic.message, 6));
       break;
     case DiagnosticReason.ASSERTION_FAILED:
-      logger.error('  ASSERT     %s %s\n      %s', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`), diagnostic.message);
+      logger.error('  ASSERT     %s %s\n%s', diagnostic.testName, chalk.gray(`${diagnostic.duration}s`), indentLines(diagnostic.message, 6));
       break;
   }
   for (const addl of diagnostic.additionalMessages ?? []) {
     logger.print(`      ${addl}`);
   }
 }
 
+/**
+ * Takes a multiline string and indents every line with the same number of spaces.
+ */
+function indentLines(message: string, count = 2): string {
+  return message.split('\n').map(line => ' '.repeat(count) + line).join('\n');
+}
+
 export function printLaggards(testNames: Set<string>) {
   const parts = [
     '  ',
@@ -319,3 +326,14 @@ export function printLaggards(testNames: Set<string>) {
 
   logger.print(chalk.grey(parts.filter(x => x).join(' ')));
 }
+
+export function formatError(error: any): string {
+  const name = error.name || 'Error';
+  const message = error.message || String(error);
+
+  if (error.cause) {
+    return `${name}: ${message}\n${chalk.gray('Cause: ' + formatError(error.cause))}`;
+  }
+
+  return `${name}: ${message}`;
+}

packages/@aws-cdk/integ-runner/lib/workers/extract/extract_worker.ts

@@ -3,7 +3,7 @@ import { IntegSnapshotRunner, IntegTestRunner } from '../../runner';
 import type { IntegTestInfo } from '../../runner/integration-tests';
 import { IntegTest } from '../../runner/integration-tests';
 import type { IntegTestWorkerConfig, SnapshotVerificationOptions, Diagnostic } from '../common';
-import { DiagnosticReason, formatAssertionResults } from '../common';
+import { DiagnosticReason, formatAssertionResults, formatError } from '../common';
 import type { IntegTestBatchRequest } from '../integ-test-worker';
 import type { IntegWatchOptions } from '../integ-watch-worker';
 
@@ -73,7 +73,7 @@ export async function integTestWorker(request: IntegTestBatchRequest): Promise<I
           workerpool.workerEmit({
             reason: DiagnosticReason.TEST_FAILED,
             testName: `${runner.testName}-${testCaseName} (${request.profile}/${request.region})`,
-            message: `Integration test failed: ${e}`,
+            message: `Integration test failed: ${formatError(e)}`,
             duration: (Date.now() - start) / 1000,
           });
         }
@@ -83,7 +83,7 @@ export async function integTestWorker(request: IntegTestBatchRequest): Promise<I
       workerpool.workerEmit({
         reason: DiagnosticReason.TEST_ERROR,
         testName: `${testInfo.fileName} (${request.profile}/${request.region})`,
-        message: `Error during integration test: ${e}`,
+        message: `Error during integration test: ${formatError(e)}`,
         duration: (Date.now() - start) / 1000,
       });
     }

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/private/exec.ts

@@ -1,7 +1,7 @@
 import * as child_process from 'node:child_process';
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import split = require('split2');
-import { ToolkitError } from '../../../toolkit/toolkit-error';
+import { AssemblyError } from '../../../toolkit/toolkit-error';
 
 type EventPublisher = (event: 'open' | 'data_stdout' | 'data_stderr' | 'close', line: string) => void;
 
@@ -45,16 +45,27 @@ export async function execInChildProcess(commandAndArgs: string, options: ExecOp
           return;
       }
     });
+
+    const stderr = new Array<string>();
+
     proc.stdout.pipe(split()).on('data', (line) => eventPublisher('data_stdout', line));
-    proc.stderr.pipe(split()).on('data', (line) => eventPublisher('data_stderr', line));
+    proc.stderr.pipe(split()).on('data', (line) => {
+      stderr.push(line);
+      return eventPublisher('data_stderr', line);
+    });
 
     proc.on('error', fail);
 
     proc.on('exit', code => {
       if (code === 0) {
         return ok();
       } else {
-        return fail(new ToolkitError(`${commandAndArgs}: Subprocess exited with error ${code}`));
+        let cause: Error | undefined;
+        if (stderr.length) {
+          cause = new Error(stderr.join('\n'));
+          cause.name = 'ExecutionError';
+        }
+        return fail(AssemblyError.withCause(`${commandAndArgs}: Subprocess exited with error ${code}`, cause));
       }
     });
   });