cuic
expects that Chrome is installed in the running computer. After
that, you can launch an instance by using [[cuic.chrome/launch]]. By
default, the instance is launched in headless-mode, but this can be
changed by providing :headless false
option. Based on the selected
mode, cuic
sets appropriate defaults to browser's startup options.
If more customization is needed, the startup options can also be set
manually at the launch time. See [[cuic.chrome/launch]] for complete
reference of the available startup options.
;; launch headless chrome
(def headless-chrome (chrome/launch))
;; launch non-headless chrome
(def foreground-chrome (chrome/launch {:headless false}))
Since version 96, Chrome has a new headless mode that allows users to get the
full browser functionality (even run extensions). Between versions 96 to 108 it was
--headless=chrome, after version 109 --headless=new. cuic
supports both old and new
headless modes.
;; launch in old headless mode
(def old-headless-chrome (chrome/launch {:headless "old"}))
;; deprecated: equivalent with {:headless "old"} but may be removed in future
(def old-headless-chrome (chrome/launch {:headless true}))
;; launch in new headless mode
(def new-headless-chrome (chrome/launch {:headless "new"}))
If you're using a non-standard Chrome/Chromium installation, you can
provide the executable path as a parameter to the launch
invocation:
(def custom (chrome/launch {:headless false} "/custom/chrome/path"))
Each launched Chrome instance get their own user data directories, so
they don't interfere or share any state (like local storage or cookies)
with each other. When instances are terminated, their data directory is
removed as well. cuic
handles all of this setup and termination
logic automatically.
Launched instances may be terminated by using [[cuic.chrome/terminate]].
They also implement java.lang.AutoCloseable
so they can be used with
Clojure' with-open
macro:
(with-open [chrome (chrome/launch)]
;; use `chrome`
)
;; `chrome` is automatically terminated when `with-open` block ends
cuic
logs information about the lifecycle and stdout/stderr of the
launched browsers using clojure.tools.logging
. To obtain these logs,
you must configure your logging library implementation to include
cuic.chrome
(or cuic
) logger with the desired logging level:
FATAL
- unexpected non-recoverable errorsERROR
- unexpected but recoverable errorsDEBUG
- browser lifecycle eventsTRACE
- stdout and stderr of the browser processIn practice, you don't need the logging when you're developing the app and tests locally. However, when running the tests in CI environment, having a log file with
TRACE
level logging has turned out a valuable artifact when debugging test failures.
Once you've obtained a Chrome instance, you have three different options
to use it in cuic.core
functions:
cuic
's query functions
allow defining the browser explicitly, binding the retrieved element to
the used browser. See "Multi-browser testing" for more details).cuic.core/*browser*
variable and Clojure's binding
macro.
This is the recommended option for test runs (see testing guide
for more details).The next sections of this guide assume that you've set the default browser by using either methods two or three.
Can you improve this documentation? These fine people already did:
Matti Lankinen & Joona PiirainenEdit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close