Documentation

Sandbox

Properties

Property	Modifier	Type	Default value
`display`	`public`	`string`	`':0'`
`stream`	`public`	`VNCServer`	`undefined`

Methods

doubleClick()

doubleClick(x?: number, y?: number): Promise<void>

Double left click on the mouse position.

Parameters

Parameter	Type
`x`?	`number`
`y`?	`number`

Returns

Promise<void>

drag()

drag(from: [number, number], to: [number, number]): Promise<void>

Drag the mouse from the given position to the given position.

Parameters

Parameter	Type	Description
`from`	[`number`, `number`]	The starting position.
`to`	[`number`, `number`]	The ending position.

Returns

Promise<void>

getApplicationWindows()

getApplicationWindows(application: string): Promise<string[]>

Get the window ID of the window with the given title.

Parameters

Parameter	Type
`application`	`string`

Returns

Promise<string[]> The ID of the window.

getCurrentWindowId()

getCurrentWindowId(): Promise<string>

Get the current window ID.

Returns

Promise<string> The ID of the current window.

getCursorPosition()

getCursorPosition(): Promise<CursorPosition>

Get the current cursor position.

Returns

Promise<CursorPosition> A object with the x and y coordinates

Throws

Error if cursor position cannot be determined

getScreenSize()

getScreenSize(): Promise<ScreenSize>

Get the current screen size.

Returns

Promise<ScreenSize> An ScreenSize object

Throws

Error if screen size cannot be determined

getWindowTitle()

getWindowTitle(windowId: string): Promise<string>

Get the title of the window with the given ID.

Parameters

Parameter	Type	Description
`windowId`	`string`	The ID of the window.

Returns

Promise<string> The title of the window.

launch()

launch(application: string, uri?: string): Promise<void>

Launch an application.

Parameters

Parameter	Type	Description
`application`	`string`	The application to launch.
`uri`?	`string`	The URI to open in the application.

Returns

Promise<void>

leftClick()

leftClick(x?: number, y?: number): Promise<void>

Left click on the mouse position.

Parameters

Parameter	Type
`x`?	`number`
`y`?	`number`

Returns

Promise<void>

middleClick()

middleClick(x?: number, y?: number): Promise<void>

Middle click on the mouse position.

Parameters

Parameter	Type
`x`?	`number`
`y`?	`number`

Returns

Promise<void>

mousePress()

mousePress(button: "left" | "right" | "middle"): Promise<void>

Press the mouse button.

Parameters

Parameter	Type	Default value
`button`	`"left"` \| `"right"` \| `"middle"`	`'left'`

Returns

Promise<void>

mouseRelease()

mouseRelease(button: "left" | "right" | "middle"): Promise<void>

Release the mouse button.

Parameters

Parameter	Type	Default value
`button`	`"left"` \| `"right"` \| `"middle"`	`'left'`

Returns

Promise<void>

moveMouse()

moveMouse(x: number, y: number): Promise<void>

Move the mouse to the given coordinates.

Parameters

Parameter	Type	Description
`x`	`number`	The x coordinate.
`y`	`number`	The y coordinate.

Returns

Promise<void>

open()

open(fileOrUrl: string): Promise<void>

Open a file or a URL in the default application.

Parameters

Parameter	Type	Description
`fileOrUrl`	`string`	The file or URL to open.

Returns

Promise<void>

press()

press(key: string | string[]): Promise<void>

Press a key.

Parameters

Parameter	Type	Description
`key`	`string` \| `string`[]	The key to press (e.g. “enter”, “space”, “backspace”, etc.). Can be a single key or an array of keys.

Returns

Promise<void>

rightClick()

rightClick(x?: number, y?: number): Promise<void>

Right click on the mouse position.

Parameters

Parameter	Type
`x`?	`number`
`y`?	`number`

Returns

Promise<void>

screenshot()

screenshot(): Promise<Uint8Array<ArrayBufferLike>>

Take a screenshot and save it to the given name.

Returns

Promise<Uint8Array<ArrayBufferLike>> A Uint8Array bytes representation of the screenshot.

screenshot(format)

screenshot(format: "bytes"): Promise<Uint8Array<ArrayBufferLike>>

Take a screenshot and save it to the given name.

Parameters

Parameter	Type	Description
`format`	`"bytes"`	The format of the screenshot.

Returns

Promise<Uint8Array<ArrayBufferLike>> A Uint8Array bytes representation of the screenshot.

screenshot(format)

screenshot(format: "blob"): Promise<Blob>

Take a screenshot and save it to the given name.

Parameters

Parameter	Type
`format`	`"blob"`

Returns

Promise<Blob> A Blob representation of the screenshot.

screenshot(format)

screenshot(format: "stream"): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>

Take a screenshot and save it to the given name.

Parameters

Parameter	Type
`format`	`"stream"`

Returns

Promise<ReadableStream<Uint8Array<ArrayBufferLike>>> A ReadableStream of bytes representation of the screenshot.

scroll()

scroll(direction: "down" | "up", amount: number): Promise<void>

Scroll the mouse wheel by the given amount.

Parameters

Parameter	Type	Default value	Description
`direction`	`"down"` \| `"up"`	`'down'`	The direction to scroll. Can be “up” or “down”.
`amount`	`number`	`1`	The amount to scroll.

Returns

Promise<void>

wait()

wait(ms: number): Promise<void>

Wait for the given amount of time.

Parameters

Parameter	Type	Description
`ms`	`number`	The amount of time to wait in milliseconds.

Returns

Promise<void>

waitAndVerify()

waitAndVerify(
   cmd: string, 
   onResult: (result: CommandResult) => boolean, 
   timeout: number, 
interval: number): Promise<boolean>

Wait for a command to return a specific result.

Parameters

Parameter	Type	Default value	Description
`cmd`	`string`	`undefined`	The command to run.
`onResult`	(`result`: `CommandResult`) => `boolean`	`undefined`	The function to check the result of the command.
`timeout`	`number`	`10`	The maximum time to wait for the command to return the result.
`interval`	`number`	`0.5`	The interval to wait between checks.

Returns

Promise<boolean> true if the command returned the result within the timeout, otherwise false.

write()

write(text: string, options: object): Promise<void>

Write the given text at the current cursor position.

Parameters

Parameter	Type	Description
`text`	`string`	The text to write.
`options`	`object`	An object containing the chunk size and delay between each chunk of text.
`options.chunkSize`	`number`	The size of each chunk of text to write. Default is 25 characters.
`options.delayInMs`	`number`	The delay between each chunk of text. Default is 75 ms.

Returns

Promise<void>

betaCreate()

betaCreate(this, opts)

static betaCreate<S>(this: S, opts?: SandboxBetaCreateOpts): Promise<InstanceType<S>>

Create a new sandbox from the default desktop sandbox template.

Type Parameters

Type Parameter
`S` extends typeof `Sandbox`

Parameters

Parameter	Type	Description
`this`	`S`	-
`opts`?	`SandboxBetaCreateOpts`	connection options.

Returns

Promise<InstanceType<S>> sandbox instance for the new sandbox.

Example

const sandbox = await Sandbox.create()

Constructs

Sandbox

betaCreate(this, template, opts)

static betaCreate<S>(
   this: S, 
   template: string, 
opts?: SandboxBetaCreateOpts): Promise<InstanceType<S>>

Create a new sandbox from the specified sandbox template.

Type Parameters

Type Parameter
`S` extends typeof `Sandbox`

Parameters

Parameter	Type	Description
`this`	`S`	-
`template`	`string`	sandbox template name or ID.
`opts`?	`SandboxBetaCreateOpts`	connection options.

Returns

Promise<InstanceType<S>> sandbox instance for the new sandbox.

Example

const sandbox = await Sandbox.create('<template-name-or-id>')

Constructs

Sandbox

create()

create(this, opts)

static create<S>(this: S, opts?: SandboxOpts): Promise<InstanceType<S>>

Create a new sandbox from the default desktop sandbox template.

Type Parameters

Type Parameter
`S` extends typeof `Sandbox`

Parameters

Parameter	Type	Description
`this`	`S`	-
`opts`?	`SandboxOpts`	connection options.

Returns

Promise<InstanceType<S>> sandbox instance for the new sandbox.

Example

const sandbox = await Sandbox.create()

Constructs

Sandbox

create(this, template, opts)

static create<S>(
   this: S, 
   template: string, 
opts?: SandboxOpts): Promise<InstanceType<S>>

Create a new sandbox from the specified sandbox template.

Type Parameters

Type Parameter
`S` extends typeof `Sandbox`

Parameters

Parameter	Type	Description
`this`	`S`	-
`template`	`string`	sandbox template name or ID.
`opts`?	`SandboxOpts`	connection options.

Returns

Promise<InstanceType<S>> sandbox instance for the new sandbox.

Example

const sandbox = await Sandbox.create('<template-name-or-id>')

Constructs

Sandbox

Interfaces

SandboxBetaCreateOpts

Configuration options for the Sandbox environment. SandboxOpts

Properties

display?

optional display: string;

Display identifier.

dpi?

optional dpi: number;

Dots per inch (DPI) setting for the display.

resolution?

optional resolution: [number, number];

The screen resolution in pixels, specified as [width, height].

SandboxOpts

Configuration options for the Sandbox environment. SandboxOpts

Properties

display?

optional display: string;

Display identifier.

dpi?

optional dpi: number;

Dots per inch (DPI) setting for the display.

resolution?

optional resolution: [number, number];

The screen resolution in pixels, specified as [width, height].

​Sandbox

​Properties

​Methods

​doubleClick()

Parameters

Returns

​drag()

Parameters

Returns

​getApplicationWindows()

Parameters

Returns

​getCurrentWindowId()

Returns

​getCursorPosition()

Returns

Throws

​getScreenSize()

Returns

Throws

​getWindowTitle()

Parameters

Returns

​launch()

Parameters

Returns

​leftClick()

Parameters

Returns

​middleClick()

Parameters

Returns

​mousePress()

Parameters

Returns

​mouseRelease()

Parameters

Returns

​moveMouse()

Parameters

Returns

​open()

Parameters

Returns

​press()

Parameters

Returns

​rightClick()

Parameters

Returns

​screenshot()

screenshot()

Returns

screenshot(format)

Parameters

Returns

screenshot(format)

Parameters

Returns

screenshot(format)

Parameters

Returns

​scroll()

Parameters

Returns

​wait()

Parameters

Returns

​waitAndVerify()

Parameters

Returns

​write()

Parameters

Returns

​betaCreate()

betaCreate(this, opts)

Type Parameters

Parameters

Returns

Example

Sandbox

Properties

Methods

doubleClick()

drag()

getApplicationWindows()

getCurrentWindowId()

getCursorPosition()

getScreenSize()

getWindowTitle()

launch()

leftClick()

middleClick()

mousePress()

mouseRelease()

moveMouse()

open()

press()

rightClick()

screenshot()

scroll()

wait()

waitAndVerify()

write()

betaCreate()

create()

Interfaces

SandboxBetaCreateOpts

Properties

display?

dpi?

resolution?

SandboxOpts

Properties

display?

dpi?

resolution?