Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/getsentry/sentry-javascript/llms.txt

Use this file to discover all available pages before exploring further.

The Sentry JavaScript SDK has comprehensive test coverage including unit tests, integration tests, and E2E tests. This guide explains how to run them all.
You must run yarn build before yarn test will work, as tests depend on built type definitions.

​
Unit Tests

​
Run All Unit Tests

From the repository root: 
yarn test
This runs unit tests for all packages except integration and E2E test packages: 
"test": "nx run-many -t test --exclude \"@sentry-internal/{browser-integration-tests,e2e-tests,integration-shims,node-integration-tests,node-core-integration-tests,cloudflare-integration-tests}\""

​
Run Tests for a Single Package

Navigate to the package directory and run tests: 
cd packages/core
yarn test
Or run tests with coverage: 
cd packages/core
yarn test:watch  # Watch mode for development

​
Run Tests for Changed Packages

To run tests only for packages affected by your changes: 
yarn test:pr

​
Test Configuration

Tests are run with Vitest. Each package has a test script in its package.json: 
"scripts": {
  "test": "vitest run",
  "test:watch": "vitest --watch"
}

​
Integration Tests

Integration tests verify SDK behavior in real runtime environments.

​
Browser Integration Tests

Test browser-specific functionality using Playwright: 
cd dev-packages/browser-integration-tests
yarn test

​
Node.js Integration Tests

Test Node.js-specific functionality: 
cd dev-packages/node-integration-tests
yarn test

​
Cloudflare Integration Tests

Test Cloudflare Workers functionality: 
cd dev-packages/cloudflare-integration-tests
yarn test

​
E2E Tests

E2E tests verify SDK behavior in real-world framework scenarios using a local npm registry (Verdaccio).

​
Prerequisites

  1. Docker - Required to run the Verdaccio registry container
  2. Volta with pnpm support - Enable with VOLTA_FEATURE_PNPM=1

​
Setup

  1. Build packages and create tarballs:
yarn build
yarn build:tarball
You must re-run yarn build:tarball after any changes to packages for the changes to take effect in E2E tests.
  1. Configure environment (optional):
cd dev-packages/e2e-tests
cp .env.example .env
# Fill in Sentry project auth info if running tests that send data to Sentry

​
Run E2E Tests

Run all E2E tests: 
yarn test:e2e
Run a specific test application: 
yarn test:run <app-name>
# Example: yarn test:run nextjs-app-dir
Run with a specific variant: 
yarn test:run <app-name> --variant <variant-name>
# Example: yarn test:run nextjs-pages-dir --variant 15

​
How E2E Tests Work

  1. A fake npm registry (Verdaccio) is launched in Docker
  2. SDK packages are built, packed, and published to Verdaccio
  3. Test applications install packages from Verdaccio
  4. Tests run against the test applications
This ensures tests use your local changes, not published versions from npm.

​
E2E Test Structure

Test applications live in dev-packages/e2e-tests/test-applications/: 
dev-packages/e2e-tests/
├── test-applications/
│   ├── nextjs-app-dir/
│   │   ├── .npmrc              # Points to Verdaccio
│   │   ├── package.json        # Uses "latest || *" for @sentry/*
│   │   └── test-recipe.json    # Build and test commands
│   ├── react-router-6/
│   └── ...
└── README.md

​
Important: The .npmrc File

Every E2E test application must have an .npmrc file: 
@sentry:registry=http://127.0.0.1:4873
@sentry-internal:registry=http://127.0.0.1:4873
Without this file, pnpm will install packages from the public npm registry instead of your local Verdaccio instance, causing tests to use published versions instead of your local changes.
To verify packages are from Verdaccio, check: 
cat node_modules/@sentry/browser/package.json | grep version
# Should show: "0.0.0-pr.12345" (Verdaccio)
# NOT: "8.0.0" (public npm)

​
Testing Locally

To test local SDK versions in external test projects, you have several options: Symlink your local package: 
cd packages/browser
yarn link

cd /path/to/your/project
yarn link @sentry/browser

​
Option 2: yalc

Use yalc to install packages as if they were published: 
# In the SDK repo
cd packages/browser
yarn yalc:publish

# In your project
yalc add @sentry/browser
See docs/using-yalc.md for details.

​
Option 3: Tarballs

Install from a tarball: 
# In the SDK repo
yarn build:tarball

# In your project
yarn add /path/to/sentry-javascript/packages/browser/sentry-browser-*.tgz

​
CI Testing

​
Browser Tests

yarn test:ci:browser

​
Node Tests

yarn test:ci:node

​
Bun Tests

yarn test:ci:bun

​
Adding Tests

Any non-trivial fixes/features should include tests. You’ll find a test/ folder in each package.

​
Unit Tests

Add tests in the package’s test/ directory: 
packages/core/
├── src/
│   └── hub.ts
└── test/
    └── lib/
        └── hub.test.ts

​
Integration Tests

  • Browser changes: Add tests in dev-packages/browser-integration-tests
  • Node changes: Add tests in dev-packages/node-integration-tests
  • E2E tests: Add test apps in dev-packages/e2e-tests/test-applications

​
Common Issues

​
Tests fail after SDK changes

Rebuild packages: 
yarn build:dev
yarn test

​
E2E tests use wrong package versions

  1. Check for .npmrc file in test application
  2. Rebuild tarballs: yarn build && yarn build:tarball
  3. Delete node_modules in test app and re-run

​
Docker/Verdaccio issues

  • Ensure Docker daemon is running
  • Check port 4873 is not in use: lsof -i :4873
  • Stop existing containers: docker ps && docker stop <container-id>

​
Type errors in tests

Ensure types are built: 
yarn build:dev

​
Debugging Tests

  1. Enable debug mode: Add debug: true to Sentry config
  2. Check browser console: Look for SDK initialization errors
  3. Inspect network requests: Verify events are sent correctly
  4. Check installed versions: Verify package versions in node_modules

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us