Wait

Wait

Use the wait object to wait for a particular session or screen state. For example, you can wait until the cursor is found at a particular position or text is present at a certain location before continuing execution. Wait functions are often used in conjunction with asynchronous activities such as connecting to the host and waiting for a response after sending data.

Wait functions return Promise objects which will resolve successfully when the expected condition is met, or reject if it times out before the expected condition is met.

wait.forConnect(2000)
  .then(function () {
    console.log('Lets carry on now');
  })
  .catch(function (error) {
    console.log('Timed out:', error.message);
  });

or by wrapping in async functions and using await:

async function myAsyncFunction() {
  await wait.forFixedTime(2000);
  console.log('The wait is over');
}

To wait for multiple conditions using a single wait instance, each wait, in turn, must complete before continuing. If it is necessary to perform concurrent waits, use a separate instance of the wait object.

Constructor

new Wait(session)

Creates a new Wait object for the session.

Parameters:
Name Type Description
session Session

the session that the wait will interact with

Methods

setDefaultTimeout(timeout)

Sets the timeout value for all functions. The default is 10000 (10 seconds).

Parameters:
Name Type Description
timeout Number

timeout to use for all wait functions in milliseconds
Throws:
  • if column is out of range
Type
RangeError

forConnect(timeoutopt) → {Promise}

Waits for a connect request to complete.

Parameters:
Name Type Attributes Description
timeout Number <optional>

timeout in milliseconds
Returns:
  • Resolved if the session is already connected or when it finally connects. Rejected if the wait times out.
Type
Promise

forDisconnect(timeoutopt) → {Promise}

Waits for a session disconnect request to complete.

Parameters:
Name Type Attributes Description
timeout Number <optional>

timeout in milliseconds
Returns:
  • Resolved if the session is already disconnected, or when it finally disconnects. Rejected if the wait times out.
Type
Promise

forFixedTime(timeoutopt) → {Promise}

Waits unconditionally for a fixed time.

Parameters:
Name Type Attributes Description
timeout Number <optional>

timeout in milliseconds
Returns:
  • Resolved after the timeout has elapsed.
Type
Promise

forCursor(position, timeoutopt) → {Promise}

Waits for the cursor to arrive at the specified position.

Parameters:
Name Type Attributes Description
position Position

specifying the row and column.
timeout Number <optional>

timeout in milliseconds
Throws:
  • if column is out of range
Type
RangeError
Returns:

Resolved if the cursor is already in position, or when it is finally located. Rejected if the wait times out.

Type
Promise

forText(text, position, timeoutopt) → {Promise}

Waits for text at the specified position.

Parameters:
Name Type Attributes Description
text String

text to expect
position Position

position specifying the row and column
timeout Number <optional>

timeout in milliseconds
Throws:

if position is out of range

Type
RangeError
Returns:
  • Resolved if the text is already at the specified position, or when it is finally found. Rejected if the wait times out.
Type
Promise

forHostPrompt(text, column, timeoutopt) → {Promise}

Waits for a command prompt located at a particular column on the screen.

This method is generally used with VT hosts where it is necessary to wait for a login or shell prompt. After the prompt is displayed the cursor will end up in a known column but the row is not necessarily consistent. To handle this situation, this method can be used to wait until the prompt has arrived.

Parameters:
Name Type Attributes Description
text String

prompt to expect
column Number

where cursor is expected
timeout Number <optional>

timeout in milliseconds
Throws:
  • if column is out of range
Type
RangeError
Returns:
  • Resolved if the conditions are already met, or when the conditions are finally met. Rejected if the wait times out.
Type
Promise

forScreenChange(timeoutopt) → {Promise}

Waits for the host screen to change.

This method returns when a screen update is detected. It makes no guarantees about the number of subsequent updates that may arrive before the screen is complete. Waiting repeatedly until the screen contents match some known stopping criteria is advisable.

Parameters:
Name Type Attributes Description
timeout Number <optional>

in milliseconds.
Returns:

resolved if the screen changes. Rejected if the wait times out.

Type
Promise

forHostSettle(settleTimeopt, timeoutopt) → {Promise}

Monitors incoming screen data and resolves settleTime ms after the last update and the keyboard is unlocked.This function is useful when data arrives in multiple packets and you want to be sure the whole screen has been received before carrying on.

NOTE: Wait.forHostSettle should only be used when other more targeted wait functions are insufficient.

Parameters:
Name Type Attributes Description
settleTime Number <optional>

in milliseconds. Default is 200 ms.
timeout Number <optional>

in milliseconds.
Returns:

Resolves settleTime ms after the last screen update received and the keyboard is unlocked.

Type
Promise