# GUI automation

The GUI automation API consist of a set of JavaScript functions which enables programmatic access to some features normally controlled by a user in the GUI. These functions are grouped in a global `window.Exivity` object.

## `session`

Control the current user session.

### `.login`

`function(string username, string password): void`\
Attempts to login given the username and password.

### `.logout`

`function(): void`\
Logs out the current user, and cleans up local storage used by the current session.

### `.refreshToken`

`function(string token): void`\
Attempts to use the given token to login (always refreshes the given token).

### `.apiRoot`

`function(string root): void`\
Set the domain (e.g. `https://example.com:8002`) for the Exivity API.

## `navigate`

Navigate the GUI.

### `.home`

`function(): void`\
Navigate to the root URL of the Exivity instance, which is the Dashboard if a user is currently logged in, or the login page otherwise.

### `.to`

`function(string path): void`\
Navigates to the given URL fragment.

## `report`

Control the report filters and more.

### `.byId`

`function(int id): void`\
Select a report definition.

### `.depth`

`function(int depth): void`\
Select a reporting depth.

### `.daterangeStart`

`function(string start): void`\
Select a the reporting start date, in *YYYYMMDD* format.

### `.daterangeEnd`

`function(string end): void`\
Select a the reporting end date, in *YYYYMMDD* format.

### `.filterAccount`

`function(int id): void`\
Filter the report by showing only this account.

### `.showSingleAccount`

`function(bool show = true): void`\
On the summary report, show only the single account set with [`filterAccount`](#filteraccount).

### `.showAllSummaries`

`function(bool show = true): void`\
Show all summaries if on the `/reports/summary` page.

### `.showConsolidatedSummaries`

`function(bool show = true): void`\
Show consolidated summary on the `/reports/summary` page.

### `.showSummaryAccounts`

`function(bool show = true): void`\
Show accounts on summary report.

### `.showSummaryServices`

`function(bool show = true): void`\
Show services on summary report.

### `.showSummaryInstances`

`function(bool show = true): void`\
Show instances on summary report.

### `.summaryGroupInstanceBy`

`function(string key): void`\
Group the instances on the summary report by this key. The `key` argument should be one of: `instances`, `services`.

## `wait`

Functions returning a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) to make it easier to determine the state of the GUI.

### `.ms`

`function(int|float ms): Promise`\
Wait for *ms* and then resolve the returned promise.

### `.networkIdle`

`function(int waitBefore = 100, int waitAfter = 100, int timeout = 60000): Promise`\
Wait for the network stack to become idle, optionally specifying:

* A timeout before starting to detect network traffic
* A timeout after detecting that the network became idle
* A timeout after which the promise will reject. Set to `0` to disable.

### `.syncComplete`

`function(): Promise`\
Wait for data synchronisation to complete.