@dynatrace/rum-javascript-sdk 1.331.18 → 1.333.2

package/docs/testing.md

@@ -1,215 +0,0 @@
-# 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);