@dynatrace/rum-javascript-sdk 1.329.3 → 1.329.4

package/docs/testing.md

@@ -0,0 +1,123 @@
+# 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"
+    }));
+});
+```
+
+## 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.
+
+## 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);

package/docs/types.md

@@ -0,0 +1,44 @@
+# 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
+
+## Configuration
+Make sure to add these paths to `"typeRoots"` in tsconfig.json under `"compilerOptions"`
+```
+"typeRoots": ["./node_modules/@types", "./node_modules/@dynatrace/"],
+```
+
+## Usage examples
+Type inference works out of the box for dynatrace calls.
+```ts
+if (window.dynatrace) {
+    window.dynatrace.sendEvent({
+        "event_properties.prop": "value"
+    });
+} else {
+    // handle missing dynatrace api
+}
+```
+
+In case some specific types or enums are needed, you can import them from `dynatrace` types library.
+```ts
+import { JSONObject } from '@dynatrace/rum-javascript-sdk/types';
+
+function createJSONObject(): JSONObject {
+    return {
+        "event_properties.someProp": "someValue"
+    };
+}
+
+if (window.dynatrace) {
+    window.dynatrace.sendEvent(createJSONObject());
+} else {
+    // handle missing dynatrace api
+}
+```
+
+Refer to the [user actions documentation](./USERACTIONS.md) for details about `dynatrace.userActions`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynatrace/rum-javascript-sdk",
-  "version": "1.329.3",
+  "version": "1.329.4",
   "description": "JavaScript API for Real User Monitoring (RUM)",
   "sideEffects": false,
   "type": "module",
@@ -12,7 +12,7 @@
     "dist/types/**/*.d.ts",
     "dist/testing/**/*.js",
     "dist/testing/**/*.d.ts",
-    "*.md"
+    "docs/*.md"
   ],
   "exports": {
     "./api": {