Introduction

Benefits and Useful Features

Getting Started

Installation

go get github.com/ghetzel/go-webfriend/cmd/webfriend

Usage

As a standalone utility

As a server

As a Golang library

Command Reference

Assert Module

assert::compare HAVE {
value: any
test: string
}


Return an error if the given value is not equal to the other value.

Parameters

Name Data Type Default Value Description
value any 
-
test string 
-

assert::contains HAVE {
value: any
test: string
}


Return an error if the given value does not contain another value.

Parameters

Name Data Type Default Value Description
value any 
-
test string 
-

assert::empty VALUE {
message: string
snippet: string
}


Return an error if the given value not empty.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::equal HAVE {
value: any
test: string
}


Return an error if the given value is not equal to the other value.

Parameters

Name Data Type Default Value Description
value any 
-
test string 
-

assert::exists VALUE {
message: string
snippet: string
}


Return an error if the given value is null or zero-length.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::false VALUE {
message: string
snippet: string
}


Return an error if the given value is not false.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::gt HAVE {
value: any
test: string
}


Return an error if the given value is not numerically greater than the second value.

Parameters

Name Data Type Default Value Description
value any 
-
test string 
-

assert::gte HAVE {
value: any
test: string
}


Return an error if the given value is not numerically greater than or equal to the second value.

Parameters

Name Data Type Default Value Description
value any 
-
test string 
-

assert::is_array VALUE {
message: string
snippet: string
}


Return an error if the given value is not an array.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::is_boolean VALUE {
message: string
snippet: string
}


Return an error if the given value is not a boolean value.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::is_duration VALUE {
message: string
snippet: string
}


Return an error if the given value is not parsable as a duration.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::is_numeric VALUE {
message: string
snippet: string
}


Return an error if the given value is not a numeric value.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::is_object VALUE {
message: string
snippet: string
}


Return an error if the given value is not an object.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::is_scalar VALUE {
message: string
snippet: string
}


Return an error if the given value is not a scalar value.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::is_string VALUE {
message: string
snippet: string
}


Return an error if the given value is not a string.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::is_time VALUE {
message: string
snippet: string
}


Return an error if the given value is not parsable as a time.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::lt HAVE {
value: any
test: string
}


Return an error if the given value is not numerically less than the second value.

Parameters

Name Data Type Default Value Description
value any 
-
test string 
-

assert::lte HAVE {
value: any
test: string
}


Return an error if the given value is not numerically less than or equal to the second value.

Parameters

Name Data Type Default Value Description
value any 
-
test string 
-

assert::not_contains HAVE {
value: any
test: string
}


Return an error if the given value contains another value.

Parameters

Name Data Type Default Value Description
value any 
-
test string 
-

assert::not_equal HAVE {
value: any
test: string
}


Return an error if the given value is equal to the other value.

Parameters

Name Data Type Default Value Description
value any 
-
test string 
-

assert::not_null VALUE {
message: string
snippet: string
}


Return an error if the given value is null.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::null VALUE {
message: string
snippet: string
}


Return an error if the given value is not null.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

assert::true VALUE {
message: string
snippet: string
}


Return an error if the given value is not true.

Parameters

Name Data Type Default Value Description
message string 
-
snippet string 
-

Cookies Module

Commands for interacting with the browser’s cookie storage backend.

cookies::clear


Clears all browser cookies.

cookies::delete NAME {
url: string
domain: string
path: string
}


Deletes a cookie by name, and optionally matching additional criteria.

Parameters

Name Data Type Default Value Description
url string 
-

Deletes all cookies with the given name where domain and path match the given URL.
domain string 
-

If specified, deletes only cookies with this exact domain.
path string 
-

If specified, deletes only cookies with this exact path.

cookies::get NAME -> cookie


Get a cookie by its name.

Return Parameters

Name Data Type Description
name string

The name of the cookie.
value string

The cookie’s value.
domain string

The applicable domain for the cookie.
path string

The cookie’s path.
size int

The size of the cookie.
expires time

The cookie’s expiration date.
http_only bool

The cookie is flagged as being inaccessible to client-side scripts.
secure bool

The cookie is flagged as “secure”
session bool

This is a session cookie.
same_site string

The same site value of the cookie (“Strict” or “Lax”)
url string

The URL the cookie should refer to (when setting)

cookies::list {
urls: []string
names: []string
} -> []cookie


List all cookies, either for the given set of URLs or for the current tab (if omitted).

Parameters

Name Data Type Default Value Description
urls []string 
-

an array of strings representing the URLs to retrieve cookies for. If omitted, the URL of the current browser tab will be used
names []string 
-

A list of cookie names to include in the output. If non-empty, only these cookies will appear (if present).

cookies::map {
urls: []string
names: []string
} -> map


A variant of cookies::list that returns matching cookies as a map of name=value pairs.

Parameters

Name Data Type Default Value Description
urls []string 
-

an array of strings representing the URLs to retrieve cookies for. If omitted, the URL of the current browser tab will be used
names []string 
-

A list of cookie names to include in the output. If non-empty, only these cookies will appear (if present).

cookies::set {
name: string
value: string
domain: string
path: string
size: int
expires: time
http_only: bool
secure: bool
session: bool
same_site: string
url: string
}


Set a cookie.

Parameters

Name Data Type Default Value Description
name string 
-

The name of the cookie.
value string 
-

The cookie’s value.
domain string 
-

The applicable domain for the cookie.
path string 
-

The cookie’s path.
size int 
-

The size of the cookie.
expires time 
-

The cookie’s expiration date.
http_only bool 
-

The cookie is flagged as being inaccessible to client-side scripts.
secure bool 
-

The cookie is flagged as “secure”
session bool 
-

This is a session cookie.
same_site string 
-

The same site value of the cookie (“Strict” or “Lax”)
url string 
-

The URL the cookie should refer to (when setting)

Core Module

Commonly used commands for basic browser interaction.

back


Navigate back through the current tab’s history.

click SELECTOR {
multiple: bool
delay: duration "20ms"
match_text: string
} -> []element


Click on HTML element(s) matches by selector. If multiple is true, then all elements matched by selector will be clicked in the order they are returned. Otherwise, an error is returned unless selector matches exactly one element.

Examples

Click on the element with id “login”
click "#login"
Click on all <a> elements on the page, waiting 150ms between each click.

	click "a" {
	  multiple: true,
	  delay:    "150ms",
	}

Parameters

Name Data Type Default Value Description
multiple bool 
-

Permit multiple elements to be clicked.
delay duration 
"20ms"

If Multiple clicks are permitted, what is the delay between each click.
match_text string 
-

If provided, this represents a regular expression that the text value of matching elements must match to be clicked.

click_at {
x: int
y: int
} -> []element


Click the page at the given X, Y coordinates.

Parameters

Name Data Type Default Value Description
x int 
-

The X-coordinate to click at
y int 
-

The Y-coordinate to click at

configure {
user_agent: string
latitude: float
longitude: float
accuracy: float 1
disable_scripts: bool
emulate_touch: bool
background_color: string
hide_scrollbars: bool
}


Configures various features of the Remote Debugging protocol and provides environment setup.

Parameters

Name Data Type Default Value Description
user_agent string 
-

Override the default User-Agent header sent with all requests
latitude float 
-

Specify the Geographic latitude to emulate [-90.0, 90.0]
longitude float 
-

Specify the Geographic longitude to emulate [-180.0, 180.0]
accuracy float 
1

Specify a Geolocation error margin (accurate to within n meters)
disable_scripts bool 
-

Disable JavaScript execution in the browser.
emulate_touch bool 
-

Emulate a touch-capable device.
background_color string 
-

Set the default background color of the underlying window in the following formats: #RRGGBB, #RRGGBBAA, rgb(), rgba(), hsv(), hsva(), hsl(), hsla().
hide_scrollbars bool 
-

Set whether scrollbars should be hidden all the time.

env NAME {
fallback: any
required: bool false
detect_type: bool true
joiner: string
} -> any


Retrieves a system environment variable and returns the value of it, or a fallback value if the variable does not exist or (optionally) is empty.

Examples

Get the value of the USER environment variable and store it
env 'USER' -> $user
Require the LANG, USER, and CI environment variables; and fail they are not set.
env 'LANG' { required: true }
env 'USER' { required: true }
env 'CI'   { required: true }

Parameters

Name Data Type Default Value Description
fallback any 
-

The value to return if the environment variable does not exist, or (optionally) is empty.
required bool 
false

Whether empty values should be ignored or not.
detect_type bool 
true

Whether automatic type detection should be performed or not.
joiner string 
-

If specified, this string will be used to split matching values into a list of values. This is useful for environment variables that contain multiple values joined by a separator (e.g: the PATH variable.)

exit


Immediately close the browser without error or delay.

export NAME


Specify a variable that should be exported to external Javascripts.

fail MESSAGE


Immediately exit the script in an error-like fashion with a specific message.

field SELECTOR {
value: any
autoclear: bool true
enter: bool
click: selector
} -> []element


Locate and enter data into a form input field.

Examples

Type in a username and password, then hit Enter to submit.

	field '#username' {
	  value: 'myuser',
	}
	field '#password' {
	  value: 'p@ssw0rd!',
	  enter: true,
	}

Parameters

Name Data Type Default Value Description
value any 
-

The value to enter into the field.
autoclear bool 
true

Whether to clear the existing contents of the field before entering new data.
enter bool 
-

Whether to automatically send an “Enter” keystroke after typing in the given value
click selector 
-

An element to click after the field value is changed.

focus SELECTOR -> element


Focuses the given HTML element described by selector. One and only one element may match the selector.

go URI {
referrer: string
wait_for_load: bool true
timeout: duration "30s"
request_poll_timeout: duration "5s"
clear_requests: bool false
require_originating_request: bool true
continue_on_error: bool
continue_statuses: []int
continue_on_timeout: bool false
load_event_name: string "Page.loadEventFired"
username: string
password: string
realm: string
} -> object


Navigate to a URL.

Examples

Go to Google.
go "google.com"
Go to www.example.com, only wait for the first network response, and don’t fail if the request times out.

	go "https://www.exmaple.com" {
	  timeout:             '10s',
	  continue_on_timeout: true,
	  load_event_name:     'Network.responseReceived',
	}

Parameters

Name Data Type Default Value Description
referrer string 
-

If a URL is specified, it will be used as the HTTP Referer [sic] header field when going to the given page. If the URL of the currently-loaded page and the referrer are the same, the page will no change.

For this reason, you may specify the special value ‘random’, which will generate a URL with a randomly generated path component to ensure that it is always different from the current page. Specifying None will omit the field from the request.
wait_for_load bool 
true

Whether to block until the page has finished loading.
timeout duration 
"30s"

The amount of time to wait for the page to load.
request_poll_timeout duration 
"5s"

The amount of time to poll for the originating network request.
clear_requests bool 
false

Whether the resources stack that is queried in page::resources and page::resource is cleared before navigating. Set this to false to preserve the ability to retrieve data that was loaded on previous pages.
require_originating_request bool 
true

Whether the originating network request is required in the return value. If this is false, the response may be missing status, headers, and timing details.
continue_on_error bool 
-

Whether to continue execution if an error is encountered during page load (e.g.: HTTP 4xx/5xx, SSL, TCP connection errors).
continue_statuses []int 
-

These HTTP status codes are not considered errors.
continue_on_timeout bool 
false

Whether to continue execution if load_event_name is not seen before timeout elapses.
load_event_name string 
"Page.loadEventFired"

The RPC event to wait for before proceeding to the next command.
username string 
-

Provide a username if one is requested via HTTP Basic authentication.
password string 
-

Provide a password if one is requested via HTTP Basic authentication.
realm string 
-

Only provide credentials if the HTTP Basic Authentication Realm matches this one.

Return Parameters

Name Data Type Description
url string

The final URL of the page that was loaded.
status int

The HTTP status code of the loaded page.
timing_details map

A map of durations (in milliseconds) that various phases of the page load took.
headers map

Map of HTTP response headers.
mime_type string

The MIME type of the response content.
remote_address string

The remote address of the loaded page.
protocol string

The protocol that was negotiated and used to load the page.

highlight SELECTOR {
r: int 0
g: int 128
b: int 128
a: float 0.5
}


Highlight the node matching the given selector, or clear all highlights if the selector is “none”

Parameters

Name Data Type Default Value Description
r int 
0

The red component of the highlight color (0 <= r < 256)
g int 
128

The green component of the highlight color (0 <= g < 256)
b int 
128

The blue component of the highlight color (0 <= b < 256)
a float 
0.5

The alpha component of the highlight color (0.0 <= a <= 1.0)

inspect {
x: float
y: float
highlight: bool true
r: int 0
g: int 128
b: int 128
a: float 0.5
} -> element


Retrieve the element at the given coordinates, optionally highlighting it.

Parameters

Name Data Type Default Value Description
x float 
-

The X-coordinate to inspect.
y float 
-

The Y-coordinate to inspect.
highlight bool 
true

Whether to highlight the inspected DOM element or not.
r int 
0

The red component of the highlight color (0 <= r < 256)
g int 
128

The green component of the highlight color (0 <= g < 256)
b int 
128

The blue component of the highlight color (0 <= b < 256)
a float 
0.5

The alpha component of the highlight color (0.0 <= a <= 1.0)

javascript SCRIPT -> any


Inject Javascript into the current page, evaluate it, and return the results. The script is wrapped in an anonymous function whose return value will be returned from this command as a native data type.

Scripts will have access to all exported variables in the calling script (exported with the “export” command). They are available to injected script as a plain object accessible using the “webfriend” variable.

Examples

Use the webfriend local variable to access Friendscript data from JavaScript, make a change, then pass it back.
$pi = 3.0
javascript "return webfriend.pi + 0.14" -> $pi
# $pi is now 3.14
Inject a script that will retrieve all <a> tags on a page and return their “href” attributes (if present).
javascript begin
	var as = document.querySelectorAll('a');
	var hrefs = [];
	for(var i = 0; i < as.length; i++) {
	    var a = as[i];
	    var href = a.getAttribute('href');
	    if (href && href.length) {
	        hrefs.push(href);
	    }
	}
	return hrefs;
end -> $result
# $result now contains an array of zero or more strings as returned from JavaScript.

log MESSAGE


Outputs a line to the log.

netrc MACHINE {
filename: string "~/.netrc"
extra_fields: []string
} -> object


Retrieve a username and password from a .netrc-formatted file.

Parameters

Name Data Type Default Value Description
filename string 
"~/.netrc"

The path to the .netrc file to load values from.
extra_fields []string 
-

A list of additional, non-standard fields to retrieve from the .netrc entry

Return Parameters

Name Data Type Description
ok bool

Whether there was a match or not.
machine string

The machine name that matched.
login string

The login name.
password string

The password.
fields map

Any additional values retrieved from the entry

put VALUE -> any


Store a value in the current scope. Strings will be automatically converted into the appropriate data types (float, int, bool) if possible.

reload


Reload the currently active tab.

resize {
width: int
height: int
scale: float
mobile: any
fit_window: bool
orientation: string "landscapePrimary"
angle: int
} -> object


Resizes the active viewport of the current page using the Chrome Device Emulation API. This does not resize the window itself, but rather the area the current page interprets the window to be.

This is useful for setting the size of the area that will be rendered for screenshots and screencasts, or for testing responsive design elements.

Parameters

Name Data Type Default Value Description
width int 
-

The width of the screen.
height int 
-

The height of the screen.
scale float 
-

The scaling factor of the content.
mobile any 
-

Whether to emulate a mobile device or not. If a map is provided, mobile emulation will be enabled and configured using the following keys:


Value Data Type Description
width int, optional The width of the mobile screen to emulate.
height int, optional The height of the mobile screen to emulate.
x int, optional The horizontal position of the currently viewable portion of the mobile screen.
y int, optional The vertical position of the currently viewable portion of the mobile screen.
fit_window bool 
-

Whether to fit the viewport contents to the available area or not.
orientation string 
"landscapePrimary"

Which screen orientation to emulate, if any.
angle int 
-

The angle of the screen to emulate (in degrees; 0-360).

Return Parameters

Name Data Type Description
width int

The final width of the page after resize.
height int

The final height of the page after resize.

run FILENAME {
result_key: string
data: map
isolated: bool true
} -> any


Evaluates another Friendscript loaded from another file. The filename is the absolute path or basename of the file to search for in the FRIENDSCRIPT_PATH environment variable to load and evaluate. The FRIENDSCRIPT_PATH variable behaves like the the traditional *nix PATH variable, wherein multiple paths can be specified as a colon-separated (:) list. The directory of the calling script (if available) will always be checked first.

Returns: The value of the variable named by result_key at the end of the evaluated script’s execution.

Parameters

Name Data Type Default Value Description
result_key string 
-

Specifies a key in the scope of the evaluate script that will be used as the result value of this command.
data map 
-

Provides a set of initial variables to the script.
isolated bool 
true

If true, the scope of the running script will not be able to modify data in the parent scope.

scroll_to SELECTOR


Scroll the viewport to the location of the first element matched by selector.

scroll_to_coords X {
y: int
}


Scroll the viewport to the given X,Y coordinates relative to the top-left of the current page.

Parameters

Name Data Type Default Value Description
y int 
-

select SELECTOR {
timeout: duration "5s"
min_matches: int 1
interval: duration "125ms"
} -> []element


Polls the DOM for an element that matches the given selector. Either the element will be found and returned within the given timeout, or a TimeoutError will be returned.

Parameters

Name Data Type Default Value Description
timeout duration 
"5s"

The timeout before we stop waiting for the element to appear.
min_matches int 
1

The minimum number of matches necessary to be considered a successful match.
interval duration 
"125ms"

The polling interval between element re-checks.

stop


Stop loading the currently active tab.

type INPUT {
alt: bool
control: bool
shift: bool
meta: bool
is_keypad: bool
key_down_time: duration "30ms"
key_down_jitter: duration
delay: duration "30ms"
delay_jitter: duration
} -> string


Input the given textual data as keyboard input into the currently focused page element. The input text contains raw unicode characters that will be typed literally, as well as key names (in accordance with the DOM pre-defined keynames described at https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). These sequences appear between square brackets “[” “]”.

Example: Type in the Konami code

type "[ArrowUp][ArrowUp][ArrowDown][ArrowDown][ArrowLeft][ArrowRight][ArrowLeft][ArrowRight]BA"

Parameters

Name Data Type Default Value Description
alt bool 
-
control bool 
-
shift bool 
-
meta bool 
-
is_keypad bool 
-

Whether the text being input is issued via the numeric keypad or not.
key_down_time duration 
"30ms"

How long that each individual keystroke will remain down for.
key_down_jitter duration 
-

An amount of time to randomly vary the key_down_time duration from within each keystroke.
delay duration 
"30ms"

How long to wait between issuing individual keystrokes.
delay_jitter duration 
-

An amount of time to randomly vary the delay duration from between keystrokes.

unexport NAME


Specify a variable that should be unexported.

wait DELAY


Pauses execution of the current script for the given duration.

wait_for EVENT {
timeout: duration "30s"
}


Wait for a specific event or events matching the given glob pattern, up to an optional Timeout duration.

Parameters

Name Data Type Default Value Description
timeout duration 
"30s"

The timeout before we stop waiting for the event.

wait_for_load {
timeout: duration "30s"
}


Wait for a page load event.

Parameters

Name Data Type Default Value Description
timeout duration 
"30s"

The timeout before we stop waiting for the event.

File Module

file::write DESTINATION {
data: stream
value: any
autoclose: bool true
} -> object


Write a value or a stream of data to a file at the given path. The destination path can be a local filesystem path, a URI that uses a custom scheme registered outside of the application, or the string “temporary”, which will write to a temporary file whose path will be returned in the response.

Parameters

Name Data Type Default Value Description
data stream 
-

The data to write to the destination.
value any 
-

The data to write as a discrete value.
autoclose bool 
true

Whether to attempt to close the destination (if possible) after reading/writing.

Return Parameters

Name Data Type Description
path string

The filesystem path that the data was written to.
size int

The size of the data (in bytes).
took duration

The amount of time it took to complete writing the data.

Format Module

fmt::autotype INPUT -> any


Takes an input value and returns that value as the most appropriate data type based on its contents.

fmt::camelize INPUT -> string


Return the given string converted to camelCase.

fmt::codepoints INPUT -> []int


Return an array of Unicode codepoints for each character in the given string.

fmt::format PATTERN {
data: any
} -> string


Format the given string according to the given pattern and values.

Parameters

Name Data Type Default Value Description
data any 
-

fmt::join INPUTS {
joiner: string ","
} -> string


Join an array of inputs into a single string, with each item separated by a given joiner string.

Parameters

Name Data Type Default Value Description
joiner string 
","

fmt::lcp INPUTS -> string


Returns the longest common prefix among an array of input strings.

fmt::lower INPUT -> string


Return the given string converted to lowercase.

fmt::pascalize INPUT -> string


Return the given string converted to PascalCase.

fmt::replace INPUT {
find: any
replace: string
count: int -1
} -> string


Replaces values in an input string (exact matches or regular expressions) with a replacement value. Exact matches will be replaced up to a certain number of times, or all occurrences of count is -1 (default).

Parameters

Name Data Type Default Value Description
find any 
-
replace string 
-
count int 
-1

fmt::split INPUT {
on: string ","
} -> []string


Split a given string by a given delimiter.

Parameters

Name Data Type Default Value Description
on string 
","

fmt::strip INPUT -> string


Strip leading and trailing whitespace from the given string.

fmt::title INPUT -> string


Return the given string converted to Title Case.

fmt::trim INPUT {
prefix: string
suffix: string
} -> string


Remove a leading and/org trailing string value from the given string.

Parameters

Name Data Type Default Value Description
prefix string 
-
suffix string 
-

fmt::underscore INPUT -> string


Return the given string converted to underscore_case.

fmt::upper INPUT -> string


Return the given string converted to UPPERCASE.

Http Module

http::defaults {
headers: map
params: map
cookies: map
timeout: duration "30s"
body: any
request_type: string "json"
response_type: string
disable_verify_ssl: bool
certificate_bundle: string
statuses: string "200-299"
continue_on_error: bool
raw_body: bool
}


Set default options that apply to all subsequent HTTP requests.

Parameters

Name Data Type Default Value Description
headers map 
-

The headers to send with the request.
params map 
-

Query string parameters to add to the request.
cookies map 
-

A map of cookie key=value pairs to include in the request.
timeout duration 
"30s"

The amount of time to wait for the request to complete.
body any 
-

The body of the request. This is processed according to what is specified in RequestType.
request_type string 
"json"

The type of data in Body, specifying how it should be encoded. Valid values are “raw”, “form”, and “json”
response_type string 
-

Specify how the response body should be decoded. Can be “raw”, or a MIME type that overrides the Content-Type response header.
disable_verify_ssl bool 
-

Whether to disable TLS peer verification.
certificate_bundle string 
-

The path to the root TLS CA bundle to use for verifying peer certificates.
statuses string 
"200-299"

A comma-separated list of numbers (e.g.: 200) or inclusive number ranges (e.g. 200-399) specifying HTTP statuses that are expected and non-erroneous.
continue_on_error bool 
-

Whether to continue execution if an error status is encountered.
raw_body bool 
-

Specify that absolutely no processing should be done on the response body.

http::delete URL {
headers: map
params: map
cookies: map
timeout: duration "30s"
body: any
request_type: string "json"
response_type: string
disable_verify_ssl: bool
certificate_bundle: string
statuses: string "200-299"
continue_on_error: bool
raw_body: bool
} -> object


Perform an HTTP DELETE request.

Parameters

Name Data Type Default Value Description
headers map 
-

The headers to send with the request.
params map 
-

Query string parameters to add to the request.
cookies map 
-

A map of cookie key=value pairs to include in the request.
timeout duration 
"30s"

The amount of time to wait for the request to complete.
body any 
-

The body of the request. This is processed according to what is specified in RequestType.
request_type string 
"json"

The type of data in Body, specifying how it should be encoded. Valid values are “raw”, “form”, and “json”
response_type string 
-

Specify how the response body should be decoded. Can be “raw”, or a MIME type that overrides the Content-Type response header.
disable_verify_ssl bool 
-

Whether to disable TLS peer verification.
certificate_bundle string 
-

The path to the root TLS CA bundle to use for verifying peer certificates.
statuses string 
"200-299"

A comma-separated list of numbers (e.g.: 200) or inclusive number ranges (e.g. 200-399) specifying HTTP statuses that are expected and non-erroneous.
continue_on_error bool 
-

Whether to continue execution if an error status is encountered.
raw_body bool 
-

Specify that absolutely no processing should be done on the response body.

Return Parameters

Name Data Type Description
status int

The numeric HTTP status code of the response.
status_text string

A textual description of the HTTP response code.
took int

The time (in millisecond) that the request took to complete.
headers map

Response headers sent back from the server.
content_type string

The MIME type of the response body (if any).
length int

The length of the response body in bytes.
body any

The decoded response body (if any).
error bool

If the response status is considered an error, and errors aren’t fatal, this will be true.

http::get URL {
headers: map
params: map
cookies: map
timeout: duration "30s"
body: any
request_type: string "json"
response_type: string
disable_verify_ssl: bool
certificate_bundle: string
statuses: string "200-299"
continue_on_error: bool
raw_body: bool
} -> object


Perform an HTTP GET request.

Parameters

Name Data Type Default Value Description
headers map 
-

The headers to send with the request.
params map 
-

Query string parameters to add to the request.
cookies map 
-

A map of cookie key=value pairs to include in the request.
timeout duration 
"30s"

The amount of time to wait for the request to complete.
body any 
-

The body of the request. This is processed according to what is specified in RequestType.
request_type string 
"json"

The type of data in Body, specifying how it should be encoded. Valid values are “raw”, “form”, and “json”
response_type string 
-

Specify how the response body should be decoded. Can be “raw”, or a MIME type that overrides the Content-Type response header.
disable_verify_ssl bool 
-

Whether to disable TLS peer verification.
certificate_bundle string 
-

The path to the root TLS CA bundle to use for verifying peer certificates.
statuses string 
"200-299"

A comma-separated list of numbers (e.g.: 200) or inclusive number ranges (e.g. 200-399) specifying HTTP statuses that are expected and non-erroneous.
continue_on_error bool 
-

Whether to continue execution if an error status is encountered.
raw_body bool 
-

Specify that absolutely no processing should be done on the response body.

Return Parameters

Name Data Type Description
status int

The numeric HTTP status code of the response.
status_text string

A textual description of the HTTP response code.
took int

The time (in millisecond) that the request took to complete.
headers map

Response headers sent back from the server.
content_type string

The MIME type of the response body (if any).
length int

The length of the response body in bytes.
body any

The decoded response body (if any).
error bool

If the response status is considered an error, and errors aren’t fatal, this will be true.

http::head URL {
headers: map
params: map
cookies: map
timeout: duration "30s"
body: any
request_type: string "json"
response_type: string
disable_verify_ssl: bool
certificate_bundle: string
statuses: string "200-299"
continue_on_error: bool
raw_body: bool
} -> object


Perform an HTTP HEAD request.

Parameters

Name Data Type Default Value Description
headers map 
-

The headers to send with the request.
params map 
-

Query string parameters to add to the request.
cookies map 
-

A map of cookie key=value pairs to include in the request.
timeout duration 
"30s"

The amount of time to wait for the request to complete.
body any 
-

The body of the request. This is processed according to what is specified in RequestType.
request_type string 
"json"

The type of data in Body, specifying how it should be encoded. Valid values are “raw”, “form”, and “json”
response_type string 
-

Specify how the response body should be decoded. Can be “raw”, or a MIME type that overrides the Content-Type response header.
disable_verify_ssl bool 
-

Whether to disable TLS peer verification.
certificate_bundle string 
-

The path to the root TLS CA bundle to use for verifying peer certificates.
statuses string 
"200-299"

A comma-separated list of numbers (e.g.: 200) or inclusive number ranges (e.g. 200-399) specifying HTTP statuses that are expected and non-erroneous.
continue_on_error bool 
-

Whether to continue execution if an error status is encountered.
raw_body bool 
-

Specify that absolutely no processing should be done on the response body.

Return Parameters

Name Data Type Description
status int

The numeric HTTP status code of the response.
status_text string

A textual description of the HTTP response code.
took int

The time (in millisecond) that the request took to complete.
headers map

Response headers sent back from the server.
content_type string

The MIME type of the response body (if any).
length int

The length of the response body in bytes.
body any

The decoded response body (if any).
error bool

If the response status is considered an error, and errors aren’t fatal, this will be true.

http::options URL {
headers: map
params: map
cookies: map
timeout: duration "30s"
body: any
request_type: string "json"
response_type: string
disable_verify_ssl: bool
certificate_bundle: string
statuses: string "200-299"
continue_on_error: bool
raw_body: bool
} -> object


Perform an HTTP OPTIONS request.

Parameters

Name Data Type Default Value Description
headers map 
-

The headers to send with the request.
params map 
-

Query string parameters to add to the request.
cookies map 
-

A map of cookie key=value pairs to include in the request.
timeout duration 
"30s"

The amount of time to wait for the request to complete.
body any 
-

The body of the request. This is processed according to what is specified in RequestType.
request_type string 
"json"

The type of data in Body, specifying how it should be encoded. Valid values are “raw”, “form”, and “json”
response_type string 
-

Specify how the response body should be decoded. Can be “raw”, or a MIME type that overrides the Content-Type response header.
disable_verify_ssl bool 
-

Whether to disable TLS peer verification.
certificate_bundle string 
-

The path to the root TLS CA bundle to use for verifying peer certificates.
statuses string 
"200-299"

A comma-separated list of numbers (e.g.: 200) or inclusive number ranges (e.g. 200-399) specifying HTTP statuses that are expected and non-erroneous.
continue_on_error bool 
-

Whether to continue execution if an error status is encountered.
raw_body bool 
-

Specify that absolutely no processing should be done on the response body.

Return Parameters

Name Data Type Description
status int

The numeric HTTP status code of the response.
status_text string

A textual description of the HTTP response code.
took int

The time (in millisecond) that the request took to complete.
headers map

Response headers sent back from the server.
content_type string

The MIME type of the response body (if any).
length int

The length of the response body in bytes.
body any

The decoded response body (if any).
error bool

If the response status is considered an error, and errors aren’t fatal, this will be true.

http::post URL {
headers: map
params: map
cookies: map
timeout: duration "30s"
body: any
request_type: string "json"
response_type: string
disable_verify_ssl: bool
certificate_bundle: string
statuses: string "200-299"
continue_on_error: bool
raw_body: bool
} -> object


Perform an HTTP POST request.

Parameters

Name Data Type Default Value Description
headers map 
-

The headers to send with the request.
params map 
-

Query string parameters to add to the request.
cookies map 
-

A map of cookie key=value pairs to include in the request.
timeout duration 
"30s"

The amount of time to wait for the request to complete.
body any 
-

The body of the request. This is processed according to what is specified in RequestType.
request_type string 
"json"

The type of data in Body, specifying how it should be encoded. Valid values are “raw”, “form”, and “json”
response_type string 
-

Specify how the response body should be decoded. Can be “raw”, or a MIME type that overrides the Content-Type response header.
disable_verify_ssl bool 
-

Whether to disable TLS peer verification.
certificate_bundle string 
-

The path to the root TLS CA bundle to use for verifying peer certificates.
statuses string 
"200-299"

A comma-separated list of numbers (e.g.: 200) or inclusive number ranges (e.g. 200-399) specifying HTTP statuses that are expected and non-erroneous.
continue_on_error bool 
-

Whether to continue execution if an error status is encountered.
raw_body bool 
-

Specify that absolutely no processing should be done on the response body.

Return Parameters

Name Data Type Description
status int

The numeric HTTP status code of the response.
status_text string

A textual description of the HTTP response code.
took int

The time (in millisecond) that the request took to complete.
headers map

Response headers sent back from the server.
content_type string

The MIME type of the response body (if any).
length int

The length of the response body in bytes.
body any

The decoded response body (if any).
error bool

If the response status is considered an error, and errors aren’t fatal, this will be true.

http::put URL {
headers: map
params: map
cookies: map
timeout: duration "30s"
body: any
request_type: string "json"
response_type: string
disable_verify_ssl: bool
certificate_bundle: string
statuses: string "200-299"
continue_on_error: bool
raw_body: bool
} -> object


Perform an HTTP PUT request.

Parameters

Name Data Type Default Value Description
headers map 
-

The headers to send with the request.
params map 
-

Query string parameters to add to the request.
cookies map 
-

A map of cookie key=value pairs to include in the request.
timeout duration 
"30s"

The amount of time to wait for the request to complete.
body any 
-

The body of the request. This is processed according to what is specified in RequestType.
request_type string 
"json"

The type of data in Body, specifying how it should be encoded. Valid values are “raw”, “form”, and “json”
response_type string 
-

Specify how the response body should be decoded. Can be “raw”, or a MIME type that overrides the Content-Type response header.
disable_verify_ssl bool 
-

Whether to disable TLS peer verification.
certificate_bundle string 
-

The path to the root TLS CA bundle to use for verifying peer certificates.
statuses string 
"200-299"

A comma-separated list of numbers (e.g.: 200) or inclusive number ranges (e.g. 200-399) specifying HTTP statuses that are expected and non-erroneous.
continue_on_error bool 
-

Whether to continue execution if an error status is encountered.
raw_body bool 
-

Specify that absolutely no processing should be done on the response body.

Return Parameters

Name Data Type Description
status int

The numeric HTTP status code of the response.
status_text string

A textual description of the HTTP response code.
took int

The time (in millisecond) that the request took to complete.
headers map

Response headers sent back from the server.
content_type string

The MIME type of the response body (if any).
length int

The length of the response body in bytes.
body any

The decoded response body (if any).
error bool

If the response status is considered an error, and errors aren’t fatal, this will be true.

Page Module

Commands for inspecting and manipulating the current DOM document and browser viewport.

page::clear_intercepts


Clear all request intercepts.

page::intercept MATCH {
body: any
file: string
wait_for_headers: bool
reject: bool
method: string
url: string
headers: map
post_data: map
statuses: []int
realm: string
username: string
password: string
persistent: bool
}


Intercept all requests where the requested URL matches match, and modify the request according to the provided arguments.

Parameters

Name Data Type Default Value Description
body any 
-

Rewrite the response body with the provided string or with the contents of an io.Reader.
file string 
-

Read the response body contents from the named file.
wait_for_headers bool 
-

Specify that the interception should wait for response headers to be sent. Otherwise the request is intercepted prior to making the request.
reject bool 
-

Should the request be aborted/rejected.
method string 
-

Rewrite the request method to this.
url string 
-

Rewrite the request URL to this value.
headers map 
-

Set the request headers. Not valid is WaitForHeaders is set.
post_data map 
-

Update the POST data to these values.
statuses []int 
-

Only apply to response HTTP status codes in this list.
realm string 
-

Send credentials in response to this realm. If empty, the provided credentials will be sent to any authentication challenge.
username string 
-

Username to authenticate with.
password string 
-

Password to authenticate with.
persistent bool 
-

Specify whether the intercept should persist after the first match.

page::pdf DESTINATION {
autoclose: bool true
}


Render the current page as a PDF document, writing it to the given filename or writable destination object.

Parameters

Name Data Type Default Value Description
autoclose bool 
true

Whether the given destination should be automatically closed for writing after the PDF is written.

page::remove SELECTOR {
parent: selector
} -> int


Remove all occurrences of the element(s) matching the given selector.

Parameters

Name Data Type Default Value Description
parent selector 
-

page::screenshot DESTINATION {
selector: selector
use: string "tallest"
width: int
height: int
x: int -1
y: int -1
format: string "png"
quality: int
autoclose: bool true
autoresize: bool true
} -> object


Render the current page as a PNG or JPEG image, writing it to the given filename or writable destination object.

If the filename is the string "temporary", a file will be created in the system’s temporary area (e.g.: /tmp) and the screenshot will be written there. It is the caller’s responsibility to remove the temporary file if desired. The temporary file path is available in the return object’s path parameter.

Parameters

Name Data Type Default Value Description
selector selector 
-

If specified, the screenshot will attempt to capture just the matching element.
use string 
"tallest"

Determines how to handle multiple elements that are matched by Selector. May be “tallest” or “first”.
width int 
-
height int 
-
x int 
-1
y int 
-1
format string 
"png"

The output image format of the screenshot. May be “png” or “jpeg”.
quality int 
-

The quality of the image used during encoding. Only applies to “jpeg” format.
autoclose bool 
true

Whether the given destination should be automatically closed for writing after the screenshot is written.
autoresize bool 
true

Automatically resize the screen to the width and height.

Return Parameters

Name Data Type Description
element element

Details about the element that matched the given selector (if any).
width int

The width of the screenshot (in pixels).
height int

The height of the screenshot (in pixels).
x int

The X position (relative to the viewport) the screenshot was taken at.
y int

The Y position (relative to the viewport) the screenshot was taken at.
path string

The filesystem path that the screenshot was written to.
size int

The size of the screenshot (in bytes).

page::source SELECTOR -> string


Return the source for the given element, or for the whole page.

page::text SELECTOR -> string


Return the text content for the given element, or for the whole page.

Parse Module

parse::json FILEORREADER -> any


Parses the given file as a JSON document and returns the resulting value.

parse::yaml FILEORREADER -> any


Parses the given file as a YAML document and returns the resulting value.

Url Module

url::encode_query QUERYMAP -> string


Take a map or previous URL response structure and encode the values into a string that can be used in another URL or form post data. This command does not automaticlly prepend a “?” character to the output.

url::escape STRINGORSTRUCT -> string


Escapes the string so it can be safely placed inside a URL path segment, replacing special characters (including /) with %XX sequences as needed.

url::parse U -> url


Parse the given URL string or structure, and return a structured representation of the various parts of a URL.

Return Parameters

Name Data Type Description
scheme string
host string
domain string
port int
path string
raw_query string
fragment string
query map
full string
url url

url::parse_query URLORQUERYSTRING -> map


Take a URL or map of query string key=value pairs and return a map of values.

Vars Module

vars::clear KEY


Unset the value at the given key.

vars::ensure KEY {
message: string
}


Emit an error if the given key does not exist, optionally with a user-specified message.

Parameters

Name Data Type Default Value Description
message string 
-

vars::get KEY {
fallback: any
} -> any


Return the value of a specific variable defined in a scope.

Parameters

Name Data Type Default Value Description
fallback any 
-

vars::interpolate FORMAT {
values: any
} -> string


Return a value interpolated with values from a scope or ones that are explicitly provided.

Parameters

Name Data Type Default Value Description
values any 
-

vars::keys -> []string


Return a sorted list of all variable names in the current scope.

vars::pop KEY -> any


Take the last value from the array at key. If key is an array, the last value of that array will be returned and the remainder will be left at key. Empty arrays will return nil and be unset. Non-array values will be returned and the key will be unset.

vars::push KEY {
value: any
}


Push the given value onto the array at the specified key, creating the array if not present, and converting the existing value into an array already set to non-array value.

Parameters

Name Data Type Default Value Description
value any 
-

vars::set KEY {
value: any
interpolate: bool true
} -> any


Set the named variable to the given value, optionally interpolating variables from the current scope into the variable.

Parameters

Name Data Type Default Value Description
value any 
-
interpolate bool 
true

Appendix

Time Formats

A special string can be used to specify how a given date value should be formatted for display. Diecast supports the same syntax as Golang’s time.Format function, as well as additional commonly-used formats.

Predefined Formats

Format String Example
kitchen “3:04PM”
timer “15:04:05”
rfc3339 “2006-01-02T15:04:05Z07:00”
rfc3339ns “2006-01-02T15:04:05.999999999Z07:00”
rfc822 “02 Jan 06 15:04 MST”
rfc822z “02 Jan 06 15:04 -0700”
rfc1123 “Mon, 02 Jan 2006 15:04:05 MST”
rfc1123z “Mon, 02 Jan 2006 15:04:05 -0700”
epoch “1136239445”
epoch-ms “1136239445999”
epoch-us “1136239445999999”
epoch-ns “1136239445999999999”
day “Monday”
slash “01/02/2006”
slash-dmy “02/01/2006”
ymd “2006-01-02”
ruby “Mon Jan 02 15:04:05 -0700 2006”
ansic “Mon Jan _2 15:04:05 2006”
ruby “Mon Jan 02 15:04:05 -0700 2006”
unixdate “Mon Jan _2 15:04:05 MST 2006”
stamp “Jan _2 15:04:05”
stamp-ms “Jan _2 15:04:05.000”
stamp-us “Jan _2 15:04:05.000000”
stamp-ns “Jan _2 15:04:05.000000000”

Custom Formats

You can also specify a custom format string by using the components the the reference date as an example to Diecast on how to translate the given date into the output you want. The reference date/time is: Mon Jan 2 15:04:05 MST 2006. In the predefined formats above, the examples given all use this reference date/time, and you can refer to those formats for building your own strings.

For example, given the date 2018-03-10T16:30:00, and the custom format string “Mon, January _1, 2006”, that date would be displayed as “Sat, March 10, 2018”. The format was built by providing examples from the reference date on how to do the conversion. The values used in the reference date have been carefully chosen to avoid any ambiguity when specifying custom formats.