Module Webdriver.Make

Parameters

module IO : HTTP_CLIENT

Signature

WebDriver is a W3C specification to remote control a web browser. This allow you to simulate and test user interactions on your website in real life conditions, with javascript enabled, on as many browsers and operating systems you can get your hands on.

type json = Yojson.Safe.t
type 'a io = 'a IO.t

The client I/O monad, within which communication happens with the WebDriver server.

Commands

type session

A connection to the WebDriver server. A session statefully holds the active windows, tabs, cookies, and other state required by the browser.

type 'a cmd = session:session -> 'a io

Every browser command takes place within a session.

module Infix : sig ... end

Since the ~session parameter is generally constant, this module provides a reader monad to sequence multiple commands within the same session. You can either pass explicitly the ~session argument or open this module.

module Error : sig ... end

All potentital errors raised by the WebDriver protocol.

exception Webdriver of Error.t

Every command that fails raises this exception, which contains some hint as to what went wrong.

Sessions

In order to create a session, a connection to a WebDriver-compatible browser must be established:

module Capabilities : sig ... end

The requested capabilities when creating a new session.

module Session : sig ... end

For creating and deleting sessions manually.

val run : host:string -> Capabilities.t -> 'a cmd -> 'a io

run ~host capabilities cmd is a helper function to create a new session on host with the required capabilities, execute the cmd within that session, and finally ensure that the session is deleted on termination of cmd (from its natural death or an exception.)

module Timeouts : sig ... end

Configure the timeouts for page loads, script execution and the implicit wait when searching for elements on a page.

module Wait : sig ... end

Even though the browser attempts to complete most operations before giving back control, some commands might trigger too soon and raise an error. The recommended strategy is to sleep and retry the operation repeatedly until it succeeds.

val goto : string -> unit cmd

goto url ask the browser to visit the page at url.

val current_url : string cmd

The current url.

val back : unit cmd

Click the browser back button, to reload the previous url in history.

val forward : unit cmd

Click the forward button, to move forward to the next url in history.

val refresh : unit cmd

Refresh the current url.

Cookies management.

HTML Elements

type elt

An HTML element.

type using = [
  1. | `css
    (*

    CSS selectors, like "h1 span"

    *)
  2. | `link_text
    (*

    The exact text in an <a>...</a>

    *)
  3. | `partial_link_text
    (*

    The partial text present in a link

    *)
  4. | `tag_name
    (*

    the HTML tag name, like "h1" or "div"

    *)
  5. | `xpath
    (*

    XPath query

    *)
]

A strategy to find an element on a page.

val find_first : ?from:elt -> using -> string -> elt cmd

find_first `using "query" returns the first element that matches the query (interpreted with using). The element is searched inside the current frame of the current window, and if a ?from parent element is provided, the search takes place inside it.

raise (Webdriver { error = `no_such_element ; _ }) otherwise.

let* elt = find_first `css "h1 a" in ...
  let* elt = find_first `xpath "//h1//a" in ...
val find_all : ?from:elt -> using -> string -> elt list cmd

find_all `using "query" behaves like find_first, but returns a list of all elements matching the query.

val active : elt cmd

The currently focused element on the page.

Inspecting HTML elements

val text : elt -> string cmd

The inner text of an element, ignoring any other markup.

val tag_name : elt -> string cmd

The HTML tag of an element, for example "div".

val attribute : elt -> string -> string cmd

attribute e attr returns the value of the HTML attribute attr of the element e.

val property : elt -> string -> string option cmd

property e prop returns Some value of the DOM property prop of the element e, or None if undefined.

val is_selected : elt -> bool cmd

The boolean status of a checkbox, a radio or an option in a select.

val is_enabled : elt -> bool cmd

The boolean status of an interactive element.

val is_displayed : elt -> bool cmd

Determines if the element is visible.

val css : elt -> string -> string cmd

css e prop returns the computed value of the css property prop for the element e.

val aria_role : elt -> string cmd

aria_role e returns the accessibility role of the element e. See ARIA Roles on MDN

val aria_label : elt -> json cmd

aria_role e returns the accessibility label of the element e. See ARIA Labels on MDN

type rect = {
  1. x : float;
  2. y : float;
  3. width : float;
  4. height : float;
}
val rect : elt -> rect cmd

The position and size of an element on the page.

Interactions

val click : elt -> unit cmd

Performs a mouse click on this element.

val double_click : elt -> unit cmd

Performs a mouse double click on this element.

val submit : elt -> unit cmd

Submit a form element and its descendents.

val clear : elt -> unit cmd

Clears the content of an input element.

val send_keys : elt -> string -> unit cmd

send_keys e str sends the string str to an input element, as if typed from a keyboard. For special keys like enter or backspace, use the predefined values in the module Key:

send_keys my_input ("hello" ^ Key.enter)
module Key : sig ... end

Special keys on a keyboard.

type action

A sequence of interactions from a user device.

val perform : action list -> unit cmd

perform actions executes the sequence of actions for each input source. The actions are synchronized vertically, such that:

  perform [ mouse    [ `down button0 ; `pause  ; `up button0 ]
          ; keyboard [ `down "a"     ; `up "a" ; `pause      ]
          ]
  • The mouse starts a left click and the keyboard presses "a" simultaneously;
  • Then the keyboard releases the "a" key;
  • And finally the mouse releases the left click.

The `pause action does nothing and is used for synchronization.

The pressed keys and buttons stay pressed at the end of the interaction, unless explicitly released.

val release : unit cmd

release any pending keys or button from previous interactions.

Timing actions

type pause = [
  1. | `noop
    (*

    do nothing

    *)
  2. | `pause of int
    (*

    wait for duration (in ms)

    *)
]
val none : ?name:string -> pause list -> action

An inoperative device, that can be used to time the duration of each vertical frame.

val sleep : int -> unit cmd

sleep duration waits for duration in milliseconds before continuing.

Keyboard actions

type key = [
  1. | pause
  2. | `down of Key.t
    (*

    press down the key

    *)
  3. | `up of Key.t
    (*

    release a pressed key

    *)
]

A typing interaction from a keyboard.

val keyboard : ?name:string -> key list -> action

keyboard keys is an action that simulates the typing of keys from a keyboard. The currently active element will receive the key events.

val typing : string -> key list

typing keys is a helper function to produce an alternating sequence of `down key and `up key to simulate the typing of keys:

 typing "ab" = [`down "a" ; `up "a" ; `down "b" ; `up "b"]

The modifier Key.alt, Key.control, Key.meta and Key.shift will be pressed differently to trigger the desired shortcut:

 typing (Key.control ^ "a") (* CTRL-A *)
      = [`down Key.control ; `down "a" ; `up "a" ; `up Key.control]

Pointer actions

type move

A pointer movement to a new location, taking some duration of time (in milliseconds). The default duration is a teleportation in 0ms.

val absolute : ?duration:int -> (int * int) -> move

absolute (x, y) moves the pointer to the position (x, y) measured from the top left of the document.

val relative : ?duration:int -> (int * int) -> move

relative (dx, dy) moves the pointer by (dx, dy) from its current location.

val center : ?duration:int -> ?offset:(int * int) -> elt -> move

center ~offset:(dx, dy) elt moves the pointer to the center of the element elt offsetted by offset. The default offset is (0, 0).

type button = int

An integer representing the nth button on a mouse.

val button_left : button

The left mouse button (at position 0).

val button_middle : button

The middle mouse button (at position 1).

val button_right : button

The right mouse button (at position 2).

type pointer = [
  1. | pause
  2. | `cancel
    (*

    cancel the pointer current action

    *)
  3. | `down of button
    (*

    press down the button

    *)
  4. | `up of button
    (*

    release a pressed button

    *)
  5. | `move of move
    (*

    move the pointer

    *)
]

An action from a mouse/touch/pen device

val mouse : ?name:string -> pointer list -> action

mouse actions describes the movement, click, etc of a mouse pointer.

val touch : ?name:string -> pointer list -> action

touch actions describes the interactions of a touch finger device. If multiple touch devices are used in the same perform, they must have different names.

val pen : ?name:string -> pointer list -> action

pen actions describes the interactions of a pencil.

Scroll wheel actions

type scroll

A scroll movement, taking some duration of time in milliseconds.

val scroll_absolute : ?duration:int -> ?x:int -> ?y:int -> unit -> scroll

scroll_absolute ~x ~y () resets the scrollbar such that the position x, y falls into view, as measured from the top of the page. The default value of x and y is 0.

val scroll_to : ?duration:int -> ?dx:int -> ?dy:int -> elt -> scroll

scroll_to ~dx ~dy elt resets the scrollbar such that the center of the element elt, offsetted by (dx, dy), is inside the view. The default offset of dx and dy is 0.

type wheel = [
  1. | pause
  2. | `scroll of scroll
    (*

    scroll to a position

    *)
]

An action from the scroll wheel.

val wheel : ?name:string -> wheel list -> action

wheel scrolls performs the scrolling actions.

Document

val title : string cmd

The page title of the current document.

val source : string cmd

The HTML source code of the current document.

val print : string cmd

The current page, printed as a PDF.

val screenshot : ?elt:elt -> unit -> string cmd

Returns a PNG screenshot of the current page, or of the provided ?elt.

val switch_to_frame : [ `top | `id of int | `elt of elt ] -> unit cmd

Focus the selected frame inside the current document.

  • The `top frame is the current document root.
  • The `id n frame is the nth frame in the page.
  • The `elt e frame is the frame associated with the HTML element e.
val switch_to_parent_frame : unit cmd

Focus the parent of the currently selected frame.

module Window : sig ... end

Windows and tabs management.

module Alert : sig ... end

Popup management: alert, confirm and prompt

Javascript execution

val execute : string -> json cmd

excute "js" runs the js on the current page, returning its result in json.

val execute_async : string -> json cmd

excute_async "js" runs the js asynchronously on the current page.

This function terminates when the javascript callback arguments[0] is called, and returns its parameter as json. This can be used to block until some component has initialized:

    let* _ =
      execute_async
        {| var k = arguments[0]; something.onload(k); |}
    in
    (* blocks until onload triggers k *)