Browser clickpath events

When you record a browser clickpath, your interactions with your web application are captured as a series of events. There are different event types to simulate interaction and control the clickpath, for instance, navigating to a URL, a click, selecting an option, entering information, or a JavaScript snippet. Besides the type, events have different properties, like the target (consisting of locators to identify web elements on a page) and the wait strategy.

Browser clickpath event types and their properties are described below. Clickpath events are editable during initial configuration or at any point later in edit mode in monitor settings (see the images below). You can edit, reorder, delete, and add events.

Recorded clickpath

Clickpath events in edit mode

Important

A synthetic "event" is not the same thing as an "action"—only events that trigger web requests are called actions, so your script might have more events than actions. Synthetic actions (similar to user actions in Real User Monitoring) hold the performance data collected during clickpath runs.

The Navigate event simulates entering a URL in the address bar of a browser and then loading the page. Single-URL browser monitors comprise a single Navigate event.

To enhance synthetic monitor security, Dynatrace blocks monitors from sending requests to a local host (for example, localhost or 127.0.0.1).

In recorded clickpaths, the first event is automatically created as a Navigate event. However, when adding events manually or editing a clickpath, you can add a JavaScript event as the first event of the monitor. Navigate events can be preceded only by one or more JavaScript events. A clickpath requires at least one Navigate event.

If you re-record your clickpath by selecting Record again, any JavaScript events that precede the first Navigate event will be erased—if you want to retain your initial JavaScript events, opt to Discard changes introduced by recording again.

Going to a new webpage by clicking a link in the current webpage creates a Click event in desktop profiles (or a Tap event in mobile profiles), not a Navigate event.

See the sections below on wait and validation controls.

Basic authentication

You can automate signing in to the specified URL using basic authentication—Enable basic authentication.

To automate form-based login, begin recording your clickpath. During recording, type in your username and password as usual. Your login credentials will be securely recorded and stored so that signing in is automated during monitor runs—see Supported authentication methods in Synthetic Monitoring for more information. See the Keystroke event for information on recording data entry, including user credentials, into fields.

Dynatrace stores and manages all Synthetic Monitoring credentials in a credential vault. Credentials are access controlled and can be designated as owner only or public.

You can choose an existing credential (Select credentials). You can only see the credentials that you have access to in this list, that is, public credentials or owner-only credentials created by you.

Navigate event credential from vault

You can Create new credentials by entering a Username and Password. Provide a name for the credential and Save to vault. The credentials you create this way are automatically set to owner-only permissions and can only be used by you.

Note that you must have permission to access the credential vault in order to create credentials in script or UI mode in a browser monitor in this way. You can always capture entered credentials as part of a recorded clickpath.

Navigate event create credential

Click

In browser monitors, the Click event defines where to perform a mouse click on a page. It's inserted when you click an element such as a link, button, or field.

See the sections below on wait and validation controls.

The Click event interacts with a specific element on the web page. See the information on locators below to define how an element should be found.

Tap

In mobile device profiles (including tablets, laptops with touch, and custom devices specified as mobile), the Tap event defines where on a page to record tapping the device screen with a fingertip. For example, a Tap is inserted when you tap a hyperlink, button, or select a field.

When recording on mobile device profiles, the cursor changes to an icon that represents a fingertip.

Mobile cursor

See the sections below on wait and validation controls.

The Tap event interacts with a specific element on screen. See the information on locators below to define how an element should be found.

Keystroke

The Keystroke event captures the string you type in a field on a web page.

  • The string is recorded in Text value, which can be edited. All text is captured by default as Plain text. However, for passwords stored to the credential vault, the text type is Credentials.

    Dynatrace stores and manages all Synthetic Monitoring credentials in a credential vault. Credentials are access controlled and can be designated as owner only or public.

    Read on below to learn how to capture or set a password and how to create a token in a Keystroke event.

  • Simulate Return key automatically simulates the pressing of the Return key after keystrokes, for example, to submit a search string or trigger a login. When creating a monitor in UI mode, this saves you from having to set up a Click event after entering data into a field.

  • Simulate blur event (enabled by default) defines whether a blur event is simulated, which is usually when a text field loses focus.

  • See the sections below on wait and validation controls.

  • The Keystroke event interacts with a specific element on screen such as a form field. See the information on locators below to define how an element should be found.

Capturing or setting a password in Keystroke

In a Keystroke event, a recorded password is captured by default as Plain text. You can Save to credential vault—the data type automatically changes to Credentials.

Reset text value only if you want to clear the captured credential and convert the field to unencrypted text.

Captured password in Keystroke

You can also use a different credential stored in the vault or create a new one in a Keystroke event. First, change the data type to Credentials.

You can choose an existing credential (Select credentials). You can only see the credentials that you have access to in this list, that is, public credentials or owner-only credentials created by you.

You can choose from user ID/password pairs or token credentials. Note in the image below how only the password from a retrieved UID/password pair is used.

Retrieve credentials to Keystroke

You can Create new credentials by entering a Username and Password. Provide a name for the credential and Save to vault. The credentials you create this way are automatically set to owner-only permissions and can only be used by you.

Note that you must have permission to access the credential vault in order to create credentials in script or UI mode in a browser monitor in this way. You can always capture entered credentials as part of a recorded clickpath.

Create a credential in Keystroke

Create a token in Keystroke

You can use an existing token you have access to in Keystroke. Change the text type to Credentials and select the ID of the credential you wish to use (Select credentials).

To create a new token, select Create new credentials. Select Token as the Credential type. Edit the default credential name, provide a Token value, and Save to vault. The credentials you create this way are automatically set to owner-only permissions and can only be used by you.

Note that you must have permission to access the credential vault in order to create credentials in script or UI mode in a browser monitor in this way.

Create a token in Keystroke

Select option

The Select option event describes the use of lists in a clickpath.

The Index describes the position of the chosen item from the top; the first item in a list is always annotated 0. The Value field shows the text value of the item selected.

Click Add another selection to add another item to select in the same list. You can delete selected options as required.

See the sections below on wait and validation controls.

The Select option event interacts with a specific element on screen. See the information on locators below to define how an element should be found.

JavaScript

The JavaScript event allows you to execute snippets of JavaScript as part of your browser clickpaths.

With JavaScript events, you can create clickpaths for scenarios with some dynamic parts where it might be necessary to react on the page, for example:

  • Login flows including random security questions
  • Complex date selectors
  • Pages using A/B testing
  • Signups or product order workflows
  • Custom validations

In the editor provided, define your JavaScript snippet, the target window, and wait strategy. The API that allows you to store and retrieve values, control JavaScript event outcome, or skip execution is described below.

JavaScript event

When adding events manually or editing a clickpath, you can add a JavaScript event as the first event of the monitor for such use cases as fetching a credential from the credential vault and setting a variable for use in the Navigate event URL. This feature requires ActiveGate version 1.225 and Chromium version 88+ on private Synthetic locations.

Navigate events can be preceded only by one or more JavaScript events; a clickpath requires at least one Navigate event.

If you re-record your clickpath by selecting Record again, any JavaScript events that precede the first Navigate event will be erased—if you want to retain your initial JavaScript events, opt to Discard changes introduced by recording again.

JavaScript event API

The JavaScript event offers a basic API for the following operations.

Store and retrieve values across monitor events

  • api.setValue(key, value)—Sets a value for the key. Use a separate instance of api.setValue() for each key-value pair you wish to specify.
  • api.getValue(key)—Gets the value of the key previously set by api.setValue().
  • api.getValues()—Returns an object holding the key-value pairs that were previously set by api.setValue().

Variables can be passed only in the context of a single execution of browser clickpath. You also need to make sure that when you refer to a variable, the data behind it is logically available to the monitor.

After you set a global variable using the api.setValue() method, you can subsequently apply its value using the {variable_name} convention with api.getValue() or api.getValues(). You can also apply the value in subsequent browser clickpath configuration fields using the {variable_name} convention. The UI informs you whenever this is possible.

Variable and key names have a 100-character limit. Global variable values have a 5000-character limit.

Mark events as failed or finished

  • api.fail(message)—Marks the request as failed, providing the message as the reason, and marks the monitor execution as failed. message appears as the Failure reason for the execution in the Multidimensional analysis page. The message parameter has a 200-character limit.
  • api.finish()—Finishes the JavaScript event so that the next event is executed.
  • api.startAsyncSyntheticEvent()—Causes the JavaScript event to wait for a later call of api.finish() or api.fail() to end it. As the use of this method overrides the wait condition, we recommend setting the wait time to None.

Skip clickpath events

These methods skip events after completion of the current event.

  • api.skipNextSyntheticEvent()—Skips execution of the next event.
  • api.skipNextSyntheticEvents(n)—Skips execution of the next n consecutive events.
  • api.skipSyntheticEvent(eventIndex)—Skips execution of the event with the index eventIndex. Event index numbers start at 1 and match the event numbers displayed in the web UI.
  • api.skipSyntheticEvents(eventIndexes)—Skips execution of multiple events; the array eventIndexes specifies the indexes of events to skip, for example, api.skipSyntheticEvents([8, 9]).

Basic logging

  • api.info(message)—Logs a message using the info log level.
  • api.warn(message)—Logs a message using the warning log level.
  • api.error(message)—Logs a message using the error log level.

The message parameter has a 200-character limit. After local playback, logging appears at the bottom of the Dynatrace web UI. Select Show full log as shown in the image below. When executing monitors from a private Synthetic locations, log lines (with the [CUSTOM] prefix) can be found in the VUC test execution file.

Log file for local playback

Retrieve data

  • api.getCredential(id, type)—Retrieves a credential value, given the credential ID (id) and (type), which can be username, password, or token. You must provide the exact value of one of the autocomplete suggestions for the credential ID; using dynamic identifiers like variables is not supported. The list consists of only those credentials to which you have access.

    Requires ActiveGate version 1.212+ for private Synthetic locations.

    Important

    As a security best practice, we recommend that you use only dedicated test credentials for synthetic monitors.

  • api.getContext().location

    • api.getContext().location.name—Returns the name of the private or public location from where the monitor is executed. This is helpful when applying conditional logic such as displaying localized pages or using different login information per location.
    • api.getContext().location.cloudPlatform—Returns the name of the cloud platform on which a public Synthetic location is deployed.

    During local playback, properties of the context are undefined. We recommend setting a default value to cover this scenario.

Examples

Cookies enable you to store browser state information on the client side so that each monitor execution is based on the same state and you can accurately monitor a performance baseline.

You can set cookies in Additional options when creating a browser monitor or in Advanced setup in monitor settings in edit mode. These cookies are valid for the entire monitor execution. If you want to set cookies only for a specific portion of your clickpath, use the Cookie event.

In edit mode, enable Set cookies, then provide a Name and cookie Value. Every cookie must be unique within the list.

The following symbols are not allowed in the cookie value: ;,\". Provide the Domain of the cookie, and optionally, the Path to the cookie. Save your cookie.

Select Add cookie to define additional cookies.

Cookie event

Common controls

This section describes controls that are common to several event types.

Amount of time to wait before the next event is triggered

While Dynatrace automatically selects an appropriate wait time for each event, you can customize this setting to define how long Dynatrace should wait before the next event is executed.

  • None

  • Wait for page to load completely waits for network activity to be completed after the load event is triggered. This is the default wait time used when loading a new page.

  • Wait for specific period of time allows you to specify the number of seconds that Dynatrace should wait between this event and the next.

  • Wait for background network activity to complete waits for all network activity to be complete following the event. This is the default wait time used for XHRs and interactions within single-page applications.

    This option is not available for Navigate events.

  • Wait for specific element to appear allows wait for a specific HTML element on the page by specifying the CSS or DOM locator for the element. You can also specify to text to validate against in the element, and a timeout for locating the element.

  • Wait for next event waits until one of the locators of the next event is found. This is basically the same as Wait for specific element to appear but automatically uses the locators of the next event.

Note

Be sure to specify a wait time that it does not exceed the programmed timeout values for browser clickpaths (see below). These timeouts cannot be changed. A problem will be generated if these timeouts are exceeded.

  • Script timeout: 5 minutes
  • Event timeout: 60 seconds

Validate content

Content validation helps to verify that your browser monitor loads the expected page content or element. Validations are performed through validation rules—select Add custom content validation to define a validation rule.

In browser clickpaths, you define validations for each event; for single-URL monitors, you define validation for the monitor as a whole as they only contain a single event.

All validation is performed after following all redirects, even if the very first response delivers HTML content.

You can validate based on specific text on a web page, a specific element, text included within an element, or text in the DOM or any resource. You can opt to pass or fail your monitor/event based on your validation criteria. If pass criteria are not met (or fail criteria are met), the monitor/event fails and the execution is aborted.

Validation criteria

When defining validation, specify the tab (Target window) in which the text/element should be found.

If your validation is based on content (contains text), the markup text for an element (contains text in element), or text in the DOM or a resource (contains text in DOM or any resource), you must provide the text string (Specify text). Enclose placeholder values in brackets, for example {email}. Optionally, you can specify text as a regular expression (Evaluate as regular expression).

If your validation searches for an element (contains element) or the markup text for an element (contains text in element), you must specify the CSS Selector or DOM locators to use during replay—select Add locator, then select DOM or CSS, and provide the locator reference. You can add as many locators as you like.

Validation

You can add more than one validation to an event/monitor. If you have defined multiple validation rules, you can reorder and delete rules as required.

Validation rules

Edit element locators

This control is available in Click, Tap, Keystroke, and Select option events.

When one of the above events in your clickpath targets a specific element on a web page, you can edit the element locators in either DOM or CSS Selector format. Locators help Dynatrace identify the element during playback. Click Add locator, then select DOM or CSS, and provide the locator reference.

You can add as many locators as you like. You can also edit or delete any existing locators for your event.

optional You can also specify the tab (Target window) in which the element should be found. window[0] is the first window opened and window[1] represents the second window (or tab).