KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #codex #claude-code #cli #react #mcp #open-source #deepseek-harness #dsh-plugin #ai

sentry-testkit

★ 115 Open GitHub ↗

A Sentry plugin to allow Sentry report interception and further inspection of the data being sent

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Test what your app reports to [Sentry](https://sentry.io/welcome/) — without sending anything to Sentry's servers.

When building tests for your application you want to assert that the right flow-tracking or error is being sent to _Sentry_, **but** without really sending it and swamping your Sentry project with false reports from test runs and CI.

## Sentry Testkit — to the rescue

_Sentry Testkit_ enables Sentry to work natively in your application while running tests: reports are intercepted and logged into memory instead of being sent over the wire. Your tests can then fetch and assert on everything that was (or wasn't) captured:

- **Errors and messages** — `captureException`, `captureMessage`, breadcrumbs, tags, extra, user
- **Performance transactions and spans** — names, ops, attributes, span trees
- **Structured logs** — everything sent via `Sentry.logger.*`
- **Feature flags** — which flags were evaluated when an error was captured
- **Async-safe assertions** — built-in `waitFor*` helpers, no sleeps and no flaky tests

## Installation

**npm:**
```sh
npm install sentry-testkit --save-dev
```
**yarn:**
```sh
yarn add sentry-testkit --dev
```

Requires Sentry JavaScript SDK **v9 or v10**. Using Sentry v8? Stay on `sentry-testkit@6` or see the [v7 migration guide](https://zivl.github.io/sentry-testkit/docs/migration/version-7).

## Usage

```javascript
// some.spec.js
const sentryTestkit = require('sentry-testkit')

const { testkit, sentryTransport } = sentryTestkit()

// initialize your Sentry instance with sentryTransport
Sentry.init({
    dsn: 'some_dummy_dsn',
    transport: sentryTransport,
    enableLogs: true, // if you want to test Sentry.logger.* calls
    //... other configurations
})

test('collects error events', async function () {
  // run any scenario that eventually calls Sentry.captureException(...)
  const reports = await testkit.waitForReports(1)
  expect(reports[0].error.message).toEqual('something went wrong')
})

test('collects performance events', async function () {
  // run any scenario that eventually starts and ends a span
  await testkit.waitForTransactions(1)
  expect(testkit.findTransaction('checkout-flow')).toBeDefined()
})

test('collects structured logs', async function () {
  Sentry.logger.info('user logged in', { userId: 42 })
  await Sentry.flush()
  expect(testkit.logs()[0].attributes.userId).toEqual(42)
})
```

More querying power when you need it:

```javascript
testkit.findReportByMessage(/user \d+/)
testkit.reportsWithTag('section', 'billing')
testkit.transactionsWithTag('flow', 'signup')
testkit.reports()[0].flags // [{ flag: 'new-checkout', result: true }]
testkit.reset()            // clean state between tests
```

## Integration modes

The custom transport shown above is the most common setup, but the testkit can intercept Sentry traffic in whichever way fits your test environment:

| Mode | Use case |
|------|----------|
| **Transport** (`sentryTransport`) | Unit/integration tests — replaces Sentry's HTTP sender |
| **Browser entry** (`sentry-testkit/browser`) | Same as transport, without any Node.js dependencies |
| **Local server** (`localServer`) | A real local endpoint that mimics Sentry's API and generates a local DSN |
| **Puppeteer** (`testkit.puppeteer`) | E2E tests — captures the page's Sentry requests |
| **Network interception** (`initNetworkInterceptor`) | Bring your own interceptor (nock, MSW, ...) |
| **Jest mock** (`sentry-testkit/dist/jestMock`) | Auto-injects the testkit as `global.testkit` |

### Running in browser

`sentry-testkit` relies on `express` and `http` packages from NodeJS. We have a separate entry `sentry-testkit/browser` which does not include any NodeJS-related code:

```javascript
const sentryTestkit = require('sentry-testkit/browser')

const { testkit } = sentryTestkit()
// Your code for browser
```

## Testkit API

See the full API description and documentation here: https://zivl.github.io/sentry-testkit/

## Roadmap

sentry-testkit is expanding to cover the full modern Sentry SDK surface — user feedback, cron check-ins, sessions, session replay, attachments, metrics, and more. Follow (or help shape) the plan in the [tracking issue](https://github.com/zivl/sentry-testkit/issues/313).

## Raven-Testkit

The good old legacy `raven-testkit` documentation can be found [here](https://github.com/zivl/sentry-testkit/blob/master/LEGACY_API.md). It is still there to serve `Raven`, which is the old legacy SDK of _Sentry_ for JavaScript/Node.js platforms.

## Change Log

We're constantly and automatically updating our [CHANGELOG](https://github.com/zivl/sentry-testkit/blob/master/packages/sentry-testkit/CHANGELOG.md) file, so it's always a good spot to check out what we have been up to...

## Contribution

We'd love any kind of contribution to get better, improve our capabilities, fix bugs, and bring more features as Sentry expands their tools as well. Please check our [CONTRIBUTING](https://github.com/zivl/sentry-testkit/blob/master/CONTRIBUTING.md) guidelines for more info and how to get started.

## License

Sentry Testkit is [MIT licensed](https://github.com/zivl/sentry-testkit/blob/master/LICENSE).

sentry-testkit

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README