Element

Element module contains function to interact with Elements found in the Browser.

`click! : Element => Result {} [ WebDriverError Str, ElementNotFound Str ]`

Click on a Element.

# find button element
button = browser |> Browser.find_element!(Css("#submit-button"))?
# click the button
button |> Element.click!()?

`get_text! : Element => Result Str [ WebDriverError Str, ElementNotFound Str ]`

Get text of the Element.

This function will return the displayed text in the Browser for this Element and it's children.

When the Element is not visible, then the text will be an empty Str.

# find button element
button = browser |> Browser.find_element!(Css("#submit-button"))?
# get button text
button_text = button |> Element.get_text!()?

`get_value! : Element => Result a [ ElementNotFound Str, PropertyTypeError Str, WebDriverError Str ] where a implements Decoding`

Get value of the Element.

When there is no value in this element then returns the default value for used type:

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

# find input element
input = browser |> Browser.find_element!(Css("#email-input"))?
# get input value
input_value = input |> Element.get_value!()?
input_value |> Assert.sh uld_be("my-email@fake-email.com")

# find input element
input = browser |> Browser.find_element!(Css("#age-input"))?
# get input value
input_value = input |> Element.get_value!()?
input_value |> Assert.should_be(18)

`is_selected! : Element => Result [ Selected, NotSelected ] [ WebDriverError Str, ElementNotFound Str ]`

Check if Element is selected.

Can be used on checkbox inputs, radio inputs, and option elements.

# find checkbox element
checkbox = browser |> Browser.find_element!(Css("#is-tasty-checkbox"))?
# get button text
is_tasty_state = checkbox |> Element.is_selected!()?
# asert expected value
is_tasty_state |> Assert.should_be(Selected)

`is_visible! : Element => Result [ Visible, NotVisible ] [ WebDriverError Str, ElementNotFound Str ]`

Check if Element is visible in the Browser.

# find error message element
error_msg = browser |> Browser.find_element!(Css("#error-msg"))?
# get button text
is_visible = checkbox |> Element.is_visible!()?
# assert expected value
is_visible |> Assert.should_be(Visible)

`get_attribute! : Element, Str => Result Str [ WebDriverError Str, ElementNotFound Str ]`

Get attribute of an Element.

Attributes are values you can see in the HTML DOM, like <input class"test" type="password" />

When the attribute is not present on the Element, this function will return empty Str.

# find input element
input = browser |> Browser.find_element!(Css("#email-input"))?
# get input type
input_type = input |> Element.get_attribute!("type")?

`get_attribute_or_empty! : Element, Str => Result (Result Str [Empty]) [ WebDriverError Str, ElementNotFound Str ]`

Get attribute of an Element.

Attributes are values you can see in the HTML DOM, like <input class"test" type="password" />

checkbox_type = checkbox |> Element.get_attribute_or_empty!("type")?
when checkbox_type is
    Ok(type) -> type |> Assert.should_be("checkbox")
    Err(Empty) -> Assert.fail_with("should not be empty")

`get_property! : Internal.Element, Str => Result a [ ElementNotFound Str, PropertyTypeError Str, WebDriverError Str ] where a implements Decoding`

Get property of an Element.

Properties are the keys that you get when using GetOwnProperty on a element in the browser.

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

# get input value
input_value = input |> Element.get_property!("value")?
# expect to have value "email@emails.com"
input_value |> Assert.should_be("email@emails.com")

Bool:

is_checked = name_input |> Element.get_property!("checked")?
is_checked |> Assert.should_be(Bool.false)

Bool as Str:

is_checked = name_input |> Element.get_property!("checked")?
is_checked |> Assert.should_be("false")

Num:

client_height = name_input |> Element.get_property!("clientHeight")?
client_height |> Assert.should_be(17)

`get_property_or_empty! : Element, Str => Result (Result a [Empty]) [ WebDriverError Str, ElementNotFound Str, PropertyTypeError Str ] where a implements Decoding`

Get property of an Element.

Properties are the keys that you get when using GetOwnProperty on a element in the browser.

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 Err(Empty) will be returned.

# get input value
input_value = input |> Element.get_property_or_empty!("value")?
# expect to have value "email@emails.com"
input_value |> Assert.should_be(Ok("email@emails.com"))

is_checked = name_input |> Element.get_property!("checked")?
when is_checked is
    Ok(value) -> value |> Assert.should_be(Bool.false)
    Err(Empty) -> Assert.fail_with("input should have a checked prop")

client_height = name_input |> Element.get_property!("clientHeight")?
client_height |> Assert.should_be(Ok(17))

`input_text! : Element, Str => Result {} [ WebDriverError Str, ElementNotFound Str ]`

Send a Str to a Element (e.g. put text into an input).

# find email input element
email_input = browser |> Browser.find_element!(Css("#email"))?
# input an email into the email input
email_input |> Element.send_keys!("my.fake.email@fake-email.com")?

Special key sequences:

{enter} - simulates an "enter" key press

# find search input element
search_input = browser |> Browser.find_element!(Css("#search"))?
# input text and submit
search_input |> Element.send_keys!("roc lang{enter}")?

`clear! : Internal.Element => Result {} [ WebDriverError Str, ElementNotFound Str ]`

Clear an editable or resetable Element.

# find button element
input = browser |> Browser.find_element!(Css("#email-input"))?
# click the button
input |> Element.clear!()?

`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>

`find_element! : Element, Locator => Result Element [ WebDriverError Str, ElementNotFound Str ]`

Find an Element inside the tree of another 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 = element |> Element.find_element!(Css("#my-id"))?

# find the html element with a css selector ".my-class"
button = element |> Element.find_element!(Css(".my-class"))?

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

`try_find_element! : Element, Locator => Result [ Found Element, NotFound ] [ WebDriverError Str, ElementNotFound Str ]`

Find an Element inside the tree of another 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.

maybe_button = element |> Element.try_find_element!(Css("#submit-button"))?

when maybe_button is
    NotFound -> Stdout.line!("Button not found")
    Found(el) ->
        button_text = el |> Element.get_text!()?
        Stdout.line!("Button found with text: $(button_text)")

`find_single_element! : Element, Locator => Result Element [ AssertionError Str, ElementNotFound Str, WebDriverError Str ]`

Find an Element inside the tree of another 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 = element |> Element.find_single_element!(Css("#submit-button"))?

`find_elements! : Element, Locator => Result (List Element) [ WebDriverError Str, ElementNotFound Str ]`

Find all Elements inside the tree of another Element 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 in the DOM tree of **element**
list_items = element |> Element.find_elements!(Css("#my-list li"))?

`get_tag_name! : Element => Result Str [ WebDriverError Str, ElementNotFound Str ]`

Get the HTML tag name of an Element.

# find input element
input = browser |> Browser.find_element!(Css("#email-input"))?
# get input tag name
tag_name = input |> Element.get_tag_name!()?
# tag name should be "input"
tag_name |> Assert.should_be("input")

`get_css_property! : Element, Str => Result Str [ WebDriverError Str, ElementNotFound Str ]`

Get a css property of an Element.

# find input element
input = browser |> Browser.find_element!(Css("#email-input"))?
# get input type
input_border = input |> Element.get_css_property!("border")?
# assert
input_border |> Assert.should_be("2px solid rgb(0, 0, 0)")

`get_rect! : Element => Result ElementRect [ WebDriverError Str, ElementNotFound Str ]`

Get the position and size of the Element.

# find input element
input = browser |> Browser.find_element!(Css("#email-input"))?
# get input tag name
rect = input |> Element.get_rect!()?
# assert the rect
rect.height |> Assert.should_be(51)?
rect.width |> Assert.should_be(139)?
rect.x |> Assert.should_be_equal_to(226.1243566)?
rect.y |> Assert.should_be_equal_to(218.3593754)

`use_iframe! : Element, (Internal.Browser => Result {} ) => Result {}`

Switch the context to an iFrame.

This function runs a callback in which you can interact with the page inside an iFrame.

frame_el = browser |> Browser.find_element!(Css("iframe"))?

Element.use_iframe!(frame_el, |frame|
    span = frame |> Browser.find_element!(Css("#span-inside-frame"))?
    span |> Assert.element_should_have_text!("This is inside an iFrame")?
)