[ftr/services/browser] document methods exposed from the remote

test/functional/services/browser.js

@@ -23,14 +23,37 @@ export function BrowserProvider({ getService }) {
   const remote = getService('remote');
 
   return new class BrowserService {
+    /**
+     * Gets the dimensions of a window.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#getWindowSize
+     *
+     * @param  {string} windowHandle Optional - Omit this argument to query the currently focused window.
+     * @return {Promise<{width: number, height: number}>}
+     */
     async getWindowSize(...args) {
       return await remote.getWindowSize(...args);
     }
 
+
+    /**
+     * Sets the dimensions of a window.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#setWindowSize
+     *
+     * @param {string} windowHandle Optional
+     * @param {number} width
+     * @param {number} height
+     * @return {Promise<void>}
+     */
     async setWindowSize(...args) {
       await remote.setWindowSize(...args);
     }
 
+    /**
+     * Gets the URL that is loaded in the focused window/frame.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#getCurrentUrl
+     *
+     * @return {Promise<string>}
+     */
     async getCurrentUrl() {
       // strip _t=Date query param when url is read
       const current = await remote.getCurrentUrl();
@@ -40,6 +63,14 @@ export function BrowserProvider({ getService }) {
       return currentWithoutTime;
     }
 
+    /**
+     * Navigates the focused window/frame to a new URL.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#get
+     *
+     * @param {string} url
+     * @param {boolean} insertTimestamp Optional
+     * @return {Promise<void>}
+     */
     async get(url, insertTimestamp = true) {
       if (insertTimestamp) {
         const urlWithTime = modifyUrl(url, parsed => {
@@ -51,62 +82,169 @@ export function BrowserProvider({ getService }) {
       return await remote.get(url);
     }
 
+    /**
+     * Moves the remote environment’s mouse cursor to the specified element or relative
+     * position. If the element is outside of the viewport, the remote driver will attempt
+     * to scroll it into view automatically.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#moveMouseTo
+     *
+     * @param {Element} element Optional
+     * @param {number} xOffset Optional
+     * @param {number} yOffset Optional
+     * @return {Promise<void>}
+     */
     async moveMouseTo(...args) {
       await remote.moveMouseTo(...args);
     }
 
+    /**
+     * Reloads the current browser window/frame.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#refresh
+     *
+     * @return {Promise<void>}
+     */
     async refresh() {
       await remote.refresh();
     }
 
+    /**
+     * Navigates the focused window/frame back one page using the browser’s navigation history.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#goBack
+     *
+     * @return {Promise<void>}
+     */
     async goBack() {
       await remote.goBack();
     }
 
+    /**
+     * Types into the focused window/frame/element.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#pressKeys
+     *
+     * @param  {string|string[]} keys
+     * @return {Promise<void>}
+     */
     async pressKeys(...args) {
       await remote.pressKeys(...args);
     }
 
+    /**
+     * Clicks a mouse button at the point where the mouse cursor is currently positioned. This
+     * method may fail to execute with an error if the mouse has not been moved anywhere since
+     * the page was loaded.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#clickMouseButton
+     *
+     * @param {number} button Optional
+     * @return {Promise<void>}
+     */
     async clickMouseButton(...args) {
       await remote.clickMouseButton(...args);
     }
 
+    /**
+     * Depresses a mouse button without releasing it.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#pressMouseButton
+     *
+     * @param {number} button Optional
+     * @return {Promise<void>}
+     */
     async pressMouseButton(...args) {
       await remote.pressMouseButton(...args);
     }
 
+    /**
+     * Releases a previously depressed mouse button.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#releaseMouseButton
+     *
+     * @param {number} button Optional
+     * @return {Promise<void>}
+     */
     async releaseMouseButton(...args) {
       await remote.releaseMouseButton(...args);
     }
 
+    /**
+     * Gets the HTML loaded in the focused window/frame. This markup is serialised by the remote
+     * environment so may not exactly match the HTML provided by the Web server.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#getPageSource
+     *
+     * @return {Promise<string>}
+     */
     async getPageSource(...args) {
       return await remote.getPageSource(...args);
     }
 
+    /**
+     * Gets all logs from the remote environment of the given type. The logs in the remote
+     * environment are cleared once they have been retrieved.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#getLogsFor
+     *
+     * @param {string} type
+     * @return {Promise<LogEntry[]>}
+     */
     async getLogsFor(...args) {
       return await remote.getLogsFor(...args);
     }
 
+    /**
+     * Gets a screenshot of the focused window and returns it in PNG format.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#takeScreenshot
+     *
+     * @return {Promise<Buffer>}
+     */
     async takeScreenshot(...args) {
       await remote.takeScreenshot(...args);
     }
 
+    /**
+     * Double-clicks the primary mouse button.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#doubleClick
+     *
+     * @return {Promise<void>}
+     */
     async doubleClick(...args) {
       await remote.doubleClick(...args);
     }
 
+    /**
+     * Switches the currently focused window to a new window.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#switchToWindow
+     *
+     * @param {string} handle
+     * @return {Promise<void>}
+     */
     async switchToWindow(...args) {
       await remote.switchToWindow(...args);
     }
 
+    /**
+     * Gets a list of identifiers for all currently open windows.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#getAllWindowHandles
+     *
+     * @return {Promise<string[]>}
+     */
     async getAllWindowHandles(...args) {
       return await remote.getAllWindowHandles(...args);
     }
 
+    /**
+     * Closes the currently focused window. In most environments, after the window has been
+     * closed, it is necessary to explicitly switch to whatever window is now focused.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#closeCurrentWindow
+     *
+     * @return {Promise<void>}
+     */
     async closeCurrentWindow(...args) {
       await remote.closeCurrentWindow(...args);
     }
 
+    /**
+     * Executes JavaScript code within the focused window/frame. The code should return a value synchronously.
+     * https://theintern.io/leadfoot/module-leadfoot_Session.html#execute
+     *
+     * @param  {string|function} function
+     * @param  {...any[]} args
+     */
     async execute(...args) {
       return await remote.execute(...args);
     }