chrome

An actor that manages an instance of the chrome browser via an erlang port. The browser is started to allow remote debugging via pipes, once the pipe is disconnected, chrome should quit automatically.

All messages to the browser are sent through this actor to the port, and responses are returned to the sender. The actor manages associating responses with the correct request by adding auto-incrementing ids to the requests, so callers don’t need to worry about this.

When the browser managed by this actor is closed, the actor will also exit.

To start a browser, it’s preferrable to use the launch functions from the root chrobot module, which perform additional checks and validations.

Types

BrowserConfig

</>

pub type BrowserConfig {
  BrowserConfig(
    path: String,
    args: List(String),
    start_timeout: Int,
    log_level: LogLevel,
  )
}

Constructors

BrowserConfig(
  path: String,
  args: List(String),
  start_timeout: Int,
  log_level: LogLevel,
)

BrowserInstance

</>

pub type BrowserInstance {
  BrowserInstance(port: Port)
}

Constructors

```
BrowserInstance(port: Port)
```

BrowserVersion

</>

pub type BrowserVersion {
  BrowserVersion(
    protocol_version: String,
    product: String,
    revision: String,
    user_agent: String,
    js_version: String,
  )
}

Constructors

BrowserVersion(
  protocol_version: String,
  product: String,
  revision: String,
  user_agent: String,
  js_version: String,
)

LaunchError

</>

Errors that may occur during launch of the browser instance

pub type LaunchError {
  UnknowOperatingSystem
  CouldNotFindExecutable
  FailedToStart
  UnresponsiveAfterStart
  ProtocolVersionMismatch(
    supported_version: String,
    got_version: String,
  )
}

Constructors

```
UnknowOperatingSystem
```
```
CouldNotFindExecutable
```
```
FailedToStart
```
```
UnresponsiveAfterStart
```
This is used by the launch functions of the root chrobot module
```
ProtocolVersionMismatch(
  supported_version: String,
  got_version: String,
)
```
Arguments
- supported_version
  
  Version supported by the protocol
- got_version
  
  Version the browser reported

LogLevel

</>

The log level the browser is using.

pub type LogLevel {
  LogLevelSilent
  LogLevelWarnings
  LogLevelInfo
  LogLevelDebug
}

Constructors

```
LogLevelSilent
```
Log nothing
```
LogLevelWarnings
```
Log only warnings, this is the default
```
LogLevelInfo
```
Log normal but uncommon events, like buffering a long message, shutdown
```
LogLevelDebug
```
Log everything, including protocol payloads

Message

</>

pub type Message {
  Shutdown(reply_with: Subject(Nil))
  Kill
  Call(
    reply_with: Subject(Result(d.Dynamic, RequestError)),
    method: String,
    params: Option(Json),
    session_id: Option(String),
  )
  Send(method: String, params: Option(Json))
  AddListener(listener: Subject(d.Dynamic), method: String)
  RemoveListener(listener: Subject(d.Dynamic))
  UnexpectedPortMessage(d.Dynamic)
  PortResponse(String)
  SetLogLevel(LogLevel)
  PortExit(Int)
}

Constructors

```
Shutdown(reply_with: Subject(Nil))
```
Initiate graceful shutdown of the browser
```
Kill
```
Kill by shutting down actor

Call(
  reply_with: Subject(Result(d.Dynamic, RequestError)),
  method: String,
  params: Option(Json),
  session_id: Option(String),
)

Make a protocol call and receive response

Send(method: String, params: Option(Json))

Make a protocol call and ignore response

AddListener(listener: Subject(d.Dynamic), method: String)

RemoveListener(listener: Subject(d.Dynamic))

```
UnexpectedPortMessage(d.Dynamic)
```
(From Port) Message that could not be matched
```
PortResponse(String)
```
(From Port) Protocol Message
```
SetLogLevel(LogLevel)
```
Allows you to set the log level of the running instance
```
PortExit(Int)
```
(From Port) Port has exited

RequestError

</>

Errors that may occur when a protocol request is made

pub type RequestError {
  PortError
  ChromeAgentTimeout
  ChromeAgentDown
  ProtocolError
  BrowserError(code: Int, message: String, data: String)
  NotFoundError
  RuntimeException(text: String, line: Int, column: Int)
}

Constructors

```
PortError
```
```
ChromeAgentTimeout
```
OTP actor timeout
```
ChromeAgentDown
```
OTP actor down
```
ProtocolError
```
The ProtocolError variant is used by /protocol domains to return a homogeneous error type for all requests.

BrowserError(code: Int, message: String, data: String)

This is an error response from the browser itself

```
NotFoundError
```
A requested resource could not be found
```
RuntimeException(text: String, line: Int, column: Int)
```
A runtime exception thrown by JavaScript code being evaluated in the browser

Constants

default_timeout

</>

pub const default_timeout: Int

Functions

add_listener

</>

pub fn add_listener(
  browser: Subject(Message),
  method: String,
) -> Subject(Dynamic)

Add an event listener (Experimental! Event forwarding is not really supported yet)

call

</>

pub fn call(
  browser: Subject(Message),
  method: String,
  params: Option(Json),
  session_id: Option(String),
  time_out: Int,
) -> Result(Dynamic, RequestError)

Issue a protocol call to the browser and expect a response

get_default_chrome_args

</>

pub fn get_default_chrome_args() -> List(String)

Get the default arguments the browser should be started with, to be used inside the launch_with_config function

get_local_chrome_path

</>

pub fn get_local_chrome_path() -> Result(String, LaunchError)

Try to find a hermetic chrome installation in the current directory, of the kind installed by browser_install or the puppeteer install script. The installation must be in a directory called chrome.

get_system_chrome_path

</>

pub fn get_system_chrome_path() -> Result(String, LaunchError)

Try to find a system chrome installation in some obvious places.

get_version

</>

pub fn get_version(
  browser: Subject(Message),
) -> Result(BrowserVersion, RequestError)

Hardcoded protocol call to get the browser version See: https://chromedevtools.github.io/devtools-protocol/tot/Browser/#method-getVersion

is_local_chrome_path

</>

pub fn is_local_chrome_path(
  relative_path: String,
  os_family: OsFamily,
) -> Bool

Returns whether the given path is a local chrome installation, of the kind created by browser_install or the puppeteer install script. This can be used to scan a directory with simplifile.get_files.

launch

</>

pub fn launch() -> Result(Subject(Message), LaunchError)

Cleverly try to find a chrome installation and launch it with reasonable defaults.

If CHROBOT_BROWSER_PATH is set, use that
If a local chrome installation is found, use that
If a system chrome installation is found, use that
If none of the above, return an error

If you want to always use a specific chrome installation, take a look at launch_with_config or launch_with_env to set the path explicitly.

Be aware that this function will not validate that the browser launched successfully, please use the higher level functions from the root chrobot module instead if you want these guarantees.

launch_window

</>

pub fn launch_window() -> Result(Subject(Message), LaunchError)

Like launch, but launches the browser with a visible window, not in headless mode, which is useful for debugging and development.

launch_with_config

</>

pub fn launch_with_config(
  cfg: BrowserConfig,
) -> Result(Subject(Message), LaunchError)

Launch a browser with the given configuration, to populate the arguments, use get_default_chrome_args.

Be aware that this function will not validate that the browser launched successfully, please use the higher level functions from the root chrobot module instead if you want these guarantees.

Example

let config =
BrowserConfig(
  path: "chrome/linux-116.0.5793.0/chrome-linux64/chrome",
  args: get_default_chrome_args(),
  start_timeout: 5000,
)
let assert Ok(browser_subject) = launch_with_config(config)

launch_with_env

</>

pub fn launch_with_env() -> Result(Subject(Message), LaunchError)

Launch a browser, and read the configuration from environment variables. The browser path variable must be set, all others will fall back to a default.

Be aware that this function will not validate that the browser launched successfully, please use the higher level functions from the root chrobot module instead if you want these guarantees.

Configuration variables:

CHROBOT_BROWSER_PATH - The path to the browser executable
CHROBOT_BROWSER_ARGS - The arguments to pass to the browser, separated by spaces
CHROBOT_BROWSER_TIMEOUT - The timeout in milliseconds to wait for the browser to start, must be an integer
CHROBOT_LOG_LEVEL - The log level to use, one of silent, warnings, info, debug

listen_once

</>

pub fn listen_once(
  browser: Subject(Message),
  method: String,
  time_out: Int,
) -> Result(Dynamic, RequestError)

A blocking call that waits for a specified event to arrive once, and then resolves, removing the event listener.

quit

</>

pub fn quit(
  browser: Subject(Message),
) -> Result(Nil, CallError(Nil))

Quit the browser and shut down the actor.
This function will attempt graceful shutdown, if the browser does not respond in time, it will also send a kill signal to the actor to force it to shut down. The result typing reflects the success of graceful shutdown.

remove_listener

</>

pub fn remove_listener(
  browser: Subject(Message),
  listener: Subject(Dynamic),
) -> Nil

Remove an event listener (Experimental! Event forwarding is not really supported yet)

send

</>

pub fn send(
  browser: Subject(Message),
  method: String,
  params: Option(Json),
) -> Nil

Issue a protocol call to the browser without waiting for a response, when the response arrives, it will be discarded. It’s probably best to not use this and instead just use call and discard unneeded responses. All protocol calls yield a response and can be used with call, even if they don’t specify any response parameters.

set_log_level

</>

pub fn set_log_level(
  browser: Subject(Message),
  level: LogLevel,
) -> Nil

Allows you to set the log level of a running browser instance

Constructors

Constructors

Constructors

Constructors

Arguments

Constructors

Constructors

Constructors

Example