Etaoin Documentation

Etaoin is a pure Clojure implementation of the Webdriver protocol. It is designed to be a lightweight, fast, and Selenium-free alternative for automating browsers, testing frontend behavior, and simulating human actions.

Key features include:

• Browser Support: Currently supports Chrome, Firefox, Safari, and Edge.
• Connection Modes: Can connect to a remote WebDriver process or launch one automatically.
• Human-like Simulation: Capable of imitating human behavior such as delays and typos.
• Lightweight: Minimal dependencies and a compact structure centered around a single main namespace.

Etaoin supports CSS and XPath selectors. By default, the driver's :locator is set to "xpath".

Selector Types

1. Keywords: Any keyword (except :active) is treated as an HTML ID attribute (e.g., :uname becomes id="uname").
2. Strings:
   • If the driver is in XPath mode, strings are treated as XPath.
   • If the driver is in CSS mode, strings are treated as CSS.
3. Maps: Explicitly define the syntax using :xpath or :css keys.

Switching Locators

Use e/use-css or e/use-xpath to get a new driver instance configured with a different default locator.

;; Using a map with explicit CSS
(e/fill driver {:css "input#uname"} "value")

;; Switching the whole driver to CSS mode
(def driver-css (e/use-css driver))
(e/fill driver-css "input#uname" "value")

(e/fill driver {:css "input#uname[name='username']"} "CSS can be tricky, too")

In v0.4.0, the driver instance changed from being an atom to being a map.

Impact: If your code uses swap! or similar atom-manipulation functions on the driver instance, you must refactor your code. All internal functions that previously modified the driver atom now return a new version of the map instead.

To use Etaoin, you must add the library as a dependency and install the appropriate WebDrivers for the browsers you intend to control.

Clojure Users

Add to your project.clj:

[etaoin "1.1.43"]

Or to your deps.edn:

etaoin/etaoin {:mvn/version "1.1.43"}

Babashka Users

Add to your bb.edn:

etaoin/etaoin {:mvn/version "1.1.43"}

Tip: Babashka uses timbre for logging. To reduce noise, set the log level to :info:

(require '[taoensso.timbre :as timbre])
(timbre/set-level! :info)

Etaoin provides several ways to capture visual state:

• screenshot: Saves the entire visible page to a PNG file.
• screenshot-element: (Chrome/Firefox only) Captures a specific element.
• with-screenshots: A macro that takes a screenshot after every form executed within the block. Files are named using the pattern <webdriver-name>-<timestamp>.png.

;; Full page screenshot
(e/screenshot driver "path/to/image.png")

;; Element screenshot (Chrome/Firefox)
(e/screenshot-element driver {:tag :form} "element.png")

;; Automatic screenshots after every step
(e/with-screenshots driver "target/dir"
  (e/fill driver :uname "et")
  (e/fill driver :uname "ao"))

You can select an <option> from a <select> element using the click function by providing a selector that includes the target value or text.

Safari Quirk: Safari may require you to click the select element itself before clicking the specific option.

Etaoin provides a select convenience function that handles the Safari quirk automatically and selects the first option matching the provided text.

;; Click by value
(e/click driver [{:id :dropdown} {:value "o4"}])

;; Click by text
(e/click driver [{:id :dropdown} {:fn/text "bar three"}])

;; Using the convenience function (handles Safari quirk)
(e/select driver :dropdown "bar")

This experimental feature allows you to preview how documentation will look on cljdoc.org. You must push your changes to GitHub for a full preview (including links and images).

bb cljdoc-preview start
bb cljdoc-preview ingest
bb cljdoc-preview view
bb cljdoc-preview stop

Use js-execute to run synchronous JavaScript. You can pass arguments to the script, which are accessible via the arguments array in JS. To return data to Clojure, include a return statement in your script; Etaoin automatically converts the resulting JSON to EDN.

For asynchronous scripts (e.g., those using setTimeout), use js-async. You must call the callback function provided by WebDriver as the last argument in your script to signal completion.

;; Synchronous execution with arguments and return value
(e/js-execute driver "return {foo: arguments[0].val}" {:val "hello"})

;; Asynchronous execution
(e/js-async driver 
  "var callback = arguments[arguments.length-1];
   setTimeout(function() { callback('done'); }, 1000);")

To see which parts of the unit and doc tests are covered, run the test-coverage task. Results are output to ./target/clofidence/index.html. For best results, run this on macOS where all supported browsers are accessible.

bb test-coverage