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 appearoptions
additional optional argumentspollDelayInMs
int, how many ms between checks that the field is present or not - default is200
// 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 fortimeout
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 lockcallback
The function to call with exclusivity under the named lockopts
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 aField
to wait for click onoptions
an object containing optional arguments;throws
bool, iftrue
then an exception is thrown if the field was not clicked beforetimout
has elapsed - default istrue
timeout
int, for how many ms should we wait before giving up - default is60000
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, iftrue
then an exception is thrown if the predicate has not returned a truthy value beforetimout
has elapsed - default istrue
timeout
the number of ms we wait before giving up - default is10000
interval
the number of ms to pause between each invocation of the predicate. Default is200
Return value
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");
}