butterbee/config

Butterbee can be configured using the gleam.toml file. When you call the new function in the webdriver module, butterbee tries to parse the gleam.toml file in the root of the project. If it can’t find it, it will use the default configuration.

Example of the default configuration in toml format:

# gleam.toml

[tools.butterbee.driver]
max_wait_time = 20000
request_timeout = 5000
data_dir = "/tmp/butterbee"

[tools.butterbee.capabilities.always_match]
webSocketUrl = true

[tools.butterbee.browser.firefox]
cmd = "firefox"
flags = []
host = "127.0.0.1"

[tools.butterbee.browser.chromium]
cmd = "chromedriver"
flags = []
host = "127.0.0.1"

Driver Config

The driver config module contains functions for parsing and creating driver configurations. The driver configuration specifies general options the webdriver needs to run, such as the maximum wait time, and the request timeout.

# gleam.toml

[tools.butterbee.driver]
max_wait_time = 20000
request_timeout = 5000
data_dir = "/tmp/butterbee"

Capabilities Config

This module provides functionality for parsing and creating capabilities requests from TOML configuration files for WebDriver(state) BiDi sessions.

In browser automation contexts, capabilities define the desired properties and features that a WebDriver(state) session should support. They specify requirements like browser version, platform, extensions, timeouts, and other session-specific configurations. Capabilities are used during session negotiation to match the requested features with what the browser/driver can provide.

The capabilities matching process typically involves:

always_match: Capabilities that must be satisfied for the session to be created
first_match: A list of capability sets where at least one must be satisfied

# gleam.toml
# TODO: add realistic example here, the current example works but is not realistic

[tools.butterbee.capabilities.always_match]
webSocketUrl = true
"goog:chromeOptions" = { args = ["--headless=new"] }

[[tools.butterbee.capabilities.first_match]]
browserVersion = "latest"
"chrome:options" = { debuggerAddress = "localhost:9222" }

[[tools.butterbee.capabilities.first_match]]
"moz:firefoxOptions" = { binary = "/usr/bin/firefox", args = [
  "-headless",
  "-safe-mode",
], prefs = { "dom.webnotifications.enabled" = false }, log = { level = "trace" } }
browserVersion = "stable"
}

Browser Config

This module provides functionality for parsing and creating browser configurations from TOML configuration files for WebDriver BiDi sessions.

Chromium support

Because chromium does not natively support WebDriver BiDi, butterbee uses the chromedriver to control chromium. Which has a BiDi to CDP mapper built in.

Chromedriver does not come with chromium built in, so make sure you have chromium installed. Chromedriver will search for the chromium binary on your system. so no additional configuration is needed.

# gleam.toml

[tools.butterbee.browser.firefox]
cmd = "firefox"
flags = ["-headless"]
host = "127.0.0.1"

[tools.butterbee.browser.chromium]
cmd = "chromedriver"
flags = []
host = "127.0.0.1"

Headless

to run the browsers headless, add the following to your gleam.toml file:

[tools.butterbee.browser.firefox]
flags = ["-headless"]

[tools.butterbee.capabilities.always_match]
webSocketUrl = true
"goog:chromeOptions" = { args = ["--headless=new"] }

Types

BrowserConfig

</>

pub type BrowserConfig {
  BrowserConfig(
    start_url: String,
    cmd: String,
    extra_flags: List(String),
    host: String,
  )
}

Constructors

```
BrowserConfig(
  start_url: String,
  cmd: String,
  extra_flags: List(String),
  host: String,
)
```
Arguments

start_url

The url that is loaded when the browser is started.

cmd

The path to the browser executable, or the name of the browser if it is in the PATH.

extra_flags

Extra flags to pass to the browser.

host

The host to use for the browser.

BrowserType

</>

pub type BrowserType {
  Firefox
  Chromium
}

Constructors

```
Firefox
```
```
Chromium
```

ButterbeeConfig

</>

Represents the [tools.butterbee] section of your gleam.toml file

pub type ButterbeeConfig {
  ButterbeeConfig(
    driver: DriverConfig,
    capabilities: option.Option(
      capabilities_request.CapabilitiesRequest,
    ),
    browser_config: option.Option(
      dict.Dict(BrowserType, BrowserConfig),
    ),
  )
}

Constructors

ButterbeeConfig(
  driver: DriverConfig,
  capabilities: option.Option(
    capabilities_request.CapabilitiesRequest,
  ),
  browser_config: option.Option(
    dict.Dict(BrowserType, BrowserConfig),
  ),
)

DriverConfig

</>

pub type DriverConfig {
  DriverConfig(
    max_wait_time: Int,
    request_timeout: Int,
    data_dir: String,
  )
}

Constructors

DriverConfig(
  max_wait_time: Int,
  request_timeout: Int,
  data_dir: String,
)

Values

default_browser_config

</>

pub fn default_browser_config() -> dict.Dict(
  BrowserType,
  BrowserConfig,
)

Returns the default browser configuration

default_browser_type

</>

pub const default_browser_type: BrowserType

Returns the default browser type, firefox

default_capabilities_config

</>

pub fn default_capabilities_config() -> capabilities_request.CapabilitiesRequest

Creates a default CapabilitiesRequest with only the webSocketUrl capability for always_match.

default_config

</>

pub const default_config: ButterbeeConfig

The default config. See the toml representation of the default configuration above

default_data_dir

</>

pub const default_data_dir: String

Butterbee will use this data directory unless overridden. The data directory is used to store profile data for browsers.

default_driver_config

</>

pub const default_driver_config: DriverConfig

default_host

</>

pub const default_host: String

Butterbee will use this host url unless overridden

default_max_wait_time

</>

pub const default_max_wait_time: Int

Butterbee will use this maximum wait time unless overridden. This settings determines how long butterbee will perform a retry function for before timing out (and failing the test).

default_port

</>

pub const default_port: Int

Butterbee will use this port unless overridden

default_request_timeout

</>

pub const default_request_timeout: Int

Butterbee will use this request timeout unless overridden. Warn: This value is not currently used.

with_browser_config

</>

pub fn with_browser_config(
  config: ButterbeeConfig,
  browser_type: BrowserType,
  browser_config: BrowserConfig,
) -> ButterbeeConfig

with_capabilities

</>

pub fn with_capabilities(
  config: ButterbeeConfig,
  capabilities: capabilities_request.CapabilitiesRequest,
) -> ButterbeeConfig

with_cmd

</>

pub fn with_cmd(
  config: BrowserConfig,
  cmd: String,
) -> BrowserConfig

with_driver_config

</>

pub fn with_driver_config(
  config: ButterbeeConfig,
  driver: DriverConfig,
) -> ButterbeeConfig

with_extra_flags

</>

pub fn with_extra_flags(
  config: BrowserConfig,
  extra_flags: List(String),
) -> BrowserConfig

with_host

</>

pub fn with_host(
  config: BrowserConfig,
  host: String,
) -> BrowserConfig

with_start_url

</>

pub fn with_start_url(
  config: BrowserConfig,
  start_url: String,
) -> BrowserConfig

Driver Config

Capabilities Config

Browser Config

Chromium support

Headless

Constructors

Arguments

Constructors

Constructors

Constructors