Wait

The Wait modules lets the flow wait for various events.

Wait for seconds

Wait the given amount of seconds.

Parameters

• timeout the number of seconds to wait

// Pause execution for 2 seconds before continuing
Wait.forSeconds(2);

Wait for milliseconds

Wait the given amount of milliseconds.

Parameters

• timeout the number of milliseconds to wait

// Pause execution for a more precise time interval (200 milliseconds = 0.2 seconds)
Wait.forMilliseconds(200);

Wait for field

Wait for the given field to appear - will return when field appear or throw an exception when the given amount of seconds has elapsed.

Parameters

• field the field to wait for e.g. Fields["myfield"]
• timeout the max amount of seconds to wait for the field to appear
• options additional optional arguments
  • pollDelayInMs int, how many ms between checks that the field is present or not - default is 200

// Wait up to 10 seconds for a field named "myfield" to appear
// Using the default poll interval of 200ms
Wait.forField(Fields["myfield"], 10);

// Wait up to 10 seconds for a field named "myField" to appear
// But check for the field only once per second instead of the default 200ms
Wait.forField(Fields["myField"], 10, { pollDelayInMs: 1000 });

Wait for field to disappear

Wait for the given field to disappear - will return when field disappears or throw an exception when the given amount of seconds has elapsed.

Parameters

• field the field to wait for e.g. Fields["myfield"]
• timeout the max amount of seconds to wait for the field to disappear

// Wait up to 10 seconds for a field named "myfield" to disappear from the UI
Wait.forFieldToDisappear(Fields["myfield"], 10);

Wait for window

Wait for the given window to appear - will return when a matching window appears or throw an exception when the given amount of seconds has elapsed. There is also a forWindowToDisappear variant.

Parameters

• title the title of the window to wait for
• timeout the max amount of seconds to wait for the field to appear

// Wait up to 10 seconds for any window containing "Notepad" in its title to appear
// This is useful when automating external applications
Wait.forWindow("Notepad", 10);

// Wait up to 10 seconds for any window with "Notepad" in its title to close
Wait.forWindowToDisappear("Notepad", 10);

Wait for lock

Wait.forLock(...) allows for exclusive access to a shared resource among concurrently running flows (from separate sessions) or from other asynchronous tasks (e.g. when using the Task module).

Parameters

• lockName The name of the lock
• callback The function to call with exclusivity under the named lock
• opts Options (default: { timeout: 3000 })

Return value

true if the lock was obtained within the timeout. false otherwise

To access a shared resource with exclusivity:

// Define a function that will be executed when the lock is acquired
function accessSharedResourceFn() {
  // This code will only run when we have exclusive access to the resource
  // Write your critical section code here that needs to be synchronized
}

// Attempt to acquire a lock named 'resourceLock' for up to 5 seconds
// If lock acquisition fails, the function returns false
if (!Wait.forLock("resourceLock", accessSharedResourceFn, { timeout: 5000 })) {
  throw Error("Failed to access the shared resource");
}
// Code here runs after the lock has been released

Wait for click

Wait.forClick(...) and Wait.forRightClick(...) can be used to wait for a user to click a given field.

Parameters

• field an instance of a Field to wait for click on
• options an object containing optional arguments;
  • throws bool, if true then an exception is thrown if the field was not clicked before timout has elapsed - default is true
  • timeout int, for how many ms should we wait before giving up - default is 60000

Return value

If option.throw is false then true is returned if the field was clicked, false otherwise.

// Wait for the user to left-click on the OK button
// Will throw an error if the button is not clicked within the default 60 seconds
Wait.forClick(Fields["OK"]);

// Wait for the user to right-click on the Cancel button, but only for 5 seconds
// Instead of throwing an exception, returns false if not clicked within that time
if (!Wait.forRightClick(Fields["Cancel"], { throws: false, timeout: 5000 })) {
  // This code runs if the button was not clicked within 5 seconds
  console.log("User did not click the Cancel button in time");
} else {
  // This code runs if the button was clicked within 5 seconds
  console.log("User clicked the Cancel button");
}

Wait for predicate

Wait.for(...) can be used to wait for an arbitrary condition to be met. Use this for any condition that isn’t directly supported by other methods in the Wait api.

Parameters

• predicate a function returning a truthy value when the awaited condition is met and falsy values otherwise.
• options an optional object containing arguments;
  • throws bool, if true then an exception is thrown if the predicate has not returned a truthy value before timout has elapsed - default is true
  • timeout the number of ms we wait before giving up - default is 10000
  • interval the number of ms to pause between each invocation of the predicate. Default is 200

The first truthy value returned by the predicate is returned or null if no such value was produced. If the throw option is true (default) and no truthy value is produced by the predicate, an exception is thrown in stead.

// Define a predicate function that returns a truthy value when a condition is met
// This example waits for a combobox field to have a non-empty value
function predicate() {
  return new Field('**/combobox').read(); // Returns the field's value or null if empty
}

// Method 1: Wait up to 3 seconds without throwing an exception on timeout
// Instead returns null if the condition wasn't met in time
var maybeValue = Wait.for(predicate, { throws: false, timeout: 3000 });
if (!maybeValue) {
  console.log("Combobox did not get a value within 3 seconds");
} else {
  console.log("Combobox value is: " + maybeValue);
}

// Method 2: Wait up to 10 seconds (default timeout) with exception handling
// Will throw an exception if the condition isn't met in time
try {
  var value = Wait.for(predicate); // Using default 10 second timeout
  console.log("Combobox value is: " + value);
} catch (e) {
  console.log("Timed out waiting for combobox to get a value");
}

If you need to pass arguments, you can use a second-order function:

function hasValue(field, value) {
  return new Field(field).read() === value;
}

if (Wait.for(hasValue("**/combobox", "Florida"))) {
  // handle the case where the combobox has the value "Florida"
}