• Public
  • Public/Protected
  • All

Interface LegacyApi







$includeFolder: string

A relic from Sahi, just defined to ensure backward compatibility


Application: Type<ThenableApplication>


Environment: Type<ThenableEnvironment>


Key: Key


Logger: Logger


MouseButton: MouseButton


Region: Type<ThenableRegion>


TestCase: Type<TestCase>


context: TestExecutionContext

The current TestExecutionContext provided by Sakuli runtime this is usually not needed in a Testcase.


driver: ThenableWebDriver

Instance of ThenableWebDriver. Can execute any native method of webdriver. It's not recommended to use it in a testcase.










  • _assert(condition: Promise<boolean>, message?: undefined | string): Promise<void>



  • _assertEqual(expected: any, actual: any, message?: undefined | string): Promise<void>


  • _assertEqualArrays(expected: Array<any>, actual: Array<any>, message?: undefined | string): Promise<void>



  • _assertFalse(condition: Promise<boolean>, message?: undefined | string): Promise<void>



  • _assertNotEqual(expected: any, actual: any, message?: undefined | string): Promise<void>



  • _assertNotNull(value: any, message?: undefined | string): Promise<void>


  • _assertNotTrue(condition: Promise<boolean>, message?: undefined | string): Promise<void>


  • _assertNull(value: any, message?: undefined | string): Promise<void>


  • _assertTrue(condition: Promise<boolean>, message?: undefined | string): Promise<void>














  • _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


    • query: SahiElementQueryOrWebElement

      query to the Element to click on

    • Optional combo: undefined | string

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

    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





  • Compares the .innerHTML of an element with the given html string. Both .innerHTML and the snippet are unified using the html function from common-tags library.


    Assume the following HTML-snippet:

    <div id="d1" style="background-color: yellow"><i>Formatted</i> Text</div>

    Check if an element contains certain HTML:

    await _containsHTML(_div(0), '<i>Formatted</i>'); // -> true
    await _containsHTML(_div(0), 'Text'); // -> true
    await _containsHTML(_div(0), '<i>Formatted</i> Text'); // -> true
    await _containsHTML(_div(0), '<i>.*</i>'); // -> true
    await _containsHTML(_div(0), 'Formatted Text'); // -> false
    await _containsHTML(_div(0), 'Non existent'); // -> false


    Returns Promise<boolean>


  • Checks if the displayed text of the element contains the given text. The text parameter is turned into an RegExp object before performing the check.


    Assume following HTML-snippet:

    <p ="intro">
    Lorem ipsum dolor sit amet. consetetur sadipscing elitr
    <!-- Inner HTML-tags are stripped -->
    <div>Hello <i>World</i></div>
    <div id="pending-request">
        There are 5 pending request

    Check if a element contains certain text:

    const containsIpsumDolor = await _containsText(_paragraph('intro'), 'ipsum dolor') // -> true
    const containsYpsumDolor = await _containsText(_paragraph('intro'), 'ypsum dolor') // -> false
    const containsText = await _containsText(_div(0), 'Hello World'); // -> true
    const probablyDynamicText = await _containsText(_div('pending-request'), "There are . pending requests"); // -> true


    Returns Promise<boolean>













  • _dynamicInclude(): Promise<void>





  • _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>


  • Resolves to true / false when the element can be found in the DOM or not.


    Assume this HTML-snippet:


    Determine if an element is present in the current DOM:

    const present = await _exists(_div("Hello")); // -> true
    const absent = await _exists(_div("World")); // -> false


    Returns Promise<boolean>







  • 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





  • Retrieves the value of an element attribute.


    Assume this HTML-snippet:

        class="widget primary"
    >Foo bar</div>

    Accessing the values of div attributes:

    const dataTestId = await _getAttribute(_div(/Foo bar/), 'data-testid'); // -> "foo-element"
    const classNames = await _getAttribute(_div(/Foo bar/), 'class'); // -> "widget primary"


    Returns Promise<string>



  • Finds all option elements within the queried element and resolves to an array with all visible texts of the options. If the parameter value is set to "value" it will resolve to an array with all option values.


    Assume this HTML-snippet:

    <select name="answers">
        <option value="a-yes">Yes</option>
        <option value="a-no">No</option>
        <option value="a-maybe">Maybe</option>

    Accessing either to displayed text or the actual values of the options:

    const optionTexts = await _getOptions(_select('answers')); // -> ['Yes', 'No', 'Maybe']
    const optionValues = await _getOptions(_select('answers'), "value"); // -> ['a-yes', 'a-no', 'a-maybe']


    Returns Promise<string[]>


  • Retrieves the text content of the selected option within the select element.


    Assume this HTML-snippet:

    <select name="answers">
        <option value="a-yes">Yes</option>
        <option value="a-no">No</option>
        <option selected="selected" value="a-maybe">Maybe</option>
        <!-- Selected attribute is also set if the user (or Sakuli) selects the option in the browser -->

    Accessing either the displayed text or the actual value of the options:

    const selectedOptionText = await _getSelected(_select('answers')); // -> 'a-maybe'


    Returns Promise<string>


  • _getSelectionText(): Promise<string>



  • Retrieves the actual value from the value attribute of an Element or Query.


    Assume this HTML-snippet:

    <input type="text" name="with-value" value="Hello World" />
    <div id="without-value"></div>

    Accessing the value of [value]

    const valueFromInput = await _getValue(_textbox('with-value')); // -> "Hello World"
    const noValue = await _getValue(_div('without-value')); // -> undefined


    Returns Promise<string>
















  • Checks if the element has an attribute checked. This is useful for checkboxes or radio inputs.


    Assume this HTML-snippet:

       <input type="radio" name="payment" value=debit-card" />
       <input type="radio" name="payment" value="cash" />

    Checks if a radio input is checked or not:

    const checked = await _isChecked(_radio(0)); // -> true
    const notChecked = await _isChecked(_radio(1)); // -> false


    Returns Promise<boolean>


  • Checks if an element is enabled. An element is considered as enabled when it has no disabled attribute set.


    Assume this HTML-snippet:

    <input type="text" id="enabled-input" />
    <input type="text" disabled id="disabled-input" />

    Check if the inputs are enabled:

    const enabled = await _isEnabled(_textbox('enabled-input')); // -> true
    const disabled = await _isEnabled(_textbox('disabled-input')); // -> false


    Returns Promise<boolean>


  • Tests if this element is currently displayed. Using a timeout of maximum one second. If a longer timeout is needed, ActionApi._wait can be used. It uses WebElement.isDisplayed internally.


    Assume this HTML-snippet:

    <div>Hello World</div>
    <div style="display: none">Ninja Element</div>

    Testing the visibility of the elements:

    const visible = await _isVisible(_div("Hello World")) // -> true
    const invisible = await _isVisible(_div("Ninja Element")) // -> false
    // Waits at most 5 seconds until element is visible
    await _wait(5000, () => _isVisible(_div('Hello World')));


    Returns Promise<boolean>




















  • _navigateTo(target: string, forceReload?: undefined | false | true, credentials?: undefined | object): 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 | object

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

    Returns Promise<any>


























  • _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>




  • Styles in HTML elements are calculated by the browser based on various CSS rules. _style returns the computed style that is finally applicable to the element. If the element inherits the named style from its parent, the parent will be queried for its value. Where possible, color values will be converted to their hex representation (e.g. #00ff00 instead of rgb(0, 255, 0)).

    Accessing the style directly as an attribute will not return a computed style. Always use _style instead.

    Warning: A proper assertion will be difficult as some browser may interpret it differently.


    Returns Promise<string>




















  • _title(): Promise<string>
  • Retrieves the current text content of the documents title element.


    Assuming the following document:

    <!DOCTYPE html>
      <title>Tested with Sakuli</title>

    Accessing the current Title of the element:

    const title = await _title() // -> "Tested with Sakuli";

    Returns Promise<string>








  • _wait(millis: number, expression?: undefined | function): 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 | function

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

    Returns Promise<void>



  • _xy(): Promise<never>