@types/nightwatch/index.d.ts

TypeScript definitions for nightwatch

// Type definitions for nightwatch 2.0
// Project: http://nightwatchjs.org
// Definitions by: Rahul Kavalapara <https://github.com/rkavalap>
//                 Connor Schlesiger <https://github.com/schlesiger>
//                 Clayton Astrom <https://github.com/ClaytonAstrom>
//                 Lukas Beranek <https://github.com/lloiser>
//                 Vaibhav Singh <https://github.com/vaibhavsingh97>
//                 Andrei Rusu <https://github.com/beatfactor>
//                 David Burns <https://github.com/AutomatedTester>
//                 Ravi Sawlani <https://github.com/gravityvi>
//                 Binayak Ghosh <https://github.com/swrdfish>
//                 Harshit Agrawal <https://github.com/harshit-bs>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 4.5

import { WebElement, By } from 'selenium-webdriver';

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; should be one of {android|chrome|firefox|htmlunit|internet explorer|iPhone|iPad|opera|safari}.
     */
    browserName?: string | undefined;

    /**
     * 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;
    on_failure?: boolean | undefined;
    on_error?: boolean | undefined;
    path?: string | undefined;
}

export interface NightwatchTestRunner {
    type?: string | undefined;
    options?:
        | {
              ui?: string | undefined;
          }
        | 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;
          }
        | 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;

    /**
     * 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;

    /**
     * @default false
     */
    backwards_compatibility_mode?: boolean;

    disable_global_apis?: boolean;
}

export interface NightwatchGlobals {
    /**
     * 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: any;

    /**
     * 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 NightwatchTestSuite {
    name: string;
    module: string;
    group: string;
    results: any;
}

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

export interface NightwatchLanguageChains {
    to: Expect;
    be: Expect;
    been: Expect;
    is: Expect;
    that: Expect;
    which: Expect;
    and: Expect;
    has: Expect;
    have: Expect;
    with: Expect;
    at: Expect;
    of: Expect;
}

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

export interface Expect extends NightwatchLanguageChains, NightwatchBrowser {
    /**
     * Returns the DOM Element
     */
    element(property: string): this;

    /**
     * These methods will perform assertions on the specified target on the current element.
     * The targets can be an attribute value, the element's inner text and a css property.
     */
    equal(value: string): this;
    equals(value: string): this;
    contain(value: string): this;
    contains(value: string): this;
    match(value: string | RegExp): this;
    startWith(value: string): this;
    startsWith(value: string): this;
    endWith(value: string): this;
    endsWith(value: string): this;

    /**
     * Negates any of assertions following in the chain.
     */
    not: this;

    /**
     * These methods perform the same thing which is essentially retrying the assertion for the given amount of time (in milliseconds).
     * before or after can be chained to any assertion and thus adding retry capability. You can change the polling interval by defining
     * a waitForConditionPollInterval property (in milliseconds) as a global property in your nightwatch.json or in
     * your external globals file. Similarly, a default timeout can be specified as a global waitForConditionTimeout property (in milliseconds).
     */
    before(value: number): this;
    after(value: number): this;

    /**
     * Checks if the type (i.e. tag name) of a specified element is of an expected value.
     */
    a(value: string, message?: string): this;
    an(value: string, message?: string): this;

    /**
     * Checks if a given attribute of an element exists and optionally if it has the expected value.
     */
    attribute(name: string, message?: string): this;

    /**
     * Checks a given css property of an element exists and optionally if it has the expected value.
     */
    css(property: string, message?: string): this;

    section(property: string): this;

    /**
     * Property that checks if an element is currently enabled.
     */
    enabled: this;

    /**
     * Property that checks if an element is present in the DOM.
     */
    present: this;

    /**
     * Property that checks if an OPTION element, or an INPUT element of type checkbox or radio button is currently selected.
     */
    selected: this;

    /**
     * Property that retrieves the text contained by an element. Can be chained to check if contains/equals/matches the specified text or regex.
     */
    text: this;

    /**
     * Property that retrieves the value (i.e. the value attributed) of an element. Can be chained to check if contains/equals/matches the specified text or regex.
     */
    value: this;

    /**
     * Property that asserts the visibility of a specified element.
     */
    visible: this;
}

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

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

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

    /**
     * Checks if the given element contains the specified text.
     *
     * ```
     *    this.demoTest = function (client) {
     *      browser.assert.containsText('#main', 'The Night Watch');
     *    };
     * ```
     */
    containsText(selector: string | ElementProperties, expectedText: string, message?: string): NightwatchAPI;

    /**
     * Checks if the given element has the specified CSS class.
     *
     * ```
     *    this.demoTest = function (client) {
     *      browser.assert.cssClassPresent('#main', 'container');
     *    };
     * ```
     */
    cssClassPresent(selector: string | ElementProperties, className: string, message?: string): NightwatchAPI;

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

    deepEqual(value: any, expected: any, message?: string): NightwatchAPI;

    deepStrictEqual(value: any, expected: any, message?: string): NightwatchAPI;

    doesNotThrow(value: any, expected: any, message?: string): NightwatchAPI;

    /**
     * Checks if the given element exists in the DOM.
     *
     * ```
     *    this.demoTest = function (client) {
     *      browser.assert.elementPresent("#main");
     *    };
     * ```
     */
    elementPresent(selector: string | ElementProperties, msg?: string): NightwatchAPI;

    equal(value: any, expected: any, message?: string): NightwatchAPI;

    fail(actual?: any, expected?: any, message?: string, operator?: string): NightwatchAPI;

    ifError(value: any, message?: string): NightwatchAPI;

    notDeepEqual(actual: any, expected: any, message?: string): NightwatchAPI;

    notDeepStrictEqual(value: any, message?: string): NightwatchAPI;

    notEqual(actual: any, expected: any, message?: string): NightwatchAPI;

    notStrictEqual(value: any, expected: any, message?: string): NightwatchAPI;

    ok(actual: boolean, message?: string): NightwatchAPI;

    strictEqual(value: any, expected: any, message?: string): NightwatchAPI;

    throws(fn: () => void, message?: string): NightwatchAPI;

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

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

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

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

    /**
     * Checks if the given form element's value equals the expected value.
     *
     * ```
     *    this.demoTest = function (client) {
     *      browser.assert.value("form.login input[type=text]", "username");
     *    };
     * ```
     */
    value(selector: string | ElementProperties, expectedText: string, message?: string): NightwatchAPI;

    /**
     * Checks if the given form element's value contains the expected value.
     *
     * ```
     *    this.demoTest = function (client) {
     *      browser.assert.valueContains("form.login input[type=text]", "username");
     *    };
     * ```
     */
    valueContains(selector: string | ElementProperties, expectedText: string, message?: string): NightwatchAPI;

    /**
     * Checks if the given element is visible on the page.
     *
     * ```
     *    this.demoTest = function (client) {
     *      browser.assert.visible(".should_be_visible");
     *    };
     * ```
     */
    visible(selector: string | ElementProperties, message?: string): NightwatchAPI;

    /**
     * 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: string | ElementProperties, message?: string): NightwatchAPI;

    /**
     * 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: string | ElementProperties, message?: string): NightwatchAPI;

    /**
     * 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: string | ElementProperties,
        domProperty: string,
        expected: string | number,
        msg?: string,
    ): NightwatchAPI;

    /**
     * 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: string | ElementProperties,
        domProperty: string,
        expected: string | number,
        msg?: string,
    ): NightwatchAPI;

    NightwatchAssertionsError: NightwatchAssertionsError;
}

export interface ElementProperties {
    /**
     * the element selector name
     *
     * @example
     * '@searchBar'
     */
    selector: string;

    /**
     * locator strategy can be one of
     *  - css selector
     *  - link text
     *  - partial link text
     *  - tag name
     *  - xpath
     *
     * @example
     * 'css selector'
     */
    locateStrategy?: string;

    /**
     * used to target a specific element in a query that results in multiple elements returned. Normally,
     * only the first element is used (index = 0) but using the index property, you can specify any element within the result.
     */
    index?: number;

    /**
     * used to overwrite this setting when using waitForElement* commands.
     */
    abortOnFailure?: boolean;

    /**
     * used to overwrite the default timeout for when using waitForElement* commands or assertions.
     */
    timeout?: number;

    /**
     * used to overwrite the default retry interval for when using waitForElement* commands or assertions.
     */
    retryInterval?: number;

    /**
     * Some element commands like .click() or .getText() will throw a NoSuchElement error if the element cannot be located, causing the test to fail.
     * If this option is set to true then this error is ignored.
     */
    suppressNotFoundErrors?: boolean;
}

export interface NightwatchTypedCallbackResult<T> {
    status: 0;
    value: T;
    error: Error;
}
export interface NightwatchCallbackResultError {
    status: 1; // we cannot use `number` so giving it a "symbolic" value allows to disjoint the union
    value: {
        message: string;
        screen: string;
        class: string;
        stackTrace: Array<{
            fileName: string;
            lineNumber: number;
            className: string;
            methodName: string;
        }>;
    };
    state: Error | string;
}

export type NightwatchCallbackResult<T> = NightwatchTypedCallbackResult<T> | NightwatchCallbackResultError;

export interface NightwatchLogEntry {
    /**
     * The log entry message.
     */
    message: string;

    /**
     * The time stamp of log entry in seconds.
     */
    opt_timestamp: number;

    /**
     * The log type, if known.
     */
    opt_type?: string;

    /**
     * Severity level
     */
    level: 'ALL' | 'DEBUG' | 'FINE' | 'FINER' | 'FINEST' | 'INFO' | 'OFF' | 'SEVERE' | 'WARNING' | Level | number;
}

export interface Level {
    /**
     * the level's name.
     */
    name: string;

    /**
     * the level's numeric value.
     */
    level: number;
}

export interface NightwatchKeys {
    /** Releases all held modifier keys. */
    NULL: string;
    /** OS-specific keystroke sequence that performs a cancel action. */
    CANCEL: string;
    /** The help key. This key only appears on older Apple keyboards in place of the Insert key. */
    HELP: string;
    /** The backspace key. */
    BACK_SPACE: string;
    /** The tab key. */
    TAB: string;
    /** The clear key. This key only appears on full-size Apple keyboards in place of Num Lock key. */
    CLEAR: string;
    /** The return key. */
    RETURN: string;
    /** The enter (numpad) key. */
    ENTER: string;
    /** The shift key. */
    SHIFT: string;
    /** The control key. */
    CONTROL: string;
    /** The alt key. */
    ALT: string;
    /** The pause key. */
    PAUSE: string;
    /** The escape key. */
    ESCAPE: string;

    /** The space bar. */
    SPACE: string;
    /** The page up key. */
    PAGEUP: string;
    /** The page down key. */
    PAGEDOWN: string;
    /** The end key. */
    END: string;
    /** The home key. */
    HOME: string;
    /** The left arrow. */
    ARROW_LEFT: string;
    LEFT_ARROW: string;
    /** The up arrow. */
    ARROW_UP: string;
    UP_ARROW: string;
    /** The right arrow. */
    ARROW_RIGHT: string;
    RIGHT_ARROW: string;
    /** The down arrow. */
    ARROW_DOWN: string;
    DOWN_ARROW: string;
    /** The insert key. */
    INSERT: string;
    /** The delete key. */
    DELETE: string;
    /** The semicolon key. */
    SEMICOLON: string;
    /** The equals key. */
    EQUALS: string;

    /** The numpad zero key. */
    NUMPAD0: string;
    /** The numpad one key. */
    NUMPAD1: string;
    /** The numpad two key. */
    NUMPAD2: string;
    /** The numpad three key. */
    NUMPAD3: string;
    /** The numpad four key. */
    NUMPAD4: string;
    /** The numpad five key. */
    NUMPAD5: string;
    /** The numpad six key. */
    NUMPAD6: string;
    /** The numpad seven key. */
    NUMPAD7: string;
    /** The numpad eight key. */
    NUMPAD8: string;
    /** The numpad nine key. */
    NUMPAD9: string;

    /** The numpad multiply (*) key. */
    MULTIPLY: string;
    /** The numpad add (+) key. */
    ADD: string;
    /** The numpad separator (=) key. */
    SEPARATOR: string;
    /** The numpad subtract (-) key. */
    SUBTRACT: string;
    /** The numpad decimal (.) key. */
    DECIMAL: string;
    /** The numpad divide (/) key. */
    DIVIDE: string;

    /** The F1 key. */
    F1: string;
    /** The F2 key. */
    F2: string;
    /** The F3 key. */
    F3: string;
    /** The F4 key. */
    F4: string;
    /** The F5 key. */
    F5: string;
    /** The F6 key. */
    F6: string;
    /** The F7 key. */
    F7: string;
    /** The F8 key. */
    F8: string;
    /** The F9 key. */
    F9: string;
    /** The F10 key. */
    F10: string;
    /** The F11 key. */
    F11: string;
    /** The F12 key. */
    F12: string;
    /** The meta (Windows) key. */
    META: string;
    /** The command (⌘) key. */
    COMMAND: string;
}

export interface NightwatchAPI extends SharedCommands, WebDriverProtocol, NightwatchCustomCommands {
    baseURL: string;
    assert: NightwatchAssertions;
    expect: Expect;
    verify: NightwatchAssertions;

    page: {
        [name: string]: () => EnhancedPageObject<any, any, any>;
    } & NightwatchCustomPageObjects;

    /**
     * SessionId of the session used by the Nightwatch api.
     */
    sessionId: string;

    /**
     * Override the sessionId used by Nightwatch client with another session id.
     */
    setSessionId(sessionId: string): this;

    options: NightwatchTestOptions;

    Keys: NightwatchKeys;

    currentTest: NightwatchTestSuite;

    globals: NightwatchGlobals;

    launchUrl: string;
    launch_url: string;
}

// tslint:disable-next-line:no-empty-interface
export interface NightwatchCustomCommands {}

// tslint:disable-next-line:no-empty-interface
export interface NightwatchCustomAssertions {}

// tslint:disable-next-line:no-empty-interface
export interface NightwatchCustomPageObjects {}

export interface NightwatchBrowser
    extends NightwatchAPI,
        NightwatchComponentTestingCommands,
        NightwatchCustomCommands {}

export interface NightwatchComponentTestingCommands {
    importScript(scriptPath: string, options: { scriptType: string; componentTyp: string }, callback: () => void): this;
    mountReactComponent(componentPath: string, props: string | (() => void), callback: () => void): this;
    mountVueComponent(componentPath: string, options: any, callback: () => void): this;
    launchComponentRenderer(): this;
}

// tslint:disable-next-line
export interface NightwatchElement extends WebElement {}

export type NightwatchTest = (browser: NightwatchBrowser) => void;

export interface NightwatchTestFunctions {
    before?: NightwatchTestHook | undefined;
    after?: NightwatchTestHook | undefined;
    beforeEach?: NightwatchTestHook | undefined;
    afterEach?: NightwatchTestHook | undefined;
    '@tags'?: string | string[] | undefined;
    '@disabled'?: boolean | undefined;
    [key: string]: any;
}

export type NightwatchTestHook = GlobalNightwatchTestHookEach | GlobalNightwatchTestHook;

export type GlobalNightwatchTestHookEach = (browser: NightwatchBrowser, done: (err?: any) => void) => void;

export type GlobalNightwatchTestHook = (done: (err?: any) => void) => void;

export interface NightwatchTestHooks extends NightwatchGlobals {
    before?: GlobalNightwatchTestHook | undefined;
    after?: GlobalNightwatchTestHook | undefined;
    beforeEach?: GlobalNightwatchTestHookEach | undefined;
    afterEach?: GlobalNightwatchTestHookEach | undefined;
}

export function element(locator: string | ElementProperties | By | WebElement, options?: any): WebElement;

export type NightwatchTests = NightwatchTestFunctions | NightwatchTestHooks;

/**
 * Performs an assertion
 *
 */
export type NightwatchAssert = (
    passed: boolean,
    receivedValue?: any,
    expectedValue?: any,
    message?: string,
    abortOnFailure?: boolean,
    originalStackTrace?: string,
) => void;

/**
 * Abstract assertion class that will subclass all defined assertions
 *
 * All assertions must implement the following api:
 *
 * - @param {T|function} expected
 * - @param {string} message
 * - @param {function} pass
 * - @param {function} value
 * - @param {function} command
 * - @param {function} - Optional failure
 */
export interface NightwatchAssertion<T, U = any> {
    expected: (() => T) | T;
    message: string;
    pass(value: T): any;
    value(result: U): T;
    command(callback: (result: U) => void): this;
    failure?(result: U): boolean;
    api: NightwatchAPI;
    client: NightwatchClient;
}

export interface NightwatchClient {
    api: NightwatchAPI;
    locateStrategy: LocateStrategy;
    options: NightwatchOptions;
    // TODO: Add reporter
    // reporter: reporte
    sessionID: string;
    settings: NightwatchOpt