feat(react): Export captureReactException method (#15746)

AbhiPrasad · web-flow · commit e9248e0caca9 · 2025-03-20T10:16:57.000-04:00
This PR exports the `captureReactException` method from the React
package, making it available as a public API. Additionally, it refactors
the implementation to use `withScope` instead of directly passing
context to `captureException`. This was done so that the arguments to
`captureReactException` better align to `captureException`.

Users can now directly access and use this method in their applications:

```javascript
import * as Sentry from '@sentry/react';

class ErrorBoundary extends React.Component {
  componentDidCatch(error, info) {
    Sentry.captureReactException(error, info);
  }

  render() {
    return this.props.children;
  }
}
```

The reason why `captureReactException` is named as such and not
`captureReactErrorBoundaryException` is because it can be used in other
scenarios as well, like with the new React 19 error APIs. Therefore it
was generalized to just be `captureReactException`.
diff --git a/packages/react/src/error.ts b/packages/react/src/error.ts
@@ -1,6 +1,5 @@
-import { captureException } from '@sentry/browser';
+import { captureException, withScope } from '@sentry/browser';
 import { isError } from '@sentry/core';
-import type { EventHint } from '@sentry/core';
 import { version } from 'react';
 import type { ErrorInfo } from 'react';
 
@@ -46,7 +45,7 @@ export function captureReactException(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   error: any,
   { componentStack }: ErrorInfo,
-  hint?: EventHint,
+  hint?: Parameters<typeof captureException>[1],
 ): string {
   // If on React version >= 17, create stack trace from componentStack param and links
   // to to the original error using `error.cause` otherwise relies on error param for stacktrace.
@@ -65,11 +64,9 @@ export function captureReactException(
     setCause(error, errorBoundaryError);
   }
 
-  return captureException(error, {
-    ...hint,
-    captureContext: {
-      contexts: { react: { componentStack } },
-    },
+  return withScope(scope => {
+    scope.setContext('react', { componentStack });
+    return captureException(error, hint);
   });
 }
 
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
@@ -1,7 +1,7 @@
 export * from '@sentry/browser';
 
 export { init } from './sdk';
-export { reactErrorHandler } from './error';
+export { captureReactException, reactErrorHandler } from './error';
 export { Profiler, withProfiler, useProfiler } from './profiler';
 export type { ErrorBoundaryProps, FallbackRender } from './errorboundary';
 export { ErrorBoundary, withErrorBoundary } from './errorboundary';
diff --git a/packages/react/test/errorboundary.test.tsx b/packages/react/test/errorboundary.test.tsx
@@ -12,6 +12,8 @@ import { useState } from 'react';
 import type { ErrorBoundaryProps, FallbackRender } from '../src/errorboundary';
 import { ErrorBoundary, UNKNOWN_COMPONENT, withErrorBoundary } from '../src/errorboundary';
 
+const mockScope = new Scope();
+const scopeSetContextSpy = vi.spyOn(mockScope, 'setContext');
 const mockCaptureException = vi.fn();
 const mockShowReportDialog = vi.fn();
 const mockClientOn = vi.fn();
@@ -27,6 +29,9 @@ vi.mock('@sentry/browser', async requireActual => {
     showReportDialog: (options: any) => {
       mockShowReportDialog(options);
     },
+    withScope: (callback: (scope: any) => any) => {
+      return callback(mockScope);
+    },
   };
 });
 
@@ -102,6 +107,7 @@ describe('ErrorBoundary', () => {
     mockCaptureException.mockClear();
     mockShowReportDialog.mockClear();
     mockClientOn.mockClear();
+    (mockScope.setContext as any).mockClear();
   });
 
   it('renders null if not given a valid `fallback` prop', () => {
@@ -265,20 +271,19 @@ describe('ErrorBoundary', () => {
 
       expect(mockCaptureException).toHaveBeenCalledTimes(1);
       expect(mockCaptureException).toHaveBeenLastCalledWith(expect.any(Error), {
-        captureContext: {
-          contexts: { react: { componentStack: expect.any(String) } },
-        },
         mechanism: { handled: true },
       });
 
+      expect(scopeSetContextSpy).toHaveBeenCalledTimes(1);
+      expect(scopeSetContextSpy).toHaveBeenCalledWith('react', { componentStack: expect.any(String) });
+
       expect(mockOnError.mock.calls[0]?.[0]).toEqual(mockCaptureException.mock.calls[0]?.[0]);
 
       // Check if error.cause -> react component stack
       const error = mockCaptureException.mock.calls[0]?.[0];
       const cause = error.cause;
-      expect(cause.stack).toEqual(
-        mockCaptureException.mock.calls[0]?.[1]?.captureContext.contexts.react.componentStack,
-      );
+
+      expect(cause.stack).toEqual(scopeSetContextSpy.mock.calls[0]?.[1]?.componentStack);
       expect(cause.name).toContain('React ErrorBoundary');
       expect(cause.message).toEqual(error.message);
     });
@@ -325,12 +330,12 @@ describe('ErrorBoundary', () => {
 
       expect(mockCaptureException).toHaveBeenCalledTimes(1);
       expect(mockCaptureException).toHaveBeenLastCalledWith('bam', {
-        captureContext: {
-          contexts: { react: { componentStack: expect.any(String) } },
-        },
         mechanism: { handled: true },
       });
 
+      expect(scopeSetContextSpy).toHaveBeenCalledTimes(1);
+      expect(scopeSetContextSpy).toHaveBeenCalledWith('react', { componentStack: expect.any(String) });
+
       // Check if error.cause -> react component stack
       const error = mockCaptureException.mock.calls[0]?.[0];
       expect(error.cause).not.toBeDefined();
@@ -364,21 +369,19 @@ describe('ErrorBoundary', () => {
 
       expect(mockCaptureException).toHaveBeenCalledTimes(1);
       expect(mockCaptureException).toHaveBeenLastCalledWith(expect.any(Error), {
-        captureContext: {
-          contexts: { react: { componentStack: expect.any(String) } },
-        },
         mechanism: { handled: true },
       });
 
+      expect(scopeSetContextSpy).toHaveBeenCalledTimes(1);
+      expect(scopeSetContextSpy).toHaveBeenCalledWith('react', { componentStack: expect.any(String) });
+
       expect(mockOnError.mock.calls[0]?.[0]).toEqual(mockCaptureException.mock.calls[0]?.[0]);
 
       const thirdError = mockCaptureException.mock.calls[0]?.[0];
       const secondError = thirdError.cause;
       const firstError = secondError.cause;
       const cause = firstError.cause;
-      expect(cause.stack).toEqual(
-        mockCaptureException.mock.calls[0]?.[1]?.captureContext.contexts.react.componentStack,
-      );
+      expect(cause.stack).toEqual(scopeSetContextSpy.mock.calls[0]?.[1]?.componentStack);
       expect(cause.name).toContain('React ErrorBoundary');
       expect(cause.message).toEqual(thirdError.message);
     });
@@ -410,20 +413,18 @@ describe('ErrorBoundary', () => {
 
       expect(mockCaptureException).toHaveBeenCalledTimes(1);
       expect(mockCaptureException).toHaveBeenLastCalledWith(expect.any(Error), {
-        captureContext: {
-          contexts: { react: { componentStack: expect.any(String) } },
-        },
         mechanism: { handled: true },
       });
 
+      expect(scopeSetContextSpy).toHaveBeenCalledTimes(1);
+      expect(scopeSetContextSpy).toHaveBeenCalledWith('react', { componentStack: expect.any(String) });
+
       expect(mockOnError.mock.calls[0]?.[0]).toEqual(mockCaptureException.mock.calls[0]?.[0]);
 
       const error = mockCaptureException.mock.calls[0]?.[0];
       const cause = error.cause;
       // We need to make sure that recursive error.cause does not cause infinite loop
-      expect(cause.stack).not.toEqual(
-        mockCaptureException.mock.calls[0]?.[1]?.captureContext.contexts.react.componentStack,
-      );
+      expect(cause.stack).not.toEqual(scopeSetContextSpy.mock.calls[0]?.[1]?.componentStack);
       expect(cause.name).not.toContain('React ErrorBoundary');
     });
 
@@ -580,11 +581,11 @@ describe('ErrorBoundary', () => {
 
         expect(mockCaptureException).toHaveBeenCalledTimes(1);
         expect(mockCaptureException).toHaveBeenLastCalledWith(expect.any(Object), {
-          captureContext: {
-            contexts: { react: { componentStack: expect.any(String) } },
-          },
           mechanism: { handled: expected },
         });
+
+        expect(scopeSetContextSpy).toHaveBeenCalledTimes(1);
+        expect(scopeSetContextSpy).toHaveBeenCalledWith('react', { componentStack: expect.any(String) });
       },
     );
   });
