Script Editing Reference

The Eggplant Monitor user journey step scripts are written in Ruby with associated Selenium bindings. Below are the various functions you can use in your Monitoring scripts.

Important

Changes take effect as soon as you save. When modifying code, we strongly recommend commenting out any existing lines (with a #) and adding new lines with clear comments, so changes can be reverted if needed.

If in doubt, contact Eggplant Customer Support before making changes.

Script Behavior Functions (EggPlant::Script)

These methods control user journey behavior and live under the EggPlant::Script:: namespace. Some functions are advanced—change with caution.

Method/Attribute with Example	Return Value	Description
EggPlant::Script::getCustomString() Example: EggPlant::Script::getCustomString()	string	Gets the custom string for the currently running script.
EggPlant::Script::getCustomString(ScriptID, shard) Example: EggPlant::Script::getCustomString(123, 4)	string	Do not modify without consulting Customer Support first. Gets the custom string from different scripts.
EggPlant::Script::getCustomNumber() Example EggPlant::Script::getCustomNumber()	int	Gets the custom number for the currently running script.
EggPlant::Script::getCustomNumber(ScriptID, shard) Example: EggPlant::Script::getCustomNumber(123, 4)	int	Do not modify without consulting Customer Support first. Gets the custom number from different scripts.
EggPlant::Script::setCustomString(String) Example: EggPlant::Script::setCustomString('hello world')	n/a	Sets the custom string for the currently running script.
EggPlant::Script::setCustomString(String, ScriptID, shard) Example: EggPlant::Script::setCustomString('hello world', 123, 4)	n/a	Do not modify without consulting Customer Support first. Sets the custom string for different scripts.
EggPlant::Script::setCustomNumber(int) Example: EggPlant::Script::setCustomNumber(123456)	n/a	Sets the custom number for the currently running script.
EggPlant::Script::setCustomNumber(int, ScriptID, shard) Example: EggPlant::Script::setCustomNumber(123456, 123, 4)	n/a	Do not modify without consulting Customer Support first. Sets the custom string for different scripts.
EggPlant::Script::setResultCode(resultCode) Example: EggPlant::Script::setResultCode(23)	n/a	Do not modify this function without consulting Customer Support first. Forces a specific result code for the step. This function requires an integer parameter; it returns a script error (RC=103) if a parameter is not passed, or if the passed parameter is not an integer. Notes: - This function forces the result code for the step (irrespective of the success/failure of other checks). Use with caution; this overrides step outcomes. -This function is useful for run-time checks (such as no stock available) on an otherwise dummy step.
EggPlant::Script::setRequiredText(String) Example EggPlant::Script::setRequiredText('Condition not met')	n/a	Sets the expected phrase to the given string for the current step. The phrase is set in the running script and all future runs (as soon as the method is called).
EggPlant::Script::setRequiredText(String, step) Example: EggPlant::Script::setRequiredText('Condition not met', 2)	n/a	Sets the expected phrase to the given string for the specified step. The step number is indexed from 1 and refers to all steps irrespective of whether the step is enabled.
EggPlant::Script::getFormVariable(String) Example EggPlant::Script::getFormVariable('foo')	string	Gets the value of the named form variable for the current step. - If the name does not exist, this function returns an empty string.
EggPlant::Script::getFormVariable(String, step) Example: EggPlant::Script::getFormVariable("foo", 2)	string	Gets the variable value for the specified step. The step number is indexed from 1 and refers to steps regardless of whether the step is enabled.
EggPlant::Script::addExtraInfo(String) Example: EggPlant::Script::addExtraInfo("Selected item 4")	string	Creates/appends the given string to ExtraInfo for the given run. Multiple calls will continuously append to ExtraInfo.
EggPlant::Script::getUploadFile() Example: EggPlant::Script::getUploadFile()	string	Gets the path to the file to be uploaded for the corresponding step that is running. The file must be uploaded against the step.
EggPlant::Script::getCustomHeaders()	array	Lists all custom headers currently applied to all requests for this step. Multiple calls can be used to add multiple custom headers. Note: These headers will automatically be removed after each step. This function does not include permanent custom headers. Use getPermanentCustomHeaders to have headers persist over multiple steps.
EggPlant::Script::addCustomHeader(headerName, headerValue) Example: EggPlant::Script::addCustomHeader("x-header", "abc")	n/a	Adds a custom header for the current step only. Multiple calls can be used to add multiple custom headers. Note: These headers will automatically be removed after each step. This function does not include permanent custom headers. Use addPermanentCustomHeaders to have headers persist over multiple steps.
EggPlant::Script::removeCustomHeader(headerName) Example: EggPlant::Script::removeCustomHeader("x-header")	n/a	Removes the custom header for all requests for this step only. Use removePermanentCustomHeaders to remove permanent custom headers that persist over multiple steps. Note: Only custom headers that have been added with a method can be removed (not standard headers added by the browser.)
EggPlant::Script::getPermanentCustomHeaders() Example: EggPlant::Script::getPermanentCustomHeaders()	array	Lists all permanent custom headers currently applied to all requests at that point in time. It does not include custom headers for the current step only. Use getCustomHeaders as well if you also need those.
EggPlant::Script::addPermanentCustomHeader(name, value) Example: EggPlant::Script::addPermanentCustomHeader("x-header", "abc")	n/a	Adds a custom header applied to all subsequent steps. Multiple calls can be used to add multiple custom headers.
EggPlant::Script::removePermanentCustomHeader(name) Example: EggPlant::Script::removePermanentCustomHeader("x-header")	n/a	Removes the permanent custom header for all requests for all subsequent steps. NOTE: Only custom headers that have been added with a method can be removed (not standard headers added by the browser).

Current state of the run (EggPlant::Run)

The section describes the methods available for determining the current state of the monitor run. These all exist in the Eggplant::Run:: namespace.

info

Use or change these methods with caution. Please contact Eggplant Customer Support if in any doubt.

Method/Attribute with Example	Return Value	Description
EggPlant::Run::finalStepNumber Example: EggPlant::Run::finalStepNumber == 5...	int	Returns the final step number for the user journey run, at the point at which it is called. Steps are always indexed from 1 and include any disabled steps. If used on a step, finaStepNumber will always return the number of that step (for example, 4). However, it is rarely used like this. The finalStepNumber will generally be used in the finalise block (see the following section for more details on finalise). When called in the finalise block, finalStepNumber returns the step number that the user journey reached, which is particularly useful to know because it could fail at any step. For example: -If a 5 step journey runs to completion, finalStepNumber called in the finalise block, will return 5. -If a 5 step journey fails at step 3, finalStepNumber called in the finalise block, will return 3.
EggPlant::Run::overallResultCode Example: if EggPlant::Run::overallResultCode == 23 && Eggplant ::Run::finalStepNumber == 5...	int	Returns the latest result code for the user journey up to the last completed step. For example, if you call this method in Step 2, the overallResultCode will be the result code of Step 1. Calls to overallResultCode are generally made in the finalise bleock. (See the following section for more information on finalise.)
EggPlant::Run::severity	string	Returns the severity of the running user journey corresponding to the Eggplant::Run::overallResultCode, as one of the strings: "NULL", "OK", "WARNING", "PROBLEM", or "DOWN".
EggPlant::Run::testType	string	Returns the test type of the running user journey as one of the strings: "SCHEDULED", "RETEST", or "MANUAL".
EggPlant::Run::getRawContent()	string	Returns a single string concatenation of all HTTP for textual responses (for example, HTML, CSS, and AJAX responses) for the current step.

Helper functions

The scripts support two types of helper functions:

• Selenium helpers (extensions on the WebDriver) for simplifying Selenium interactions
• Convenience helpers (generic Ruby helpers) for commonly used functions

Selenium Helpers (called on driver)

The Selenium Helpers provide helpers for interacting with websites using Selenium. These helpers are all extensions to the Selenium::WebDriver::Driver interface, and so are referenced from the driver object.

Method/Attribute	Return Value	Description
driver.find_text(text, tag='*')	element or nil	Returns a visible element containing the text string based on the type of tag given. For example, you can just search within "div" elements if you know the text is of that type. - If there is not a match, or the only match is not visible, this method returns nil. This ensures you can interact with the returned element. - If there are multiple, visible matches, this method returns the first match.
driver.find_texts(text, tag='*')	[element] or []	The same as find_text but this method returns all matching, visible elements, not just the first. - If there is not a match, or the only match is not visible, this method returns an empty array.
driver.scroll_to(selector, distance=100, type=:css)	n/a	Scrolls to the element matching the given selector and then an additional specified distance of pixels to ensure that the selector is fully visible. You can specify the type, or the default css will be used. By default, this method scrolls an additional 100 pixels, but you can change this by defining the distance parameter. - If the selector does not exist, this method throws an exception of type: Selenium::WebDriver::Error::NoSuchElementError. (Ideally, use selector_exists before scrolling).
driver.selector_exists(selector, type=:css)	boolean	Returns whether the given selector of the given type, exists. - If the selector exists and is visible, this method returns true. - If the selector exists but is not visible, or does not exist at all, this method returns false.
driver.selectors_exist(selector, type=:css)	[element] or []	Behaves the same as selector_exists but returns all matching visible elements, not just the first. - If there is not a match, or the only match is not visible, this method returns an empty array.
driver.text_exists(text, tag='*')	boolean	Returns whether the given text based on the type of tag given, exists and is visible. - If the text exists and is visible, this method returns true. -If the text exists but is not visible, or does not exist, this method returns false.
driver.wait_for_selector(selector, timeout=30, type=:css)	boolean	Waits for up to the specified timeout in seconds for the selector, based on the given type, to exist and be visible. - If the selector is found within the timeout, this method returns true; otherwise, it returns false.
driver.wait_for_text(text, tag='*', timeout=30)	boolean	Waits for up to the specified timeout in seconds for the text, based on the type of tag given, to exist and be visible. - If the text is found and is visible within the specified timeout, this method returnstrue; Otherwise, it returns false.
driver.wait_while_selector(selector, timeout=30, type=:css)	boolean	Waits for up to the specified timeout in seconds for the selector of the given type to no longer exist on the page. - If the selector no longer exists within the specified timeout, this method returns true; Otherwise, it returns false. This is useful, for example, when additional content is loading behind a spinner, and you want to wait until the spinner has gone.
driver.wait_while_visible(selector, timeout=30, type=:css)	boolean	Waits for up to the specified timeout in seconds for the selector of the given type to no longer be visible (but still exist on the page). - If the selector is no longer visible within the specified timeout, this method returns true; Otherwise, it returns false. This is useful, for example, when additional content is loading behind a spinner, and you want to wait until the spinner has gone.

Convenience helpers (EggPlant::Helper)

The convenience helpers are Ruby helpers for some commonly-used functions. These all exist in the Eggplant::Helper:: namespace.

Method/Attribute & Examples	Return Value	Description
EggPlant::Helper::generateDate(numDays, format) Example: Eggplant::Helper::generateDate(7, "Next week is %d/%m/%Y") EggPlant::Helper::generateDate(-7, "Last week was: %d/%m/%Y")	string	Returns a date relative to now, numDays in the future (if positive), or numDays in the past (if negative). The format is how you want the date returned, as defined in the strftime Ruby function.
EggPlant::Helper::getContentBetween(src, from, start, end, look_forward=true) Examples: EggPlant::Helper::getContentBetween('abcdef','','b', 'e') # will return 'cd' EggPlant::Helper::getContentBetween('abcdef', '', 'w', 'e') # will return 'NOTFOUND' EggplantHelper::getContentBetween('z1a3y1b3', '', '1', '3') # will return 'a' EggplantHelper::getContentBetween('1a3z1b3z', 'z', '1', '3') # will return 'b' EggPlant::Helper::getContentBetween('1a3z1b3z','z','1','3',false) # will return 'a'	string	Returns a substring between the start and end points from the given src string, starting from the from string (where from acts as an anchor to find first). - If there is not a match or the from string is not found, this method returns the string NOTFOUND. By default, this method will search for the from string and then search to the right (forward) for the start string. Set look_forward to false to search backwards from the from string for the start string. - If you do not want an anchor for the from string, then set this to an empty string ('').