• Public
  • Public/Protected
  • All

Interface ActionApi

Collection of different user-input related actions that can be invoked within a web page during the test.

The action API consists of:

All methods of this interface are available as global functions in Sakuli tests.







  • _click simulates a user's click on the given element.


    _click(_button("Click Me"));
    _click(_button("Click Me"), "CTRL"); // clicks with CTRL key pressed
    _click(_button("Click Me"), "CTRL|SHIFT"); // clicks with CTRL and SHIFT keys pressed
    _click(_button("Click Me"), {force: true}); // clicks without validation
    _click(_button("Click Me"), "CTRL", {force: true}); //clicks with CTRL without validation


    • query: SahiElementQueryOrWebElement

      query to the Element to click on

    • Optional combo: undefined | string | ClickOptions

      Optional combo key(s): can be CTRL, SHIFT, ALT or META; Can also be two or more keys together like "CTRL|SHIFT"

    • Optional options: undefined | ClickOptions

      disables validations prior to the click action to enforce clicks where an element e.g. is covered

    Returns Promise<void>

    Resolves after the click is invoked, doesn't wait for further actions on the website which are possibly invoked after the click




  • _eval<T>(source: string, ..._args: any[]): Promise<T>
  • This function sends Javascript to the browser which is executed their. you can pass a list of arguments to this script.

    The function is using ThenableWebdriver.executeScript internally.

    All element queries in the _args list (e.g. _div('Hello')) are resolved to WebElements and are available as a HTMLElement in the script

    All _args are available in the arguments array in the script.

    the return value of the JavaScript is returned from this function.

    const windowOuterHeight = await _eval(`return window.outerHeight`);
    // Dispatch a custom Event from a button on the page
    const await _eval(`
       const btn = arguments[0];
       btn.dispatchEvent(new CustomEvent('something-custom'));
    `, _button('Some special Button'))

    Type parameters

    • T


    • source: string

      Javascript code which is executed in the browser

    • Rest ..._args: any[]

      A variadic list of arguments that are passed to Javascript

    Returns Promise<T>


  • Fetches an element and performs the native .focus() method in the browser. When _focus is performed on an <input> element, it will be automatically scrolled into the viewport by the browser.

    Note that not all elements will get an actual focus in the browser. Usually links and user-controls (e.g. <input>, <textarea>, <select>...) can gain focus.


    Returns Promise<void>

    Resolves when browser-script finished









  • _navigateTo(target: string, forceReload?: undefined | false | true, credentials?: undefined | { password: string; user: string }): Promise<any>
  • Navigates the browser instance to the given URL (also Data URLs are possible).

    // open sakuli.io in the browser
    await _navigateTo("https://sakuli.io");
    // navigate and authenticate on a page with http-basic
    await _navigateTo("https://sakuli.io/fictional-admin", false, {user: 'UserName', password: 'top$ecret'})

    It uses ThenableWebdriver.get() under the hood.


    • target: string

      The URL of the Website to test - Could be any string that can be entered in a browser navigationbar

    • Optional forceReload: undefined | false | true

      Forces the page to reload after it has been loaded - it is a relict of Sahi. Default: false

    • Optional credentials: undefined | { password: string; user: string }

      If a site requires "Http-Basic-Authentication" you can pass the credentials here

    Returns Promise<any>


  • _pageIsStable(timeout?: undefined | number, interval?: undefined | number): Promise<boolean>
  • Continuously fetches the page source and checks for DOM changes. Will be repeated every $timeout milliseconds until either the DOM does no longer change or $timeout is reached

    // Wait for a stable DOM with default timeout and interval, continue test execution if it does not stabilize within timeout
    await _pageIsStable();
    // Wait for a stable DOM with custom timeout and default interval, continue test execution if it does not stabilize within timeout
    await _pageIsStable(5000);
    // Wait for a stable DOM with custom timeout and custom interval, continue test execution if it does not stabilize within timeout
    await _pageIsStable(5000, 100);
    // Wait for a stable DOM, stop test execution if it does not stabilize within timeout
    await _assertTrue(_pageIsStable(5000, 100));


    • Optional timeout: undefined | number

      Maximum timout in ms to wait for DOM stabilization. Default: 2000 ms

    • Optional interval: undefined | number

      Interval between stability checks in ms. Default: 200 ms

    Returns Promise<boolean>





  • _setSelected(query: SahiElementQueryOrWebElement, optionToSelect: string | number | string[] | number[], isMultiple?: undefined | false | true): Promise<void>
  • Sets the options within a <select> element. Selection can be done by the actual values of an option or its zero-based element index.

    This action will invoke a click on the option element which means that the selected state is not enforced. If an option is already selected, it will be unselected.


    Assume this HTML-snippet:

    <select multiple="multiple" name="cities">
        <option value="muc">Munich</option>
        <option value="vie">Vienna</option>
        <option value="dus">Dusseldorf</option>
    await _setSelected(_select('cities'), 'vie') // -> select the option Vienna
    await _setSelected(_select('cities'), 0) // -> select the option Dusseldorf


    Returns Promise<void>


  • Sets a value on an <input /> field.

    It will clear the existing value from the input before:

    • It will send each character from the value string to the input with an delay of 10 ms using .sendKeys. This ensures that components which rely on key-events (like keyup or keydown) will behave as expected on the page.

    • When .sendKeys fails, _setValue will try to set the value attribute of the dom element.


    Assume the following HTML-snippet:

        <input type="text" name="username"/>
        <input type="password" name="password" />

    _setValue can be used to enter login information:

    await _setValue(_textbox('username'), 'IamGroot');
    await _setValue(_password('password'), '$secret');


    Returns Promise<void>




  • Wait for a maximum of the given timeout. It's also possible to pass an expression function which will be evaluated during the waiting.

    // just waiting 10 seconds until proceeding
    await _wait(10000);
    // Will wait at most 5 seconds until a submit button with the text "Buy now" is visible
    await _wait(5000, () => _isVisible(_submit('Buy Now')));


    • millis: number

      Maximum amount of time to be waiting (in milliseconds)

    • Optional expression: undefined | ((...locators: SahiElementQueryOrWebElement[]) => Promise<boolean>)

      An optional function which will abort the wait when it returns a truthy value

    Returns Promise<void>


  • _xy(): Promise<never>