# JavaScript API

Repeato allows you to execute JavaScript using **Script steps**. The following globals are available while a test or batch is running.

For machine-readable documentation, use the [raw Markdown reference](/documentation/javascript-api.md.txt) or the [TypeScript declarations](/repeato-script-api.d.ts). See [JavaScript recipes](/documentation/javascript-recipes/) for complete, executable examples.

## Globals

### `data`

**Type:** `object`

An object that you can use to share data between steps.

### `data.scannedText`

**Type:** `string`

The string scanned by the last executed **Check for text** step.

### `workspaceDir`

**Type:** `string`

The directory of the current workspace.

### `currentStepIndex`

**Type:** `number`

The zero-based index of the currently executing step.

### `testDir`

**Type:** `string`

The directory of the current test.

### `testRunDir`

**Type:** `string`

The directory of the current test run.

### `axios`

**Type:** `AxiosInstance`

The Axios HTTP client.

```js
const response = await axios.get('https://example.com')
```

### `log()`

```ts title="Signature"
log(message: object)
```

Logs a message or object.

### `sleep()`

```ts title="Signature"
sleep(milliseconds: number): Promise<void>
```

Delays execution for the given number of milliseconds.

### `getResponse()`

```ts title="Signature"
getResponse(host: string, path: string, headers?: object): Promise<string>
```

Sends a GET request to a host.

### `sendPost()`

```ts title="Signature"
sendPost(
  host: string,
  path: string,
  body: string | object,
  acceptHeader?: string,
  headers?: object,
): Promise<string>
```

Sends a POST request.

### `showDialog()`

```ts title="Signature"
showDialog({
  title,
  content,
  onConfirm,
  onClose,
}: {
  title: string
  content: string
  onConfirm?: () => void
  onClose?: () => void
}): { cancel: Function; confirm: Function }
```

Shows a dialog whose content supports Markdown, including formatted text, links, and images. The optional callbacks run when the corresponding action occurs. The returned dialog instance can be closed using `cancel()` or `confirm()`.

## `batchRunner`

Controls the current test batch and provides batch lifecycle hooks.

### `batchRunner.testBatch`

**Type:** `TestBatch`

The current batch of tests.

### `batchRunner.currentExceptionHandlerIndex`

**Type:** `number`

The index of the current exception handler.

### `batchRunner.currentTestIndex`

**Type:** `number`

The index of the current test.

### `batchRunner.batchRun`

**Type:** `BatchRun`

The current batch run. Use `log(batchRunner.batchRun)` to inspect all properties.

### `batchRunner.isPlaying`

**Type:** `boolean`

Indicates whether the batch runner is currently running.

### `batchRunner.runMode`

**Type:** `string`

The current run mode.

### `batchRunner.stop()`

```js
stop(): Promise<void>
```

Stops the batch runner.

### `batchRunner.createBatchRunExport()`

```ts title="Signature"
createBatchRunExport(): Promise<string>
```

Creates an export of the current batch run in the workspace's `batchRuns` folder and returns its path.

### `batchRunner.uploadReport()`

```ts title="Signature"
uploadReport(dirPath: string): Promise<string>
```

Uploads the report at `dirPath` to the Repeato cloud and returns the report URL.

### `batchRunner.setTestBatchById()`

```ts title="Signature"
batchRunner.setTestBatchById(batchId: string)
```

Sets the test batch for the batch runner.

### `batchRunner.setRunMode()`

```ts title="Signature"
batchRunner.setRunMode(mode: string)
```

Sets the run mode to all tests or failed tests only.

```js
batchRunner.setRunMode('AllTests')
batchRunner.setRunMode('OnlyFailed')
```

### `batchRunner.addOnBatchStart()`

```ts title="Signature"
batchRunner.addOnBatchStart(key: string, callback: (batch: Batch) => void)
```

Registers a callback that runs just before the batch starts.

### `batchRunner.addOnTestFail()`

```ts title="Signature"
batchRunner.addOnTestFail(
  key: string,
  callback: (test: Test, testRun: TestRun, stepResult: StepResult) => void,
)
```

Registers a callback that runs when a test fails.

### `batchRunner.addOnTestSuccess()`

```ts title="Signature"
batchRunner.addOnTestSuccess(
  key: string,
  callback: (test: Test, testRun: TestRun) => void,
)
```

Registers a callback that runs when a test succeeds.

### `batchRunner.addOnBatchCompleted()`

```ts title="Signature"
batchRunner.addOnBatchCompleted(
  key: string,
  callback: (batchRun: BatchRun) => void,
)
```

Registers a callback that runs when the batch completes, whether it succeeds or fails.

### `batchRunner.removeOnBatchStart()`

```ts title="Signature"
batchRunner.removeOnBatchStart(key: string)
```

Removes a callback registered with `addOnBatchStart()`.

### `batchRunner.removeOnTestFail()`

```ts title="Signature"
batchRunner.removeOnTestFail(key: string)
```

Removes a callback registered with `addOnTestFail()`.

### `batchRunner.removeOnTestSuccess()`

```ts title="Signature"
batchRunner.removeOnTestSuccess(key: string)
```

Removes a callback registered with `addOnTestSuccess()`.

### `batchRunner.removeOnBatchCompleted()`

```ts title="Signature"
batchRunner.removeOnBatchCompleted(key: string)
```

Removes a callback registered with `addOnBatchCompleted()`.

### `batchRunner.testRunner`

**Type:** `TestRunner`

Provides access to all `testRunner` properties and methods. Use `log(batchRunner.testRunner)` to inspect them.

## `testRunner`

Controls execution of the current test and exposes step lifecycle hooks.

### `testRunner.currentTest`

**Type:** `Test`

The current test. Use `log(testRunner.currentTest)` to inspect all properties.

### `testRunner.currentTestRun`

**Type:** `TestRun`

The current test run. Use `log(testRunner.currentTestRun)` to inspect all properties.

### `testRunner.lastStepResult`

**Type:** `StepResult`

The result of the previously executed step. Use `log(testRunner.lastStepResult)` to inspect all properties.

### `testRunner.currentStepIndex`

**Type:** `number`

The zero-based index of the current step.

### `testRunner.setNextStepId()`

```ts title="Signature"
testRunner.setNextStepId(id: string)
```

Sets the next step to execute by ID.

```js
testRunner.setNextStepId('AH23D6')
```

### `testRunner.setNextStepIndex()`

```ts title="Signature"
testRunner.setNextStepIndex(index: number)
```

Sets the next step to execute by its zero-based index.

### `testRunner.goBackBy()`

```ts title="Signature"
testRunner.goBackBy(stepCount: number)
```

Moves back by `stepCount` steps and continues execution from there.

### `testRunner.addOnScreenshotSaved()`

```ts title="Signature"
testRunner.addOnScreenshotSaved(
  key: string,
  listener: (stepResult: StepResult, screenshotPath: string) => void,
)
```

Registers a listener that runs as soon as a screenshot has been saved.

### `testRunner.addOnStepCompleted()`

```ts title="Signature"
testRunner.addOnStepCompleted(
  key: string,
  callback: (stepResult: StepResult) => void,
)
```

Registers a callback that runs whenever a step completes.

### `testRunner.removeOnScreenshotSaved()`

```ts title="Signature"
testRunner.removeOnScreenshotSaved(key: string)
```

Removes a listener registered with `addOnScreenshotSaved()`.

### `testRunner.removeOnStepCompleted()`

```ts title="Signature"
testRunner.removeOnStepCompleted(key: string)
```

Removes a callback registered with `addOnStepCompleted()`.

### `testRunner.setScaleInvariantMatchingEnabled()`

```ts title="Signature"
testRunner.setScaleInvariantMatchingEnabled(enabled: boolean)
```

Enables or disables scale-invariant matching. It is enabled by default.

## `deviceConnector`

Provides information about and sends commands to the currently connected device.

### `deviceConnector.selectedDeviceData`

**Type:** `DeviceData`

All data related to the currently connected device. Use `log(deviceConnector.selectedDeviceData)` to inspect it.

### `deviceConnector.sendString()`

```ts title="Signature"
sendString(value: string): Promise<void>
```

Sends a string to the device. The app under test must have a focused input field to receive the data.

### `deviceConnector.clearText()`

```js
clearText(): Promise<void>
```

Clears the currently selected input field.

### `deviceConnector.sendClick()`

```ts title="Signature"
sendClick(xPercentage: number, yPercentage: number): Promise<void>
```

Sends a touch event to the device. Coordinates range from `0` to `1`; `sendClick(0.5, 0.5)` taps the center of the screen.

### `deviceConnector.sendDown()`

```ts title="Signature"
sendDown(xPercentage: number, yPercentage: number): Promise<void>
```

Sends a touch-down event. Each `sendDown()` needs a `sendUp()`; combine it with `sendMove()` to simulate a drag gesture.

### `deviceConnector.sendMove()`

```ts title="Signature"
sendMove(xPercentage: number, yPercentage: number): Promise<void>
```

Sends a move event. Use `sendDown()` first and finish the drag with `sendUp()`.

### `deviceConnector.sendUp()`

```ts title="Signature"
sendUp(xPercentage: number, yPercentage: number): Promise<void>
```

Sends a touch-up event.

### `deviceConnector.sendAdbCommand()`

```ts title="Signature"
sendAdbCommand(command: string): Promise<string>
```

Sends an Android Debug Bridge (ADB) command.

### `deviceConnector.addOnDeviceLog()`

```ts title="Signature"
deviceConnector.addOnDeviceLog(
  listenerName: string,
  callback: (log: string) => void,
)
```

Registers a callback that runs for every log line sent by the app under test.

### `deviceConnector.sendIdbCommand()`

```ts title="Signature"
sendIdbCommand(command: string): Promise<string>
```

Sends an iOS Development Bridge (IDB) command.

```js
await deviceConnector.sendIdbCommand('list-targets')
```

### `deviceConnector.takeScreenshot()`

```ts title="Signature"
takeScreenshot(filepath: string): Promise<void>
```

Takes a screenshot and saves it at `filepath`.

### `deviceConnector.setClipboard()`

```ts title="Signature"
setClipboard(content: string): Promise<void>
```

Sets the device clipboard to a string.

### `deviceConnector.getClipboard()`

```js
getClipboard(): Promise<string>
```

Gets the device clipboard content.

### `deviceConnector.vision()`

```ts title="Signature"
vision(
  prompt: string,
  region: { x: number; y: number; width: number; height: number } | undefined,
): Promise<string>
```

Sends a prompt and a screenshot of the current device screen to the vision module. Pass a region to limit the screenshot to part of the screen.

## `audioTools`

Provides text-to-speech, audio playback, and audio recording.

### `audioTools.say()`

```ts title="Signature"
audioTools.say(text: string)
```

Turns the given text into audio.

### `audioTools.playAudio()`

```ts title="Signature"
playAudio(url: string): Promise<number>
```

Plays audio from the given URL.

### `audioTools.stopAudio()`

```js
audioTools.stopAudio()
```

Stops the currently playing audio.

### `audioTools.recordAudio()`

```ts title="Signature"
recordAudio(duration: number): Promise<string>
```

Records audio for the given duration in milliseconds and returns the URL of the temporary recording.