@dynatrace/rum-javascript-sdk 1.329.2 → 1.329.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +4 -4
  2. package/docs/USERACTIONS.md +990 -0
  3. package/docs/testing.md +123 -0
  4. package/docs/types.md +44 -0
  5. package/package.json +110 -109
package/docs/testing.md ADDED
@@ -0,0 +1,123 @@
1
+ # Dynatrace RUM JavaScript Testing Framework for Playwright
2
+
3
+ This framework provides a Playwright fixture for testing observability by interacting with the Dynatrace Real User Monitoring (RUM) API.
4
+
5
+ ## Setup Instructions
6
+
7
+ Follow these steps to configure and use the framework:
8
+
9
+ ### 1. Create an Access Token
10
+ 1. Navigate to the **Access Tokens** app in Dynatrace.
11
+ 2. Create a new token with the following permission:
12
+ - **Permission**: `Read RUM manual insertion tags`
13
+ - **Scope**: `API V2`
14
+ 3. Copy the generated token for use in the next steps.
15
+
16
+ ### 2. Provide Required Parameters
17
+ To use the framework, you need to provide the following details:
18
+ - **Environment URL**: The URL of the Dynatrace API endpoint to connect to, see
19
+ [RUM manual insertion tags API](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/environment-api/rum/rum-manual-insertion-tags)
20
+ for details. Example: _https://{your-environment-id}.live.dynatrace.com_ or
21
+ _https://{your-activegate-domain}/e/{your-environment-id}_
22
+ - **Application ID**: The application ID to identify the correct RUM JavaScript to fetch. You can find
23
+ this in the URL if you open the Experience Vitals app and select the frontend you
24
+ want to test. Example: APPLICATION-ABCDEF0123456789
25
+ - **Token**: The API token created in Step 1.
26
+
27
+ Populate your playwright config file with these fields or call `test.use` to provide them to a test suite, like so:
28
+ ```ts
29
+ import { test } from "@dynatrace/rum-javascript-sdk/test";
30
+
31
+ test.describe("my suite", () => {
32
+ test.use({
33
+ dynatraceConfig: {
34
+ appId: process.env.DT_APP_ID!,
35
+ token: process.env.DT_TOKEN!,
36
+ endpointUrl: process.env.DT_ENDPOINT_URL!
37
+ }
38
+ });
39
+ });
40
+ ```
41
+
42
+ ### 3. Assert on events
43
+
44
+ Use the provided `expect` functions to assert on events the RUM JavaScript should have sent:
45
+ ```ts
46
+ test("expect specific event", async ({ page, dynatraceTesting }) => {
47
+ await page.goto("http://127.0.0.1:3000/ui");
48
+ await page.getByText("Explore data").first().click();
49
+ await dynatraceTesting.expectToHaveSentEvent(expect.objectContaining({
50
+ "event_properties.component_rendered": "Data"
51
+ }));
52
+ });
53
+ ```
54
+
55
+ ## Troubleshooting
56
+
57
+ The test fixture works by intercepting network requests to the RUM ingestion endpoint and capturing
58
+ the events sent by the RUM JavaScript.
59
+ Note that this has an impact on your capturing environment, since these beacons report real data.
60
+
61
+ ## Testing API
62
+ The `DynatraceTesting` interface provides utility methods for validating observability-related events and beacon
63
+ requests during tests.
64
+
65
+ ---
66
+
67
+ ## Methods
68
+
69
+ ### `waitForBeacons(options?: { minCount?: number; timeout?: number }): Promise<BeaconRequest[]>`
70
+
71
+ Waits for a specified number of beacon requests or until a timeout occurs.
72
+
73
+ #### Parameters:
74
+ - `options` *(Optional)*:
75
+ - `minCount`: The minimum number of beacon requests to wait for.
76
+ - `timeout`: The maximum time to wait for beacon requests, in milliseconds. *(Default: 30,000)*
77
+
78
+ #### Returns:
79
+ A promise that resolves with an array of beacon requests.
80
+
81
+ ---
82
+
83
+ ### `expectToHaveSentEvent(event: Record<string, unknown>, options?: { timeout?: number }): Promise<void>`
84
+
85
+ Verifies that a specific event has been sent, optionally within a timeout period.
86
+
87
+ #### Parameters:
88
+ - `event`: The event to check, represented as a key-value pair object. This uses Playwright's `expect(event).toMatchObject`.
89
+ - `options` *(Optional)*:
90
+ - `timeout`: The maximum time to wait for the event to be sent, in milliseconds. *(Default: 30,000)*
91
+
92
+ #### Returns:
93
+ A promise that resolves when the event is confirmed to have been sent.
94
+
95
+ ---
96
+
97
+ ### `expectToHaveSentEventTimes(event: Record<string, unknown>, times: number, options?: { timeout?: number }): Promise<void>`
98
+
99
+ Verifies that a specific event has been sent a specified number of times, optionally within a timeout period.
100
+
101
+ #### Parameters:
102
+ - `event`: The event to check, represented as a key-value pair object. This uses Playwright's `expect(event).toMatchObject`.
103
+ - `times`: The exact number of times the event is expected to have been sent.
104
+ - `options` *(Optional)*:
105
+ - `timeout`: The maximum time to wait for the event to be sent, in milliseconds. *(Default: 30,000)*
106
+
107
+ #### Returns:
108
+ A promise that resolves when the event is confirmed to have been sent the specified number of times.
109
+
110
+ ---
111
+
112
+ ### `clearEvents(): void`
113
+
114
+ Clears all events and beacons, allowing subsequent expectations to ignore events that have been sent in the past.
115
+
116
+ #### Example:
117
+ ```typescript
118
+ sendFooEvent();
119
+ await dynatraceTesting.expectToHaveSentEventTimes({ foo: "bar" }, 1);
120
+
121
+ dynatraceTesting.clearEvents();
122
+
123
+ await dynatraceTesting.expectToHaveSentEventTimes({ foo: "bar" }, 1);
package/docs/types.md ADDED
@@ -0,0 +1,44 @@
1
+ # Dynatrace Api Types
2
+ This package contains the Typescript type information for the `dynatrace` API of the RUM JavaScript.
3
+
4
+ Keep in mind that when the RUM JavaScript is updated, this type package also has to be updated to provide accurate types.
5
+
6
+ ## Installation
7
+ > npm install --save-dev @dynatrace/rum-javascript-sdk
8
+
9
+ ## Configuration
10
+ Make sure to add these paths to `"typeRoots"` in tsconfig.json under `"compilerOptions"`
11
+ ```
12
+ "typeRoots": ["./node_modules/@types", "./node_modules/@dynatrace/"],
13
+ ```
14
+
15
+ ## Usage examples
16
+ Type inference works out of the box for dynatrace calls.
17
+ ```ts
18
+ if (window.dynatrace) {
19
+ window.dynatrace.sendEvent({
20
+ "event_properties.prop": "value"
21
+ });
22
+ } else {
23
+ // handle missing dynatrace api
24
+ }
25
+ ```
26
+
27
+ In case some specific types or enums are needed, you can import them from `dynatrace` types library.
28
+ ```ts
29
+ import { JSONObject } from '@dynatrace/rum-javascript-sdk/types';
30
+
31
+ function createJSONObject(): JSONObject {
32
+ return {
33
+ "event_properties.someProp": "someValue"
34
+ };
35
+ }
36
+
37
+ if (window.dynatrace) {
38
+ window.dynatrace.sendEvent(createJSONObject());
39
+ } else {
40
+ // handle missing dynatrace api
41
+ }
42
+ ```
43
+
44
+ Refer to the [user actions documentation](./USERACTIONS.md) for details about `dynatrace.userActions`.
package/package.json CHANGED
@@ -1,115 +1,116 @@
1
1
  {
2
- "name": "@dynatrace/rum-javascript-sdk",
3
- "version": "1.329.2",
4
- "description": "JavaScript API for Real User Monitoring (RUM)",
5
- "sideEffects": false,
6
- "type": "module",
7
- "types": "./dist/types/index.d.ts",
8
- "files": [
9
- "dist/api/**/*.js",
10
- "dist/api/**/*.d.ts",
11
- "dist/types/**/*.js",
12
- "dist/types/**/*.d.ts",
13
- "dist/testing/**/*.js",
14
- "dist/testing/**/*.d.ts"
15
- ],
16
- "exports": {
17
- "./api": {
18
- "types": "./dist/api/index.d.ts",
19
- "import": "./dist/api/index.js",
20
- "default": "./dist/api/index.js"
21
- },
22
- "./api/user-actions": {
23
- "types": "./dist/api/user-actions.d.ts",
24
- "import": "./dist/api/user-actions.js",
25
- "default": "./dist/api/user-actions.js"
26
- },
27
- "./api/promises/user-actions": {
28
- "types": "./dist/api/promises/user-actions.d.ts",
29
- "import": "./dist/api/promises/user-actions.js",
30
- "default": "./dist/api/promises/user-actions.js"
31
- },
32
- "./api/promises": {
33
- "types": "./dist/api/promises/index.d.ts",
34
- "import": "./dist/api/promises/index.js",
35
- "default": "./dist/api/promises/index.js"
36
- },
37
- "./internal": {
38
- "types": "./dist/types/internal/index.d.ts",
39
- "import": "./dist/types/internal/index.js",
40
- "default": "./dist/types/internal/index.js"
41
- },
42
- "./test": {
43
- "types": "./dist/testing/test.d.ts",
44
- "import": "./dist/testing/test.js",
45
- "default": "./dist/testing/test.js"
46
- },
47
- "./types": {
48
- "types": "./dist/types/index.d.ts",
49
- "import": "./dist/types/index.js",
50
- "default": "./dist/types/index.js"
51
- },
52
- "./types/user-actions": {
53
- "types": "./dist/types/user-actions/index.d.ts",
54
- "import": "./dist/types/user-actions/index.js",
55
- "default": "./dist/types/user-actions/index.js"
56
- },
57
- "./types/api": {
58
- "types": "./dist/types/api/index.d.ts",
59
- "import": "./dist/types/api/index.js",
60
- "default": "./dist/types/api/index.js"
61
- },
62
- "./types/rum-events": {
63
- "types": "./dist/types/rum-events/index.d.ts",
64
- "import": "./dist/types/rum-events/index.js",
65
- "default": "./dist/types/rum-events/index.js"
66
- },
67
- "./types/rum-events/event-context": {
68
- "types": "./dist/types/rum-events/event-context/index.d.ts",
69
- "import": "./dist/types/rum-events/event-context/index.js",
70
- "default": "./dist/types/rum-events/event-context/index.js"
71
- },
72
- "./types/rum-events/shared-namespaces-and-fields": {
73
- "types": "./dist/types/rum-events/shared-namespaces-and-fields/index.d.ts",
74
- "import": "./dist/types/rum-events/shared-namespaces-and-fields/index.js",
75
- "default": "./dist/types/rum-events/shared-namespaces-and-fields/index.js"
76
- }
2
+ "name": "@dynatrace/rum-javascript-sdk",
3
+ "version": "1.329.4",
4
+ "description": "JavaScript API for Real User Monitoring (RUM)",
5
+ "sideEffects": false,
6
+ "type": "module",
7
+ "types": "./dist/types/index.d.ts",
8
+ "files": [
9
+ "dist/api/**/*.js",
10
+ "dist/api/**/*.d.ts",
11
+ "dist/types/**/*.js",
12
+ "dist/types/**/*.d.ts",
13
+ "dist/testing/**/*.js",
14
+ "dist/testing/**/*.d.ts",
15
+ "docs/*.md"
16
+ ],
17
+ "exports": {
18
+ "./api": {
19
+ "types": "./dist/api/index.d.ts",
20
+ "import": "./dist/api/index.js",
21
+ "default": "./dist/api/index.js"
77
22
  },
78
- "scripts": {
79
- "build:lib": "tsc -b tsconfig.build.json",
80
- "test": "vitest --run --no-color --coverage",
81
- "lint": "eslint \"source/**/*.ts\" \"./*.{ts,js,mjs}\"",
82
- "lint:fix": "eslint \"source/**/*.ts\" \"./*.{ts,js,mjs}\" --fix && echo No Lint-Problems found",
83
- "//": "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",
84
- "doc:api-gen3-internal": "typedoc --treatWarningsAsErrors --options ./typedoc-gen3-internal.api.json --tsconfig ./tsconfig-gen3.apidoc.json --plugin typedoc-plugin-mdn-links",
85
- "doc:api-gen3-public": "typedoc --treatWarningsAsErrors --options ./typedoc-gen3-public.api.json --tsconfig ./tsconfig-gen3.apidoc.json --plugin typedoc-plugin-mdn-links",
86
- "find-deadcode": "knip"
23
+ "./api/user-actions": {
24
+ "types": "./dist/api/user-actions.d.ts",
25
+ "import": "./dist/api/user-actions.js",
26
+ "default": "./dist/api/user-actions.js"
87
27
  },
88
- "keywords": [
89
- "dynatrace",
90
- "rum",
91
- "real-user-monitoring",
92
- "javascript",
93
- "api"
94
- ],
95
- "dependencies": {
96
- "snappyjs": "0.7.0"
28
+ "./api/promises/user-actions": {
29
+ "types": "./dist/api/promises/user-actions.d.ts",
30
+ "import": "./dist/api/promises/user-actions.js",
31
+ "default": "./dist/api/promises/user-actions.js"
97
32
  },
98
- "peerDependencies": {
99
- "@playwright/test": "^1.52.0"
33
+ "./api/promises": {
34
+ "types": "./dist/api/promises/index.d.ts",
35
+ "import": "./dist/api/promises/index.js",
36
+ "default": "./dist/api/promises/index.js"
100
37
  },
101
- "author": "Dynatrace",
102
- "license": "ISC",
103
- "devDependencies": {
104
- "@types/node": "catalog:",
105
- "@vitest/coverage-v8": "catalog:",
106
- "@vitest/ui": "catalog:",
107
- "eslint": "catalog:",
108
- "jsdom": "catalog:",
109
- "knip": "catalog:",
110
- "typedoc": "catalog:",
111
- "typedoc-plugin-mdn-links": "catalog:",
112
- "typescript": "catalog:",
113
- "vitest": "catalog:"
38
+ "./internal": {
39
+ "types": "./dist/types/internal/index.d.ts",
40
+ "import": "./dist/types/internal/index.js",
41
+ "default": "./dist/types/internal/index.js"
42
+ },
43
+ "./test": {
44
+ "types": "./dist/testing/test.d.ts",
45
+ "import": "./dist/testing/test.js",
46
+ "default": "./dist/testing/test.js"
47
+ },
48
+ "./types": {
49
+ "types": "./dist/types/index.d.ts",
50
+ "import": "./dist/types/index.js",
51
+ "default": "./dist/types/index.js"
52
+ },
53
+ "./types/user-actions": {
54
+ "types": "./dist/types/user-actions/index.d.ts",
55
+ "import": "./dist/types/user-actions/index.js",
56
+ "default": "./dist/types/user-actions/index.js"
57
+ },
58
+ "./types/api": {
59
+ "types": "./dist/types/api/index.d.ts",
60
+ "import": "./dist/types/api/index.js",
61
+ "default": "./dist/types/api/index.js"
62
+ },
63
+ "./types/rum-events": {
64
+ "types": "./dist/types/rum-events/index.d.ts",
65
+ "import": "./dist/types/rum-events/index.js",
66
+ "default": "./dist/types/rum-events/index.js"
67
+ },
68
+ "./types/rum-events/event-context": {
69
+ "types": "./dist/types/rum-events/event-context/index.d.ts",
70
+ "import": "./dist/types/rum-events/event-context/index.js",
71
+ "default": "./dist/types/rum-events/event-context/index.js"
72
+ },
73
+ "./types/rum-events/shared-namespaces-and-fields": {
74
+ "types": "./dist/types/rum-events/shared-namespaces-and-fields/index.d.ts",
75
+ "import": "./dist/types/rum-events/shared-namespaces-and-fields/index.js",
76
+ "default": "./dist/types/rum-events/shared-namespaces-and-fields/index.js"
114
77
  }
115
- }
78
+ },
79
+ "keywords": [
80
+ "dynatrace",
81
+ "rum",
82
+ "real-user-monitoring",
83
+ "javascript",
84
+ "api"
85
+ ],
86
+ "dependencies": {
87
+ "snappyjs": "0.7.0"
88
+ },
89
+ "peerDependencies": {
90
+ "@playwright/test": "^1.52.0"
91
+ },
92
+ "author": "Dynatrace",
93
+ "license": "ISC",
94
+ "devDependencies": {
95
+ "@types/node": "22.10.1",
96
+ "@vitest/coverage-v8": "3.2.3",
97
+ "@vitest/ui": "3.2.3",
98
+ "eslint": "9.38.0",
99
+ "jsdom": "27.0.1",
100
+ "knip": "5.27.0",
101
+ "typedoc": "0.28.10",
102
+ "typedoc-plugin-mdn-links": "5.0.3",
103
+ "typescript": "5.8.2",
104
+ "vitest": "3.2.3"
105
+ },
106
+ "scripts": {
107
+ "build:lib": "tsc -b tsconfig.build.json",
108
+ "test": "vitest --run --no-color --coverage",
109
+ "lint": "eslint \"source/**/*.ts\" \"./*.{ts,js,mjs}\"",
110
+ "lint:fix": "eslint \"source/**/*.ts\" \"./*.{ts,js,mjs}\" --fix && echo No Lint-Problems found",
111
+ "//": "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",
112
+ "doc:api-gen3-internal": "typedoc --treatWarningsAsErrors --options ./typedoc-gen3-internal.api.json --tsconfig ./tsconfig-gen3.apidoc.json --plugin typedoc-plugin-mdn-links",
113
+ "doc:api-gen3-public": "typedoc --treatWarningsAsErrors --options ./typedoc-gen3-public.api.json --tsconfig ./tsconfig-gen3.apidoc.json --plugin typedoc-plugin-mdn-links",
114
+ "find-deadcode": "knip"
115
+ }
116
+ }