API Reference

Sentry Testkit consists of a very simple and strait-forward API using the following functions

Methods

Capture and assertions

• reports() — captured errors and messages
• transactions() — captured performance transactions
• logs() — captured structured logs
• feedback() — captured user feedback
• checkIns() — captured cron monitor check-ins

Awaiting asynchronously-sent data

• waitForReports(count, options) — and its siblings waitForTransactions, waitForLogs, waitForFeedback, waitForCheckIns

Finding and filtering

• findReport(error)
• findReportByMessage(message)
• findTransaction(name)
• reportsWithTag(key, value) — and transactionsWithTag(key, value)
• isExist(error)
• getExceptionAt(index)

Utilities

• reset()

What About Nodejs? - Of Course!

Sentry Testkit has full support in both @sentry/browser and @sentry/node (as well as other @sentry/<what-ever> clients) since they have the same API and lifecycle under the hood.

Raven-Testkit

The good old legacy raven-testkit documentation can be found here. It it still there to serve Raven which is the old legacy SDK of Sentry for JavaScript/Node.js platforms

Reference

reports()

Gets all existing reports.

Returns: Array - where each member of the array consists of Sentry's Report type.

See: You may refer to the definition of Report for further explanation and details.

For example

const waitForExpect = require('wait-for-expect')

test('reports example', async function() {
    // Some scenario that will report the exceptions...

    await waitForExpect(() => expect(testkit.reports().length).toBeGreaterThan(0))
    const reports = testkit.reports()

    // Do what ever you want with the reports list
})

info

Here we use wait-for-expect library to emphasize that sometimes we need to wait until the report is being sent as it is done asynchronously. You can also use the built-in waitForReports helper instead.

Each report also exposes evaluated feature flags as report.flags — an array of { flag, result } objects taken from the event's contexts.flags, or an empty array when no flags were attached:

expect(testkit.reports()[0].flags).toEqual([{ flag: 'new-checkout', result: true }])

waitForReports(count, options)

Waits until at least count reports have been captured. This replaces "sleep then assert" patterns and third-party polling helpers — Sentry transports are asynchronous, so reports may not be captured yet when your assertion runs.

Arguments

• count: Number - the minimum number of reports to wait for
• options: Object (optional) - { timeout: Number }, defaults to { timeout: 1000 } (milliseconds)

Returns: Promise<Array> - resolves with the captured reports once the count is reached; rejects with a descriptive error if the timeout elapses first.

For example

test('waitForReports example', async function() {
    Sentry.captureException(new Error('sentry test kit is awesome!'))

    const reports = await testkit.waitForReports(1)
    expect(reports[0].error.message).toEqual('sentry test kit is awesome!')
})

Sibling helpers with the same signature exist for the other captured types: waitForTransactions(count, options) and waitForLogs(count, options).

findReport(error)

Finds a report by a given error.

Uses Array.prototype.find under the hood

Arguments

• error: Error - An error object to look for in the reports

Returns: Report | undefined - the report object if one found. undefined otherwise.

See: You may refer to the definition of Report for further explanation and details.

For example

test('findReport example', async function() {
    const err = new Error('error to look for')

    // Some faulty scenario that will report err

    const report = testkit.findReport(err)
    expect(report).toBeDefined()
})

findReportByMessage(message)

Finds a report by its message — either a captureMessage message or a captured error's message.

Arguments

• message: String | RegExp - exact message to match, or a regular expression to test against

Returns: Report | undefined - the first matching report. undefined otherwise.

For example

test('findReportByMessage example', async function() {
    Sentry.captureException(new Error('failed to fetch user 42'))
    await testkit.waitForReports(1)

    expect(testkit.findReportByMessage(/user \d+/)).toBeDefined()
})

findTransaction(name)

Finds a transaction by its name.

Arguments

• name: String | RegExp - exact transaction name to match, or a regular expression to test against

Returns: Transaction | undefined - the first matching transaction. undefined otherwise.

For example

test('findTransaction example', async function() {
    Sentry.startInactiveSpan({ op: 'transaction', name: 'checkout-flow' }).end()
    await testkit.waitForTransactions(1)

    expect(testkit.findTransaction(/^checkout/)).toBeDefined()
})

reportsWithTag(key, value)

Gets all reports carrying a given tag, optionally with a specific value.

Arguments

• key: String - the tag key to look for
• value: String (optional) - when provided, only reports whose tag equals this value are returned

Returns: Array - the matching reports (empty array when none match).

For example

test('reportsWithTag example', async function() {
    Sentry.withScope(scope => {
        scope.setTag('section', 'billing')
        Sentry.captureException(new Error('tagged error'))
    })
    await testkit.waitForReports(1)

    expect(testkit.reportsWithTag('section', 'billing')).toHaveLength(1)
})

A sibling helper with the same signature exists for transactions: transactionsWithTag(key, value).

isExist(error)

Checks whether a given error exist (i.e. has been reported)

Arguments

• error: Error - An error object to look for in the reports

Returns: Boolean - true if the error exists. false otherwise.

For example

 test('isExist example', async function() {
    const err = new Error('error to look for')
    Sentry.captureException(err)
    await waitForExpect(() => expect(testkit.reports()).toHaveLength(1))
    expect(testkit.isExist(err)).toBe(true)
})

getExceptionAt(index)

Extracts the exception object of a report in a specific position.

Arguments

• index : Number - index position of the report.

Returns: ReportError.

See: You may refer to the definition of ReportError for further explanation and details.

For example

test('getExceptionAt example', async function() {
    Sentry.captureException(new Error('testing get exception at index 0'))
    Sentry.captureException(new Error('testing get exception at index 1'))
    await waitForExpect(() => expect(testkit.reports()).toHaveLength(2))
    const { message } = testkit.getExceptionAt(1)
    expect(message).toEqual('testing get exception at index 1')
})

transactions()

Gets all existing transactions.

Returns: Array - where each member of the array consists of a Transaction type.

See: You may refer to the definition of Transaction for further explanation and details.

For example

test('transactions example', async function() {
    // Some scenario that will create a transaction...

    await waitForExpect(() => expect(testkit.transactions().length).toBeGreaterThan(0))
    const transactions = testkit.transactions()

    // Do what ever you want with the transactions
})

logs()

Gets all captured structured logs (requires enableLogs: true in Sentry.init).

Returns: Array - where each member of the array consists of a Log type:

Field	Type	Description
level	string	trace | debug | info | warn | error | fatal
message	string	The log body
attributes	Object	Log attributes as plain values, e.g. { userId: 42 }
timestamp	number	Epoch time in seconds
traceId	string	The trace this log belongs to, if any
severityNumber	number	The numeric severity, if any
originalLog	Object	The raw log item as sent by the SDK

For example

test('logs example', async function() {
    Sentry.logger.info('user logged in', { userId: 42 })
    await Sentry.flush()

    const [log] = testkit.logs()
    expect(log.level).toEqual('info')
    expect(log.message).toEqual('user logged in')
    expect(log.attributes.userId).toEqual(42)
})

feedback()

Gets all captured user feedback submitted via Sentry.captureFeedback(...) or the feedback widget.

Returns: Array - where each member of the array consists of a FeedbackReport type:

Field	Type	Description
message	string	The feedback message
name	string	The submitter's name, if provided
contactEmail	string	The submitter's email, if provided
url	string	The page the feedback was submitted from, if provided
associatedEventId	string	The id of the error event this feedback is linked to, if any
source	string	The feedback source, if provided
replayId	string	The associated replay id, if any
eventId	string	The feedback event's own id
originalFeedback	Object	The raw feedback event as sent by the SDK

For example

test('feedback example', async function() {
    Sentry.captureFeedback({ message: 'the checkout page is confusing', email: 'jane@example.com' })

    const [feedback] = await testkit.waitForFeedback(1)
    expect(feedback.message).toEqual('the checkout page is confusing')
    expect(feedback.contactEmail).toEqual('jane@example.com')
})

checkIns()

Gets all captured cron monitor check-ins reported via Sentry.captureCheckIn(...) or Sentry.withMonitor(...).

Returns: Array - where each member of the array consists of a CheckIn type:

Field	Type	Description
checkInId	string	The check-in id (used to correlate an in_progress with its ok/error)
monitorSlug	string	The monitor's slug
status	string	in_progress | ok | error
duration	number	The check-in duration in seconds, for a finished check-in
release	string	The release, if set
environment	string	The environment, if set
originalCheckIn	Object	The raw check-in payload as sent by the SDK

For example

test('check-in example', async function() {
    const checkInId = Sentry.captureCheckIn({ monitorSlug: 'nightly-report', status: 'in_progress' })
    Sentry.captureCheckIn({ checkInId, monitorSlug: 'nightly-report', status: 'ok', duration: 12.5 })

    const checkIns = await testkit.waitForCheckIns(2)
    expect(checkIns.map(c => c.status)).toEqual(['in_progress', 'ok'])
})

reset()

Resets the testkit state and clear all existing reports.

For example

test('reset example', async function() {
    Sentry.captureException(new Error('Sentry test kit is awesome!'))
    await waitForExpect(() => expect(testkit.reports()).toHaveLength(1))
    expect(testkit.reports()).toHaveLength(1)
    testkit.reset()
    expect(testkit.reports()).toHaveLength(0)
})

tip

Calling reset() is very useful to run between tests, see more info and examples here