Selenium IDE is a standalone 3rd party tool for creating Selenium test cases. These test cases can be imported as script files into Synthetic Monitoring ASM and used within Browser Checks to collect performance metrics for the scenario.

Step 1: Create a Selenium Script

Create your Selenium script using Selenium IDE. It does not matter which Selenium IDE or Browser version you use; note that in some cases, some manual effort will be needed in order to convert your scenarios into a working ASM Scenario.

...

In some cases, users must make changes to their Selenium IDE script before it can be used within ASM as a Scenario. This article explains how ASM handles Selenium IDE scripts so you can easily understand how to convert your scripts into Scenarios.

Supported Selenium IDE Commands

Use the following table as a reference when determining whether a certain Selenium IDE command is compatible with your ASM Scenario.

Usage Assertion Modes

Assertion Modes

All Selenium Assertions can be used in 3 modes: assert, verify, and waitFor.

Modes In Synthetic Monitoring

Verify = Assert

In Synthetic Monitoring, false results from both verify and assert are treated the same: as a major failure.

For clarity, we recommend you only use Assert commands in any scripts you want to use with Synthetic Monitoring.

WaitFor

With waitFor commands, the behavior is the same as in Selenium IDE.

Modes in Selenium IDE

Assert

When an assert command returns false, test execution will be aborted. This means that all following test steps after that line of code are skipped.

Verify

When a verify command returns false, test execution will continues, and the failure is logged. Usually this behavior is desired when a particular failure does not reflect a vital component.

WaitFor

The waitFor commands wait for some condition before continuing. If the condition is already true, they return true immediately. If the condition does not become true within the timeout threshold, the test will fail and execution is aborted.

Usage Types

Selenium commands are generally one of three types: Actions, Accessors, and Assertions.

Actions

Actions are commands that generally manipulate the state of the application. They do things like click this link and select that option. If an Action fails, or has an error, the execution of the current test is stopped.

Many Actions can be called with the AndWait suffix, e.g. clickAndWait. This suffix tells Selenium that the action will cause the browser to make a call to the server, and that Selenium should wait for a new page to load.

Accessors

Accessors examine the state of the application and store the results in variables, e.g. storeTitle. They are also used to automatically generate Assertions.

Assertions

Assertions are like Accessors, but they verify that the state of the application conforms to what is expected. Examples include make sure the page title is X and verify that this checkbox is checked.

insertPageBreak

...

Custom ASM Commands

ASM supports several commands which are not utilized in native Selenium IDE: insertPageBreak, takeScreenshot, and getDictionary.

setLocation

The setLocation command may be utilized in order to mimic a certain location from within the browser. To use, specify “setLocation” as the command and specify the desired coordinates as the Target:

...

Accepted syntax for Target coordinates includes:

• latitude: 59.3259965, longitude: 18.0057939

• 59.3259965, 18.0057939

insertPageBreak

ASM scenarios support a custom command called insertPageBreak. This command creates a new page break that separates different pages (which typically consist of multiple URL calls) from each other.

...

The command expects one argument

...

- a name - which will be shown on the Result Details page in ASM.

They provide logical divisions in the page flow, typically by adding a page break before each workflow step that could utilize multiple web pages on a site.

Page breaks can be entered manually into scripts or automatically generated when recording web sessions.

Example

For example, If the login portion of a web page sequence takes place over two or three HTML pages, the manual Page break Break could define organize the set of HTML pages to be all part of into a single group before the next logical page navigation , - another Page Break, which could be “Check my account.”

When should I use insertPageBreak?

Typically, insertPageBreak is only necessary if you need to set a custom title or if requests which are triggered as a result of . Manual page breaks are helpful when requests triggered by executing multiple different commands all end up as part of the same step, and you wish there is a need to split these requests into multiple steps.

Dictionary Concept

In Synthetic Monitoring, the concept of “Dictionaries” is a repository to store:

• User names

• Passwords

• Internal access URLs

• And other sensitive data

Dictionaries can be used for data reuse in multiple environments or to hide access information during monitoring. This lets you use passwords in scenarios without having them displayed in cleartext or reuse a single URL in several different scenarios without manually coding it.

The getDictionary Command

The Apica custom Selenium scripting command getDictionary allows you to access a user-defined dictionary from inside a check scenario script.

The getDictionary fetches the whole Dictionary (with all key/value pairs) and stores it locally for when the script executes. 

Selenium Example:

When the getDictionary command fetches pre-defined variables from a dictionary, it expects two arguments:

1. Target: Your API Token or Authorization Ticket

2. Value: The dictionary URL https://api-wpm.apicasystem.com/v3/scenarios/proxysniffer/dictionaries/{dictionary_key}

Here’s a screenshot of a Selenium step with getDictionary

...

Command

...

Target

...

Value

...

getDictionary

...

63F6E******************

...

{API URL}/DougApicaKey

...

Postman Screenshot example of the API GET command for the DougApicaKey dictionary:

...

Another Postman Screenshot example of the API GET command for the ApicaKey dictionary. You can see how each dictionary has defined different key-value pairs.

...

Selenium Example 1: The Dictionary Key "DougApicaKey" has 3 key values (excluding the sample value) that are used in the scenario.

(Click on image for a larger version)

...

Selenium Example 2: The Dictionary Key "Apicakey" has 2 key values (excluding the sampleKey value) that are used in this scenario.

In this case, the username and password values, from your dictionary will be used in the Selenium scenario rather than these values being hard-coded in the script.

...

It is possible to disable automatic insertion of page breaks via the Edit Check settings. See https://apica-kb.atlassian.net/wiki/spaces/ASMDOCS/pages/2134212678/Understanding+Browser+Check+Results#Page-Breaks-in-a-Browser-Check-Result for more information on page breaks.

takeScreenshot

The command takeScreenshot takes a screenshot that will be visible in the Details.

Description

This is in addition to the regular Details Result Screenshots feature.

Use the normal takeScreenshot, which captures just what is visible in Chrome, while Firefox captures the entire "page."

Adding takeScreenshot anywhere in your script will allow you to get screenshots at this step in the scenario.

Apica Custom Script Extension

The Apica custom extensions can be downloaded from the https://wpm.apicasystem.com/ManageScenarios view in Synthetic Monitoring:

Download

...

To download the Apica Extension:

• https://wpm.apicasystem.com/Account/Login to Synthetic Monitoring

• Open the https://wpm.apicasystem.com/ManageScenarios view

• Click the https://wpm.apicasystem.com/ManageScenarios/DownloadScriptExtension link

Install Extension

Install Apica Extension

In order to use the Apica Extension with Selenium IDE, you need to add it as an option and restart Selenium IDE.

Install Extension

To install the Apica extension:

Start in Firefox:

...

• Open Selenium IDE

...

• Open the Options menu

• Select Options...

The Selenium IDE options dialog opens:

In the General tab:

...

• Find the Selenium Core Extensions field

• Click Browse

...

• Find the downloaded plugin file (apicaExt.js)

• Select the file

• Click Open

...

• Click OK

Reopen the IDE window to apply the changes.

• Close Selenium IDE

Next time you open Selenium IDE, the plugin will be loaded.

Encrypted Selenium Variables

Don’t just Mask. Encrypt!

...

Emulating users clicking through your web application with scenarios is an important aspect of synthetic monitoring. Still, a downside of using these scenarios is that sensitive credentials or other data can be exposed to other Apica Synthetic users.  To improve the security and control of important data, we have added the ability to encrypt variables in your scenarios.  Any data stored in an encrypted variable is completely inaccessible except when the scenario is actually being run, so you can now safely add scenarios to even your most sensitive applications without the fear of your information getting into the wrong hands.

...

To add an encrypted variable to your scenarios, add a variable using the Selenium "store" command, and start the name of your variable with "encryptapica."  You can then use that variable safely anywhere in your scenario.

...

Step

...

Screenshot

...

1. Edit a Check with a Selenium Scenario. Find this in the Check Information section, where you can select which Scenario to edit.

   1. Click the green Debug Scenario icon to the right of the chosen scenario.

...

...

1. Identify the sensitive information that you want to encrypt.

In this example, we have a password being passed in the clear each time it is run. We’ll want to encrypt this password with the Apica crypto service that will pass a variable name in its place.

...

...

1. Store the value as encrypted by adding/

storing a new variable to hold the encrypted value.

a. Near the top of your scenario, Add/Declare a new variable with the 'Store' Command in the dropdown box.

1. ‘encryptapica’ is the string that calls/envokes the crypto service and precedes the name of the item you want to protect with encryption (in this case, the password), so “encryptapicapassword” is the value for what we still store.

...

1. Enter the original Target Value

a. Double-click in the target field.

b. A new dialog box, “Update Encrypted Value” will appear to enter in your plaintext value. Be sure that you have a version of this plaintext securely stored somewhere because Apica will not retrieve the plaintext value.

Click the Update & Encrypt to begin the encryption.

...

...

1. After the encryption has been completed, the green lock will appear, and the words “[ENCRYPTED BY APICA]” will be in the Target field.

...

1. In the step where, in this example, the password originally appeared, you now will replace the plaintext password with the stored variable name that you selected. In this case, in step 25, the variable ‘encryptapicapassword’ will be entered as $(variable_name) or ‘$(encryptapicapassword)’

...

1. You are finished. Please test your scenario to ensure it passes the encrypted values to your application, and then remember to click SAVE SCENARIO.

...

In the video tutorial below, we will demonstrate this process for a script with a plaintext password replaced using this crypto service.

Masking Selenium Values

When command values contain sensitive information, they can be masked by using the apica Prefixes. This will prevent the value from being displayed in results.

Example

Let’s assume you use a scenario with the following commands:

...

Command

...

Target

...

Value

...

open

...

/

...

selectWindow

...

null

...

type

...

id=username

...

user1

...

type

...

id=password

\{\{${maskapicaPassword}\}\}

...

clickAndWait

...

_input@value='Log in'

If you want to mask the value secretPa$$word in the Check Result page the following steps are required:

• Add the command Store to store the password as a variable with the prefix maskapica

• Use this variable with the actual command which uses the password.

Your commands should now look like this:

...

Command

...

Target

...

Value

...

store

...

secretPa$$word

...

maskapicaPassword

...

open

...

/

...

selectWindow

...

null

...

type

...

id=username

...

user1

...

type

...

id=password

\{\{${maskapicaPassword}\}\}

...

clickAndWait

...

_input@value='Log in'

When Synthetic Monitoring runs a check using this scenario the result will be saved with the executed scenario commands list as the example above. When Synthetic Monitoring shows the check result on the check results page Synthetic Monitoring will recognize that there is a command value which starts with maskapica.

The command’s target will be masked on the the check results page:

...

Command

...

Target

...

Value

...

store

...

*******

...

maskapicaPassword

...

open

...

/

...

selectWindow

...

null

...

type

...

id=username

...

user1

...

type

...

id=password

\{\{${maskapicaPassword}\}\}

...

clickAndWait

...

//input@value='Log in'

Prefixes

Synthetic Monitoring supports custom security prefixes for use in select scenario values where information may need more security.

‘apica’ to store information

Store a result with “apica”

Synthetic Monitoring will store the command result for later display when the "apica" prefix is used in a command value.

Display

The command value is shown in Details in the Details Result Scenario in the Value column.

Example

...

Command

...

Target

...

Value

...

storeCookieByName

...

ServerID

...

apicaServerID

This example will store the ServerID cookie value and show it as apicaServerID Extracted Value.

This prefix will work with any command that starts with “store."

‘maskapica’ hide a value

Maskapica

When the "maskapica" prefix is used in a command value, the web performance monitor will store the command target (the example Target below is '$(ExternalPassword) ') as is in the result but will mask it (as the example Value below, “maskapicaPassword“) on the check result page. 

Example

...

Limitations of Selenium IDE within ASM Scenarios

Key Codes

When using sendKeys in Selenium IDE, certain key codes are not available in Scenario Migration.

Overview

${KEY_ENTER}

${KEY_SHIFT}

${KEY_LEFT}

JavaScript Execution

WebDriver’s JavascriptExecutor will wrap all JS and evaluate it as an anonymous expression.

Impact on JavaScript execution

This means that you need to use the “return” keyword:

browserbot.getCurrentWindow().document.title

becomes

return document.title;

The same is true when evaluation expressions using storeEval or assertEval:

Selenium IDE

...

assertEval

\{\{${stored_var} > 0\}\}

...

true

WebDriver

...

assertEval

\{\{return ${stored_var} > 0\}\}

...

true

Note that there are multiple commands that will result in javascript evaluation: gotoIf, assertEval, getEval, storeEval

Key Strokes

If you need to simulate a keypress input event, such as pressing the enter key, you must use keyPress or keyPressAndWait (if the keystroke triggers a new page load), with the ASCII as an argument.

Overview

Example: Press enter key and wait for new page load

...

keyPressAndWait

...

id=gh-ac

...

\13

Response Times

Agents running Microsoft Windows may handle very short report times incorrectly.

Waterfall graph

Agents running Microsoft Windows sometimes report 0ms for URL calls with very quick response times (0-20ms).

Return Required

For Selenium commmands that execute javascript snippets, the command expects a returned value

Return Command In Scripts

The following commands result in javascript evaluation/expects a javascript snippet as argument, which must include the 'return' keyword:

GotoIf

RunScript

RunScriptAndWait

GetEval

StoreEval

StoreExpression

Type & sendKeys

Even though the "type" command should work in most cases, we strongly recommend that you use "sendKeys" instead.

Key Strokes

If you need to simulate a key press input event, such as pressing the enter key, you must use keyPress or keyPressAndWait (if the key stroke triggers a new page load), with
the ascii code as argument:

Example: Press enter key and wait for new page load
keyPressAndWait | id=gh-ac | \13

Script Variables

Check Details. The command will insert an additional screenshot onto the page in addition to whatever screenshots have been added in the Edit Check settings. This command is helpful when troubleshooting scripts as it gives a snapshot of what exactly happens at a particular step.

getDictionary

See Storing and Retrieving Information Using the ASM Dictionary.

Limitations of Selenium IDE within ASM Scenarios

Key Codes

When using sendKeys in Selenium IDE, the key codes ${KEY_ENTER}, ${KEY_SHIFT}, and ${KEY_LEFT} are not valid commands within Selenium IDE. Use keyPress or keyPressAndWait (if the keystroke triggers a new page load) instead. When entering a keystroke, use the respective ASCII values for the key you want to be pressed. For example, if you want to press Enter within an application, use the command keyPress and the value \13.

The “value” of the command corresponds to the ASCII “Oct” value of the key you are trying to press; see https://www.asciitable.com/ for a full list. Some examples of values which correspond to keys include the following:

\10 corresponds to “backspace”

\9 corresponds to “tab”

JavaScript Execution

Selenium WebDriver’s JavascriptExecutor will wrap all JavaScript and evaluate it as an anonymous expression. Therefore, the “return” keyword must be used when executing JavaScript within the “Target” field for the following commands:

GotoIf

GetEval

StoreEval

StoreExpression

The following commands do not require the use of “return”:

RunScript

RunScriptAndWait

For example, if you are trying to determine whether the result of the expression ${stored_var} > 0 is true, use the following code:

The following screenshot (supplemental text provided) shows an example in which JavaScript is being used to execute another check upon completion of the current scenario. Basically, the check kicks off another check when it’s finished.

Within the scenario:

...

Run execution log:

...

Javascript snippet:

var xhr = new XMLHttpRequest();

xhr.open('POST', 'https://api-asm.apica.io/v3/checks/3393731/job?auth_ticket=${auth_ticket}', true);

xhr.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');

xhr.onreadystatechange = function () {
    if (xhr.readyState === 4) { 
        if (xhr.status === 200) { 
            var response = JSON.parse(xhr.responseText);
            console.log('Success:', response); 
        } else {
            console.error('Error:', xhr.statusText);
        }
    }
};

xhr.send();

return "check ID 3393731 has been executed!"

The “runScript” or “runScriptAndWait” commands could also be used with the above Javascript if the “return” statement is omitted.

Type & sendKeys

Even though the type command works in most cases, Apica strongly recommends using sendKeys instead of type. The type command edits the HTML format of the code, while the sendKeys command attempts to simulate actual typing and is therefore able to trigger javascript code in fields.

Incrementing a Stored Numeric Value

It is currently not possible to change the value of a variable from within a javascriptJavaScript snippet.

##

This Selenium IDE code will change the value of $counter:

However the following example won't affect The following command will not change the value of $counter:

...

Usage Assertion Modes

In order to assert a command within Selenium IDE, you can use the assert, verify, or waitFor commands; the assert command will stop the Selenium IDE script if the expected condition is not met, while the verify command will log an error message but not stop the script. ASM scenarios, by contrast, treat the assert and verify commands the same way - if the expected condition is not met, both commands will result in a failure of the scenario.

By contrast, the behavior of the waitFor command is the same within Selenium IDE and ASM Scenarios. Within both tools, the waitFor command will wait for a specified element and will result in a script failure if the element is not found within the specified timeframe. The default timeframe is 30 seconds and can be changed with “setTimeout”.