Scripting reference

Reference guide for scripting synthetic tests

1. Getting started

Before you get started, refer to the Test scripting document for a review of how to add synthetic scripts to your test configuration. Here are the basics you need to know before writing your first script.

// Comments like these are ignored

// So are blank lines
  • Each line of the script contains a command and any parameters.
  • Parameters are tab delimited
  • A script timeout of 120 seconds is enforced for all tests

2. Operating on the DOM

Commands operating on the DOM identify the element with a format of attribute=value
If you are filling out a form and you want to populate an element like this:

<input type="text" class="tabInputFields" id="lgnId1" value="" tabindex="1" 
maxlength="99" name="loginId"/>

You can identify the element as id=lgnld1, name=loginId or tabindex=1. The class attribute is special and is referenced as className. Use the name attribute when possible for form fields.

In addition to attribute matching, you can match on innerText and innerHtml. Both will match the contents of the DOM element instead of the attributes.

<div dojoattachpoint="containerNode" class="label">Delete</div>

This can be identified by innerText=Delete. Matching is case sensitive and matches on the full string.

3. Multi-step scripts

SpeedCurve does not report data for multi-step scripts separately. If scripting a multi-step transaction, you need to disable data logging for intermediate steps.

// Supress data logging
logData 0

// Navigate through a user journey
navigate    https://www.yoursite.com
navigate    https://www.yoursite.com/pagetwo

// Enable data logging
logData 1

// Record this step
navigate    https://www.yoursite.com/lastpage

Explore these additional recipes for scripting multi-step scripts.

4. Working with variables

In order to simplify your scripts and help with script maintenance, variable may be used.

Replacing URL for a test using %URL%

URL: https://speedcurve.com
navigate %URL%
// output: navigate  https://speedcurve.com

Host of the URL for the test (not including protocol) using %HOST%

URL: https://speedcurve.com
setDnsName %HOST% dns.example
// output: setDnsName  speedcurve.com dns.example

Origin of the URL (includes protocol and port if defined) using %ORIGIN%

URL: https://speedcurve.com/blog
setCookie  %ORIGIN% foo=bar
// output: setCookie https://speedcurve.com foo=bar

URL: https://speedcurve.com:8080/blog
setCookie  %ORIGIN% foo=bar
// output: setCookie https://speedcurve.com:8080 foo=bar

%HOST_REGEX% – Using HOST compatible with regular expressions by escaping dots

URL: https://speedcurve.com
setHeader  Foo: Bar  %HOST_REGEX%
// output: setHeader Foo: Bar  speedcurve\.com

%HOSTR% – Using the final host name of the URL after following redirects

URL: https://redirect.speedcurve.com
setDnsName %HOSTR% dns.example
// output: setDnsName  speedcurve.com dns.example

%TEST_ID% – replaced with the id of the current test

// URL: https://speedcurve.com

navigate    %URL%/?tag=%TEST_ID%

// output: navigate https://speedcurve.com/?tag=230518_XF_3

5. Command reference

Navigating and Interacting with the DOM

navigate

Navigates the browser to the provided url.

// usage: navigate <url>
navigate    https://speedcurve.com

click

Triggers a click event for the identified element. This DOES NOT have an implied wait after the event.

// usage: click <attribute=value>
click   id=Go

clickAndWait

Triggers a click event for the identified element and waits for the browser activity to complete.

// usage: clickAndWait <attribute=value>
clickAndWait    innerText=Publish

selectValue

Selects a value from a dropdown list of the element.

// usage: selectValue   <attribute=value>   <value>
selectValue id=country  usa

sendClick / sendClickAndWait

Creates a javascript OnClick event and sends it to the indicated element.

// usage: sendClickAndWait  <attribute=value>
sendClickAndWait    innerText=Send

sendKeyDown / sendKeyUp / sendKeyPress (AndWait)

Creates a javascript keyboard event (OnKeyDown, OnKeyUp, OnKeyPress) and sends it to the indicated element.

// usage: sendKeyDownAndWait    <attribute=value>    <key>
// <key> - Key command to send (special values are ENTER, DEL, DELETE, BACKSPACE, 
//TAB, ESCAPE, PAGEUP, PAGEDOWN)
sendKeyDownAndWait  name=user    x

setInnerHTML

Sets the innerHTML of the given DOM element to the provided value. INCLUDES HTML formatting.

// usage: setInnerHTML  <attribute=value>   <value>
setInnerHTML    myContent   %MSG%

setInnerText

Sets the innerText of the given DOM element to the provided value. DOES NOT INCLUDE HTML formatting.

// usage: setInnerText  <attribute=value>   <value>
setInnerText    myContent   %MSG%

setValue

Sets the value attribute of the given DOM element to the provided value. Currently only "input" and "textArea" element types are supported.

// usage: setValue  <attribute=value>   <value>
setValue    name=loginId    userName

submitForm

Triggers a submit event for the identified form.

// usage: submitForm    <attribute=value>
example: submitForm name=AOLLoginForm

exec

Executes javascript.

// usage: exec  <javascript code>
exec    window.setInterval('window.scrollBy(0,600)', 1000);

execAndWait

Executes javascript and waits for the browser to complete any activity generated from the action.

// usage: execAndWait   <javascript code>
execAndWait window.setInterval('window.scrollBy(0,600)', 1000);

End conditions

setABM

Sets the "Activity Based Measurement" mode.
Valid values are:

  • 0 - Disabled (Web 1.0 - Measure based off of document complete)
  • 1 - Enabled (Web 2.0 - Measure until activity stops)
    The default if not specified in the script is 1 (Enabled) Browser Support: IE, Chrome, Firefox
// usage: setABM    <mode>
setABM  0

setActivityTimeout

Overrides the timeout value for the time after the last network activity before a test is considered complete (defaults to 2000 which is 2 seconds).

// usage: setActivityTimeout    <timeout in milliseconds>
setActivityTimeout  5000

setTimeout

Overrides the timeout value for the individual script steps.

// usage: setTimeout    <timeout in seconds>
setTimeout  60

Request Manipulation

block

Blocks individual requests from loading. The command matches the list of things to block against the full url of each request (including host name).

// usage: block    <block strings>
block    adswrapper.js addthis.com

blockDomains

Blocks all requests from the given domains from loading. Takes a space-delimited list of full domains to block.

// usage: blockDomains    <block domains>
blockDomains    adswrapper.js addthis.com

blockDomainsExcept

Blocks all requests not from one of the given domains from loading. Takes a space-delimited list of full domains to allow.

// usage: blockDomainsExcept    <allow domains>
blockDomainsExcept    www.example.com cdn.example.com

Explore this recipe for further examples of request blocking.

setCookie

Stores a browser cookie to be used while navigating.

// usage: setCookie <path>  <value>
setCookie   http://www.speedcurve.com   zip=80212
// setting multiple cookes for a path
setCookie   http://www.speedcurve.com   TestData = Test; expires = Sat,01-Jan-2031 00:00:00 GMT

setDns

Allows for overriding the IP address to be used for a host name. The override is effectively the same as populating an entry in the hosts file and will eliminate the DNS lookup times.

// usage: setDns    <host name> <IP Address>
setDns  www.speedcurve.com  127.0.0.1

setDNSName

Allows for overriding a host name (creating a fake CNAME). Browser Support: IE, Chrome, Firefox

// usage: setDnsName    <name to override>  <real name>
setDnsName  mark.speedcurve.com www.speedcurve.com

Explore this recipe for further examples of DNS manipulation.

setUserAgent

Overrides the User Agent string sent by the browser.

🚧

Caution

You will still be using the same browser engine so you are still limited by the capabilities and behavior of that browser even if you are spoofing another browser.

// usage: setUserAgent    <user agent string>
setUserAgent    Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) Version/3.0 Mobile/1A543 Safari/419.3

overrideHost

Replaces the value of the Host: HTTP header for the given host with the provided replacement. It also adds a new header (x-Host:) with the original value.

// usage: overrideHost  <host>    <new host>
overrideHost    www.speedcurve.com    www.notspeedcurve.com

overrideHostUrl

For all requests to the given host, rewrite the requests to go to a different server and include the original host in the new URI.

// usage: overrideHostUrl   <host>    <new host>
overrideHostUrl www.speedcurve.com    staging.speedcurve.com

addHeader

Adds the specified header to every http request (in addition to the headers that exist, DOES NOT overwrite an existing header).

// usage: addHeader <header>    {filter}
addHeader   Pragma: akamai-x-cache-on

setHeader

Adds the specified header to every http request, overriding the header if it already exists.

// usage: setHeader <header>    {filter}
setHeader   UA-CPU: none-ya

resetHeaders

Clears any headers that were specified through addHeaders or setHeaders (in case you want to only override headers for part of a script).

// usage: resetHeaders
resetHeaders

Misc

combineSteps

Causes multiple script steps to be combined into a single "step" in the results

// usage: combineSteps  [count]
combineSteps

// Sample Script:
combineSteps
navigate    www.google.com
navigate    www.yahoo.com
navigate    www.aol.com

if/else/endif

Conditionally execute a block of script code based on run number or cached state for the test. Conditional blocks can be nested.

// usage:  if   [cached|run]    <value>
//        else
//        endif

if    run    1
    if    cached    0
        <do something for first view of first run>
    endif
else
    <do something else for everything but first run>
endif

expireCache

Expires any cache entries that will expire within the specified number of seconds. This can be used to simulate a repeat view after a certain amount of time (for example, what it would be like to browse the page the next day). It does not help with simulating content changes but any resources with a short expiration will end up being checked with if-modified-since requests.

// usage: expireCache   <seconds>
expireCache 86400

setLocation

Specifies a geolocation override position.

// usage: setLocation   <lat>,<lng>    <accuracy>
setLocation    38.954980,-77.447956    10

sleep

Pauses the script operation for a given number of seconds.

// usage: sleep <seconds to sleep>
example: sleep  5

speedcurve_removePTST

Removes PTST/SpeedCurve from the User Agent string

// Usage: remove PTST/SpeedCurve from User Agent string
speedcurve_removePTST 1

speedcurve_clearcerts

Clears the OS certificate caches which causes IE to do OCSP/CRL checks during SSL negotiation if the certificates are not already cached.

// Usage: Clears certificate chache in IE
speedcurve_clearcerts 1

What’s Next

For synthetic scripting examples, check out: