Instructions

One of the instructions has to be present in every command. These properties are evaluated (and their effect is executed) in the order, in which they are listed below:

if-then-else
while-do
do-until
repeat-do
setViewport
url
go
scroll
focus
clearValue
setValue
addValue
selectOptionByIndex
selectOptionByValue
moveCursor
click
clickIfVisible
keys
elementSendKeys
wait
isExisting
isVisible
isVisibleWithinViewport
isEnabled
isSelected
isFocused
isNotExisting
isNotVisible
isNotVisibleWithinViewport
isNotEnabled
isNotSelected
isNotFocused
hasAttribute
hasClass
hasValue
hasText
hasInnerHtml
hasOuterHtml
break
abort
file

if-then-else

Conditional command consisting of two or three three instructions, which each points to a sub-command or to an array of sub-commands to perform:

if

Type: Object | Array (mandatory)

then

Type: Object | Array (optional)

else

Type: Object | Array (optional)

At first the sub-commands from the if instruction are performed. If they succeed, the execution continues with sub-commands from the then instruction. If they fail, the execution continues with sub-commands from the else instruction. The success or failure of the whole conditional command will depend on either of then and else instructions, which are executed. The success or failure of the if instruction decides only the following condition branch.

{
  url: 'https://google.com',
  wait: '#lst-ib'
},
{
  if: {
    hasAttribute: {
      selector: '#lst-ib',
      name: 'autocomplete',
      value: 'off'
    }
  },
  then: {
    setValue: {
      selector: '#lst-ib',
      value: 'why is autocomplete off'
    }
  }
},
{
  file: 'google'
}

while-do

Cyclic command with the condition evaluated before the loop body. If the condition evaluates to a truthy value, the loop body will be executed. Then the condition will be evaluated again and so on. The command consists of two instructions, which each points to a sub-command or to an array of sub-commands to evaluate and perform:

while

Type: Object | Array (mandatory)

do

Type: Object | Array (optional)

At first the sub-commands from the while instruction are performed. If they succeed, the execution continues with sub-commands from the do instruction. If they fail, sub-commands from the do instruction will be skipped and the execution will continue with the next command. The success or failure of the whole cyclic command will depend on the loop body in the do instruction. The success or failure of the while instruction decides only if the loop is entered or not.

{
  url: 'https://google.com',
  wait: '#lst-ib'
},
{
  while: {
    isNotFocused: '#lst-ib'
  },
  do: {
    keys: ['Tab']
  }
},
{
  file: 'google'
}

do-until

Cyclic command with the condition evaluated after the loop body. The loop body will be executed and then the condition evaluated. If it evaluates to a falsy value, the loop body will be executed again and so on. The command consists of two instructions, which each points to a sub-command or to an array of sub-commands to evaluate and perform:

do

Type: Object | Array (optional)

until

Type: Object | Array (mandatory)

At first the sub-commands from the do instruction are performed. Then the sub-commands from the until instruction are performed. If they succeed, the execution will continue with the next command. The success or failure of the until instruction decides only if the loop is re-entered or not. The success or failure of the whole cyclic command will depend on the loop body in the do instruction.

{
  url: 'https://google.com',
  wait: '#lst-ib'
},
{
  do: {
    keys: ['Tab']
  },
  until: {
    isFocused: '#lst-ib'
  }
},
{
  file: 'google'
}

repeat-do

Cyclic command with the known count of repetitions of the loop body. The loop body will be executed the specified count of times. The command consists of two instructions, which one points to a repetition count and the other to a sub-command or to an array of sub-commands to perform:

repeat

Type: Number (mandatory)

do

Type: Object | Array (optional)

At first the current repetition count is compared to the specified target one. If if is less, the execution continues with sub-commands from the do instruction. It it is greater or equal to it, sub-commands from the do instruction will be skipped and the execution will continue with the next command. Then the current repetition count is incremented by one and the condition evaluated again and so on. The success or failure of the whole cyclic command will depend on the loop body in the do instruction.

{
  url: 'https://google.com',
  wait: '#lst-ib'
},
{
  repeat: 10,
  do: {
    click: '#lst-ib'
  }
},
{
  isFocused: '#lst-ib',
  file: 'google'
}

setViewport

Type: Object

Resizes the web browser viewport to the specified width and height values (in pixels), overriding the viewport value in options. Once this instruction is used, the viewport size will stay, until it is modified by this instruction again, or until the viewport option is detected in another instruction.

If the input object for this instruction is left empty ({}), the viewport will be resized to the original value set in options.

{
  setViewport: {with: 640, height: 480},
  url: 'https://google.com',
  file: 'google'
}

url

Type: String

Navigates (changes the current window location) to the specified URL.

{
  url: 'https://google.com',
  file: 'google'
}

If it is omitted, the command will reuse the location from the previous command. A command without URL can cause some page changes, wait for an element state and/or save a snapshot.

go

Type: String: 'back', 'forward', 'refresh' or 'reload'

Navigates backwards or forwards using the browser history, or refreshes the current page, or reloads the whole browser session.

{
  go: 'back',
  file: 'previous'
}

scroll

Type: String | Object

Scrolls the page, so that the element with the specified selector or mouse coordinates become visible. If an object is used for the specification, it should contain the following properties:

selector - String - selector of the element to move the mose to.
offset - Object - relative offset to the top left corner of the specified element expected as left and top numeric properties.

{
  url: 'https://google.com',
  scroll: {
    selector: '#lst-ib'
  },
  file: 'google'
}

The offset value can be specified instead of the selector and shares the format with the moveCursor instruction.

focus

Type: String

Focuses the the specified element by JavaScript.

The input string should contain selector of the element to set focus to.

{
  url: 'https://google.com',
  wait: '#lst-ib',
  focus: 'input[name=btnK]',
  file: 'google'
}

clearValue

Type: String

Clears value of an input element at the specified selector.

{
  url: 'https://google.com',
  clearValue: '#lst-ib',
  file: 'google'
}

setValue

Type: Object

Set value of an input element either by providing the new value or using [keyboard key identifiers]. The previous value will be cleared. The object should contain the following properties:

selector - String - selector of an input element.
value - String|Number|Array - string or numeric value, or an array of keys (strings) to send to the element for setting its value.

{
  url: 'https://google.com',
  setValue: {
    selector: '#lst-ib',
    value: 'Hi'
  }
},
{
  setValue: {
    selector: '#lst-ib',
    value: ['Enter']
  }
  file: 'google',
}

addValue

Type: Object

Appends to the current value of an input element. The object should contain the following properties:

selector - String - selector of an input element.
value - String|Number - string or numeric value.

{
  url: 'https://google.com',
  setValue: {
    selector: '#lst-ib',
    value: ' there!'
  },
  file: 'google'
}

selectOptionByIndex

Type: Object

Select an option element of a select element by the specified (zero-based) index. The object should contain the following properties:

selector - String - selector of a select element.
index - Number - numeric (0-based integer) index of an option to select.

{
  url: 'https://example.com',
  setValue: {
    selector: 'select',
    index: 1 // select second option
  }
}

selectOptionByValue

Type: Object

Select an option element of a select element by the specified value of the value attribute. The object should contain the following properties:

selector - String - selector of a select element.
value - String - value of the value attribute of an option to select.

{
  url: 'https://example.com',
  setValue: {
    selector: 'select',
    value: 'second'
  }
}

moveCursor

Type: String | Object

Moves the mouse cursor to an element with the specified selector. If an object is used for the specification, it should contain the following properties:

selector - String - selector of the element to move the mose to.
offset - Object - relative offset to the top left corner of the specified element expected as left and top numeric properties.

{
  url: 'https://google.com',
  moveCursor: {
    selector: '#lst-ib',
    offset: {
      left: 10
      top: 5,
    }
  },
  file: 'google'
}

clickIfVisible

Type: String

Triggers a click event on an element with the specified selector, if the elment is visible. Otherwise continues silently.

{
  url: 'https://google.com',
  clickIfVisible: 'input[name=btnK]',
  file: 'google'
}

click

Type: String

Triggers a click event on an element with the specified selector.

{
  url: 'https://google.com',
  click: 'input[name=btnK]',
  file: 'google'
}

keys

Type: String|Array

Sends either a text (string) typed by keys, or single keystrokes (array) to the browser.

{
  url: 'https://google.com',
  click: 'input[name=btnK]',
  keys: 'test',
  file: 'google'
}

Special keys are listed in the WebDriver documentation.

elementSendKeys

Type: Object

Sends a text (string) to an element in the browser. The object should contain the following properties:

selector - String - selector of the element to send the keys or text to.
text - String - the text to send to the element.

{
  url: 'https://google.com',
  elementSendKeys: {
    selector: 'input[name=btnK]',
    text: 'test'
  },
  file: 'google'
}

wait

Type: Number | String | Function | Array (optional)

Delays taking of the snapshot until a condition s met depending on the value type:

Number - number of milliseconds to wait:

{
  url: 'https://google.com',
  wait: 1000,
  file: 'google'
}

String - selector of a node to look for. As soon as this node is found in DOM, the waiting will stop:

{
  url: 'https://google.com',
  wait: '#footer',
  file: 'google'
}

If the selector is prefixed by the exclamation mark ("!"), the waiting waiting will stop, once the node disappears from DOM:

{
  url: 'https://google.com',
  wait: '!.gsfi',
  file: 'google'
}

Function - callback, which is supposed to return a Promise. Once this promise is resolved, the waiting will stop. The callback obtains the [webdriverio] client instance and can use [WebdriverIO API] to interact with the browser:

{
  url: 'https://google.com',
  wait: function (browser) {
    return browser.$('#footer')
      .then(element => element.waitForExist({ timeout: 1000 }));
  },
  file: 'google'
}

Array - an array of items of types described above. They will be processed one by one. Once the last one is finished, the waiting will stop:

{
  url: 'https://google.com',
  wait: '!.gsfi',
  file: 'google'
}

If wait is omitted, the task will advance to another item without delay. It can still save a snapshot immediately.

hasAttribute

Type: Object

Checks, that the attribute with the specified value exists in the element with the specified selector. The input object should contain the following properties:

selector - String - selector of the element to check.
name - String - attribute name.
value - String - attribute value.

{
  url: 'https://google.com',
  wait: '#lst-ib',
  hasAttribute: {
    selector: '#lst-ib',
    name: 'autocomplete',
    value: 'off'
  },
  file: 'google'
}

hasClass

Type: Object

Checks, that at least one of the specified classes is included or omitted in the element with the specified selector. The input object should contain the following properties:

selector - String - selector of the element to check.
value - String - space-delimited class list.
allRequired - Boolean - if all classes in the list have to match. Optional. The default value is false.

Class names starting with the exclamation mark ("!") are expected to be omitted, otherwise the class names are expected to be included in the specified element.

The check will succeed, if at least one class from the list will be included or omitted. If you want all classes to pass the check, set the instruction property allRequired to true. (Or use multiple commands with the hasClass instruction.)

{
  url: 'https://google.com',
  wait: '#lst-ib',
  hasClass: {
    selector: '#lst-ib',
    value: 'gsfi !hidden',
    allRequired: true
  },
  file: 'google'
}

hasValue

Type: Object

Checks, that the value of the textarea, select or text input element with the specified selector is equal to the specified one. The input object should contain the following properties:

selector - String - selector of the element to check.
value - String - element value.

{
  url: 'https://google.com',
  wait: '#lst-ib',
  hasValue: {
    selector: '#lst-ib',
    value: 'test'
  },
  file: 'google'
}

hasText

Type: Object

Checks, that the text in the interactable element with the specified selector is equal to the specified one. The input object should contain the following properties:

selector - String - selector of the element to check.
value - String - element text.

{
  url: 'https://google.com',
  wait: '.gb_P',
  hasText: {
    selector: '#lst-ib',
    value: 'Gmail'
  },
  file: 'google'
}

hasInnerHtml

Type: Object

Checks, that the HTML markup inside the element with the specified selector is equal to the specified value. The input object should contain the following properties:

selector - String - selector of the element to check.
value - String - element content.

{
  url: 'https://google.com',
  wait: '.gb_P',
  hasInnerHtml: {
    selector: '#lst-ib',
    value: 'Gmail'
  },
  file: 'google'
}

hasOuterHtml

Type: Object

Checks, that the HTML markup of the element with the specified selector (including the element and its attributes) is equal to the specified value. The input object should contain the following properties:

selector - String - selector of the element to check.
value - String - element and its content.

{
  url: 'https://google.com',
  wait: '.gb_P',
  hasOuterHtml: {
    selector: '#lst-ib',
    value: '<a class="gb_P" data-pid="23" href="https://mail.google.com/mail/?tab=wm">Gmail</a>'
  },
  file: 'google'
}

isEnabled

Type: String

Checks, that the specified element is currently enabled (does not have the disabled attribute set).