Test.Runner.Browser

Browser automation.

This module lets you drive a real browser via the W3C WebDriver protocol.

See tests/src/Tests/Browser.gren for full usage examples.

Permissions

type alias Permissions =
{ httpPerm : Permission
, cpPerm : Permission
, fsPerm : Permission
}

Subsystem permissions needed for browser tests.

You can create these manually in your program's init, or if you trust the package to gather permissions for you, get them from the initialize convenient function.
initialize : (Permissions -> Task a) -> Task a

Convenience function to get a Permissions record.

Note: Because this is used as part of your application initialization, it implicitly gives the package unlimited permissions. If you want more control, you'll need to create your own Permissions record. See the README section on Subsystems and Permissions for an example.

Running Browser Tests

withSession : Permissions -> Options -> (Session -> Test) -> Test

Start an automated browser session.

This gives you a Session value that you can pass to the other functions in this module that manipulate or query the session.
type Options

Options for configuring the browser session. Create with options and customize with setVisibility and setPort.
options : Options

Default options: headless browser on port 9515.
setVisibility : Visibility -> Options -> Options

Set whether browser runs headless or with a visible window.
setPort : Int -> Options -> Options

Set the webdriver communicaiton port (default: 9515).
type Visibility
= Headless
| Visible

Whether Chrome runs with a visible window or headless. See setVisibility.
type Session

A browser session. You get this from withSession and is required for the browser interaction functions.

Navigation

getUrl : Session -> Task Error String

Get the current page URL.
getTitle : Session -> Task Error String

Get the current page title.

Finding Elements

findElement : String -> Session -> Task Error Element

Find a single element by CSS selector.
findElements : String -> Session -> Task Error (Array Element)

Find all elements matching a CSS selector.
type Element

A reference to a DOM element found via findElement or findElements.

Element Interaction

click : Element -> Session -> Task Error {}

Click an element.
sendKeys : String -> Element -> Session -> Task Error {}

Send keystrokes to an element. Use Test.Runner.Key for special keys like Enter, Escape, Backspace, etc.

import Test.Runner.Key as Key

-- Type text then press Enter:
Browser.sendKeys ("hello" ++ Key.enter) input session

Modifier keys (Key.shift, Key.control, Key.alt, Key.meta) are sticky — they stay held down and apply to subsequent characters until released with Key.null:

-- Type "HELlo" (shift held for first 3 chars, then released):
Browser.sendKeys (Key.shift ++ "hel" ++ Key.null ++ "lo") input session
clear : Element -> Session -> Task Error {}

Clear the contents of an input element.
getText : Element -> Session -> Task Error String

Get the visible text of an element.
getAttribute : String -> Element -> Session -> Task Error String

Get an attribute value of an element.

Screenshots

screenshot : Path -> Session -> Task Error Screenshot

Capture a screenshot of the current viewport and save it to the given path.
elementScreenshot : Element -> Path -> Session -> Task Error Screenshot

Capture a screenshot of a specific element and save it to the given path.
type Screenshot

A screenshot captured from the browser. Created by screenshot or elementScreenshot.

Errors

type Error
= ChromeDriverError String
| HttpError String
| FileSystemError String

Errors that can occur during a browser session.

  • ChromeDriverError means we got an error directly from chromedriver.
  • HttpError means we got an error trying to communicate with chromedriver.
  • FileSystemError means we got an error interacting with the filesystem (e.g. saving a screenshot).