Taurus Actions for Scriptless Functional Testing

When creating a Scriptless GUI Test, you can use a set of predefined test actions, such as opening a web page, selecting dropdown items, submitting forms, typing text, and clicking buttons. Scriptless Tests additionally support control structures such as conditionals and loops. All available actions and control structures are explained in this article.

• An object is a set of locators for finding a GUI element, such as a button, field, or menu item.
• A child object is an iterable object that is defined relative to another object, such as cells in table rows. (Only applicable within for-each loops.)

GUI Functional Testing supports the following predefined Taurus actions and arguments:

Answer Dialog

Intercepts a synchronously displayed JavaScript dialog, and sends a response. Use Answer Dialog before the action that triggers the dialog. Typically used together with Assert Dialog.

• Type defines the type of JavaScript dialog, one of Alert, Confirm, or Prompt.
• Response defines the response to send back to the function. Example: #OK, #Cancel, or any other string.

Answer Dialog Best Practices:

If the dialog is still loading when you open a new page, the Answer Dialog action may fail to trigger.

• In this case, make the test trigger the "#Cancel" response, and perform another action to close the dialog (like opening a new tab and closing it). This workaround works only for synchronously displayed dialogs.

If the dialog is being loaded after you leave a page, the Answer Dialog action may fail to trigger.

• The Answer Dialog action cannot capture dialogs that are triggered in your browser by beforeunload events, and a modal dialog can block test script execution. Such dialogs are commonly used, for example, to prevent navigating away from a page without saving or submitting a form.
  To prevent such dialogs from blocking test execution, you can choose to suppress beforeunload events by overwriting their handler in the test script. Add a Script Eval action somewhere before the point where the blocking dialog pops up, with the following script:

  window.onbeforeunload = function(e) {
      delete e.returnValue;
  }

  This sample script redefines the return value of the beforeunload event and prevents the browser from popping up a dialog during the test. This means that the original logic of the dialog (for example, checking for unsaved changes) will not be executed when you use this workaround. For more details about the beforeUnload event, see https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onbeforeunload .

Assert Dialog

Verifies whether a JavaScript dialog was open in the previous step. Use Assert Dialog after the action that triggers the dialog. Typically used together with Answer Dialog.

• Type defines the type of JavaScript dialog, one of Alert, Confirm, or Prompt.
• Message defines the dialog message to assert.

Assert Eval

Verifies that the evaluation of a JavaScript expression returns a true value. For more examples, see Implementing Custom JavaScript Actions for Scriptless Testing.

• Script defines a custom JavaScript expression to evaluate. Do not include the return keyword.
  The following example tests whether a string myvar contains a substring.

  ``${myVar}``.includes("access not granted")

  Tip: Use the Store Text action to save text from the screen into a string variable such as myvar.

Assert Text

Verifies whether a given string exists in an element on the web page.

• Object defines an object, such as a text field or paragraph.
• Text defines a text pattern to assert. Use the asterisk wildcard to match any string, for example, "task-* completed successfully" matches "task-20220101 completed successfully."

Assert Title

Verifies that the current page title is set to a given string.

• Text defines a full-string text pattern to assert in the page title. Use the asterisk wildcard to match any string, for example, "image.png (*)" matches "image.png (400x600)".

Assert Value

Verifies the status of a UI element that can be set to a value, such as a checkbox or radio button. Use the asterisk wildcard to match any string, for example, "* credit card" matches "VISA credit card".

• Object defines an object, such as a text field, search box, checkbox, or radio button.
• Value defines the value to assert.

Click

Simulates a single left-click by a user on, for example, a link or button.

• Object defines an object to left-click.

Close Window

Closes a browser window. See also Open Window, Switch Window.

• Window ID defines the ID of the window to close.
  • win_ser_local : Identifies the initial window
  • number: Identifies the window by its index. The number can be surrounded by quotes.
    Examples: 0 is the first window, 1 is the second window, and so on.
  • win_ser_number: An alternative way to identify a window by its index.
    Example: Use win_ser_0 to navigate to the first window.
  • win_ser_name: Replace the name part with a keyword of your choice. If the name is not in use yet, the name is assigned to the focused open window. To switch back to this window later, use the same name again.
    Example: win_ser_addressbook

Context Click

Simulates a user right-clicking, typically used to open a context menu.

• Object defines an object to right-click.

Double Click

Simulates a double left-click by a user.

• Object defines an object to double-click.

Drag

Simulates a drag-and-drop action by a user.

• Object to Drag defines the source object.
• Object where to drop defines the target object.

Echo String

Lets you print debug information to the console of the test runner in the Chrome Developer Tools pane.

• Text defines the text to print to the console.

Edit Content

Simulates editing the rich text content of an element. Specifically, it sets the innerHTML content of the target object to the given value, identical to how JavaScript content editing is done.

• Object defines an element that contains text, such as P, H1, SPAN, or DIV.
• HTML Text defines the innerHTML content to put into this element. The value supports rich text HTML formatting.

Go

Navigates to a web page in the current web browser window.

• URL defines the URL of the web page to open.

Keys

Simulates a user pressing a key with focus on an object.
Tip: If you want to type text into a text field, use the type action instead.

• Object defines a target object.
• Key defines the key presses to send to this object. Find the key name in the list of keys at selenium.dev and prefix “KEY_”, for example, KEY_BACK_SPACE.

Maximize Window

Resizes the current browser window to the maximum size, depending on operating system and browser.

Mouse Down

• Object defines the object where to hold down the mouse button. See also Mouse Up.

Mouse Move

• Object defines the object where to move the mouse pointer.

Mouse Up

• Object defines the object where to release the mouse button. See also Mouse Down.

Mouse Over

• Object defines the object over which the mouse pointer hovers. See also Mouse Out.

In the Debugger, the MouseOver action only triggers the "mouse over" event handler that is defined for the element using JavaScript. The MouseOver action does not trigger other handlers that web browsers support by default, such as changing hover states of links or displaying the title as a tooltip.

Mouse Out

• Object defines the object from which the mouse pointer leaves after hovering. See also Mouse Over.

Open Window

Opens a new web browser window and navigates to a URL. See also Close Window and Switch Window.

• URL defines the URL to open in a new browser window.

Pause For

Simulates a slow user interaction, or you can use it to wait for content to load.

• Time defines the time to wait before the next test step, in seconds or in 1d2h3m4s5ms format.
  Examples: 7d, 1d1s, 48h,

Resize Window

Simulates a user changing the window size. The accepted min and max values depend on operating system and browser.

• Window Size defines the new width and height value in pixels, separated by a comma.

Script Eval

Lets you define and run custom actions written in JavaScript. You can expand this field into a multi-line JavaScript editor with syntax highlighting. Any log is printed to the console in the Chrome Developer Tools pane. For more examples, see Implementing Custom JavaScript Actions for Scriptless Testing.

• Script defines the custom JavaScript to run.
  Example 1:

  document.getElementById("mytable").rows.length

  Example 2:

  (function() {
      if (${a} == 0) {
          console.log("hi");
      }
  })()

Select

Selects a menu item from a drop-down menu.

• Object defines a drop-down menu object.
• Value defines the string value of the menu item to select from this drop-down menu.

Example: The Object is a country selection menu. To select Paris, set the Value equal to "Paris".

Recordings often include clicking and then selecting the item, but clicking is not required to select.

Store Eval

Evaluates a JavaScript and stores the results of evaluation in a variable. Reference the variable as ${variable_name}, and declare it as variable_name. You can expand this field to become a multi-line JavaScript editor with syntax highlighting. For more examples, see Implementing Custom JavaScript Actions for Scriptless Testing.

• Script defines a JavaScript expression. Do not include the return keyword.
• Variable defines a variable in which to store the string.
  Example: customer_id

Store String

Saves any hard-coded string into a variable, similar to a global variable. Reference the variable as ${variable_name}, and declare it as variable_name.

• Variable defines a variable in which to store the string.
• Text defines a string.

Store Text

Saves the HTML InnerText of an element into a variable. Reference the variable as ${variable_name}, and declare it as variable_name.

• Object defines a text field object.
• Variable defines a variable in which to store the field's text.

Store Title

Saves the current page title into a variable. Reference the variable as ${variable_name}, and declare it as variable_name. Usually used in conjunction with Assert Title.

• Variable defines a variable in which to store the current page title.

Store Value

Stores the value attribute of an input element, such as a menu, checkbox, or radio button, into a variable. Example values are "on" or "off" for a radio button or checkbox, or the selected menu item name of a menu. Reference the variable as ${variable_name}, and declare it as variable_name.

• Object defines an object such as a menu, radio button, or checkbox.
• Variable defines a variable in which to store the input element's value.
  Example: variable_name

Submit

Simulates a user clicking the submit button on a form in manually written tests. When recording a test, this action is recorded as click.

• Object defines any object in a form to submit the whole form.

Switch Frame

Changes focus to another frame or iframe. Selenium can work only with the DOM in the active frame. To address elements in another frame, always call Switch Frame first.

• Frame defines an iframe or frame to select, inside the current window.
  Examples for valid values in italics:
  • id=my_frame_name — Identifies a frame by its id selector
  • css=#my_frame_name — Identifies a frame by its css selector
  • xpath=//div[@id='main']/div[3]/iframe — Identifies a frame by its xpath
  • win_ser_local — Identifies the initial window
  • index=number — Identifies the window by its index. The number can be surrounded by quotes.
    Examples: index=0 is the first frame, index=1 is the second frame, and so on.
  • relative=parent — Identifies the parent frame
  • relative=top — Identifies the top frame

Switch Window

Simulates a user switching between several open windows. You define the window ID by providing the name or a number, as described at https://gettaurus.org/docs/Apiritif/#Window-management.

• Window ID defines the ID of the window to close.
  • win_ser_local : Identifies the initial window
  • number: Identifies the window by its index. The number can be surrounded by quotes.
    Examples: 0 is the first window, 1 is the second window, and so on.
  • win_ser_number: An alternative way to identify a window by its index.
    Example: Use win_ser_0 to navigate to the first window.
  • win_ser_name: Replace the name part with a keyword of your choice. If the name is not in use yet, the name is assigned to the focused open window. To switch back to this window later, use the same name again.
    Example: win_ser_addressbook

Type

Simulates a user typing a string into a text field.
Tip: If you want to send individual keystrokes, use the keys action instead.

• Object defines a text input object as the target.
• Text defines the text to type in UTF-8 format. Example: Hello World

Type Secret

Simulates a user typing a secret value into a masked form field, such as <input type="password">. Use this Action when entering values that should be displayed as asterisks to testers in the BlazeMeter interface. BlazeMeter uses the actual value when recording and executing the test. Its interface, however, will not reveal the value to testers in Script Mode, in Debug Mode, nor in reports.

• Object defines a text input object with input type="password" as the target.
• Secret defines the password to enter into the field.

Wait For

Waits either for a UI Element to change its state (whether it can be clicked, seen, or whether it is present at all) or for a timeout to expire.

• Object defines any UI element.
• Condition defines the state change to wait for. Must be one of Clickable, NotClickable, Visible, NotVisible, Present, NotPresent.
• Timeout defines the time to wait in seconds or in 1d2h3m4s5ms format.
  Examples: 1, 1200ms, 500ms

If necessary, you can branch scenarios, or repeat sets of actions. GUI Functional Testing supports the following control structures:

If Else

The If-Else Condition lets you branch the sequence of steps depending on a condition that is either true or false. Afterwards the scenario execution continues with the next step outside the If/Else action.

The following are examples of valid conditions in JavaScript format:

${customer_type} === "enterprise"
${number} === 42

• Condition is an expression that returns true or false.
• Then defines the actions that are executed if the condition is true. This block is mandatory.
• Else defines the actions that are executed if the condition is false. This block is optional.

For Loop

The For Loop lets you repeat actions while counting down or up; the actions in the body (such as Store Eval or Type) can reference the counter value.

Choose a name for the counter variable and initialize the counter with a start value. After every repetition of the body, the counter increases by your chosen step value. After the counter reaches the end value, the loop ends, and the scenario execution continues outside the for-loop. If needed, you can even even define variable step, start, and end values in a CSV data file.

• Variable defines a name for your counter variable.
  Example: counter
• Start defines the integer start value of the counter (inclusive), or a variable.
  Example: 0, or ${myStartValue}
• End defines the integer end value of the counter (inclusive), or a variable.
  Example: 10, or ${myEndValue}
• Step defines how much to increase the counter in each loop. Must be an integer or a variable.
  Example: 1, or ${myStepValue}
• Loop Body defines the set of actions that you want to repeat. Actions in the body can use the counter variable as parameter.
  Example: To type text with changing values into a field named QueryField, define the following:
  • Action: Type
  • Target: QueryField
  • Text: This is loop number ${counter}

Tip: Avoid endless loops. To count up, choose a start value smaller than the end value, and a positive step value. To count down, choose a start value greater than the end value, and a negative step value.

For Each Loop

The For Each action lets you repeat actions while iterating over a list, such as menu items, button groups, or even cells in table rows. The actions in the loop body can reference the iterator as parameters. You cannot nest a For Each loop inside another For Each loop.

• Iterator defines a list of elements to which you want to apply an action. For example, a dropdown menu with menu items, a list with entries, a group of radio buttons.
• Loop Body defines the actions that you want to repeat. Actions in the body can use objects, or the iterator, or child objects of the iterator.

Advanced Use Case: Loop For Each Child Object

Optionally, define secondary Child Objects for the Iterator to loop over. The concept of Child Objects is only applicable within a For Each action.

• Each parent can have several different child objects defined.
• Each Child Object has one or more locators.
• The Child Object locator is relative to one instance of the object identified by the iterator (parent locator). You cannot change the iterator while its child object is in use in the loop body.

You must define child objects manually for each parent object (the Chrome Recorder does not create Child Objects automatically). The Iterator identifies a list of elements on the page, specifically, all elements that match the first locator that returns any element. The For Each body is repeated for each element from that list. The Actions in the For Each body can use either the Iterator object, or a Child Object as parameter.

Example scenario: Iterate over cells in table rows to assert a value

1. Open your GUI Functional test and add a For Each action.
2. As iterator, select an existing parent object or create a new one.
   In this example, the parents are table rows, so we use an object with an XPath of //tr.
3. Edit the parent object.
   
4. Click Add Child Objects and define locators relative to the parent.
   In this example, the Child Objects are cells in the fifth column of each row, so we enter an XPath of /td[5].
   
5. Click Edit again to save changes to the parent object.
6. Define the For Each Loop body. In this example, we add an Assert Text action.
   1. As Object, select the parent object. Clear the searchbar if necessary, and then select the Child Object.
      
   2. Define additional parameters. In this example, we enter "5 USD" in the Text field.
      
7. Run the test.
   BlazeMeter repeats the test actions for the fifth cell of each row.

The Parent Objects as well as the Child Objects identify different elements in every iteration:

1. In the first iteration, the action is applied to the fifth column in the first row.
2. In the second iteration, the action is applied to the fifth column in the second row.
3. And so on.