Transaction Scripting Reference

Last updated: Wed Nov 20 00:53:27 GMT 2019

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

Table of contents

Example scripts

For quicker orientation, there is a comprehensive collection of script examples provided by the transaction scripting examples repository in our 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.

Namespacethousandeyes
Moduledriver
Import Syntaximport { driver } from 'thousandeyes';
Used Likeawait driver.get('https://google.com');
Supported methods
  • 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 )
Referencehttps://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.

Namespaceselenium-webdriver
ModuleWebElement
Find an elementconst element = await driver.findElement(By.css('.someClass'))
Supported methods
  • clear()
  • click()
  • getAttribute( attributeName )
  • getCssValue( cssStyleProperty )
  • getId()
  • getText()
  • sendKeys( ...args )
  • submit()
Referencehttps://selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_WebElement.html

Waiting for events

Defines common conditions for use with WebDriver wait.

Namespaceselenium-webdriver
Moduleuntil
Import Syntaximport { until } from 'selenium-webdriver';
Used Likeawait 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 )
Referencehttps://selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/until.html

Generating keyboard events

Representations of pressable keys that aren't text.

Namespaceselenium-webdriver
ModuleKey
Import Syntaximport { Key } from 'selenium-webdriver';
Used Likeawait driver.findElement(By.css('.form-input')).sendKeys(Key.RETURN);
Supported methods
  • Key.chord( ...keys )
ValuesSee the reference below.
Referencehttps://selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_Key.html

Taking screenshots

Namespacethousandeyes
Moduledriver
MethodtakeScreenshot()
Used Likeawait driver.takeScreenshot();
DescriptionTakes 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.
ParametersNone
ReturnsNone

Handling credentials

Namespacethousandeyes
Modulecredentials
Import Syntaximport { credentials } from 'thousandeyes';
Used Likecredentials.get('MyPasswordName');
Methodget( 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).

ParameterscredentialName (string) The name of the credential to fetch
Returns(string) The password or sensitive value associated with the supplied credential name

Handling downloads

Namespacethousandeyes
Moduledownloads
Import Syntaximport { downloads } from 'thousandeyes';
Used Likeawait downloads.waitForDownload('myFilename.txt', 10 * 1000);
MethodwaitForDownload( 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
ReturnsNone, if the download is successful, else will throw an error

Measuring transaction time(s)

ThousandEyes transactions support two types of measuring time:

Markers

Markers are custom time delimiters, enabling precise time measurements of smaller sections of the transaction.

Start a marker:

Namespacethousandeyes
Modulemarkers
Methodstart( markerName )
Description

Starts a marker with the supplied name.

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

ParametersmarkerName (string) The name of the marker
ReturnsNone. Will throw an error if attempting to start a previously started marker.

Stop a marker:

Namespacethousandeyes
Modulemarkers
Methodstop( markerName )
DescriptionStops the marker matching the supplied name.
ParametersmarkerName (string) The name of the marker
ReturnsNone. 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:

Namespacethousandeyes
Modulemarkers
Methodset( 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.

ParametersmarkerName (string) The name of the marker
ReturnsNone.

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:

Namespacethousandeyes
Moduletransaction
Methodstart()
Description

Sets the start time of the transaction.

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

ParametersNone
ReturnsNone

Set the overall transaction time end moment:

Namespacethousandeyes
Moduletransaction
Methodstop()
Description

Sets the end time of the transaction.

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

ParametersNone
ReturnsNone

Element locators

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

Namespaceselenium-webdriver
ClassBy
Import Syntaximport { By } from 'selenium-webdriver';
Used Likeawait 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 )
Referencehttps://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.

Namespaceassert
Moduleassert
Import Syntaximport assert from 'assert';
Used Likeassert(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] )
Referencehttps://nodejs.org/api/assert.html

Further information

For further information about transaction testing head back to the Transaction Scripting Guide.

If you have any questions, reach out to reach out to ThousandEyes Customer Success team.