How to Contribute: Browser SDK Integration Testing Guide for Sentry

Overview

Sentry's browser SDK integration tests run with Playwright on the latest stable releases of Chromium, Firefox, and WebKit.

Structure

Tests are grouped by scope (e.g., breadcrumbs or onunhandledrejection). Each group contains a folder with one or more test‑case subfolders and optional resources.

Every group provides a default template.hbs HTML skeleton and a default init.js script that calls Sentry.init(). If a test case does not define its own template.hbs or init.js, the group defaults are used.

The subject.js file contains the logic that sets up the test environment. It can be defined locally as a fallback. Unlike template.hbs and init.js, subject.js is optional because the injectScriptAndGetEvents helper from utils/helpers.ts can inject the script instead.

Each test case requires a test.ts file that holds the assertions and, if needed, script‑injection logic. Local definitions of init.js, template.hbs and subject.js take precedence over the group defaults.

Helpers

The utils/helpers.ts module provides reusable helper functions used inside test.ts. These helpers expose a convenient API for interacting with Playwright’s native API.

Fixtures

Fixtures allow defining global and test‑specific information inside test.ts. The current fixtures.ts extends the pure version of Playwright’s test() function. All tests should import utils/fixtures.ts instead of the @playwright/test exported sentryTest function so that the additional Sentry‑specific fixtures are available.

Running Tests Locally

Run the tests with the default Chromium browser: yarn test Run the tests with a different browser, for example Firefox or WebKit:

yarn test --browser='firefox'
yarn test --browser='webkit'

Run the tests on all three browsers: yarn test --browser='all' Filter tests by title:

yarn test -g "XMLHttpRequest without any handlers set"

Additional CLI options are documented in the Playwright documentation.

Troubleshooting

Unstable Tests

If tests fail randomly with errors such as Page Closed, Target Closed, or similar, the typical cause is a race condition between the page action defined in subject and the Sentry event/request listeners. First, check whether the asynchronous logic in utils/helpers.ts can be replaced by a helper. If not, consider orchestrating the waiting with Promise.all (or deliberately not waiting) using Playwright methods. Manual timeout logic is discouraged.

Build Errors

Before a test runs, each test case’s page is built under dist/case. If the build fails, verify the following:

Whether the test group defines the default template.hbs and init.js files.

Whether the test case defines a subject.js file.

If either init.js or subject.js contains non‑browser code.

Whether the webpack configuration is valid.

Practical Walk‑through

Clone the Sentry JavaScript repository:

https://github.com/getsentry/sentry-javascript.git

Install Dependencies

cd sentry-javascript
yarn
yarn lerna bootstrap
yarn build

Run Playwright Integration Tests

Enter the integration‑test package:

cd packages/integration-tests
# PWDEBUG=1 yarn test  → opens Playwright Inspector
yarn test