doc: E2E testing documentation updates

.cursor/rules/sdk_development.mdc

@@ -121,6 +121,54 @@ Each package typically contains:
 - Integration tests use Playwright extensively
 - Never change the volta, yarn, or package manager setup in general unless explicitly asked for
 
+### E2E Testing
+
+E2E tests are located in `dev-packages/e2e-tests/` and verify SDK behavior in real-world framework scenarios.
+
+#### How Verdaccio Registry Works
+
+E2E tests use [Verdaccio](https://verdaccio.org/), a lightweight npm registry running in Docker. Before tests run:
+
+1. SDK packages are built and packed into tarballs (`yarn build && yarn build:tarball`)
+2. Tarballs are published to Verdaccio at `http://127.0.0.1:4873`
+3. Test applications install packages from Verdaccio instead of public npm
+
+#### The `.npmrc` Requirement
+
+Every E2E test application needs an `.npmrc` file with:
+
+```
+@sentry:registry=http://127.0.0.1:4873
+@sentry-internal:registry=http://127.0.0.1:4873
+```
+
+Without this file, pnpm installs from the public npm registry instead of Verdaccio, so your local changes won't be tested. This is a common cause of "tests pass in CI but fail locally" or vice versa.
+
+#### Running a Single E2E Test
+
+```bash
+# Build packages first
+yarn build && yarn build:tarball
+
+# Run a specific test app
+cd dev-packages/e2e-tests
+yarn test:run <app-name>
+
+# Run with a specific variant (e.g., Next.js 15)
+yarn test:run <app-name> --variant <variant-name>
+```
+
+#### Common Pitfalls and Debugging
+
+1. **Missing `.npmrc`**: Most common issue. Always verify the test app has the correct `.npmrc` file.
+
+2. **Stale tarballs**: After SDK changes, must re-run `yarn build:tarball`.
+
+3. **Debugging tips**:
+   - Check browser console logs for SDK initialization errors
+   - Use `debug: true` in Sentry config
+   - Verify installed package version: check `node_modules/@sentry/*/package.json`
+
 ### Notes for Background Tasks
 
 - Make sure to use [volta](https://volta.sh/) for development. Volta is used to manage the node, yarn and pnpm version used.

CLAUDE.md

@@ -120,6 +120,54 @@ Each package typically contains:
 - Integration tests use Playwright extensively
 - Never change the volta, yarn, or package manager setup in general unless explicitly asked for
 
+### E2E Testing
+
+E2E tests are located in `dev-packages/e2e-tests/` and verify SDK behavior in real-world framework scenarios.
+
+#### How Verdaccio Registry Works
+
+E2E tests use [Verdaccio](https://verdaccio.org/), a lightweight npm registry running in Docker. Before tests run:
+
+1. SDK packages are built and packed into tarballs (`yarn build && yarn build:tarball`)
+2. Tarballs are published to Verdaccio at `http://127.0.0.1:4873`
+3. Test applications install packages from Verdaccio instead of public npm
+
+#### The `.npmrc` Requirement
+
+Every E2E test application needs an `.npmrc` file with:
+
+```
+@sentry:registry=http://127.0.0.1:4873
+@sentry-internal:registry=http://127.0.0.1:4873
+```
+
+Without this file, pnpm installs from the public npm registry instead of Verdaccio, so your local changes won't be tested. This is a common cause of "tests pass in CI but fail locally" or vice versa.
+
+#### Running a Single E2E Test
+
+```bash
+# Build packages first
+yarn build && yarn build:tarball
+
+# Run a specific test app
+cd dev-packages/e2e-tests
+yarn test:run <app-name>
+
+# Run with a specific variant (e.g., Next.js 15)
+yarn test:run <app-name> --variant <variant-name>
+```
+
+#### Common Pitfalls and Debugging
+
+1. **Missing `.npmrc`**: Most common issue. Always verify the test app has the correct `.npmrc` file.
+
+2. **Stale tarballs**: After SDK changes, must re-run `yarn build:tarball`.
+
+3. **Debugging tips**:
+   - Check browser console logs for SDK initialization errors
+   - Use `debug: true` in Sentry config
+   - Verify installed package version: check `node_modules/@sentry/*/package.json`
+
 ### Notes for Background Tasks
 
 - Make sure to use [volta](https://volta.sh/) for development. Volta is used to manage the node, yarn and pnpm version used.

CONTRIBUTING.md

@@ -73,6 +73,89 @@ the tests in each location. Check out the `scripts` entry of the corresponding `
 
 Note: you must run `yarn build` before `yarn test` will work.
 
+## Running E2E Tests Locally
+
+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 pnpm in Volta by setting `VOLTA_FEATURE_PNPM=1` in your environment. See [Volta pnpm docs](https://docs.volta.sh/advanced/pnpm).
+
+### Step-by-Step Instructions
+
+1. **Build the SDK packages and create tarballs:**
+
+   ```bash
+   yarn build
+   yarn build:tarball
+   ```
+
+   Note: You must re-run `yarn build:tarball` after any changes to packages.
+
+2. **Set up environment (optional):**
+
+   ```bash
+   cd dev-packages/e2e-tests
+   cp .env.example .env
+   # Fill in Sentry project auth info if running tests that send data to Sentry
+   ```
+
+3. **Run all E2E tests:**
+
+   ```bash
+   yarn test:e2e
+   ```
+
+4. **Or run a specific test application:**
+
+   ```bash
+   yarn test:run <app-name>
+   # Example: yarn test:run nextjs-app-dir
+   ```
+
+5. **Run with a specific variant:**
+   ```bash
+   yarn test:run <app-name> --variant <variant-name>
+   # Example: yarn test:run nextjs-pages-dir --variant 15
+   ```
+
+### Common Issues and Troubleshooting
+
+#### Packages install from public npm instead of Verdaccio
+
+Every E2E test application **must** have an `.npmrc` file with:
+
+```
+@sentry:registry=http://127.0.0.1:4873
+@sentry-internal:registry=http://127.0.0.1:4873
+```
+
+Without this, pnpm will fetch packages from the public npm registry instead of the local Verdaccio instance, causing tests to use outdated/published versions instead of your local changes.
+
+#### Tests fail after making SDK changes
+
+Make sure to rebuild tarballs:
+
+```bash
+yarn build
+yarn build:tarball
+```
+
+#### Docker-related issues
+
+- Ensure Docker daemon is running
+- Check that port 4873 is not in use by another process
+- Try stopping and removing existing Verdaccio containers
+
+#### Debugging test failures
+
+1. Check browser console logs for SDK initialization errors
+2. Enable debug mode in the test app's Sentry config: `debug: true`
+3. Verify packages are installed from Verdaccio by checking the version in `node_modules/@sentry/*/package.json`
+
+For more details, see [dev-packages/e2e-tests/README.md](dev-packages/e2e-tests/README.md).
+
 ## Debug Build Flags
 
 Throughout the codebase, you will find a `__DEBUG_BUILD__` constant. This flag serves two purposes:

dev-packages/e2e-tests/README.md

@@ -88,6 +88,81 @@ EOF
 
 Make sure to add a `test:build` and `test:assert` command to the new app's `package.json` file.
 
+### The `.npmrc` File
+
+Every test application needs an `.npmrc` file (as shown above) to tell pnpm to fetch `@sentry/*` and `@sentry-internal/*` packages from the local Verdaccio registry. Without it, pnpm will install from the public npm registry and your local changes won't be tested - this is one of the most common causes of confusing test failures.
+
+To verify packages are being installed from Verdaccio, check the version in `node_modules/@sentry/*/package.json`. If it shows something like `0.0.0-pr.12345`, Verdaccio is working. If it shows a released version (e.g., `8.0.0`), the `.npmrc` is missing or incorrect.
+
+## Troubleshooting
+
+### Common Issues
+
+#### Tests fail with "Cannot find module '@sentry/...'" or use wrong package version
+
+1. Verify the test application has an `.npmrc` file (see above)
+2. Rebuild tarballs: `yarn build && yarn build:tarball`
+3. Delete `node_modules` in the test application and re-run the test
+
+#### Docker/Verdaccio issues
+
+- Ensure Docker daemon is running
+- Check that port 4873 is not already in use: `lsof -i :4873`
+- Stop any existing Verdaccio containers: `docker ps` and `docker stop <container-id>`
+- Check Verdaccio logs for errors
+
+#### Tests pass locally but fail in CI (or vice versa)
+
+- Most likely cause: missing `.npmrc` file
+- Verify all `@sentry/*` dependencies use `latest || *` version specifier
+- Check if the test relies on environment-specific behavior
+
+### Debugging Tips
+
+1. **Enable Sentry debug mode**: Add `debug: true` to the Sentry init config to see detailed SDK logs
+2. **Check browser console**: Look for SDK initialization errors or warnings
+3. **Inspect network requests**: Verify events are being sent to the expected endpoint
+4. **Check installed versions**: `cat node_modules/@sentry/browser/package.json | grep version`
+
+## Bundler-Specific Behavior
+
+Different bundlers handle environment variables and code replacement differently. This is important when writing tests or SDK code that relies on build-time constants.
+
+### Webpack
+
+- `DefinePlugin` replaces variables in your application code
+- **Does NOT replace values inside `node_modules`**
+- Environment variables must be explicitly defined
+
+### Vite
+
+- `define` option replaces variables in your application code
+- **Does NOT replace values inside `node_modules`**
+- `import.meta.env.VITE_*` variables are replaced at build time
+- For replacing values in dependencies, use `@rollup/plugin-replace`
+
+### Next.js
+
+- Automatically injects `process.env` via webpack/turbopack
+- Handles environment variables more seamlessly than raw webpack/Vite
+- Server and client bundles may have different environment variable access
+
+### `import.meta.env` Considerations
+
+- Only available in Vite and ES modules
+- Webpack and Turbopack do not have `import.meta.env`
+- SDK code accessing `import.meta.env` must use try-catch to handle environments where it doesn't exist
+
+```typescript
+// Safe pattern for SDK code
+let envValue: string | undefined;
+try {
+  envValue = import.meta.env.VITE_SOME_VAR;
+} catch {
+  // import.meta.env not available in this bundler
+}
+```
+
 Test apps in the folder `test-applications` will be automatically picked up by CI in the job `job_e2e_tests` (in `.github/workflows/build.yml`).
 The test matrix for CI is generated in `dev-packages/e2e-tests/lib/getTestMatrix.ts`.