leadfoot/Command.js

Leadfoot. A JavaScript client library that brings cross-platform consistency to the Selenium WebDriver API.

/**
 * @module leadfoot/Command
 */

var Element = require('./Element');
var Promise = require('dojo/Promise');
var strategies = require('./lib/strategies');
var Session = require('./Session');
var util = require('./lib/util');

/**
 * Creates a function that, when called, creates a new Command that retrieves elements from the parent context and
 * uses them as the context for the newly created Command.
 *
 * @private
 * @param {string} method
 * @returns {Function}
 */
function createElementMethod(method) {
	return function () {
		var args = arguments;

		return new this.constructor(this, function (setContext) {
			var parentContext = this._context;
			var promise;

			if (parentContext.length && parentContext.isSingle) {
				promise = parentContext[0][method].apply(parentContext[0], args);
			}
			else if (parentContext.length) {
				promise = Promise.all(parentContext.map(function (element) {
					return element[method].apply(element, args);
				})).then(function (elements) {
					// findAll against an array context will result in arrays of arrays; flatten into a single
					// array of elements. It would also be possible to resort in document order but other parallel
					// operations could not be sorted so we just don't do it anywhere and say not to rely in
					// a particular return order for results
					return Array.prototype.concat.apply([], elements);
				});
			}
			else {
				promise = this.session[method].apply(this.session, args);
			}

			return promise.then(function (newContext) {
				setContext(newContext);
				return newContext;
			});
		});
	};
}

var TOP_CONTEXT = [];
TOP_CONTEXT.isSingle = true;
TOP_CONTEXT.depth = 0;

/**
 * The Command class is a chainable, subclassable object type that can be used to execute commands serially against a
 * remote WebDriver environment. The standard Command class includes methods from the {@link module:leadfoot/Session}
 * and {@link module:leadfoot/Element} classes, so you can perform all standard session and element operations that
 * come with Leadfoot without being forced to author long promise chains.
 *
 * ***Important*: Due to a documentation tool limitation, the documentation on this page currently lists return values
 * of all methods as being of type `Promise`. All command methods actually return a new object of type `Command`. This
 * issue will be addressed in future versions of the documentation.**
 *
 * In order to use the Command class, you first need to pass it a {@link module:leadfoot/Session} instance for it to
 * use:
 *
 * ```js
 * var command = new Command(session);
 * ```
 *
 * Once you have created the Command, you can then start chaining methods, and they will execute in order one after
 * another:
 *
 * ```js
 * command.get('http://example.com')
 *   .findByTagName('h1')
 *   .getVisibleText()
 *   .then(function (text) {
 *       assert.strictEqual(text, 'Example Domain');
 *   });
 * ```
 *
 * Because these operations are asynchronous, you need to use a `then` callback in order to retrieve the value from the
 * last method. Command objects are Thenables, which means that they can be used with any Promises/A+ or ES6-confirmant
 * Promises implementation, though there are some specific differences in the arguments and context that are provided
 * to callbacks; see {@link module:leadfoot/Command#then} for more details.
 *
 * ---
 *
 * Each call on a Command generates a new Command object, which means that certain operations can be parallelised:
 *
 * ```js
 * command = command.get('http://example.com');
 * Promise.all([
 *   command.getPageTitle(),
 *   command.findByTagName('h1').getVisibleText()
 * ]).then(function (results) {
 *   assert.strictEqual(results[0], results[1]);
 * });
 * ```
 *
 * In this example, the commands on line 3 and 4 both depend upon the `get` call completing successfully but are
 * otherwise independent of each other and so execute here in parallel. This is different from commands in Intern 1
 * which were always chained onto the last called method within a given test.
 *
 * ---
 *
 * Command objects actually encapsulate two different types of interaction: *session* interactions, which operate
 * against the entire browser session, and *element* interactions, which operate against specific elements taken from
 * the currently loaded page. Things like navigating the browser, moving the mouse cursor, and executing scripts are
 * session interactions; things like getting text displayed on the page, typing into form fields, and getting element
 * attributes are element interactions.
 *
 * Session interactions can be performed at any time, from any Command. On the other hand, to perform element
 * interactions, you first need to retrieve one or more elements to interact with. This can be done using any of the
 * `find` or `findAll` methods, by the `getActiveElement` method, or by returning elements from `execute` or
 * `executeAsync` calls. The retrieved elements are stored internally as the *element context* of all chained
 * Commands. When an element method is called on a chained Command with a single element context, the result will be
 * returned as-is:
 *
 * ```js
 * command = command.get('http://example.com')
 *   // finds one element -> single element context
 *   .findByTagName('h1')
 *   .getVisibleText()
 *   .then(function (text) {
 *     // `text` is the text from the element context
 *     assert.strictEqual(text, 'Example Domain');
 *   });
 * ```
 *
 * When an element method is called on a chained Command with a multiple element context, the result will be returned
 * as an array:
 *
 * ```js
 * command = command.get('http://example.com')
 *   // finds multiple elements -> multiple element context
 *   .findAllByTagName('p')
 *   .getVisibleText()
 *   .then(function (texts) {
 *     // `texts` is an array of text from each of the `p` elements
 *     assert.deepEqual(texts, [
 *       'This domain is established to be used for […]',
 *       'More information...'
 *     ]);
 *   });
 * ```
 *
 * The `find` and `findAll` methods are special and change their behaviour based on the current element filtering state
 * of a given command. If a command has been filtered by element, the `find` and `findAll` commands will only find
 * elements *within* the currently filtered set of elements. Otherwise, they will find elements throughout the page.
 *
 * Some method names, like `click`, are identical for both Session and Element APIs; in this case, the element APIs
 * are suffixed with the word `Element` in order to identify them uniquely.
 *
 * ---
 *
 * Commands can be subclassed in order to add additional functionality without making direct modifications to the
 * default Command prototype that might break other parts of the system:
 *
 * ```js
 * function CustomCommand() {
 *   Command.apply(this, arguments);
 * }
 * CustomCommand.prototype = Object.create(Command.prototype);
 * CustomCommand.prototype.constructor = CustomCommand;
 * CustomCommand.prototype.login = function (username, password) {
 *   return new this.constructor(this, function () {
 *     return this.parent
 *       .findById('username')
 *         .click()
 *         .type(username)
 *         .end()
 *       .findById('password')
 *         .click()
 *         .type(password)
 *         .end()
 *       .findById('login')
 *         .click()
 *         .end();
 *   });
 * };
 * ```
 *
 * Note that returning `this`, or a command chain starting from `this`, from a callback or command initialiser will
 * deadlock the Command, as it waits for itself to settle before settling.
 *
 * @constructor module:leadfoot/Command
 * @param {module:leadfoot/Command|module:leadfoot/Session} parent
 * The parent command that this command is chained to, or a {@link module:leadfoot/Session} object if this is the
 * first command in a command chain.
 *
 * @param {function(setContext:Function, value:any): (any|Promise)} initialiser
 * A function that will be executed when all parent commands have completed execution. This function can create a
 * new context for this command by calling the passed `setContext` function any time prior to resolving the Promise
 * that it returns. If no context is explicitly provided, the context from the parent command will be used.
 *
 * @param {(function(setContext:Function, error:Error): (any|Promise))=} errback
 * A function that will be executed if any parent commands failed to complete successfully. This function can create
 * a new context for the current command by calling the passed `setContext` function any time prior to resolving the
 * Promise that it returns. If no context is explicitly provided, the context from the parent command will be used.
 *
 * @borrows module:leadfoot/Session#getTimeout as module:leadfoot/Command#getTimeout
 * @borrows module:leadfoot/Session#setTimeout as module:leadfoot/Command#setTimeout
 * @borrows module:leadfoot/Session#getCurrentWindowHandle as module:leadfoot/Command#getCurrentWindowHandle
 * @borrows module:leadfoot/Session#getAllWindowHandles as module:leadfoot/Command#getAllWindowHandles
 * @borrows module:leadfoot/Session#getCurrentUrl as module:leadfoot/Command#getCurrentUrl
 * @borrows module:leadfoot/Session#get as module:leadfoot/Command#get
 * @borrows module:leadfoot/Session#goForward as module:leadfoot/Command#goForward
 * @borrows module:leadfoot/Session#goBack as module:leadfoot/Command#goBack
 * @borrows module:leadfoot/Session#refresh as module:leadfoot/Command#refresh
 * @borrows module:leadfoot/Session#execute as module:leadfoot/Command#execute
 * @borrows module:leadfoot/Session#executeAsync as module:leadfoot/Command#executeAsync
 * @borrows module:leadfoot/Session#takeScreenshot as module:leadfoot/Command#takeScreenshot
 * @borrows module:leadfoot/Session#getAvailableImeEngines as module:leadfoot/Command#getAvailableImeEngines
 * @borrows module:leadfoot/Session#getActiveImeEngine as module:leadfoot/Command#getActiveImeEngine
 * @borrows module:leadfoot/Session#isImeActivated as module:leadfoot/Command#isImeActivated
 * @borrows module:leadfoot/Session#deactivateIme as module:leadfoot/Command#deactivateIme
 * @borrows module:leadfoot/Session#activateIme as module:leadfoot/Command#activateIme
 * @borrows module:leadfoot/Session#switchToFrame as module:leadfoot/Command#switchToFrame
 * @borrows module:leadfoot/Session#switchToWindow as module:leadfoot/Command#switchToWindow
 * @borrows module:leadfoot/Session#switchToParentFrame as module:leadfoot/Command#switchToParentFrame
 * @borrows module:leadfoot/Session#closeCurrentWindow as module:leadfoot/Command#closeCurrentWindow
 * @borrows module:leadfoot/Session#setWindowSize as module:leadfoot/Command#setWindowSize
 * @borrows module:leadfoot/Session#getWindowSize as module:leadfoot/Command#getWindowSize
 * @borrows module:leadfoot/Session#setWindowPosition as module:leadfoot/Command#setWindowPosition
 * @borrows module:leadfoot/Session#getWindowPosition as module:leadfoot/Command#getWindowPosition
 * @borrows module:leadfoot/Session#maximizeWindow as module:leadfoot/Command#maximizeWindow
 * @borrows module:leadfoot/Session#getCookies as module:leadfoot/Command#getCookies
 * @borrows module:leadfoot/Session#setCookie as module:leadfoot/Command#setCookie
 * @borrows module:leadfoot/Session#clearCookies as module:leadfoot/Command#clearCookies
 * @borrows module:leadfoot/Session#deleteCookie as module:leadfoot/Command#deleteCookie
 * @borrows module:leadfoot/Session#getPageSource as module:leadfoot/Command#getPageSource
 * @borrows module:leadfoot/Session#getPageTitle as module:leadfoot/Command#getPageTitle
 * @borrows module:leadfoot/Session#find as module:leadfoot/Command#find
 * @borrows module:leadfoot/Session#findAll as module:leadfoot/Command#findAll
 * @borrows module:leadfoot/Session#getActiveElement as module:leadfoot/Command#getActiveElement
 * @borrows module:leadfoot/Session#pressKeys as module:leadfoot/Command#pressKeys
 * @borrows module:leadfoot/Session#getOrientation as module:leadfoot/Command#getOrientation
 * @borrows module:leadfoot/Session#setOrientation as module:leadfoot/Command#setOrientation
 * @borrows module:leadfoot/Session#getAlertText as module:leadfoot/Command#getAlertText
 * @borrows module:leadfoot/Session#typeInPrompt as module:leadfoot/Command#typeInPrompt
 * @borrows module:leadfoot/Session#acceptAlert as module:leadfoot/Command#acceptAlert
 * @borrows module:leadfoot/Session#dismissAlert as module:leadfoot/Command#dismissAlert
 * @borrows module:leadfoot/Session#moveMouseTo as module:leadfoot/Command#moveMouseTo
 * @borrows module:leadfoot/Session#clickMouseButton as module:leadfoot/Command#clickMouseButton
 * @borrows module:leadfoot/Session#pressMouseButton as module:leadfoot/Command#pressMouseButton
 * @borrows module:leadfoot/Session#releaseMouseButton as module:leadfoot/Command#releaseMouseButton
 * @borrows module:leadfoot/Session#doubleClick as module:leadfoot/Command#doubleClick
 * @borrows module:leadfoot/Session#tap as module:leadfoot/Command#tap
 * @borrows module:leadfoot/Session#pressFinger as module:leadfoot/Command#pressFinger
 * @borrows module:leadfoot/Session#releaseFinger as module:leadfoot/Command#releaseFinger
 * @borrows module:leadfoot/Session#moveFinger as module:leadfoot/Command#moveFinger
 * @borrows module:leadfoot/Session#touchScroll as module:leadfoot/Command#touchScroll
 * @borrows module:leadfoot/Session#doubleTap as module:leadfoot/Command#doubleTap
 * @borrows module:leadfoot/Session#longTap as module:leadfoot/Command#longTap
 * @borrows module:leadfoot/Session#flickFinger as module:leadfoot/Command#flickFinger
 * @borrows module:leadfoot/Session#getGeolocation as module:leadfoot/Command#getGeolocation
 * @borrows module:leadfoot/Session#setGeolocation as module:leadfoot/Command#setGeolocation
 * @borrows module:leadfoot/Session#getLogsFor as module:leadfoot/Command#getLogsFor
 * @borrows module:leadfoot/Session#getAvailableLogTypes as module:leadfoot/Command#getAvailableLogTypes
 * @borrows module:leadfoot/Session#getApplicationCacheStatus as module:leadfoot/Command#getApplicationCacheStatus
 * @borrows module:leadfoot/Session#quit as module:leadfoot/Command#quit
 * @borrows module:leadfoot/Session#getLocalStorageKeys as module:leadfoot/Command#getLocalStorageKeys
 * @borrows module:leadfoot/Session#setLocalStorageItem as module:leadfoot/Command#setLocalStorageItem
 * @borrows module:leadfoot/Session#clearLocalStorage as module:leadfoot/Command#clearLocalStorage
 * @borrows module:leadfoot/Session#getLocalStorageItem as module:leadfoot/Command#getLocalStorageItem
 * @borrows module:leadfoot/Session#deleteLocalStorageItem as module:leadfoot/Command#deleteLocalStorageItem
 * @borrows module:leadfoot/Session#getLocalStorageLength as module:leadfoot/Command#getLocalStorageLength
 * @borrows module:leadfoot/Session#getSessionStorageKeys as module:leadfoot/Command#getSessionStorageKeys
 * @borrows module:leadfoot/Session#setSessionStorageItem as module:leadfoot/Command#setSessionStorageItem
 * @borrows module:leadfoot/Session#clearSessionStorage as module:leadfoot/Command#clearSessionStorage
 * @borrows module:leadfoot/Session#getSessionStorageItem as module:leadfoot/Command#getSessionStorageItem
 * @borrows module:leadfoot/Session#deleteSessionStorageItem as module:leadfoot/Command#deleteSessionStorageItem
 * @borrows module:leadfoot/Session#getSessionStorageLength as module:leadfoot/Command#getSessionStorageLength
 * @borrows module:leadfoot/Session#findByClassName as module:leadfoot/Command#findByClassName
 * @borrows module:leadfoot/Session#findByCssSelector as module:leadfoot/Command#findByCssSelector
 * @borrows module:leadfoot/Session#findById as module:leadfoot/Command#findById
 * @borrows module:leadfoot/Session#findByName as module:leadfoot/Command#findByName
 * @borrows module:leadfoot/Session#findByLinkText as module:leadfoot/Command#findByLinkText
 * @borrows module:leadfoot/Session#findByPartialLinkText as module:leadfoot/Command#findByPartialLinkText
 * @borrows module:leadfoot/Session#findByTagName as module:leadfoot/Command#findByTagName
 * @borrows module:leadfoot/Session#findByXpath as module:leadfoot/Command#findByXpath
 * @borrows module:leadfoot/Session#findAllByClassName as module:leadfoot/Command#findAllByClassName
 * @borrows module:leadfoot/Session#findAllByCssSelector as module:leadfoot/Command#findAllByCssSelector
 * @borrows module:leadfoot/Session#findAllByName as module:leadfoot/Command#findAllByName
 * @borrows module:leadfoot/Session#findAllByLinkText as module:leadfoot/Command#findAllByLinkText
 * @borrows module:leadfoot/Session#findAllByPartialLinkText as module:leadfoot/Command#findAllByPartialLinkText
 * @borrows module:leadfoot/Session#findAllByTagName as module:leadfoot/Command#findAllByTagName
 * @borrows module:leadfoot/Session#findAllByXpath as module:leadfoot/Command#findAllByXpath
 * @borrows module:leadfoot/Session#findDisplayed as module:leadfoot/Command#findDisplayed
 * @borrows module:leadfoot/Session#findDisplayedByClassName as module:leadfoot/Command#findDisplayedByClassName
 * @borrows module:leadfoot/Session#findDisplayedByCssSelector as module:leadfoot/Command#findDisplayedByCssSelector
 * @borrows module:leadfoot/Session#findDisplayedById as module:leadfoot/Command#findDisplayedById
 * @borrows module:leadfoot/Session#findDisplayedByName as module:leadfoot/Command#findDisplayedByName
 * @borrows module:leadfoot/Session#findDisplayedByLinkText as module:leadfoot/Command#findDisplayedByLinkText
 * @borrows module:leadfoot/Session#findDisplayedByPartialLinkText as module:leadfoot/Command#findDisplayedByPartialLinkText
 * @borrows module:leadfoot/Session#findDisplayedByTagName as module:leadfoot/Command#findDisplayedByTagName
 * @borrows module:leadfoot/Session#findDisplayedByXpath as module:leadfoot/Command#findDisplayedByXpath
 * @borrows module:leadfoot/Session#waitForDeletedByClassName as module:leadfoot/Command#waitForDeletedByClassName
 * @borrows module:leadfoot/Session#waitForDeletedByCssSelector as module:leadfoot/Command#waitForDeletedByCssSelector
 * @borrows module:leadfoot/Session#waitForDeletedById as module:leadfoot/Command#waitForDeletedById
 * @borrows module:leadfoot/Session#waitForDeletedByName as module:leadfoot/Command#waitForDeletedByName
 * @borrows module:leadfoot/Session#waitForDeletedByLinkText as module:leadfoot/Command#waitForDeletedByLinkText
 * @borrows module:leadfoot/Session#waitForDeletedByPartialLinkText as module:leadfoot/Command#waitForDeletedByPartialLinkText
 * @borrows module:leadfoot/Session#waitForDeletedByTagName as module:leadfoot/Command#waitForDeletedByTagName
 * @borrows module:leadfoot/Session#waitForDeletedByXpath as module:leadfoot/Command#waitForDeletedByXpath
 * @borrows module:leadfoot/Session#getExecuteAsyncTimeout as module:leadfoot/Command#getExecuteAsyncTimeout
 * @borrows module:leadfoot/Session#setExecuteAsyncTimeout as module:leadfoot/Command#setExecuteAsyncTimeout
 * @borrows module:leadfoot/Session#getFindTimeout as module:leadfoot/Command#getFindTimeout
 * @borrows module:leadfoot/Session#setFindTimeout as module:leadfoot/Command#setFindTimeout
 * @borrows module:leadfoot/Session#getPageLoadTimeout as module:leadfoot/Command#getPageLoadTimeout
 * @borrows module:leadfoot/Session#setPageLoadTimeout as module:leadfoot/Command#setPageLoadTimeout
 * @borrows module:leadfoot/Element#click as module:leadfoot/Command#click
 * @borrows module:leadfoot/Element#submit as module:leadfoot/Command#submit
 * @borrows module:leadfoot/Element#getVisibleText as module:leadfoot/Command#getVisibleText
 * @borrows module:leadfoot/Element#type as module:leadfoot/Command#type
 * @borrows module:leadfoot/Element#getTagName as module:leadfoot/Command#getTagName
 * @borrows module:leadfoot/Element#clearValue as module:leadfoot/Command#clearValue
 * @borrows module:leadfoot/Element#isSelected as module:leadfoot/Command#isSelected
 * @borrows module:leadfoot/Element#isEnabled as module:leadfoot/Command#isEnabled
 * @borrows module:leadfoot/Element#getSpecAttribute as module:leadfoot/Command#getSpecAttribute
 * @borrows module:leadfoot/Element#getAttribute as module:leadfoot/Command#getAttribute
 * @borrows module:leadfoot/Element#getProperty as module:leadfoot/Command#getProperty
 * @borrows module:leadfoot/Element#equals as module:leadfoot/Command#equals
 * @borrows module:leadfoot/Element#isDisplayed as module:leadfoot/Command#isDisplayed
 * @borrows module:leadfoot/Element#getPosition as module:leadfoot/Command#getPosition
 * @borrows module:leadfoot/Element#getSize as module:leadfoot/Command#getSize
 * @borrows module:leadfoot/Element#getComputedStyle as module:leadfoot/Command#getComputedStyle
 */
function Command(parent, initialiser, errback) {
	var self = this;
	var session;

	function setContext(context) {
		if (!Array.isArray(context)) {
			context = [ context ];
			context.isSingle = true;
		}

		// If the context being set has depth, then it is coming from `Command#end`,
		// or someone smart knows what they are doing; do not change the depth
		if (!('depth' in context)) {
			context.depth = parent ? parent.context.depth + 1 : 0;
		}

		self._context = context;
	}

	function fixStack(error) {
		error.stack = error.stack + util.trimStack(trace.stack);
		throw error;
	}

	if (parent && parent.session) {
		this._parent = parent;
		session = this._session = parent.session;
	}
	else if (parent && parent.sessionId) {
		session = this._session = parent;
		parent = null;
	}
	else {
		throw new Error('A parent Command or Session must be provided to a new Command');
	}

	// Add any custom functions from the session to this command object so they can be accessed automatically
	// using the fluid interfaces
	// TODO: Test
	for (var key in session) {
		if (session[key] !== Session.prototype[key]) {
			Command.addSessionMethod(this, key, session[key]);
		}
	}

	var trace = {};
	Error.captureStackTrace(trace, Command);

	this._promise = (parent ? parent.promise : Promise.resolve(undefined)).then(function (returnValue) {
		self._context = parent ? parent.context : TOP_CONTEXT;
		return returnValue;
	}, function (error) {
		self._context = parent ? parent.context : TOP_CONTEXT;
		throw error;
	}).then(
		initialiser && function (returnValue) {
			return Promise.resolve(returnValue)
				.then(initialiser.bind(self, setContext))
				.catch(fixStack);
		},
		errback && function (error) {
			return Promise.reject(error)
				.catch(errback.bind(self, setContext))
				.catch(fixStack);
		}
	);
}

/**
 * @lends module:leadfoot/Command#
 */
Command.prototype = {
	constructor: Command,

	/**
	 * The parent Command of the Command, if one exists.
	 *
	 * @member {module:leadfoot/Command=} parent
	 * @memberOf module:leadfoot/Command#
	 * @readonly
	 */
	get parent() {
		return this._parent;
	},

	/**
	 * The parent Session of the Command.
	 *
	 * @member {module:leadfoot/Session} session
	 * @memberOf module:leadfoot/Command#
	 * @readonly
	 */
	get session() {
		return this._session;
	},

	/**
	 * The filtered elements that will be used if an element-specific method is invoked. Note that this property is not
	 * valid until the parent Command has been settled. The context array also has two additional properties:
	 *
	 * - isSingle (boolean): If true, the context will always contain a single element. This is used to differentiate
	 *   between methods that should still return scalar values (`find`) and methods that should return arrays of
	 *   values even if there is only one element in the context (`findAll`).
	 * - depth (number): The depth of the context within the command chain. This is used to prevent traversal into
	 *   higher filtering levels by {@link module:leadfoot/Command#end}.
	 *
	 * @member {module:leadfoot/Element[]} context
	 * @memberOf module:leadfoot/Command#
	 * @readonly
	 */
	get context() {
		return this._context;
	},

	/**
	 * The underlying Promise for the Command.
	 *
	 * @member {Promise.<any>} promise
	 * @memberOf module:leadfoot/Command#
	 * @readonly
	 */
	get promise() {
		return this._promise;
	},

	/**
	 * Pauses execution of the next command in the chain for `ms` milliseconds.
	 *
	 * @param {number} ms Time to delay, in milliseconds.
	 * @returns {module:leadfoot/Command.<void>}
	 */
	sleep: function (ms) {
		return new this.constructor(this, function () {
			return util.sleep(ms);
		});
	},

	/**
	 * Ends the most recent filtering operation in the current Command chain and returns the set of matched elements
	 * to the previous state. This is equivalent to the `jQuery#end` method.
	 *
	 * @example
	 * command
	 *   .findById('parent') // sets filter to #parent
	 *     .findByClassName('child') // sets filter to all .child inside #parent
	 *       .getVisibleText()
	 *       .then(function (visibleTexts) {
	 *         // all the visible texts from the children
	 *       })
	 *       .end() // resets filter to #parent
	 *     .end(); // resets filter to nothing (the whole document)
	 *
	 * @param {number=} numCommandsToPop The number of element contexts to pop. Defaults to 1.
	 * @returns {module:leadfoot/Command.<void>}
	 */
	end: function (numCommandsToPop) {
		numCommandsToPop = numCommandsToPop || 1;

		return new this.constructor(this, function (setContext) {
			var command = this;
			var depth = this.context.depth;

			while (depth && numCommandsToPop && (command = command.parent)) {
				if (command.context.depth < depth) {
					--numCommandsToPop;
					depth = command.context.depth;
				}
			}

			setContext(command.context);
		});
	},

	/**
	 * Adds a callback to be invoked once the previously chained operation has completed.
	 *
	 * This method is compatible with the `Promise#then` API, with two important differences:
	 *
	 * 1. The context (`this`) of the callback is set to the Command object, rather than being `undefined`. This allows
	 *    promise helpers to be created that can retrieve the appropriate session and element contexts for execution.
	 * 2. A second non-standard `setContext` argument is passed to the callback. This `setContext` function can be
	 *    called at any time before the callback fulfills its return value and expects either a single
	 *    {@link module:leadfoot/Element} or an array of Elements to be provided as its only argument. The provided
	 *    element(s) will be used as the context for subsequent element method invocations (`click`, etc.). If
	 *    the `setContext` method is not called, the element context from the parent will be passed through unmodified.
	 *
	 * @param {Function=} callback
	 * @param {Function=} errback
	 * @returns {module:leadfoot/Command.<any>}
	 */
	then: function (callback, errback) {
		function runCallback(command, callback, value, setContext) {
			var returnValue = callback.call(command, value, setContext);

			// If someone returns `this` (or a chain starting from `this`) from the callback, it will cause a deadlock
			// where the child command is waiting for the child command to resolve
			if (returnValue instanceof command.constructor) {
				var maybeCommand = returnValue;
				do {
					if (maybeCommand === command) {
						throw new Error('Deadlock: do not use `return this` from a Command callback');
					}
				} while ((maybeCommand = maybeCommand.parent));
			}

			return returnValue;
		}

		return new this.constructor(this, callback && function (setContext, value) {
			return runCallback(this, callback, value, setContext);
		}, errback && function (setContext, value) {
			return runCallback(this, errback, value, setContext);
		});
	},

	/**
	 * Adds a callback to be invoked when any of the previously chained operations have failed.
	 *
	 * @param {Function} errback
	 * @returns {module:leadfoot/Command.<any>}
	 */
	catch: function (errback) {
		return this.then(null, errback);
	},

	/**
	 * Adds a callback to be invoked once the previously chained operations have resolved.
	 *
	 * @param {Function} callback
	 * @returns {module:leadfoot/Command.<any>}
	 */
	finally: function (callback) {
		return this.then(callback, callback);
	},

	/**
	 * Cancels all outstanding chained operations of the Command. Calling this method will cause this command and all
	 * subsequent chained commands to fail with a CancelError.
	 *
	 * @returns {module:leadfoot/Command.<void>}
	 */
	cancel: function () {
		this._promise.cancel.apply(this._promise, arguments);
		return this;
	},

	find: createElementMethod('find'),
	findAll: createElementMethod('findAll'),
	findDisplayed: createElementMethod('findDisplayed')
};

/**
 * Augments `target` with a conversion of the `originalFn` method that enables its use with a Command object.
 * This can be used to easily add new methods from any custom object that implements the Session API to any target
 * object that implements the Command API.
 *
 * Functions that are copied may have the following extra properties in order to change the way that Command works
 * with these functions:
 *
 * - `createsContext` (boolean): If this property is specified, the return value from the function will be used as
 *   the new context for the returned Command.
 * - `usesElement` (boolean): If this property is specified, element(s) from the current context will be used as
 *   the first argument to the function, if the explicitly specified first argument is not already an element.
 *
 * @memberOf module:leadfoot/Command
 * @param {module:leadfoot/Command} target
 * @param {string} key
 * @param {Function} originalFn
 */
Command.addSessionMethod = function (target, key, originalFn) {
	// Checking for private/non-functions here deduplicates this logic; otherwise it would need to exist in both
	// the Command constructor (for copying functions from sessions) as well as the Command factory below
	if (key.charAt(0) !== '_' && !target[key] && typeof originalFn === 'function') {
		target[key] = function () {
			var args = arguments;

			return new this.constructor(this, function (setContext) {
				var parentContext = this._context;
				var session = this._session;
				// The function may have come from a session object prototype but have been overridden on the actual
				// session instance; in such a case, the overridden function should be used instead of the one from
				// the original source object. The original source object may still be used, however, if the
				// function is being added like a mixin and does not exist on the actual session object for this
				// session
				var fn = session[key] || originalFn;

				if (fn.usesElement && parentContext.length && (!args[0] || !args[0].elementId)) {
					var promise;
					// Defer converting arguments into an array until it is necessary to avoid overhead
					args = Array.prototype.slice.call(args, 0);

					if (parentContext.isSingle) {
						promise = fn.apply(session, [ parentContext[0] ].concat(args));
					}
					else {
						promise = Promise.all(parentContext.map(function (element) {
							return fn.apply(session, [ element ].concat(args));
						}));
					}
				}
				else {
					promise = fn.apply(session, args);
				}

				if (fn.createsContext) {
					promise = promise.then(function (newContext) {
						setContext(newContext);
						return newContext;
					});
				}

				return promise;
			});
		};
	}
};

/**
 * Augments `target` with a method that will call `key` on all context elements stored within `target`.
 * This can be used to easily add new methods from any custom object that implements the Element API to any target
 * object that implements the Command API.
 *
 * Functions that are copied may have the following extra properties in order to change the way that Command works
 * with these functions:
 *
 * - `createsContext` (boolean): If this property is specified, the return value from the function will be used as
 *   the new context for the returned Command.
 *
 * @memberOf module:leadfoot/Command
 * @param {module:leadfoot/Command} target
 * @param {string} key
 */
Command.addElementMethod = function (target, key) {
	if (key.charAt(0) !== '_') {
		// some methods, like `click`, exist on both Session and Element; deduplicate these methods by appending the
		// element ones with 'Element'
		var targetKey = key + (target[key] ? 'Element' : '');
		target[targetKey] = function () {
			var args = arguments;

			return new this.constructor(this, function (setContext) {
				var parentContext = this._context;
				var promise;
				var fn = parentContext[0] && parentContext[0][key];

				if (parentContext.isSingle) {
					promise = fn.apply(parentContext[0], args);
				}
				else {
					promise = Promise.all(parentContext.map(function (element) {
						return element[key].apply(element, args);
					}));
				}

				if (fn && fn.createsContext) {
					promise = promise.then(function (newContext) {
						setContext(newContext);
						return newContext;
					});
				}

				return promise;
			});
		};
	}
};

// Element retrieval strategies must be applied directly to Command because it has its own custom
// find/findAll methods that operate based on the Command’s context, so can’t simply be delegated to the
// underlying session
strategies.applyTo(Command.prototype);

(function () {
	var key;
	for (key in Session.prototype) {
		Command.addSessionMethod(Command.prototype, key, Session.prototype[key]);
	}

	for (key in Element.prototype) {
		Command.addElementMethod(Command.prototype, key);
	}
})();

try {
	var chaiAsPromised = require('chai-as-promised');
}
catch (error) {}

// TODO: Add unit test
if (chaiAsPromised) {
	chaiAsPromised.transferPromiseness = function (assertion, promise) {
		assertion.then = promise.then.bind(promise);
		for (var method in promise) {
			if (typeof promise[method] === 'function') {
				assertion[method] = promise[method].bind(promise);
			}
		}
	};
}

module.exports = Command;