What's New
Product Documentation

Transaction Scripting Reference

Transaction Scripting Reference

This article contains a reference of all namespaces, classes, modules and methods that are available for creating transaction tests.

Example Scripts

For quicker orientation, there is a comprehensive collection of script examples provided by the transaction scripting examples repository in the ThousandEyes GitHub account.

Controlling the Browser

ThousandEyes provides a wrapper of the Selenium WebDriver library for JavaScript. It contains methods for controlling the browser that is used to execute the test.

Namespace

thousandeyes

Module

driver

Import Syntax

import { driver } from 'thousandeyes';

Used Like

await driver.get('https://google.com');

Supported methods

await driver.get('https://google.com');

actions( options )

executeAsyncScript( script, ...args )

executeScript( script, ...args )

findElement( locator )

findElements( locator )

get( url )

getAllWindowHandles()

getCurrentUrl()

getPageSource()

getTitle()

getWindowHandle()

manage()

navigate()

sleep( ms )

switchTo()

wait( condition, timeout, message )

Reference

https://selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_WebDriver.html

Interacting with page elements

A set of methods for interacting with elements. Once the element is located and retrieved (by using the findElement() function or similar), it can be managed using the following methods.

Namespace

selenium-webdriver

Module

WebElement

Find an element

const element = await driver.findElement(By.css('.someClass'))

Supported methods

clear()

click()

getAttribute( attributeName )

getCssValue( cssStyleProperty )

getId()

getText()

sendKeys( ...args )

submit()

Reference

https://selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_WebElement.html

Waiting for events

Defines common conditions for use with WebDriver wait.

Namespace

selenium-webdriver

Module

until

Import Syntax

import { until } from 'selenium-webdriver';

Used Like

await driver.wait(until.alertIsPresent(), 10 * 1000, 'Alert did not appear within 10 seconds!');

Supported methods

ableToSwitchToFrame( frame )

alertIsPresent()

elementIsDisabled( element )

elementIsEnabled( element )

elementIsNotSelected( element )

elementIsNotVisible( element )

elementIsSelected( element )

elementIsVisible( element )

elementLocated( locator )

elementTextContains( element, substr )

elementTextIs( element, text )

elementTextMatches( element, regex )

elementsLocated( locator )

stalenessOf( element )

titleContains( substr )

titleIs( title )

titleMatches( regex )

urlContains( substrUrl )

urlIs( url )

urlMatches( regex )

elementTextMatches( element, regex )

elementsLocated( locator )

stalenessOf( element )

titleContains( substr )

titleIs( title )

titleMatches( regex )

urlContains( substrUrl )

urlIs( url )

urlMatches( regex )

Reference

https://selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/until.html

Generating keyboard events

Representations of pressable keys that aren't text.

Namespace

selenium-webdriver

Module

Key

Import Syntax

import { Key } from 'selenium-webdriver';

Used Like

await driver.findElement(By.css('.form-input')).sendKeys(Key.RETURN);

Supported methods

Key.chord( ...keys )

Values

See the reference below

Reference

https://selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_Key.html

Taking Screenshots

Namespace

thousandeyes

Module

driver

Method

takeScreenshot()

Used Like

await driver.takeScreenshot();

Description

Takes a screenshot of the current page and stores it in memory. These screenshots will be collected at the end of the test. A maximum of 3 screenshots are allowed, new screenshots will override the old ones in case that this limit is exceeded.

Parameters

None

Returns

None

Handling Credentials

Namespace

thousandeyes

Module

credentials

Import Syntax

import { credentials } from 'thousandeyes';

Used Like

credentials.get('MyPasswordName');

Method

get( credentialName )

Description

Gets the stored credential value matching the supplied name. Only works if you have already associated the credential with the current test (Test settings page).

Parameters

credentialName (string) The name of the credential to fetch

Returns

(string) The password or sensitive value associated with the supplied credential name

Handling Downloads

Namespace

thousandeyes

Module

downloads

Import Syntax

import { downloads } from 'thousandeyes';

Used Like

await downloads.waitForDownload('myFilename.txt', 10 * 1000);

Method

waitForDownload( fileName, timeout )

Description

Waits for a download matching the supplied filename to appear and then to finish. If a file matching the supplied name has previously been downloaded, this function will complete immediately. If no file matching the supplied name has been or is currently downloading, it will wait for the supplied timeout amount of time for the file to appear and finish downloading.

Parameters

fileName (string) The name of the file to wait for

timeout (number) The max number of milliseconds to wait for download completion. Defaults to 60 seconds

Measuring transaction time(s)

ThousandEyes transactions support two types of measuring time:

  • Markers

  • Overall transaction time

Markers

Markers are custom time delimiters, enabling precise time measurements of smaller sections of the transaction. A maximum of 200 markers can be defined in a transaction script. The Waterfall tab displays the first ten markers, with a Show more link if more than ten markers are defined.

Start a marker:

Namespace

thousandeyes

Module

markers

Method

start( markerName )

Description

Starts a marker with the supplied name. This marker can later be stopped by calling the stop function with the same name.

Parameters

markerName (string) The name of the marker

Returns

None. Will throw an error if attempting to start a previously started marker.

Stop a marker:

Namespace

thousandeyes

Module

markers

Method

stop( markerName )

Description

Stops the marker matching the supplied name.

Parameters

markerName (string) The name of the marker

Returns

None. Will throw an error if attempting to stop a marker that hasn't been started yet or one that was already stopped.

Set a marker:

Namespace

thousandeyes

Module

markers

Method

set( markerName )

Description

Creates a marker that spans from transaction start time to the time this method is called. Calling set implicitly closes the marker, so there is no need to later close it.

Parameters

markerName (string) The name of the marker

Returns

None.

Overall Transaction Time

Running a transaction test implicitly causes the overall transaction time measurement, spanning from the moment the transaction test run starts and to the end of the transaction. However, if customization of overall transaction time's start and stop moments is required, the following methods can be used to such effect. |

Set the overall transaction time start moment:

Namespace

thousandeyes

Module

transaction

Method

start()

Description

Sets the start time of the transaction. If not called, the transaction start time will default to the script start time.

Parameters

None

Returns

None

Set the overall transaction time end moment:

Namespace

thousandeyes

Module

transaction

Method

stop()

Description

Sets the end time of the transaction. If not called, the transaction start time will default to the script end time.

Parameters

None

Returns

None

Element Locators

Provided is a set of mechanisms dedicated to locating elements on the page.

Namespace

selenium-webdriver

Class

By

Import Syntax

import { By } from 'selenium-webdriver';

Used Like

await driver.findElement(By.css('#myId'));

Supported static methods

By.className( name )

By.css( selector )

By.id( selector )

By.js( script, ...var_args )

By.linkText( text )

By.name( name )

By.partialLinkText( text )

By.xpath( xpath )

Reference

https://selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/by_exports_By.html

Assertions

The assert module provides a set of assertion functions for verifying invariants.

NOTE: Only strict mode is supported.

Namespace

assert

Module

assert

Import Syntax

import assert from 'assert';

Used Like

assert(url === 'https://wikipedia.org', 'Assertion failed: not on wikipedia!')

Supported methods

assert( value[, message] )

deepEqual( actual, expected[, message] )

doesNotReject( asyncFn[, error][, message] )

doesNotThrow( fn[, error][, message] )

equal( actual, expected[, message] )

fail( [message] )

ifError( value )

notDeepEqual( actual, expected[, message] )

notEqual( actual, expected[, message] )

ok( value[, message] )

rejects( asyncFn[, error][, message] )

throws( fn[, error][, message] )

Reference

https://nodejs.org/api/assert.html

Further information

For further information about transaction testing, see the Transaction Scripting Guide.

If you have any questions, contact the ThousandEyes Customer Engineering team.