sdk-core: Serialize error.cause (#360)

* sdk-core: Serialize error.cause

* sdk-core: serialize everything possible during error serialization that is not type error

* sdk-core: Fix invalid cast

* sdk-core: handle properly circural reference and objects that can be available in cause

* sdk-core: simplify object serialization fallback

---------

Co-authored-by: Konrad Dysput <konrad.dysput@saucelabs.com>

Author: konraddysput

packages/sdk-core/src/model/report/BacktraceReport.ts

@@ -71,12 +71,7 @@ export class BacktraceReport {
         let errorType: BacktraceErrorType = 'Exception';
         if (data instanceof Error) {
             this.message = this.generateErrorMessage(data.message);
-            this.annotations['error'] = {
-                ...data,
-                message: this.message,
-                name: data.name,
-                stack: data.stack,
-            };
+            this.annotations['error'] = this.unwrapErrorToAnnotation(data);
             this.classifiers = [data.name];
             this.stackTrace['main'] = {
                 stack: data.stack ?? '',
@@ -111,6 +106,22 @@ export class BacktraceReport {
         }
     }
 
+    private unwrapErrorToAnnotation(error: Error, seen = new WeakSet<object>()): Record<string, unknown> {
+        seen.add(error);
+        return {
+            ...error,
+            message: this.generateErrorMessage(error.message),
+            name: error.name,
+            stack: error.stack,
+            cause:
+                error.cause instanceof Error
+                    ? seen.has(error.cause)
+                        ? `[Circular] ${error.cause.message}`
+                        : this.unwrapErrorToAnnotation(error.cause, seen)
+                    : error.cause,
+        };
+    }
+
     private generateErrorMessage(data: unknown) {
         return typeof data === 'object' ? JSON.stringify(data, jsonEscaper()) : (data?.toString() ?? '');
     }

packages/sdk-core/tests/report/reportTests.spec.ts

@@ -100,4 +100,94 @@ describe('Backtrace report generation tests', () => {
             expect(messageReport.stackTrace[name]).toEqual(expect.objectContaining(expected));
         });
     });
+
+    describe('error annotation cause unwrapping', () => {
+        type ErrorWithCause = Error & { cause?: unknown };
+
+        /**
+         * This function is a helper to fix a potential type issue between different
+         * version of TypeScript's built-in Error type, which may or may not include the `cause` property.
+         */
+        function createError(message: string, cause?: unknown): ErrorWithCause {
+            const error: ErrorWithCause = new Error(message);
+            error.cause = cause;
+            return error;
+        }
+
+        it('should include cause in error annotation', () => {
+            const causeMessage = 'cause';
+            const cause = new Error(causeMessage);
+            const error = createError('top level', cause);
+            const report = new BacktraceReport(error);
+
+            const annotation = report.annotations['error'] as ErrorWithCause;
+            const causeAnnotation = annotation.cause as ErrorWithCause;
+            expect(causeAnnotation.message).toBe(causeMessage);
+            expect(causeAnnotation.name).toBe('Error');
+        });
+
+        it('should unwrap nested cause chain', () => {
+            const root = new Error('root');
+            const mid = createError('mid', root);
+            const top = createError('top', mid);
+            const report = new BacktraceReport(top);
+
+            const annotation = report.annotations['error'] as ErrorWithCause;
+            const midAnnotation = annotation.cause as ErrorWithCause;
+            const rootAnnotation = midAnnotation.cause as ErrorWithCause;
+            expect(midAnnotation.message).toBe(mid.message);
+            expect(rootAnnotation.message).toBe(root.message);
+            expect(rootAnnotation.cause).toBeUndefined();
+        });
+
+        it('should handle circular cause without stack overflow', () => {
+            const topLevelError = createError('error a');
+            const cause = createError('error b');
+            topLevelError.cause = cause;
+            cause.cause = topLevelError;
+
+            const report = new BacktraceReport(topLevelError);
+
+            const annotation = report.annotations['error'] as ErrorWithCause;
+            const causeAnnotation = annotation.cause as ErrorWithCause;
+            expect(causeAnnotation.message).toBe(cause.message);
+            // circular reference back to `topLevelError` — not recursed, produces circular placeholder
+            expect(causeAnnotation.cause).toEqual(`[Circular] ${topLevelError.message}`);
+        });
+
+        it('should handle self-referencing cause without stack overflow', () => {
+            const error = createError('self');
+            error.cause = error;
+
+            const report = new BacktraceReport(error);
+
+            const annotation = report.annotations['error'] as ErrorWithCause;
+            // cause points to itself — not recursed, produces circular placeholder
+            expect(annotation.cause).toEqual(`[Circular] ${error.message}`);
+        });
+
+        it('should handle non-Error cause as string value', () => {
+            const error = createError('fail', 'timeout');
+            const report = new BacktraceReport(error);
+
+            const annotation = report.annotations['error'] as ErrorWithCause;
+            expect(annotation.cause).toEqual('timeout');
+        });
+
+        it('should handle non-Error object cause as string value', () => {
+            const error = createError('fail', { code: 'ENOENT' });
+            const report = new BacktraceReport(error);
+
+            const annotation = report.annotations['error'] as ErrorWithCause;
+            expect(annotation.cause).toEqual({ code: 'ENOENT' });
+        });
+
+        it('should set cause to undefined when no cause exists', () => {
+            const error = new Error('no cause');
+            const report = new BacktraceReport(error);
+
+            const annotation = report.annotations['error'] as ErrorWithCause;
+            expect(annotation.cause).toBeUndefined();
+        });
+    });
 });