diff --git a/doc/01-user-guide.adoc b/doc/01-user-guide.adoc index 6912e11..c1c1c3f 100644 --- a/doc/01-user-guide.adoc +++ b/doc/01-user-guide.adoc @@ -2057,93 +2057,117 @@ The available `with-postmortem` options are: == Driver Options [[driver-options]] -When creating a driver instance, a map of additional parameters can optionally be passed to tweak the WebDriver and web browser behaviour. +When creating a *WebDriver* instance, you can optionally include an options map to tweak the *WebDriver* and *web browser* behaviour. -Here, for example, we set an explicit path to the chrome WebDriver binary: +Here, for example, we set an explicit path to the chrome *WebDriver* binary: //:test-doc-blocks/skip [source,clojure] ---- (def driver (e/chrome {:path-driver "/Users/ivan/downloads/chromedriver"})) ---- +[id=opt-host,refext=`:host`] +=== `:host` for WebDriver +_Default:_ -[cols="70,30"] -|=== -| Option | Defaults +_Example:_ `:host "192.68.1.12"` -a|`:host` for *WebDriver* process. When: +When: -* omitted, creates a new local WebDriver process (unless `:webdriver-url` was specified). -* specified, attempts to connect to an existing running WebDriver process. -See <>. +* Specified, Etaoin attempts to connect to an existing running WebDriver process. +* Omitted, Etaoin creates a new local WebDriver process (unless <> is specified). -Alternative: see `:webdriver-url` below. +See also <>, <>. -Example: `:host "192.68.1.12"` -| +Alternative: see <>. -|`:port` for *WebDriver* process. -If `:port` is found to already in use when creating a new local WebDriver process (see `:host`), a random port will be automatically selected. + -See also <>. +[id=opt-port,reftext=`:port`] +=== `:port` for WebDriver -Example: `:port 9997` -a| Random port when lanching local WebDriver process, else varies by vendor: +_Default:_ Etaoin selects a random unused port when lanching a local WebDriver process. +When connecting to a remote WebDriver process, varies by vendor: * chrome `9515` * firefox `4444` * safari `4445` * edge `17556` -* phantom `8910` -a| `:webdriver-url` for *WebDriver* process. When: +_Example:_ `:port 9997` -* omitted, creates a new local WebDriver process (unless `:host` was specified). -* specified, attempts to connect to an existing running WebDriver process. +See also <>, <>. -See <>. +[id=opt-webdriver-url,reftext=`webdriver-url`] +=== `:webdriver-url` +_Default:_ -Alternative: see `:host` above. +_Example:_ `:web-driver-url "https://chrome.browserless.io/webdriver"` -Example: `"https://chrome.browserless.io/webdriver"` +When: -| +* Specified, Etaoin attempts to connect to an pre-existing running *WebDriver* process. +* Omitted, creates a new local *WebDriver* process (unless <> is specified). -| `:path-driver` to *WebDriver* binary. + -Typically used if your WebDriver is not on the PATH. +See <>. -Example: -`:path-driver "/Users/ivan/Downloads/geckodriver"` -a| As you would expect, varies by vendor: +Alternative: see <> above. + +[id=opt-path-driver,reftext=`:path-driver`] +=== `:path-driver` to WebDriver binary +_Default:_ Varies by browser vendor: * chrome `"chromedriver"` * firefox `"geckodriver"` * safari `"safaridriver"` * edge `"msedgedriver"` -* phantom `"phantomjs"` -| `:args-driver` specifies extra command line arguments to *WebDriver*. +_Example:_ `:path-driver "/Users/ivan/Downloads/geckodriver"` + +Typically used if your *WebDriver* binary is not on your `PATH`. + +[id=opt-args-driver,reftext=`:args-driver`] +=== `:args-driver` for WebDriver binary +_Default:_ + +_Example:_ `:args-driver ["--binary" "/path/to/firefox/binary"]` + +(geckodriver specific, you'd probably use <> instead) + +Specifies extra command line arguments to the *WebDriver* binary. -Example: `:args-driver ["-b" "/path/to/firefox/binary"]` -| +[id=opt-webdriver-failed-launch-retries,reftext=`:webdriver-failed-launch-retries`] +=== `:webdriver-failed-launch-retries` +_Default:_ -| `:webdriver-failed-launch-retries` +* `:safari` driver `4` +* all other drivers `0` -Introduced to compensate for mysterious but recoverable failed launches of safari driver. -a| - safari `4` (for a total of 5 tries) -- all other drivers `0` +_Example:_ `:webdriver-failed-launch-retries 3` -| `:path-browser` to *web browser* binary. + -Typically used if your browser is not on the PATH. +Introduced to compensate for mysterious but recoverable failed launches of safaridriver. -Example: `:path-browser "/Users/ivan/Downloads/firefox/firefox"` -| By default, the WebDriver process automatically finds the web browser. +[id=opt-path-browser,refext=`:path-browser`] +=== `:path-browser` to web browser binary -| `:args` specifies extra command line arguments to *web browser*, see your web browser docs for what is available. +_Default:_ , The *WebDriver* implementation will make an attempt to find the *web browser* binary. -Example: `:args ["--incognito" "--app" "http://example.com"]` -| +_Example:_ `:path-browser "/Users/ivan/Downloads/firefox/firefox` -a| `:log-level` *web browser* minimal console log level. +Typically used if your *web browser* binary is not on your `PATH`. + +[id=opt-args,refext=`:args`] +=== `:args` for web browser binary +_Default:_ + +_Example:_ `:args ["--incognito" "--app" "http://example.com"]` + +Specifies extra command line arguments for the *web browser* binary, see vendor docs for what is available. + +[id=opt-log-level,reftext=`:log-level`] +=== `:log-level` for the web browser console +_Default:_ `:all` + +_Example:_ `:log-level :err` + +*Web browser* minimal console log level. Only messages with this level and above will be collected. From least to most verbose: @@ -2155,97 +2179,131 @@ From least to most verbose: See <> -Example: `:log-level :err` +[id=opt-driver-log-level,reftext=`:driver-log-level`] +=== `:driver-log-level` + +_Default:_ -| `:all` +_Example:_ `:driver-log-level "INFO"` -a| `:driver-log-level` *WebDriver* minimal log level. +*WebDriver* minimal log level. values vary by browser driver vendor: * chrome & edge `"OFF"` `"SEVERE"` `"WARNING"` `"INFO"` or `"DEBUG"` * firefox `"fatal"` `"error"` `"warn"` `"info"` `"config"` `"debug"` or `"trace"` -* phantomjs `"ERROR"` `"WARN"` `"INFO"` `"DEBUG"` - -Example: `:driver-log-level "INFO"` - -a| * phantomjs `"INFO"` -a| `:log-stdout` and `:log-stderr` *WebDriver* stdout and stderr log files +[id=opt-log-stdout,reftext=`:log-stdout`] +[id=opt-log-stderr,reftext=`:log-sterr`] +=== `:log-stdout` & `:log-stderr` for WebDriver output -Specify `:inherit` to have WebDriver process output destination inherit from calling process (for example, the console). +_Default:_ no logging: `/dev/null`, on Windows `NUL` -Example: +_Example:_ [source,clojure] ---- :log-stdout "target/chromedriver-out.log" :log-stderr "target/chromedriver-err.log" ---- -| `/dev/null`, on Windows `NUL` -| `:profile` path to custom *web browser* profile, see <> +Specify `:inherit` to have WebDriver process output destination inherit from its calling process (for example, the console or some existing redirection to a file). + +[id=opt-profile,reftext=`:profile`] +=== `:profile` path to web browser profile + +_Default:_ -Example: + +_Example:_ `:profile "/Users/ivan/Library/Application Support/Firefox/Profiles/iy4iitbg.Test"` -| +Path to custom *web browser* profile, see <>. + +[id=opt-env,reftext=`:env`] +=== `:env` variables for WebDriver process +_Default:_ + +_Example:_ `:env {:MOZ_CRASHREPORTER_URL "http://test.com"}` + +Map of extra environment variables to use when launching the *Webdriver* process. + +[id=opt-size,reftext=`:size`] +=== `:size` of intial web browser window +_Default:_ `[1024 680]` + +_Example:_ `size: [640 480]` + +Initial *web browser* window width and height in pixels. + +[id=opt-url,reftext=`:url`] +=== `:url` to open in web browser -| `:env` map of environment variables for *WebDriver* process. +_Default:_ -Example: `:env {:MOZ_CRASHREPORTER_URL "http://test.com"}` -| +_Example:_ `:url "https://clojure.org"` -| `:size` initial *web browser* window width and height in pixels +Only works with Firefox at this time. -Example: `size: [640 480]` -| [1024 680] +[id=opt-user-agent,reftext=`:user-agent`] +=== `:user-agent` for web browser +_Default:_ , Governed by WebDriver/web browser vendor -| `:url` default URL to open in *web browser*.+ -Only works in Firefox at this time. +_Example:_ `:user-agent "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)"` -Example: `:url "https://clojure.org"` -| +Overrides the web browser returned `User-Agent` header. -| `:user-agent` overrides the *web browser* `User-Agent`. -Useful for headless mode. -See <>. +[id=opt-download-dir,reftext=`:download-dir`] +=== `:download-dir` for web browser +_Default:_ , Governed by web browser vendor -Example: `:user-agent "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)"` -| Default is governed by WebDriver vendor. +_Example:_ `:download-dir "target/chrome-downloads"` -| `:download-dir` directory for *web browser* downloads files. -See <> +The directory where the *web browser* downloads files. -Example: `:download-dir "target/chrome-downloads"` -| Default is governed by browser vendor. +[id=opt-headless,reftext=`:headless`] +=== `:headless` web browser -| `:headless` run the *web browser* without a UI. +_Default:_ Normally `false`, but automatically `true` for driver creation functions like `chrome-headless`, `with-chrome-headless`, etc. + +_Example:_ `:headless true` + +Run the web browser without a user interface. See <>. -Example `:headless true` -| Normally `false`, but automatically set for driver creation functions like `chrome-headless`, `with-chrome-headless` etc. +[id=opt-prefs,reftext=`:prefs`] +=== `:prefs` for web browser + +_Default:_ + +_Example:_ see one usage in <>. + +Map of *web browser* specific preferences. -| `:prefs` map of *web browser* specific preferences. +[id=opt-proxy,reftext=`:proxy`] +=== `:proxy` for web browser -Example: see one usage in <>. -| +_Default:_ -| `:proxy` to set *web browser* proxy. +_Example:_ See <> -Example: see <>. -| +[id=opt-load-strategy,reftext=`:load-strategy`] +=== `:load-strategy` -| `:load-strategy` controls how long the *WebDriver* should wait before interacting with a page. +_Default:_ `:normal` + +_Example:_ `:load-strategy :none` + +Controls how long the *WebDriver* should wait before interacting with a page. See <>. -Example: `:load-strategy :none` -| `:normal` +[id=opt-capabilities,reftext=`:capabilities`] +=== `:capabilities` -| `:capabilities` *WebDriver*-specific options. -Read vendor docs for WebDriver before setting anything here. -You'll find an example usage under <>. -| +_Default:_ -|=== +_Example:_ See <> for an example usage. + +A *WebDriver*'s capabilities can be vendor specific and define preferred options. +Read WebDriver vendor docs before setting anything here. +While reading docs, note that Etaoin passes along `:capabilities` as `desiredCapabilties`. === Using Headless Drivers [[headless]]