webdriverio/build/index.js

import logger from '@wdio/logger';
import WebDriver, { DEFAULTS } from 'webdriver';
import { validateConfig } from '@wdio/config';
import { wrapCommand } from '@wdio/utils';
import MultiRemote from './multiremote.js';
import SevereServiceErrorImport from './utils/SevereServiceError.js';
import detectBackend from './utils/detectBackend.js';
import { getProtocolDriver } from './utils/driver.js';
import { WDIO_DEFAULTS, SupportedAutomationProtocols, Key as KeyConstant } from './constants.js';
import { getPrototype, addLocatorStrategyHandler, isStub } from './utils/index.js';
export * from './types.js';
export const Key = KeyConstant;
export const SevereServiceError = SevereServiceErrorImport;
/**
 * A method to create a new session with WebdriverIO.
 *
 * <b>
 * NOTE: If you hit "error TS2694: Namespace 'global.WebdriverIO' has no exported member 'Browser'" when using typescript,
 * add "@wdio/globals/types" into tsconfig.json's "types" array will solve it: <code> { "compilerOptions": { "types": ["@wdio/globals/types"] } } </code>
 * </b>
 *
 * @param params Options to create the session with
 * @param remoteModifier Modifier function to change the monad object
 * @return browser object with sessionId
 * @see <a href="https://webdriver.io/docs/typescript">Typescript setup</a>
 */
export const remote = async function (params, remoteModifier) {
    logger.setLogLevelsConfig(params.logLevels, params.logLevel);
    const keysToKeep = Object.keys(process.env.WDIO_WORKER_ID ? params : DEFAULTS);
    const config = validateConfig(WDIO_DEFAULTS, params, keysToKeep);
    const modifier = (client, options) => {
        /**
         * overwrite instance options with default values of the protocol
         * package (without undefined properties)
         */
        Object.assign(options, Object.entries(config)
            .reduce((a, [k, v]) => (typeof v === 'undefined' ? a : { ...a, [k]: v }), {}));
        if (typeof remoteModifier === 'function') {
            client = remoteModifier(client, options);
        }
        return client;
    };
    const { Driver, options } = await getProtocolDriver({ ...params, ...config });
    const prototype = getPrototype('browser');
    const instance = await Driver.newSession(options, modifier, prototype, wrapCommand);
    /**
     * we need to overwrite the original addCommand and overwriteCommand
     */
    if (params.framework && !isStub(params.automationProtocol)) {
        const origAddCommand = instance.addCommand.bind(instance);
        instance.addCommand = (name, fn, attachToElement) => (origAddCommand(name, fn, attachToElement));
        const origOverwriteCommand = instance.overwriteCommand.bind(instance);
        instance.overwriteCommand = (name, fn, attachToElement) => (origOverwriteCommand(name, fn, attachToElement));
    }
    instance.addLocatorStrategy = addLocatorStrategyHandler(instance);
    return instance;
};
export const attach = async function (attachOptions) {
    /**
     * copy instances properties into new object
     */
    const params = {
        automationProtocol: SupportedAutomationProtocols.webdriver,
        ...attachOptions,
        ...detectBackend(attachOptions.options),
        requestedCapabilities: attachOptions.requestedCapabilities
    };
    const prototype = getPrototype('browser');
    const { Driver } = await getProtocolDriver(params);
    const driver = Driver.attachToSession(params, undefined, prototype, wrapCommand);
    driver.addLocatorStrategy = addLocatorStrategyHandler(driver);
    return driver;
};
/**
 * WebdriverIO allows you to run multiple automated sessions in a single test.
 * This is handy when you're testing features that require multiple users (for example, chat or WebRTC applications).
 *
 * Instead of creating a couple of remote instances where you need to execute common commands like newSession() or url() on each instance,
 * you can simply create a multiremote instance and control all browsers at the same time.
 *
 * <b>
 * NOTE: Multiremote is not meant to execute all your tests in parallel.
 * It is intended to help coordinate multiple browsers and/or mobile devices for special integration tests (e.g. chat applications).
 * </b>
 *
 * @param params capabilities to choose desired devices.
 * @param automationProtocol
 * @return All remote instances, the first result represents the capability defined first in the capability object,
 * the second result the second capability and so on.
 *
 * @see <a href="https://webdriver.io/docs/multiremote">External document and example usage</a>.
 */
export const multiremote = async function (params, { automationProtocol } = {}) {
    const multibrowser = new MultiRemote();
    const browserNames = Object.keys(params);
    /**
     * create all instance sessions
     */
    await Promise.all(browserNames.map(async (browserName) => {
        const instance = await remote(params[browserName]);
        return multibrowser.addInstance(browserName, instance);
    }));
    /**
     * use attachToSession capability to wrap instances around blank pod
     */
    const prototype = getPrototype('browser');
    const sessionParams = isStub(automationProtocol) ? undefined : {
        sessionId: '',
        isW3C: multibrowser.instances[browserNames[0]].isW3C,
        logLevel: multibrowser.instances[browserNames[0]].options.logLevel
    };
    const ProtocolDriver = automationProtocol && isStub(automationProtocol)
        ? (await import(automationProtocol)).default
        : WebDriver;
    const driver = ProtocolDriver.attachToSession(sessionParams, multibrowser.modifier.bind(multibrowser), prototype, wrapCommand);
    /**
     * in order to get custom command overwritten or added to multiremote instance
     * we need to pass in the prototype of the multibrowser
     */
    if (!isStub(automationProtocol)) {
        const origAddCommand = driver.addCommand.bind(driver);
        driver.addCommand = (name, fn, attachToElement) => {
            return origAddCommand(name, fn, attachToElement, Object.getPrototypeOf(multibrowser.baseInstance), multibrowser.instances);
        };
        const origOverwriteCommand = driver.overwriteCommand.bind(driver);
        driver.overwriteCommand = (name, fn, attachToElement) => {
            return origOverwriteCommand(name, fn, attachToElement, Object.getPrototypeOf(multibrowser.baseInstance), multibrowser.instances);
        };
    }
    driver.addLocatorStrategy = addLocatorStrategyHandler(driver);
    return driver;
};