@types/nightwatch/index.d.ts

TypeScript definitions for nightwatch

import { Protocol } from "devtools-protocol";
import { Actions, By, Capabilities, RelativeBy, WebElement } from "selenium-webdriver";
import { Expect } from "./expect";

export * from "./expect";
export * from "./globals";

export const ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf";

export interface ElementResult {
    [ELEMENT_KEY]: string;
}

export interface JSON_WEB_OBJECT extends ElementResult {
    getId: () => string;
}

export type Definition = string | ElementProperties | Element | By | RelativeBy;

export type Awaitable<T, V> = Omit<T, "then"> & PromiseLike<V>;

// tslint:disable-next-line
// eslint-disable-next-line @typescript-eslint/no-invalid-void-type
type VoidToNull<T> = T extends void ? null : T;

type ExecuteScriptFunction<ArgType extends any[], ReturnValue> = (
    this: { [key: string]: any },
    ...args: ArgType
) => ReturnValue;

type ExecuteAsyncScriptFunction<ArgType extends any[], ReturnValue> = (
    this: { [key: string]: any },
    ...args: [...innerArgs: ArgType, done: (result?: ReturnValue) => void]
) => void;

export interface AppiumGeolocation {
    latitude: number;
    longitude: number;
    altitude?: number;
}

export interface ChromePerfLoggingPrefs {
    /**
     * Default: true. Whether or not to collect events from Network domain.
     */
    enableNetwork?: boolean | undefined;
    /**
     * Default: true. Whether or not to collect events from Page domain.
     */
    enablePage?: boolean | undefined;
    /**
     * A comma-separated string of Chrome tracing categories for which trace events should be collected.
     * An unspecified or empty string disables tracing.
     */
    traceCategories?: string | undefined;
    /**
     * Default: 1000. The requested number of milliseconds between DevTools trace buffer usage events. For example, if 1000,
     * then once per second, DevTools will report how full the trace buffer is. If a report indicates the buffer usage is 100%,
     * a warning will be issued.
     */
    bufferUsageReportingInterval?: number | undefined;
}

export interface ChromeOptions {
    /**
     *     List of command-line arguments to use when starting Chrome. Arguments with an associated value should be separated by a '=' sign
     * (e.g., ['start-maximized', 'user-data-dir=/tmp/temp_profile']).
     */
    args?: string[] | undefined;
    /**
     * Path to the Chrome executable to use (on Mac OS X, this should be the actual binary, not just the app. e.g.,
     * '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome')
     */
    binary?: string | undefined;
    /**
     * A list of Chrome extensions to install on startup. Each item in the list should be a base-64 encoded packed Chrome extension (.crx)
     */
    extensions?: string[] | undefined;
    /**
     * A dictionary with each entry consisting of the name of the preference and its value. These preferences are applied
     * to the Local State file in the user data folder.
     */
    localState?: Record<string, string> | undefined;
    /**
     * A dictionary with each entry consisting of the name of the preference and its value. These preferences are only applied
     * to the user profile in use.
     */
    prefs?: Record<string, string> | undefined;
    /**
     * Default: false. If false, Chrome will be quit when ChromeDriver is killed, regardless of whether the session is quit.
     * If true, Chrome will only be quit if the session is quit (or closed). Note, if true, and the session is not quit,
     * ChromeDriver cannot clean up the temporary user data directory that the running Chrome instance is using.
     */
    detach?: boolean | undefined;
    /**
     * An address of a Chrome debugger server to connect to, in the form of <hostname/ip:port>, e.g. '127.0.0.1:38947'
     */
    debuggerAddress?: string | undefined;
    /**
     * List of Chrome command line switches to exclude that ChromeDriver by default passes when starting Chrome.
     * Do not prefix switches with --.
     */
    excludeSwitches?: string[] | undefined;
    /**
     * Directory to store Chrome minidumps . (Supported only on Linux.)
     */
    minidumpPath?: string | undefined;
    /**
     * A dictionary with either a value for “deviceName,” or values for “deviceMetrics” and “userAgent.” Refer to Mobile Emulation for more information.
     */
    mobileEmulation?: Record<string, string> | undefined;
    /**
     * An optional dictionary that specifies performance logging preferences. See below for more information.
     */
    perfLoggingPrefs?: ChromePerfLoggingPrefs | undefined;
    /**
     * A list of window types that will appear in the list of window handles. For access to <webview> elements, include "webview" in this list.
     */
    windowTypes?: string[] | undefined;
}

//  TODO: visit later
export interface NightwatchDesiredCapabilities {
    /**
     * The name of the browser being used; examples: {chrome|firefox|safari|edge|internet explorer|android|iPhone|iPad|opera|brave}.
     */
    browserName?: string | null;

    /**
     * The browser version, or the empty string if unknown.
     */
    version?: string | undefined;

    /**
     * A key specifying which platform the browser should be running on. This value should be one of {WINDOWS|XP|VISTA|MAC|LINUX|UNIX|ANDROID}.
     * When requesting a new session, the client may specify ANY to indicate any available platform may be used.
     * For more information see [GridPlatforms (https://code.google.com/p/selenium/wiki/GridPlatforms)]
     */
    platform?: string | undefined;

    /**
     * Whether the session supports taking screenshots of the current page.
     */
    takesScreenShot?: boolean | undefined;

    /**
     * Whether the session can interact with modal popups, such as window.alert and window.confirm.
     */
    handlesAlerts?: boolean | undefined;

    /**
     * Whether the session supports CSS selectors when searching for elements.
     */
    cssSelectorsEnabled?: boolean | undefined;

    /**
     * Whether the session supports executing user supplied JavaScript in the context of the current page (only on HTMLUnitDriver).
     */
    javascriptEnabled?: boolean | undefined;

    /**
     * Whether the session can interact with database storage.
     */
    databaseEnabled?: boolean | undefined;

    /**
     * Whether the session can set and query the browser's location context.
     */
    locationContextEnabled?: boolean | undefined;

    /**
     * Whether the session can interact with the application cache.
     */
    applicationCacheEnabled?: boolean | undefined;

    /**
     * Whether the session can query for the browser's connectivity and disable it if desired.
     */
    browserConnectionEnabled?: boolean | undefined;

    /**
     * Whether the session supports interactions with storage objects (http://www.w3.org/TR/2009/WD-webstorage-20091029/).
     */
    webStorageEnabled?: boolean | undefined;

    /**
     * Whether the session should accept all SSL certs by default.
     */
    acceptSslCerts?: boolean | undefined;

    /**
     * Whether the session can rotate the current page's current layout between portrait and landscape orientations (only applies to mobile platforms).
     */
    rotatable?: boolean | undefined;

    /**
     * Whether the session is capable of generating native events when simulating user input.
     */
    nativeEvents?: boolean | undefined;

    /**
     * What the browser should do with an unhandled alert before throwing out the UnhandledAlertException. Possible values are "accept", "dismiss" and "ignore"
     */
    unexpectedAlertBehaviour?: string | undefined;

    /**
     * Allows the user to specify whether elements are scrolled into the viewport for interaction to align with the top (0) or bottom (1) of the viewport.
     * The default value is to align with the top of the viewport. Supported in IE and Firefox (since 2.36)
     */
    elementScrollBehaviour?: number | undefined;

    /**
     * A JSON object describing the logging level of different components in the browser, the driver, or any intermediary WebDriver servers.
     * Available values for most loggers are "OFF", "SEVERE", "WARNING", "INFO", "CONFIG", "FINE", "FINER", "FINEST", "ALL".
     * This produces a JSON object looking something like: {"loggingPrefs": {"driver": "INFO", "server": "OFF", "browser": "FINE"}}.
     */
    loggingPrefs?:
        | {
            browser?: string | undefined;
            driver?: string | undefined;
            server?: string | undefined;
        }
        | undefined;
    /**
     * This is a list of all the Chrome-specific desired capabilities.
     */
    chromeOptions?: ChromeOptions | undefined;
}

export interface NightwatchScreenshotOptions {
    enabled?: boolean | undefined;
    filename_format: ({
        testSuite,
        testCase,
        isError,
        dateObject,
    }?: {
        testSuite?: string;
        testCase?: string;
        isError?: boolean;
        dateObject?: Date;
    }) => string;
    on_failure?: boolean | undefined;
    on_error?: boolean | undefined;
    path?: string | undefined;
}

export interface NightwatchTestRunner {
    type?: string | undefined;
    options?:
        | {
            ui?: string | undefined;
            feature_path?: string | undefined;
            auto_start_session?: boolean | undefined;
            parallel?: number | undefined;
            reporter?: string | undefined;
            reporterOptions?: { [key: string]: any };
        }
        | undefined;
}

export interface NightwatchTestWorker {
    enabled: boolean;
    workers: string | number;
    node_options?: string | string[] | undefined;
}

export interface TimeoutOptions {
    /**
     * @default 60000
     */
    timeout: number;
    /**
     * @default 0
     */
    retry_attempts: number;
}

export interface NightwatchOptions {
    /**
     * Location(s) where custom commands will be loaded from.
     */
    custom_commands_path?: string | string[] | undefined;

    /**
     * Location(s) where custom assertions will be loaded from.
     */
    custom_assertions_path?: string | string[] | undefined;

    /**
     * Location(s) where page object files will be loaded from.
     */
    page_objects_path?: string | string[] | undefined;

    // An array specifying a list of Nightwatch plugin names that should be used;
    // e.g.: plugins: ['vite-plugin-nightwatch']
    plugins: string[];

    /**
     * Location of an external globals module which will be loaded and made available to the test as a property globals on the main client instance.
     * Globals can also be defined/overwritten inside a test_settings environment.
     */
    globals_path?: string | undefined;

    /**
     * An object which will be made available on the main test api, throughout the test execution.
     */
    globals?: NightwatchGlobals;

    /**
     * configuration settings for the dotenv module - a zero-dependency module that loads environment variables from a .env file into process.env. More details on https://www.npmjs.com/package/dotenv
     */
    dotenv?: any;

    /**
     * persist the same globals object between runs or have a (deep) copy of it per each test;
     * this can be useful when persisting data between test suites is needed, such as a cookie or session information.
     * @default false
     */
    persist_globals?: boolean | undefined;

    /**
     * The location where the JUnit XML report files will be saved. Set this to false if you want to disable XML reporting.
     */
    output_folder?: string | undefined;

    /**
     * An array of folders (excluding subfolders) where the tests are located.
     */
    src_folders: string | string[];

    /**
     * Used when running in parallel to determine if the output should be collected and displayed at the end.
     */
    live_output?: boolean | undefined;

    /**
     * disable support of loading of typescript files for backwards compatibility with test suites.
     */
    disable_typescript: boolean | undefined;

    /**
     * Controls whether or not to disable coloring of the cli output globally.
     */
    disable_colors?: boolean | undefined;

    /**
     * Used when running in parallel to specify the delay (in milliseconds) between starting the child processes
     */
    parallel_process_delay?: number | undefined;

    /**
     * An object containing Selenium Server related configuration options. See below for details.
     */
    selenium?: NightwatchSeleniumOptions | undefined;

    /**
     * Whether or not to automatically start the Selenium/WebDriver session. If running unit tests, this should be set tot false.
     * @default true
     */
    start_process?: boolean | undefined;

    /**
     * End the session automatically when the test is being terminated, usually after a failed assertion.
     * @default true
     */
    end_session_on_fail?: boolean | undefined;

    /**
     * Skip the remaining test cases from the current test suite, when one test case fails.
     */
    skip_testcases_on_fail?: boolean | undefined;

    /**
     * Whether or not to run individual test files in parallel. If set to true, runs the tests in parallel and determines the number of workers automatically.
     * If set to an object, can specify specify the number of workers as "auto" or a number. Example: "test_workers" : {"enabled" : true, "workers" : "auto"}
     * @default false
     */
    test_workers?: boolean | NightwatchTestWorker | undefined;

    /**
     * This object contains all the test related options. See below for details.
     */
    test_settings: NightwatchTestSettings;

    /**
     * Specifies which test runner to use when running the tests. Values can be either default (built in nightwatch runner) or mocha.
     * Example: "test_runner" : {"type" : "mocha", "options" : {"ui" : "tdd"}}
     * @default 'default'
     */
    test_runner?: string | NightwatchTestRunner | undefined;

    /**
     * Allows for webdriver config (mostly the same as selenium)
     */
    webdriver?:
        | {
            /**
             * When this is enabled, the Webdriver server is run in background in a child process and started/stopped automatically.
             * Nightwatch includes support for managing Chromedriver, Geckodriver (Firefox), Safaridriver, and Selenium Server. Please refer to the Install Webdriver section for details.
             * @default false
             */
            start_process: boolean;

            /**
             * Only useful if start_process is enabled.
             * @default none
             */
            server_path: string;

            /**
             * Only needed when the Webdriver service is running on a different machine.
             */
            host: string;

            /**
             * The port number on which the Webdriver service will listen and/or on which Nightwatch will attempt to connect.
             */
            port: number;

            /**
             * Should be set to true if connecting to a remote (cloud) service via HTTPS. Also don't forget to set port to 443.
             */
            ssl: boolean;

            /**
             * The location where the Webdriver service log file output.log file will be placed. Defaults to current directory.
             * To disable Webdriver logging, set this to false.
             * @default none
             */
            log_path: string | boolean;

            /**
             * List of cli arguments to be passed to the Webdriver process. This varies for each Webdriver implementation.
             *
             * @default none
             */
            cli_args: any;

            /**
             * Some Webdriver implementations (Safari, Edge) support both the W3C Webdriver API as well as the legacy JSON Wire (Selenium) API.
             *
             * @default false
             */
            use_legacy_jsonwire: boolean;

            /**
             * Time to wait (in ms) before starting to check the Webdriver server is up and running.
             *
             * @default 100
             */
            check_process_delay: number;

            /**
             * Maximum number of ping status check attempts when checking if the Webdriver server is up and running before returning a timeout error.
             *
             * @default 5
             */
            max_status_poll_tries: number;

            /**
             * Interval (in ms) to use between status ping checks when checking if the Webdriver server is up and running.
             *
             * @default 100
             */
            status_poll_interval: number;

            /**
             * The entire time (in ms) to wait for the Node.js process to be created and running (default is 2 min), including spawning the child process and checking the status.
             *
             * @default 120000
             */
            process_create_timeout: number;

            /**
             * Proxy requests to the Webdriver (or Selenium) service. http, https, socks(v5), socks5, sock4, and pac are accepted. Uses node-proxy-agent.
             *
             * @example http://user:pass@host:port
             * @default none
             */
            proxy: string;

            /**
             * Requests to the Webdriver service will timeout in timeout miliseconds; a retry will happen retry_attempts number of times.
             *
             * @example {timeout: 15000, retry_attempts: 5}
             */
            timeout_options: TimeoutOptions;

            /**
             * Needed sometimes when using a Selenium Server. The prefix to be added to to all requests (e.g. /wd/hub).
             */
            default_path_prefix: string;

            /**
             * Usually only needed for cloud testing Selenium services. In case the server requires credentials this username will be used to compute the Authorization header.
             *
             * The value can be also an environment variable, in which case it will look like this:
             * "username" : "${SAUCE_USERNAME}"
             *
             * @default none
             */
            username: string;

            /**
             * This field will be used together with username to compute the Authorization header.
             *
             * Like username, the value can be also an environment variable:
             * "access_key" : "${SAUCE_ACCESS_KEY}"
             *
             * @default none
             */
            access_key: string;

            /**
             * Sets the path to the Chrome binary to use.
             * On Mac OS X, this path should reference the actual Chrome executable,
             * not just the application binary (e.g. "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome").
             */
            chrome_binary?: "";

            /**
             * Sets the path to Chrome's log file. This path should exist on the machine that will launch Chrome.
             */
            chrome_log_file?: "";

            /**
             * Configures the ChromeDriver to launch Chrome on Android via adb.
             */
            android_chrome?: false;

            /**
             * Sets the path to the Edge binary to use. This path should exist on the machine that will launch Edge.
             */
            edge_binary?: "";

            /**
             * Sets the path to the Edge binary to use.
             */
            edge_log_file?: "";

            /**
             * Sets the binary to use. The binary may be specified as the path to a Firefox executable or a desired release Channel. This path should exist on the machine that will launch Firefox.
             */
            firefox_binary?: "";

            /**
             * Sets the path to an existing profile to use as a template for new browser sessions.
             * This profile will be copied for each new session - changes will not be applied to the profile itself.
             */
            firefox_profile?: "";
        }
        | undefined;

    /**
     * An array of folders or file patterns to be skipped (relative to the main source folder).
     * @example
     * "exclude" : ["excluded-folder"]
     * or:
     * "exclude" : ["test-folder/*-smoke.js"]
     */
    exclude?: string[];

    /**
     * Folder or file pattern to be used when loading the tests. Files that don't match this pattern will be ignored
     * @example
     * "filter" : "tests/*-smoke.js"
     */
    filter?: string;

    /**
     * Skip a group of tests (a subfolder); can be a list of comma-separated values (no space).
     */
    skipgroup?: string;

    /**
     * A name property will be added to the desiredCapabilities containing the test suite name when this is enabled. It is useful when using cloud testing services.
     */
    sync_test_names?: boolean;

    /**
     * Skip tests by tag name; can be a list of comma-separated values (no space).
     */
    skiptags?: string;

    /**
     * Tag(s) used/to be used during test execution.
     * Can be a single tag or an array of tags.
     */
    tag_filter?: string | string[];

    /**
     * Use xpath as the default locator strategy.
     */
    use_xpath?: boolean;

    parallel_mode?: boolean;

    report_prefix?: string;

    unit_testing_mode?: boolean;

    /**
     * @default junit
     */
    default_reporter?: string;

    /**
     * Set this to true to use the v1.x response format for commands when using ES6 async/await
     * @default false
     */
    backwards_compatibility_mode?: boolean;

    /**
     * Set this to true to disable the global objects such as element(), browser, by(), expect()
     */
    disable_global_apis?: boolean;

    /**
     * Ignore network errors (e.g. ECONNRESET errors)
     */
    report_network_errors?: boolean;

    /**
     * Interactive element commands such as "click" or "setValue" can be retried
     * if an error occurred (such as an "element not interactable" error)
     */
    element_command_retries?: number;

    /**
     * Sets the initial window size: {height: number, width: number}
     */
    window_size?: WindowSize;
}

export interface NightwatchGlobals {
    [key: string]: any;
    /**
     * this controls whether to abort the test execution when an assertion failed and skip the rest
     * it's being used in waitFor commands and expect assertions
     * @default true
     */
    abortOnAssertionFailure?: boolean | undefined;

    /**
     * this controls whether to abort the test execution when an assertion failed and skip the rest
     * it's being used in waitFor commands and expect assertions
     * @default false
     */
    abortOnElementLocateError?: boolean | undefined;

    /**
     * this will overwrite the default polling interval (currently 500ms) for waitFor commands
     * and expect assertions that use retry
     * @default 500
     */
    waitForConditionPollInterval?: number | undefined;

    /**
     * default timeout value in milliseconds for waitFor commands and implicit waitFor value for
     * expect assertions
     * @default 5000
     */
    waitForConditionTimeout?: number | undefined;

    /**
     * this will cause waitFor commands on elements to throw an error if multiple
     * elements are found using the given locate strategy and selector
     * @default false
     */
    throwOnMultipleElementsReturned?: boolean | undefined;

    /**
     * By default a warning is printed if multiple elements are found using the given locate strategy
     * and selector; set this to true to suppress those warnings
     * @default false
     */
    suppressWarningsOnMultipleElementsReturned: boolean | undefined;

    /**
     * controls the timeout time for async hooks. Expects the done() callback to be invoked within this time
     * or an error is thrown
     * @default 20000
     */
    asyncHookTimeout?: number | undefined;

    /**
     * controls the timeout value for when running async unit tests. Expects the done() callback to be invoked within this time
     *  or an error is thrown
     * @default  2000
     */
    unitTestsTimeout?: number | undefined;

    /**
     * controls the timeout value for when executing the global async reporter. Expects the done() callback to be invoked within this time
     * or an error is thrown
     * @default 20000
     */
    customReporterCallbackTimeout?: number | undefined;

    /**
     * Automatically retrying failed assertions - You can tell Nightwatch to automatically retry failed assertions until a given timeout is reached, before the test runner gives up and fails the test.
     */
    retryAssertionTimeout?: number | undefined;

    reporter: (results: any, cb: any) => void;
    beforeTestSuite(browser: any): Promise<void>;
    afterTestSuite(browser: any): Promise<void>;
    beforeTestCase(browser: any): Promise<void>;
    afterTestCase(browser: any): Promise<void>;
    onBrowserNavigate(browser: any): Promise<void>;
    onBrowserQuit(browser: any): Promise<void>;
}

export interface NightwatchSeleniumOptions {
    /**
     * Whether or not to manage the selenium process automatically.
     * @default false
     */
    start_process: boolean;

    /**
     * Whether or not to automatically start the Selenium session.
     */
    start_session: boolean;

    /**
     * The location of the selenium jar file. This needs to be specified if start_process is enabled.E.g.: lib/selenium-server-standalone-2.43.0.jar
     */
    server_path: string;

    /**
     * The location where the selenium Selenium-debug.log file will be placed. Defaults to current directory. To disable Selenium logging, set this to false
     */
    log_path: string | boolean;

    /**
     * Usually not required and only used if start_process is true. Specify the IP address you wish Selenium to listen on.
     */
    host: string;

    /**
     * The port number Selenium will listen on.
     */
    port: number | undefined;

    /**
     * List of cli arguments to be passed to the Selenium process. Here you can set various options for browser drivers, such as:
     *
     * webdriver.firefox.profile: Selenium will be default create a new Firefox profile for each session.
     * If you wish to use an existing Firefox profile you can specify its name here.
     * Complete list of Firefox Driver arguments available https://code.google.com/p/selenium/wiki/FirefoxDriver.
     *
     * webdriver.chrome.driver: Nightwatch can run the tests using Chrome browser also. To enable this you have to download the ChromeDriver binary
     * (http://chromedriver.storage.googleapis.com/index.html) and specify it's location here. Also don't forget to specify chrome as the browser name in the
     * desiredCapabilities object.
     * More information can be found on the ChromeDriver website (https://sites.google.com/a/chromium.org/chromedriver/).
     *
     * webdriver.ie.driver: Nightwatch has support for Internet Explorer also. To enable this you have to download the IE Driver binary
     * (https://code.google.com/p/selenium/wiki/InternetExplorerDriver) and specify it's location here. Also don't forget to specify "internet explorer" as the browser
     * name in the desiredCapabilities object.
     */
    cli_args: {};

    /**
     * Time to wait (in ms) before starting to check the Webdriver server is up and running
     * @default 500
     */
    check_process_delay: number;

    /**
     * Maximum number of ping status check attempts before returning a timeout error
     * @default 15
     */
    max_status_poll_tries: number;

    /**
     * Interval (in ms) to use between status ping checks when checking if the Webdriver server is up and running
     * @default 200
     */
    status_poll_interval: number;
}

// TODO: Remove duplicates from NightwatchOptions
export interface NightwatchTestSettingGeneric {
    /**
     * A url which can be used later in the tests as the main url to load. Can be useful if your tests will run on different environments, each one with a different url.
     */
    launch_url?: string | undefined;

    /**
     * The hostname/IP on which the selenium server is accepting connections.
     */
    selenium_host?: string | undefined;

    /**
     * The port number on which the selenium server is accepting connections.
     */
    selenium_port?: number | undefined;

    /**
     * Whether to show extended Selenium command logs.
     */
    silent?: boolean | undefined;

    /**
     * Use to disable terminal output completely.
     */
    output?: boolean | undefined;

    /**
     * Use to disable colored output in the terminal.
     */
    disable_colors?: boolean | undefined;

    /**
     * In case the selenium server requires credentials this username will be used to compute the Authorization header.
     * The value can be also an environment variable, in which case it will look like this: "username" : "${SAUCE_USERNAME}"
     */
    username?: string | undefined;

    /**
     * This field will be used together with username to compute the Authorization header.
     * Like username, the value can be also an environment variable: "access_key" : "${SAUCE_ACCESS_KEY}"
     */
    access_key?: string | undefined;

    /**
     * Proxy requests to the selenium server. http, https, socks(v5), socks5, sock4, and pac are accepted. Uses node-proxy-agent. Example: http://user:pass@host:port
     */
    proxy?: string | undefined;

    /**
     * An object which will be passed to the Selenium WebDriver when a new session will be created. You can specify browser name for instance along with other capabilities.
     * Example:
     *  "desiredCapabilities" : {
     *  "browserName" : "firefox",
     *  "acceptSslCerts" : true
     * }
     * You can view the complete list of capabilities https://code.google.com/p/selenium/wiki/DesiredCapabilities.
     */
    desiredCapabilities?: NightwatchDesiredCapabilities | undefined;

    /**
     * An object which will be made available within the test and can be overwritten per environment. Example:"globals" : {  "myGlobal" : "some_global" }
     */
    globals?: NightwatchTestHooks | undefined;

    /**
     * An array of folders or file patterns to be skipped (relative to the main source folder).
     * Example: "exclude" : ["excluded-folder"] or: "exclude" : ["test-folder/*-smoke.js"]
     */
    exclude?: string[] | undefined;

    /**
     * Folder or file pattern to be used when loading the tests. Files that don't match this patter will be ignored.
     * Example: "filter" : "tests/*-smoke.js"
     */
    filter?: string | undefined;

    /**
     * Do not show the Base64 image data in the (verbose) log when taking screenshots.
     */
    log_screenshot_data?: boolean | undefined;

    /**
     * Use xpath as the default locator strategy
     */
    use_xpath?: boolean | undefined;

    /**
     * Same as Selenium settings cli_args. You can override the global cli_args on a per-environment basis.
     */
    cli_args?: any;

    /**
     * End the session automatically when the test is being terminated, usually after a failed assertion.
     */
    end_session_on_fail?: boolean | undefined;

    /**
     * Skip the rest of testcases (if any) when one testcase fails..
     */
    skip_testcases_on_fail?: boolean | undefined;
}

export interface NightwatchTestSettingScreenshots extends NightwatchTestSettingGeneric {
    /**
     * Selenium generates screenshots when command errors occur. With on_failure set to true, also generates screenshots for failing or erroring tests. These are saved on the disk.
     * Since v0.7.5 you can disable screenshots for command errors by setting "on_error" to false.
     * Example:
     * "screenshots" : {
     *      "enabled" : true,
     *      "on_failure" : true,
     *      "on_error" : false,
     *      "path" : ""
     * }
     */
    screenshots: NightwatchScreenshotOptions;
}

export interface NightwatchTestOptions extends NightwatchTestSettingGeneric {
    screenshots: boolean;
    screenshotsPath: string;
}

export interface NightwatchTestSettings {
    [key: string]: NightwatchTestSettingScreenshots;
}

export interface NightwatchTestSuite {
    name: string;
    module: string;
    group: string;
    results: any;
}

export interface NightwatchAssertionsError {
    name: string;
    message: string;
    showDiff: boolean;
    stack: string;
}

export interface NightwatchEnsureResult {
    value: null;
    returned: 1;
}

export interface Ensure {
    /**
     * Ensures that the Nightwatch WebDriver client is able to switch to the designated frame.
     */
    ableToSwitchToFrame(frame: number | WebElement | By): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that waits for an alert to be opened.
     */
    alertIsPresent(): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the given element to be disabled.
     */
    elementIsDisabled(element: WebElement | Element | string): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the given element to be enabled.
     */
    elementIsEnabled(element: WebElement): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the given element to be deselected.
     */
    elementIsNotSelected(element: WebElement | Element | string): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the given element to be in the DOM, yet not displayed to the user.
     */
    elementIsNotVisible(element: WebElement | Element | string): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the given element to be selected.
     */
    elementIsSelected(element: WebElement | Element | string): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the given element to be displayed.
     */
    elementIsVisible(element: WebElement | Element | string): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will loop until an element is found with the given locator.
     */
    elementLocated(locator: By): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the given element's text to contain the given substring.
     */
    elementTextContains(
        element: WebElement | Element | string,
        substr: string,
    ): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the given element's text to equal the given text.
     */
    elementTextIs(
        element: WebElement | Element | string,
        text: string,
    ): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the given element's text to match a given regular expression.
     */
    elementTextMatches(
        element: WebElement | Element | string,
        regex: RegExp,
    ): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will loop until at least one element is found with the given locator.
     */
    elementsLocated(locator: By): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the given element to become stale.
     * An element is considered stale once it is removed from the DOM, or a new page has loaded.
     */
    stalenessOf(element: WebElement | Element | string): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the current page's title to contain the given substring.
     */
    titleContains(substr: string): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the current page's title to match the given value.
     */
    titleIs(title: string): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the current page's title to match the given regular expression.
     */
    titleMatches(regex: RegExp): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the current page's url to contain the given substring.
     */
    urlContains(substrUrl: string): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the current page's url to match the given value.
     */
    urlIs(url: string): Awaitable<NightwatchAPI, NightwatchEnsureResult>;

    /**
     * Creates a condition that will wait for the current page's url to match the given regular expression.
     */
    urlMatches(regex: RegExp): Awaitable<NightwatchAPI, NightwatchEnsureResult>;
}

export interface Assert extends NightwatchAssertions, NightwatchNodeAssertions {}

export interface NightwatchAssertions extends NightwatchCommonAssertions, NightwatchCustomAssertions {
    /**
     * Negates any of assertions following in the chain.
     */
    not: Omit<NightwatchAssertions, "not">;
}

export interface NightwatchAssertionsResult<T> {
    value: T;
    status: 0;
    returned: 1;
    passed: true;
}

export interface NightwatchCommonAssertions {
    /**
     * Checks if the given attribute of an element contains the expected value.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.attributeContains('#someElement', 'href', 'google.com');
     *    };
     * ```
     */
    attributeContains(
        selector: Definition,
        attribute: string,
        expected: string,
        message?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the given attribute of an element has the expected value.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.attributeEquals('body', 'data-attr', 'some value');
     *    };
     * ```
     */
    attributeEquals(
        selector: Definition,
        attribute: string,
        expected: string,
        message?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Check if an element's attribute value matches a regular expression.
     *
     * @example
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.attributeMatches('body', 'data-attr', '(value)');
     *    };
     * ```
     */
    attributeMatches(
        selector: Definition,
        attribute: string,
        regex: string | RegExp,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the specified css property of a given element has the expected value.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.cssProperty('#main', 'display', 'block');
     *    };
     * ```
     */
    cssProperty(
        selector: Definition,
        cssProperty: string,
        expected: string,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the specified DOM property of a given element has the expected value.
     * For all the available DOM element properties, consult the [Element doc at MDN](https://developer.mozilla.org/en-US/docs/Web/API/element).
     * Several properties can be specified (either as an array or command-separated list). Nightwatch will check each one for presence.
     */
    domPropertyContains(
        selector: Definition,
        domProperty: string,
        expected: string | number,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<any>>;

    /**
     * Checks if the specified DOM property of a given element has the expected value.
     * For all the available DOM element properties, consult the [Element doc at MDN](https://developer.mozilla.org/en-US/docs/Web/API/element).
     * If the result value is JSON object or array, a deep equality comparison will be performed.
     */
    domPropertyEquals(
        selector: Definition,
        domProperty: string,
        expected: string | number,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<any>>;

    /**
     * Check if specified DOM property value of a given element matches a regex.
     * For all the available DOM element properties, consult the [Element doc at MDN](https://developer.mozilla.org/en-US/docs/Web/API/element).
     */
    domPropertyMatches(
        selector: Definition,
        domProperty: string,
        expected: string | RegExp,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<any>>;

    /**
     * Checks if the number of elements specified by a selector is equal to a given value.
     *
     * @example
     *
     * this.demoTest = function (browser) {
     *   browser.assert.elementsCount('div', 10);
     *   browser.assert.not.elementsCount('div', 10);
     * }
     */
    elementsCount(
        selector: Definition,
        count: number,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<JSON_WEB_OBJECT[]> & { WebdriverElementId: string }>;

    /**
     * Checks if the given element exists in the DOM.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.elementPresent("#main");
     *    };
     * ```
     */
    elementPresent(
        selector: Definition,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<Array<Omit<JSON_WEB_OBJECT, "getId">>>>;

    /**
     * Checks if the given element does not exists in the DOM.
     *
     * @example
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.elementNotPresent(".should_not_exist");
     *    };
     * ```
     *
     * @deprecated In favour of `assert.not.elementPresent()`.
     */
    elementNotPresent(
        selector: Definition,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<Array<Omit<JSON_WEB_OBJECT, "getId">>>>;

    /**
     * Checks if the given element does not have the specified CSS class.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.cssClassNotPresent('#main', 'container');
     *    };
     * ```
     *
     * @deprecated In favour of `assert.not.hasClass()`.
     */
    cssClassNotPresent(
        selector: Definition,
        className: string,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the given element has the specified CSS class.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.cssClassPresent('#main', 'container');
     *    };
     * ```
     *
     * @deprecated In favour of `assert.hasClass()`.
     */
    cssClassPresent(
        selector: Definition,
        className: string,
        message?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the given element has the specified CSS class.
     *
     * @example
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.hasClass('#main', 'container');
     *      browser.assert.hasClass('#main', ['visible', 'container']);
     *      browser.assert.hasClass('#main', 'visible container');
     *    };
     * ```
     */
    hasClass(
        selector: Definition,
        className: string | string[],
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the given element contains the specified DOM attribute.
     *
     * Equivalent of: https://developer.mozilla.org/en-US/docs/Web/API/Element/hasAttribute
     *
     * @example
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.hasAttribute('#main', 'data-track');
     *    };
     * ```
     */
    hasAttribute(
        selector: Definition,
        expectedAttribute: string,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the given element is enabled (as indicated by the 'disabled' attribute).
     *
     * @example
     *  this.demoTest = function (browser) {
     *    browser.assert.enabled('.should_be_enabled');
     *    browser.assert.enabled({selector: '.should_be_enabled'});
     *    browser.assert.enabled({selector: '.should_be_enabled', suppressNotFoundErrors: true});
     *  };
     */
    enabled(selector: Definition, message?: string): Awaitable<NightwatchAPI, NightwatchAssertionsResult<boolean>>;

    /**
     * Checks if the given element is selected.
     *
     * @example
     *  this.demoTest = function (browser) {
     *    browser.assert.selected('.should_be_selected');
     *    browser.assert.selected({selector: '.should_be_selected'});
     *    browser.assert.selected({selector: '.should_be_selected', suppressNotFoundErrors: true});
     *  };
     */
    selected(selector: Definition, message?: string): Awaitable<NightwatchAPI, NightwatchAssertionsResult<boolean>>;

    /**
     * Checks if the given element contains the specified text.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.containsText('#main', 'The Night Watch');
     *    };
     * ```
     *
     * @deprecated In favour of `assert.textContains()`.
     */
    containsText(
        selector: Definition,
        expectedText: string,
        message?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the given element contains the specified text.
     *
     * @example
     * ```
     *   this.demoTest = function (browser) {
     *     browser.assert.textContains('#main', 'The Night Watch');
     *   };
     * ```
     */
    textContains(
        selector: Definition,
        expectedText: string,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Check if an element's inner text equals the expected text.
     *
     * @example
     *
     * ```
     *   this.demoTest = function (browser) {
     *     browser.assert.textEquals('#main', 'The Night Watch');
     *   };
     * ```
     */
    textEquals(
        selector: Definition,
        expectedText: string,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Check if an elements inner text matches a regular expression.
     *
     * @example
     *
     * ```
     *   this.demoTest = function (browser) {
     *     browser.assert.textMatches('#main', '^Nightwatch');
     *   };
     * ```
     */
    textMatches(
        selector: Definition,
        regex: string | RegExp,
        msg?: string,
    ): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the page title equals the given value.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.title("Nightwatch.js");
     *    };
     * ```
     *
     * @deprecated In favour of `titleEquals()`.
     */
    title(expected: string, message?: string): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the page title equals the given value.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.title("Nightwatch.js");
     *    };
     * ```
     */
    titleContains(expected: string, message?: string): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the page title equals the given value.
     * @since 2.0
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.titleEquals("Nightwatch.js");
     *    };
     * ```
     */
    titleEquals(expected: string, message?: string): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the current title matches a regular expression.
     *
     * @example
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.titleMatches('^Nightwatch');
     *    };
     * ```
     */
    titleMatches(regex: string | RegExp, msg?: string): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the current URL contains the given value.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.urlContains('google');
     *    };
     * ```
     */
    urlContains(expectedText: string, message?: string): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the current url equals the given value.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.urlEquals('https://www.google.com');
     *    };
     * ```
     */
    urlEquals(expected: string, message?: string): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the current url matches a regular expression.
     *
     * @example
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.urlMatches('^https');
     *    };
     * ```
     */
    urlMatches(regex: string | RegExp, msg?: string): Awaitable<NightwatchAPI, NightwatchAssertionsResult<string>>;

    /**
     * Checks if the given form element's value equals the expected value.
     *
     * ```
     *    this.demoTest = function (browser) {
     *      browser.assert.value("form.login input[type=text]", "username");
     *    };
     * ```
     *
     * @deprecated In favour of `assert.valueEquals()`.
     */
    value(
        selector: Definition,
        expectedText: string,
        message?: string,
    ): Awaitable<NightwatchA