Documentation

openNewWindow : Task Browser [WebDriverError Str]

Opens a new Browser window.

Only the browser provided by the test will be closed automatically, please remember to close the browser windows you open manually.

newBrowser = Browser.openNewWindow!
...
browser |> Browser.closeWindow!

openNewWindowWithCleanup : (Browser -> Task val [WebDriverError Str]err) -> Task val [WebDriverError Str]err

Opens a new Browser window and runs a callback. Will close the browser after the callback is finished.

Browser.openNewWindowWithCleanup! \browser2 ->
    browser2 |> Browser.navigateTo! "https://www.roc-lang.org/"

closeWindow : Browser -> Task {} [WebDriverError Str]

Close a Browser window.

Do not close the browser provided by the test, the automatic cleanup will fail trying to close this browser.

newBrowser = Browser.openNewWindow!
...
browser |> Browser.closeWindow!

navigateTo : Browser, Str -> Task {} [WebDriverError Str]

Navigate the browser to the given URL.

# open google.com
browser |> Browser.navigateTo! "http://google.com"

getTitle : Browser -> Task.Task Str [WebDriverError Str]

Get browser title.

browser |> Browser.navigateTo! "http://google.com"
# get title
title = browser |> Browser.getTitle!
# title = "Google"

getUrl : Browser -> Task Str [WebDriverError Str]

Get current URL.

browser |> Browser.navigateTo! "http://google.com"
# get url
url = browser |> Browser.getUrl!
# url = "https://google.com/"

Locator

Supported locator strategies

Css Str - e.g. Css ".my-button-class"

TestId Str - e.g. TestId "button" => Css "[data-testid="button"]"

XPath Str - e.g. XPath "/bookstore/book[price>35]/price"

LinkText Str - e.g. LinkText "Examples" in <a href="/examples-page">Examples</a>

PartialLinkText Str - e.g. PartialLinkText "Exam" in <a href="/examples-page">Examples</a>

findElement : Browser, Locator -> Task Element [ WebDriverError Str, ElementNotFound Str ]

Find an Element in the Browser.

When there are more than 1 elements, then the first will be returned.

See supported locators at Locator.

# find the html element with a css selector "#my-id"
button = browser |> Browser.findElement! (Css "#my-id")

# find the html element with a css selector ".my-class"
button = browser |> Browser.findElement! (Css ".my-class")

# find the html element with an attribute [data-testid="my-element"]
button = browser |> Browser.findElement! (TestId "my-element")

tryFindElement : Browser, Locator -> Task [ Found Element, NotFound ] [ WebDriverError Str, ElementNotFound Str ]

Find an Element in the Browser.

This function returns a [Found Element, NotFound] instead of an error when element is not found.

When there are more than 1 elements, then the first will be returned.

See supported locators at Locator.

maybeButton = browser |> Browser.tryFindElement! (Css "#submit-button")

when maybeButton is
    NotFound -> Stdout.line! "Button not found"
    Found el ->
        buttonText = el |> Element.getText!
        Stdout.line! "Button found with text: $(buttonText)"

findSingleElement : Browser, Locator -> Task Element [ AssertionError Str, ElementNotFound Str, WebDriverError Str ]

Find an Element in the Browser.

This function will fail if the element is not found - ElementNotFound Str

This function will fail if there are more than 1 element - AssertionError Str

See supported locators at Locator.

button = browser |> Browser.findSingleElement! (Css "#submit-button")

findElements : Browser, Locator -> Task (List Element) [ WebDriverError Str, ElementNotFound Str ]

Find all Elements in the Browser.

When there are no elements found, then the list will be empty.

See supported locators at Locator.

# find all <li> elements in #my-list
listItems = browser |> Browser.findElements! (Css "#my-list li")

takeScreenshotBase64 : Browser -> Task Str [WebDriverError Str]

Take a screenshot of the whole document.

The result will be a base64 encoded Str representation of a PNG file.

base64PngStr = browser |> Browser.takeScreenshotBase64!

setWindowRect : Browser, SetWindowRectOptions -> Task.Task WindowRect [WebDriverError Str]

Set browser window position and/or size.

x - x position y - y position width - width height - height

The result will contain new dimensions.

warning - when running not headless, the input dimensions (x, y) are the outer bound dimensions (with the frame). But the result contain the dimension of the browser viewport!

newRect = browser |> Browser.setWindowRect! (Move { x: 400, y: 600 })
# newRect is { x: 406, y: 627, width: 400, height: 600 }

newRect = browser |> Browser.setWindowRect! (Resize { width: 800, height: 750 })
# newRect is { x: 300, y: 500, width: 800, height: 750 }

newRect = browser |> Browser.setWindowRect! (MoveAndResize { x: 400, y: 600, width: 800, height: 750 })
# newRect is { x: 406, y: 627, width: 800, height: 750 }

getWindowRect : Browser -> Task WindowRect [WebDriverError Str]

Get browser window position and size.

x - x position y - y position width - width height - height

warning - when running not headless, the result contains the x and y of the browser's viewport, without the frame.

rect = browser |> Browser.getWindowRect!
# rect is { x: 406, y: 627, width: 400, height: 600 }

navigateBack : Browser -> Task {} [WebDriverError Str]

Navigate back in the browser history.

browser |> Browser.navigateBack!

navigateForward : Browser -> Task {} [WebDriverError Str]

Navigate forward in the browser history.

browser |> Browser.navigateForward!

reloadPage : Browser -> Task {} [WebDriverError Str]

Reload the current page.

browser |> Browser.reloadPage!

maximizeWindow : Browser -> Task WindowRect [WebDriverError Str]

Maximize the Browser window.

Can fail when the system does not support this operation.

newRect = browser |> Browser.maximizeWindow!

minimizeWindow : Browser -> Task WindowRect [WebDriverError Str]

Minimize the Browser window.

Can fail when the system does not support this operation.

newRect = browser |> Browser.minimizeWindow!

fullScreenWindow : Browser -> Task WindowRect [WebDriverError Str]

Make the Browser window full screen.

Can fail when the system does not support this operation.

newRect = browser |> Browser.fullScreenWindow!

executeJs : Browser, Str -> Task {} [ WebDriverError Str, JsReturnTypeError Str ] where a implements Decoding

Execute JavaScript in the Browser.

browser |> Browser.executeJs! "console.log('wow')"

executeJsWithOutput : Browser, Str -> Task a [ WebDriverError Str, JsReturnTypeError Str ] where a implements Decoding

Execute JavaScript in the Browser and get the response.

This function can be used with types like: Bool, Str, I64, F64, etc. R2E will try to cast the browser response to the choosen type.

When the response is empty e.g. property does not exist, then the default value of the choosen type will be used:

• Str - ""
• Bool - Bool.false
• Num - 0

The output will be casted to expected Roc type:

 response = browser |> Browser.executeJsWithOutput! "return 50 + 5;"
 response |> Assert.shouldBe! 55

 response = browser |> Browser.executeJsWithOutput! "return 50.5 + 5;"
 response |> Assert.shouldBe! 55.5

 response = browser |> Browser.executeJsWithOutput! "return 50.5 + 5;"
 response |> Assert.shouldBe! "55.5"

 response = browser |> Browser.executeJsWithOutput! "return true"
 response |> Assert.shouldBe! "true"

 response = browser |> Browser.executeJsWithOutput! "return true"
 response |> Assert.shouldBe! Bool.true

The function can return a Promise.

executeJsWithArgs : Browser, Str, List JsValue -> Task a [ WebDriverError Str, JsReturnTypeError Str ] where a implements Decoding

Execute JavaScript in the Browser with arguments and get the response.

This function can be used with types like: Bool, Str, I64, F64, etc. R2E will try to cast the browser response to the choosen type.

The arguments is a list of:

JsValue : [String Str, Number F64, Boolean Bool, Null]

When the response is empty e.g. property does not exist, then the default value of the choosen type will be used:

• Str - ""
• Bool - Bool.false
• Num - 0

Args can only be used using the arguments array in js.

The output will be casted to expected Roc type:

 response = browser |> Browser.executeJsWithArgs! "return 50 + 5;" []
 response |> Assert.shouldBe! 55

 response = browser |> Browser.executeJsWithArgs! "return 50.5 + 5;" [Number 55.5, String "5"]
 response |> Assert.shouldBe! 55.5

The function can return a Promise.

Cookie

R2E cookie representation

Cookie : {
    name : Str,
    value : Str,
    domain : Str,
    path : Str,
    sameSite : SameSiteOption,
    secure : Bool,
    httpOnly : Bool,
    expiry : CookieExpiry,
}

CookieExpiry : [Session, MaxAge U32]

SameSiteOption : [None, Lax, Strict]

CookieExpiry

SameSiteOption : [ None, Lax, Strict ]

addCookie : Browser, NewCookie -> Task {} [WebDriverError Str]

Add a cookie in the Browser.

browser |> Browser.addCookie! { name: "myCookie", value: "value1" }

browser |> Browser.addCookie! {
    name: "myCookie",
    value: "value1",
    domain: "my-top-level-domain.com",
    path: "/path",
    sameSite: Lax,
    secure: Bool.true,
    httpOnly: Bool.true,
    expiry: MaxAge 2865848396, # unix epoch
}

deleteCookie : Browser, Str -> Task {} [ WebDriverError Str, CookieNotFound Str ]

Delete a cookie in the Browser by name.

browser |> Browser.deleteCookie! "myCookieName"

deleteAllCookies : Browser -> Task {} [WebDriverError Str]

Delete all cookies in the Browser.

browser |> Browser.deleteAllCookies!

getCookie : Browser, Str -> Task Cookie [ WebDriverError Str, CookieNotFound Str ]

Get a cookie from the Browser by name.

cookie1 = browser |> Browser.getCookie! "myCookie"
cookie1 |> Assert.shouldBe! {
    name: "myCookie",
    value: "value1",
    domain: ".my-domain.io",
    path: "/",
    sameSite: Lax,
    expiry: Session,
    secure: Bool.true,
    httpOnly: Bool.false,
}

getAllCookies : Browser -> Task (List Cookie) [ WebDriverError Str, CookieNotFound Str ]

Get all cookies from the Browser.

cookies = browser |> Browser.getAllCookies!
cookies |> List.len |> Assert.shouldBe! 3

getAlertText : Browser -> Task Str [ WebDriverError Str, AlertNotFound Str ]

Get alert/prompt text.

text = browser |> Browser.getAlertText!
text |> Assert.shouldBe "Are you sure to close tab?"

sendTextToAlert : Browser, Str -> Task {} [ WebDriverError Str, AlertNotFound Str ]

Input text in prompt.

browser |> Browser.sendTextToAlert! "my reply"
browser |> Browser.acceptAlert!

acceptAlert : Browser -> Task {} [ WebDriverError Str, AlertNotFound Str ]

Accept alert/prompt.

browser |> Browser.acceptAlert!

dismissAlert : Browser -> Task {} [ WebDriverError Str, AlertNotFound Str ]

Dismiss alert/prompt.

browser |> Browser.dismissAlert!

getPageHtml : Browser -> Task Str [WebDriverError Str]

Get the serialized DOM as HTML Str.

html = browser |> Browser.getPageHtml!
html |> Assert.shouldContainText "<h1>Header</h1>"