@dynatrace/rum-javascript-sdk 1.331.18 → 1.333.2

package/docs/2-testing.md

@@ -0,0 +1,424 @@
+---
+title: Testing with Playwright
+---
+# Dynatrace RUM JavaScript Testing Framework for Playwright
+
+This framework provides a Playwright fixture for testing observability by interacting with the Dynatrace Real User Monitoring (RUM) API.
+
+## Setup Instructions
+
+Follow these steps to configure and use the framework:
+
+### 1. Create an Access Token
+1. Navigate to the **Access Tokens** app in Dynatrace.
+2. Create a new token with the following permission:
+    - **Permission**: `Read RUM manual insertion tags`
+    - **Scope**: `API V2`
+3. Copy the generated token for use in the next steps.
+
+### 2. Provide Required Parameters
+To use the framework, you need to provide the following details:
+- **Environment URL**: The URL of the Dynatrace API endpoint to connect to, see
+    [RUM manual insertion tags API](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/rum/rum-manual-insertion-tags)
+    for details. Example: _https://{your-environment-id}.live.dynatrace.com_ or
+    _https://{your-activegate-domain}/e/{your-environment-id}_
+  - **Application ID**: The application ID to identify the correct RUM JavaScript to fetch. You can find
+    this in the URL if you open the Experience Vitals app and select the frontend you
+    want to test. Example: APPLICATION-ABCDEF0123456789
+- **Token**: The API token created in Step 1.
+
+Populate your playwright config file with these fields or call `test.use` to provide them to a test suite, like so:
+```ts
+import { test } from "@dynatrace/rum-javascript-sdk/test";
+
+test.describe("my suite", () => {
+    test.use({
+        dynatraceConfig: {
+            appId: process.env.DT_APP_ID!,
+            token: process.env.DT_TOKEN!,
+            endpointUrl: process.env.DT_ENDPOINT_URL!
+        }
+    });
+});
+```
+
+### 3. Assert on events
+
+Use the provided `expect` functions to assert on events the RUM JavaScript should have sent:
+```ts
+test("expect specific event", async ({ page, dynatraceTesting }) => {
+    await page.goto("http://127.0.0.1:3000/ui");
+    await page.getByText("Explore data").first().click();
+    await dynatraceTesting.expectToHaveSentEvent(expect.objectContaining({
+        "event_properties.component_rendered": "Data"
+    }));
+});
+```
+
+## Important: Fixture Destructuring Order
+
+⚠️ **The order of fixture destructuring matters!**
+
+The `dynatraceTesting` fixture must be destructured **before** any custom fixtures that navigate the page. This ensures the RUM JavaScript is injected before navigation occurs.
+
+### ✅ Correct Order
+```typescript
+test("my test", async ({ dynatraceTesting, myCustomFixture, page }) => {
+    // dynatraceTesting is initialized first
+    // RUM script is injected via page.addInitScript
+    // Then myCustomFixture can safely navigate
+    await page.goto("https://example.com");
+});
+```
+
+### ❌ Incorrect Order
+```typescript
+test("my test", async ({ myCustomFixture, dynatraceTesting, page }) => {
+    // If myCustomFixture navigates the page, it happens BEFORE
+    // dynatraceTesting is initialized, so RUM script is not injected
+    // This will cause the test to fail with "no events received"
+});
+```
+
+### Why This Happens
+
+Playwright initializes fixtures in the order they appear in the destructuring pattern. The `dynatraceTesting` fixture uses `page.addInitScript()` to inject the RUM JavaScript, which only affects subsequent page navigations.
+
+### Custom Fixtures That Navigate
+
+If you have custom fixtures that call `page.goto()`, always destructure `dynatraceTesting` first:
+
+```typescript
+// Define custom fixture
+const test = base.extend<{ myApp: MyApp }>({
+    myApp: async ({ page }, use) => {
+        await page.goto("https://myapp.com");  // Navigation happens here
+        await use(new MyApp(page));
+    }
+});
+
+// Use fixtures in correct order
+test("test", async ({ dynatraceTesting, myApp }) => {
+    // ✅ Correct: dynatraceTesting initialized before myApp
+});
+```
+
+## Troubleshooting
+
+The test fixture works by intercepting network requests to the RUM ingestion endpoint and capturing
+the events sent by the RUM JavaScript.
+Note that this has an impact on your capturing environment, since these beacons report real data.
+
+### Missing Configuration Error
+
+If you see an error like:
+```
+[Dynatrace Testing] Missing required configuration fields: endpointUrl, appId, token
+```
+
+This means the required configuration was not provided. Make sure to configure the fixture using `test.use()`:
+
+```typescript
+test.use({
+    dynatraceConfig: {
+        endpointUrl: process.env.DT_ENDPOINT_URL!,
+        appId: process.env.DT_APP_ID!,
+        token: process.env.DT_TOKEN!
+    }
+});
+```
+
+### No Events Received
+
+If your tests fail with "Dynatrace didn't send any events":
+
+1. **Check fixture ordering** - Ensure `dynatraceTesting` is destructured before any fixtures that navigate the page
+2. **Check the page URL** - If you see a warning about the page already being navigated, fix the fixture order
+
+### Event Dumping
+
+When `dumpEventsOnFail` is enabled, the framework will output detailed information about received events when assertions fail:
+
+```
+[Dynatrace Testing] Event Dump (expectToHaveSentEvent - no match)
+Total events received: 3
+Total beacons received: 2
+
+Received events:
+
+Event 1: { "event_properties.custom_val": "load", ... }
+Event 2: { "event_properties.custom_val": "user-action", ... }
+Event 3: { "event_properties.custom_val": "custom", ... }
+```
+
+This helps identify why expected events weren't matched.
+
+## Testing API
+The `DynatraceTesting` interface provides utility methods for validating observability-related events and beacon
+requests during tests.
+
+---
+
+## Methods
+
+### `waitForBeacons(options?: { minCount?: number; timeout?: number }): Promise<BeaconRequest[]>`
+
+Waits for a specified number of beacon requests or until a timeout occurs.
+
+#### Parameters:
+- `options` *(Optional)*:
+    - `minCount`: The minimum number of beacon requests to wait for.
+    - `timeout`: The maximum time to wait for beacon requests, in milliseconds. *(Default: 30,000)*
+
+#### Returns:
+A promise that resolves with an array of beacon requests.
+
+---
+
+### `expectToHaveSentEvent(event: Record<string, unknown>, options?: { timeout?: number }): Promise<void>`
+
+Verifies that a specific event has been sent, optionally within a timeout period.
+
+#### Parameters:
+- `event`: The event to check, represented as a key-value pair object. This uses Playwright's `expect(event).toMatchObject`.
+- `options` *(Optional)*:
+    - `timeout`: The maximum time to wait for the event to be sent, in milliseconds. *(Default: 30,000)*
+
+#### Returns:
+A promise that resolves when the event is confirmed to have been sent.
+
+---
+
+### `expectToHaveSentEventTimes(event: Record<string, unknown>, times: number, options?: { timeout?: number }): Promise<void>`
+
+Verifies that a specific event has been sent a specified number of times, optionally within a timeout period.
+
+#### Parameters:
+- `event`: The event to check, represented as a key-value pair object. This uses Playwright's `expect(event).toMatchObject`.
+- `times`: The exact number of times the event is expected to have been sent.
+- `options` *(Optional)*:
+    - `timeout`: The maximum time to wait for the event to be sent, in milliseconds. *(Default: 30,000)*
+
+#### Returns:
+A promise that resolves when the event is confirmed to have been sent the specified number of times.
+
+---
+
+### `clearEvents(): void`
+
+Clears all events and beacons, allowing subsequent expectations to ignore events that have been sent in the past.
+
+#### Example:
+```typescript
+sendFooEvent();
+await dynatraceTesting.expectToHaveSentEventTimes({ foo: "bar" }, 1);
+
+dynatraceTesting.clearEvents();
+
+await dynatraceTesting.expectToHaveSentEventTimes({ foo: "bar" }, 1);
+```
+
+---
+
+### `toMatchEventSnapshot(options?: SnapshotOptions): Promise<void>`
+
+Compares captured events against a stored snapshot file. On first run, creates the snapshot. On subsequent runs, compares and fails if different. Volatile fields (timestamps, IDs, etc.) are processed by default to prevent flaky tests.
+
+#### Parameters:
+- `options` *(Optional)*:
+    - `ignoredFields`: Array of field names or patterns whose values are replaced with `[IGNORED]` placeholder before comparison:
+        - **Exact field names** (e.g., `"start_time"`): Value replaced with `[IGNORED]`
+        - **Wildcard patterns** (e.g., `"dt.rum.*"`): All matching fields have values replaced with `[IGNORED]`
+      
+      Default: `DEFAULT_IGNORED_FIELDS` - includes timestamps, session IDs, trace IDs, etc.
+    - `removedFields`: Array of field names or patterns to remove entirely before comparison:
+        - **Exact field names** (e.g., `"performance.time_origin"`): Field is removed
+        - **Wildcard patterns** (e.g., `"inp.*"`): All matching fields are removed
+      
+      Default: `DEFAULT_REMOVED_FIELDS` - includes web vitals, performance metrics, viewport dimensions.
+    - `ignoreEvents`: Array of event patterns to filter out completely. Events matching any pattern are excluded from the snapshot. Default: `DEFAULT_IGNORED_EVENTS` (filters long tasks and self-monitoring events).
+    - `name`: Custom snapshot name. If not provided, defaults to `"events"`.
+
+#### Returns:
+A promise that resolves when the snapshot comparison succeeds.
+
+#### Example - Basic Usage:
+```typescript
+test("captures user action events", async ({ page, dynatraceTesting }) => {
+    await page.goto("http://127.0.0.1:3000/ui");
+    await page.getByText("Submit").click();
+
+    // Wait for events to be captured
+    await dynatraceTesting.waitForBeacons({ minCount: 1 });
+
+    // Compare against snapshot
+    await dynatraceTesting.toMatchEventSnapshot();
+});
+```
+
+#### Example - Custom Ignored and Removed Properties:
+```typescript
+import { DEFAULT_IGNORED_FIELDS, DEFAULT_REMOVED_FIELDS } from "@dynatrace/rum-javascript-sdk/test";
+
+test("captures events with custom property handling", async ({ page, dynatraceTesting }) => {
+    await page.goto("http://127.0.0.1:3000/ui");
+    await page.getByText("Submit").click();
+
+    await dynatraceTesting.waitForBeacons({ minCount: 1 });
+
+    // Extend defaults with additional patterns
+    await dynatraceTesting.toMatchEventSnapshot({
+        ignoredFields: [
+            ...DEFAULT_IGNORED_FIELDS,
+            "event_properties.request_id"       // Value replaced with [IGNORED]
+        ],
+        removedFields: [
+            ...DEFAULT_REMOVED_FIELDS,
+            "user_action.resources.*"           // All matching fields removed entirely
+        ]
+    });
+});
+```
+
+#### Example - Custom Event Filtering:
+```typescript
+import { DEFAULT_IGNORED_EVENTS } from "@dynatrace/rum-javascript-sdk/test";
+
+test("captures events excluding specific patterns", async ({ page, dynatraceTesting }) => {
+    await page.goto("http://127.0.0.1:3000/ui");
+    await page.getByText("Submit").click();
+
+    await dynatraceTesting.waitForBeacons({ minCount: 1 });
+
+    // Filter out specific event types
+    await dynatraceTesting.toMatchEventSnapshot({
+        ignoreEvents: [
+            ...DEFAULT_IGNORED_EVENTS,
+            { "characteristics.has_navigation": true },  // Exclude navigation events
+            { "url.full": "http://example.com/favicon.ico" }  // Exclude specific URL
+        ]
+    });
+});
+```
+
+#### Example - Named Snapshots:
+```typescript
+test("captures multiple event sequences", async ({ page, dynatraceTesting }) => {
+    await page.goto("http://127.0.0.1:3000/ui");
+
+    // First interaction
+    await page.getByText("Login").click();
+    await dynatraceTesting.waitForBeacons({ minCount: 1 });
+    await dynatraceTesting.toMatchEventSnapshot({ name: "login-events" });
+
+    dynatraceTesting.clearEvents();
+
+    // Second interaction
+    await page.getByText("Submit").click();
+    await dynatraceTesting.waitForBeacons({ minCount: 1 });
+    await dynatraceTesting.toMatchEventSnapshot({ name: "submit-events" });
+});
+```
+
+#### Example - Browser-Specific Snapshots:
+
+Event snapshots may differ between browsers due to variations in timing, event ordering, or browser-specific behavior. To handle this, include the `browserName` fixture in your snapshot name to create separate snapshots per browser:
+
+```typescript
+test("captures events per browser", async ({ page, dynatraceTesting, browserName }) => {
+    await page.goto("http://127.0.0.1:3000/ui");
+    await page.getByText("Submit").click();
+
+    await dynatraceTesting.waitForBeacons({ minCount: 1 });
+
+    // Creates separate snapshots: basic-events-chromium, basic-events-firefox, basic-events-webkit
+    await dynatraceTesting.toMatchEventSnapshot({
+        name: `basic-events-${browserName}`
+    });
+});
+```
+
+This creates separate snapshot files for each browser:
+```
+e2e/
+├── my-test.spec.ts
+└── my-test.spec.ts-snapshots/
+    ├── basic-events-chromium.events.snap
+    ├── basic-events-firefox.events.snap
+    └── basic-events-webkit.events.snap
+```
+
+#### Snapshot Files
+
+Snapshots are stored alongside your test files in a directory named `<test-file>-snapshots/`. For example:
+```
+e2e/
+├── my-test.spec.ts
+└── my-test.spec.ts-snapshots/
+    └── events.events.snap
+```
+
+The snapshot files contain JSON-formatted event data with ignored fields replaced by `[IGNORED]` and removed fields omitted:
+```json
+[
+  {
+    "duration": "[IGNORED]",
+    "name": "click on Submit",
+    "start_time": "[IGNORED]",
+    "type": "user_action"
+  }
+]
+```
+
+#### Updating Snapshots
+
+To update snapshots when event structures change intentionally, run Playwright with the `--update-snapshots` flag:
+
+```bash
+npx playwright test --update-snapshots
+```
+
+#### Default Ignored Fields
+
+The following fields have their values replaced with `[IGNORED]` by default:
+
+| Category | Fields |
+|----------|--------|
+| **Timing** | `start_time`, `duration`, `timestamp` |
+| **Session/Instance IDs** | `dt.rum.sid`, `dt.rum.browser.sid`, `dt.rum.instance.id`, `user_session.id`, `user.anonymous_id`, `view.instance_id`, `page.instance_id`, `user_action.instance_id`, etc. |
+| **Distributed Tracing** | `trace.id`, `span.id` |
+| **Self-monitoring** | `dt.rum.sfm_events`, `dt.support.last_user_input` |
+
+#### Default Removed Fields
+
+The following fields are removed entirely by default (they vary in count or presence between runs):
+
+| Category | Fields |
+|----------|--------|
+| **Performance** | `performance.*` |
+| **Web Vitals** | `fcp.*`, `fp.*`, `ttfb.*`, `lcp.*`, `fid.*`, `inp.*`, `cls.*` |
+| **Long Tasks** | `long_task.*` |
+| **Viewport/Screen** | `browser.window.*`, `device.screen.*` |
+
+#### Default Ignored Events
+
+The following event patterns are filtered out by default:
+
+| Pattern | Description |
+|---------|-------------|
+| `{ "characteristics.has_long_task": true }` | Long task events (timing varies) |
+| `{ "characteristics.is_self_monitoring": true }` | Self-monitoring events |
+
+#### Troubleshooting Snapshot Failures
+
+When a snapshot comparison fails, the error message includes:
+1. The path to the snapshot file
+2. A line-by-line diff showing expected vs actual values
+3. Instructions for updating the snapshot
+
+Common causes of snapshot failures:
+- **New fields added to events**: Update the snapshot with `--update-snapshots`
+- **Volatile field values**: Add the field to `ignoredFields` to replace values with `[IGNORED]`
+- **Varying field presence**: Add the field to `removedFields` (use `fieldname.*` wildcard to remove all fields with that prefix)
+- **Unwanted events**: Add an event pattern to `ignoreEvents` to filter them out
+- **Intentional changes**: Review the diff and update the snapshot if correct

package/docs/{types.md → 3-types.md}

@@ -1,10 +1,16 @@
+---
+title: Dynatrace Api Types
+---
 # Dynatrace Api Types
 This package contains the Typescript type information for the `dynatrace` API of the RUM JavaScript.
 
 Keep in mind that when the RUM JavaScript is updated, this type package also has to be updated to provide accurate types.
 
 ## Installation
-> npm install --save-dev @dynatrace/rum-javascript-sdk
+
+```bash
+npm install --save-dev @dynatrace/rum-javascript-sdk
+````
 
 ## Configuration
 Make sure to add these paths to `"typeRoots"` in tsconfig.json under `"compilerOptions"`
@@ -41,4 +47,4 @@ if (window.dynatrace) {
 }
 ```
 
-Refer to the [user actions documentation](./USERACTIONS.md) for details about `dynatrace.userActions`.
+Refer to the [User Actions API](./4-useractions.md) for details about `dynatrace.userActions`.

package/docs/{USERACTIONS.md → 4-useractions.md}

@@ -1,3 +1,6 @@
+---
+title: User Actions API
+---
 # User Actions API
 
 **Experimental Feature** • This guide explains how to use the User Actions API to manually control user action creation, monitoring, and lifecycle management in your web application.
@@ -64,7 +67,7 @@ User actions can complete for various reasons, indicated by the `user_action.com
 
 ## API approaches
 
-You can use the User Actions API directly, or via its synchronous or asynchronous SDK functions, matching the pattern established in the [@dynatrace/rum-javascript-sdk](../README.md):
+You can use the User Actions API directly, or via its synchronous or asynchronous SDK functions, matching the pattern established in the [RUM JavaScript SDK Overview](./1-overview.md):
 
 ### Direct API (via `dynatrace.userActions`)
 
@@ -234,8 +237,8 @@ dynatrace.addEventModifier(evt => {
 ```
 
 :::note
-Using `event_properties` requires you to configure them in the Experience Vitals app. Non-configured properties are
-discarded on the server side. Select your Frontend, go to the Settings-Tab and configure _Event and session properties_.
+Using `event_properties` requires you to configure them on the server side.
+See [Event and session properties](https://www.dynatrace.com/support/doc/experience-vitals/experience-vitals-settings/event-and-session-properties) for more details.
 :::
 
 ### Check user action state
@@ -588,7 +591,7 @@ class CheckoutTracker {
                 ...this.checkoutAction.event_properties,
                 'event_properties.checkout_step': step,
                 ...Object.entries(additionalData).reduce((acc, [key, value]) => {
-                    // Remember to configure the properties in the Experience Vitals app!
+                    // Remember to configure the properties on the server side!
                     acc[`event_properties.${key}`] = value;
                     return acc;
                 }, {} as Record<string, any>)
@@ -979,12 +982,11 @@ All async functions follow the same pattern, accepting an optional `timeout` par
 
 ## Additional resources
 
-- [RUM JavaScript SDK Overview](../README.md)
-- [Event Modification API](./source/types/api/dynatrace-api-types.ts) - For modifying user action events
-- [RUM JavaScript Typedoc](https://www.dynatrace.com/support/doc/javascriptapi/doc-latest/)
+- [RUM JavaScript SDK Overview](./1-overview.md)
+- {@link dynatrace.addEventModifier | Event Modification API} - For modifying user action events
 
 ---
 
 :::note
-This API is experimental and subject to change. Always check for updates when upgrading to new versions of the RUM JavaScript agent.
+This API is experimental and subject to change. Always check for updates when upgrading to new versions of the RUM JavaScript.
 :::

package/package.json

@@ -1,10 +1,47 @@
 {
   "name": "@dynatrace/rum-javascript-sdk",
-  "version": "1.331.18",
+  "version": "1.333.2",
   "description": "JavaScript API for Real User Monitoring (RUM)",
   "sideEffects": false,
   "type": "module",
   "types": "./dist/types/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "api": [
+        "./dist/api/index.d.ts"
+      ],
+      "api/user-actions": [
+        "./dist/api/user-actions.d.ts"
+      ],
+      "api/promises": [
+        "./dist/api/promises/index.d.ts"
+      ],
+      "api/promises/user-actions": [
+        "./dist/api/promises/user-actions.d.ts"
+      ],
+      "test": [
+        "./dist/testing/index.d.ts"
+      ],
+      "types": [
+        "./dist/types/index.d.ts"
+      ],
+      "types/user-actions": [
+        "./dist/types/user-actions/index.d.ts"
+      ],
+      "types/api": [
+        "./dist/types/api/index.d.ts"
+      ],
+      "types/rum-events": [
+        "./dist/types/rum-events/index.d.ts"
+      ],
+      "types/rum-events/event-context": [
+        "./dist/types/rum-events/event-context/index.d.ts"
+      ],
+      "types/rum-events/shared-namespaces-and-fields": [
+        "./dist/types/rum-events/shared-namespaces-and-fields/index.d.ts"
+      ]
+    }
+  },
   "files": [
     "dist/api/**/*.js",
     "dist/api/**/*.d.ts",
@@ -42,9 +79,9 @@
       "default": "./dist/types/internal/index.js"
     },
     "./test": {
-      "types": "./dist/testing/test.d.ts",
-      "import": "./dist/testing/test.js",
-      "default": "./dist/testing/test.js"
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
     },
     "./types": {
       "types": "./dist/types/index.d.ts",
@@ -94,15 +131,15 @@
   "license": "ISC",
   "devDependencies": {
     "@types/node": "25.0.3",
-    "@vitest/coverage-v8": "3.2.3",
-    "@vitest/ui": "3.2.3",
+    "@vitest/coverage-v8": "4.1.0-beta.1",
+    "@vitest/ui": "4.1.0-beta.1",
     "eslint": "9.38.0",
     "jsdom": "27.0.1",
     "knip": "5.27.0",
     "typedoc": "0.28.10",
     "typedoc-plugin-mdn-links": "5.0.3",
     "typescript": "5.8.2",
-    "vitest": "3.2.3"
+    "vitest": "4.1.0-beta.1"
   },
   "scripts": {
     "build:lib": "tsc -b tsconfig.build.json",
@@ -110,8 +147,8 @@
     "lint": "eslint \"source/**/*.ts\" \"./*.{ts,js,mjs}\"",
     "lint:fix": "eslint \"source/**/*.ts\" \"./*.{ts,js,mjs}\" --fix && echo No Lint-Problems found",
     "//": "Note: these 2 scripts below are only for local builds. The CI build in build.groovy needs to be updated as well if there are any changes",
-    "doc:api-gen3-internal": "typedoc --treatWarningsAsErrors --options ./typedoc-gen3-internal.api.json --tsconfig ./tsconfig-gen3.apidoc.json --plugin typedoc-plugin-mdn-links",
-    "doc:api-gen3-public": "typedoc --treatWarningsAsErrors --options ./typedoc-gen3-public.api.json --tsconfig ./tsconfig-gen3.apidoc.json --plugin typedoc-plugin-mdn-links",
+    "doc:api-gen3-internal": "typedoc --treatWarningsAsErrors --options ./typedoc-gen3-internal.api.json --tsconfig ./tsconfig-gen3.apidoc.json",
+    "doc:api-gen3-public": "typedoc --treatWarningsAsErrors --options ./typedoc-gen3-public.api.json --tsconfig ./tsconfig-gen3.apidoc.json",
     "find-deadcode": "knip"
   }
 }