API.md

Functions

async bringWindowToFront(windowDescriptor)

Brings the browser window on top of all other windows.

async close(windowDescriptor)

Closes the browser window where the specified web page is opened.

async findWindow(pageTitle) ⇒ object

Retrieves a platform-specific window descriptor for the window that contains a web page with the specified title.

async generateThumbnail(sourcePath, thumbnailPath, width, height)

Creates a thumbnail image from the specified PNG image file.

async getBrowserInfo(browser) ⇒ BrowserInfo

Returns information about the specified browser.

getDevicesViewportData() ⇒ ViewportData

Gets the name and the viewport size of all devices from this table.

async getInstallations() ⇒ Object.<string, BrowserInfo>

Returns the list of the BrowserInfo objects that contain information about the browsers installed on the machine.

getViewportSize(deviceName) ⇒ DeviceViewportSize

Gets the viewport size for the specified device.

async isMaximized(windowDescriptor) ⇒ boolean

Checks if the specified browser window is maximized.

isValidDeviceName(inputString) ⇒ boolean

Checks if the provided string is a valid device name contained in the screen size database.

async maximize(windowDescriptor)

Maximizes the specified browser window.

async open(browserInfo, pageUrl)

Opens the web page in a new instance of the browser.

async resize(windowDescriptor, currentWidth, currentHeight, width, height)

Changes the browser's client area size to the new width and height.

async screenshot(windowDescriptor, screenshotPath)

Takes a screenshot of the browser window where the specified web page is opened.

watchWindow(windowDescriptor, [watchingInterval]) ⇒

Pause execution of a Promise chain while the specified browser window is opened.

Typedefs

BrowserInfo : Object

Object that contains information about the browser installed on the machine.

DeviceViewportSize : Object

Defines the size of a device viewport.

async bringWindowToFront(windowDescriptor)

Brings the browser window on top of all other windows.

Kind: global async function

Param	Type	Description
windowDescriptor	string | object	The title of the web page opened in the window or a descriptor returned by findWindow.

async close(windowDescriptor)

Closes the browser window where the specified web page is opened.

Kind: global async function

Param	Type	Description
windowDescriptor	string | object	The title of the web page opened in the window or a descriptor returned by findWindow.

async findWindow(pageTitle) ⇒ object

Retrieves a platform-specific window descriptor for the window that contains a web page with the specified title.

Kind: global async function
Returns: object - a platform-specific window descriptor that can be used as a window identifier.

Param	Type	Description
pageTitle	string	The title of the web page opened in a window whose descriptor should be retrieved.

async generateThumbnail(sourcePath, thumbnailPath, width, height)

Creates a thumbnail image from the specified PNG image file.

Kind: global async function

Param	Type	Description
sourcePath	string	Specifies the path to the source image in PNG format.
thumbnailPath	string	Specifies the path to the resulting thumbnail image. Defaults to '/thumbnails/'
width	number	Specifies the width of the thumbnail image, in pixels (default is 240).
height	number	Specifies the height of the thumbnail image, in pixels (default is 130).

async getBrowserInfo(browser) ⇒ BrowserInfo

Returns information about the specified browser.

Kind: global async function
Returns: BrowserInfo - An object that contains information about the specified browser.

Param	Type	Description
browser	string	A browser alias ('chrome', 'firefox', etc.) or a path to the browser's executable file.

getDevicesViewportData() ⇒ ViewportData

Gets the name and the viewport size of all devices from this table.

Kind: global function
Returns: ViewportData - A JSON Object that contains device names and viewport sizes.

async getInstallations() ⇒ Object.<string, BrowserInfo>

Returns the list of the BrowserInfo objects that contain information about the browsers installed on the machine.

Kind: global async function
Returns: Object.<string, BrowserInfo> - List of the BrowserInfo objects containing information about the browsers installed on the machine.
Example

{
  chrome: {
      path: 'C:\\ProgramFiles\\...\\chrome.exe',
      cmd: '--new-window',
      macOpenCmdTemplate: 'open -n -a "{{{path}}}" --args {{{pageUrl}}} {{{cmd}}}'
  },

  firefox: {
      path: 'C:\\ProgramFiles\\...\\firefox.exe',
      cmd: '-new-window',
      macOpenCmdTemplate: 'open -a "{{{path}}}" {{{pageUrl}}} --args {{{cmd}}}'
  }
}

getViewportSize(deviceName) ⇒ DeviceViewportSize

Gets the viewport size for the specified device.

Kind: global function
Returns: DeviceViewportSize - The size of the device viewport.

Param	Type	Description
deviceName	string	Specifies the name of the target device. Use values from the Device Name column of this table.

async isMaximized(windowDescriptor) ⇒ boolean

Checks if the specified browser window is maximized.

Kind: global async function
Returns: boolean - true if the browser window is maximized

Param	Type	Description
windowDescriptor	string | object	The title of the web page opened in the window or a descriptor returned by findWindow.

isValidDeviceName(inputString) ⇒ boolean

Checks if the provided string is a valid device name contained in the screen size database.

Kind: global function
Returns: boolean - true if the specified string is a valid device name.

Param	Type	Description
inputString	string	The string to be validated.

async maximize(windowDescriptor)

Maximizes the specified browser window.

Kind: global async function

Param	Type	Description
windowDescriptor	string | object	The title of the web page opened in the window or a descriptor returned by findWindow.

async open(browserInfo, pageUrl)

Opens the web page in a new instance of the browser.

Kind: global async function

Param	Type	Description
browserInfo	BrowserInfo	Provides information on the browser where the web page should be opened.
pageUrl	string	Specifies the web page URL.

async resize(windowDescriptor, currentWidth, currentHeight, width, height)

Changes the browser's client area size to the new width and height.

Kind: global async function

Param	Type	Description
windowDescriptor	string | object	Specifies the title of the web page opened in the window or a descriptor returned by findWindow.
currentWidth	number	Specifies the current width of the browser's client area, in pixels. Use the window.innerWidth property to determine it.
currentHeight	number	Specifies the current height of the browser's client area, in pixels. Use the window.innerHeight property to determine it.
width	number	Specifies the new client area width, in pixels.
height	number	Specifies the new client area height, in pixels.

async screenshot(windowDescriptor, screenshotPath)

Takes a screenshot of the browser window where the specified web page is opened.

Kind: global async function

Param	Type	Description
windowDescriptor	string | object	Specifies the title of the web page opened in the window or a descriptor returned by findWindow.
screenshotPath	string	Specifies the full path to the screenshot file. For example, D:\Temp\chrome-screenshot.jpg.

watchWindow(windowDescriptor, [watchingInterval]) ⇒

Pause execution of a Promise chain while the specified browser window is opened.

Kind: global function
Returns: Promise A Promise which resolves when the browser window is closed.

Param	Type	Default	Description
windowDescriptor	string | object		The title of the web page opened in the window or a descriptor returned by findWindow
[watchingInterval]	number	2000	A time interval in milliseconds between checking the window state

BrowserInfo : Object

Object that contains information about the browser installed on the machine.

Kind: global typedef
Properties

Name	Type	Description
path	string | undefined	The path to the executable file that starts the browser. Required on MacOS machines. On Windows machines, it is used when the winOpenCmdTemplate property is undefined.
cmd	string	Additional command line parameters.
macOpenCmdTemplate	string	A Mustache template that provides parameters for launching the browser on a MacOS machine.
winOpenCmdTemplate	string | undefined	A Mustache template that provides parameters for launching the browser on a Windows machine. If undefined, the path to the executable file specified by the path property is used.

Example

{
      path: 'C:\\ProgramFiles\\...\\firefox.exe',
      cmd: '-new-window',
      macOpenCmdTemplate: 'open -a "{{{path}}}" {{{pageUrl}}} --args {{{cmd}}}'
 }

DeviceViewportSize : Object

Defines the size of a device viewport.

Kind: global typedef
Properties

Name	Type	Description
portraitWidth	number	The viewport width in portrait orientation.
landscapeWidth	number	The viewport width in landscape orientation.