From 53fcb51c8f0bee3a65b85946b7a609302fa5eb1c Mon Sep 17 00:00:00 2001 From: Kirill Merkushev Date: Mon, 27 Nov 2017 14:15:23 +0300 Subject: [PATCH] documentation and defaults improvements (#286) documentation and defaults improvements * mention about cm start cmd, rm VOLUME from dockerfile * rm vnc mention --- Dockerfile | 4 +- docs/cli-flags.adoc | 17 +-- docs/index.adoc | 3 +- docs/quick-start-guide.adoc | 158 +++++++++++++++++++++------- docs/reloading-configuration.adoc | 8 +- docs/special-capabilities.adoc | 169 ++++++++++++++++-------------- docs/usage-statistics.adoc | 6 +- docs/video.adoc | 75 +++++++++++++ docs/windows.adoc | 35 ++++++- main.go | 2 +- 10 files changed, 341 insertions(+), 136 deletions(-) create mode 100644 docs/video.adoc diff --git a/Dockerfile b/Dockerfile index 404d2a3c..849a46a4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -4,4 +4,6 @@ RUN apk add -U tzdata && rm -Rf /var/cache/apk/* COPY selenoid /usr/bin EXPOSE 4444 -ENTRYPOINT ["/usr/bin/selenoid", "-listen", ":4444", "-conf", "/etc/selenoid/browsers.json"] +ENTRYPOINT ["/usr/bin/selenoid"] + +CMD ["-listen", ":4444", "-conf", "/etc/selenoid/browsers.json", "-video-output-dir", "/opt/selenoid/video/"] diff --git a/docs/cli-flags.adoc b/docs/cli-flags.adoc index 11c944a9..b8214c48 100644 --- a/docs/cli-flags.adoc +++ b/docs/cli-flags.adoc @@ -1,7 +1,8 @@ == Selenoid CLI Flags -The following flags are supported by ```selenoid``` command: -``` +The following flags are supported by `selenoid` command: + +---- -capture-driver-logs Whether to add driver process logs to Selenoid output -conf string @@ -36,21 +37,23 @@ The following flags are supported by ```selenoid``` command: Session idle timeout in time.Duration format (default 1m0s) -version Show version and exit -``` +-video-output-dir + Directory to save recorded video to (default "video") +---- + For example: ``` -$ ./selenoid -conf /my/custom/browsers.json -limit 10 +$ ./selenoid -conf ~/.aerokube/selenoid/browsers.json -limit 10 ``` When using Selenoid inside Docker container these flags are passed like the following: - [source,bash,subs="attributes+"] ---- # docker run -d --name selenoid \ -p 4444:4444 \ - -v /etc/selenoid:/etc/selenoid:ro \ + -v ~/.aerokube/selenoid/:/etc/selenoid/:ro \ -v /var/run/docker.sock:/var/run/docker.sock \ aerokube/selenoid:latest-release \ - -conf /my/custom/browsers.json -limit 10 + -conf /etc/selenoid/browsers.json -limit 10 -video-output-dir /opt/selenoid/video/ ---- diff --git a/docs/index.adoc b/docs/index.adoc index 652bb3be..12b48f8c 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -17,6 +17,7 @@ It is using Docker to launch browsers. Please refer to https://github.com/aeroku == Getting Started include::quick-start-guide.adoc[leveloffset=+1] +include::windows.adoc[leveloffset=+1] include::browser-images.adoc[leveloffset=+1] == Configuration @@ -25,9 +26,9 @@ include::browsers-configuration-file.adoc[leveloffset=+1] include::logging-configuration-file.adoc[leveloffset=+1] include::updating-browsers.adoc[leveloffset=+1] include::timezone.adoc[leveloffset=+1] +include::video.adoc[leveloffset=+1] include::reloading-configuration.adoc[leveloffset=+1] include::docker-compose.adoc[leveloffset=+1] -include::windows.adoc[leveloffset=+1] include::log-files.adoc[leveloffset=+1] include::cli-flags.adoc[leveloffset=+1] diff --git a/docs/quick-start-guide.adoc b/docs/quick-start-guide.adoc index a8afe41f..f260b73d 100644 --- a/docs/quick-start-guide.adoc +++ b/docs/quick-start-guide.adoc @@ -1,55 +1,137 @@ == Quick Start Guide -. Download and run http://aerokube.com/cm/latest/[Configuration Manager] from https://github.com/aerokube/cm/releases/latest[releases] page. -+ -**On Linux:** - $ curl -L -o cm https://github.com/aerokube/cm/releases/download/1.2.4/cm_linux_amd64 - $ chmod +x ./cm - $ ./cm selenoid start --vnc +[TIP] +==== +The fastest way to start is http://aerokube.com/cm/latest/[Configuration Manager], which can be downloaded +from https://github.com/aerokube/cm/releases/latest[releases] page. This tool will do all preparations automatically. +Please refer to corresponding http://aerokube.com/cm/latest/[Quick Start with Configuration Manager] section. -+ -**On Mac:** +So all the content of this page can be simplified to only: - $ curl -L -o cm https://github.com/aerokube/cm/releases/download/1.2.4/cm_darwin_amd64 - $ chmod +x ./cm - $ ./cm selenoid start --vnc +---- +./cm selenoid start +---- -+ -**On Windows** - just download the binary with your browser or if you have https://en.wikipedia.org/wiki/PowerShell[Powershell] type: +This guide will show how to start Selenoid manually. +==== - > curl -L -o cm.exe https://github.com/aerokube/cm/releases/download/1.2.4/cm_windows_amd64 - > ./cm.exe selenoid start --vnc +WARNING: This Guide assumes you already know how to deal with command line and Docker in case of docker commands. +Please take a look to CM first in any case. -+ -[NOTE] -==== -. If you have https://docs.docker.com/engine/installation/[Docker] installed you can also use this one-liner: -[source,bash,subs="attributes+"] -# docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v ${HOME}:/root -e OVERRIDE_HOME=${HOME} aerokube/cm:latest-release selenoid start --vnc --tmpfs 128 +=== Prepare -. If you are working behind proxy you should set environment variables `HTTP_PROXY`, `HTTPS_PROXY` or `NO_PROXY` described in https://docs.docker.com/engine/admin/systemd/#runtime-directory-and-storage-driver[Docker documentation]: -[source,bash,subs="attributes+"] -$ HTTP_PROXY=http://proxy.example.com:80/ ./cm selenoid start -+ -When running `cm` in container - pass variable via `-e` flag of the `docker` command. These variables work because `cm` is using the same client as `docker` command. -==== +- Create `config/browsers.json` configuration file with content: + +.config/browsers.json +[source,javascript] +---- +{ + "firefox": { + "default": "57.0", + "versions": { + "57.0": { + "image": "selenoid/vnc:firefox_57.0", + "port": "4444", + "path": "/wd/hub" + } + } + } +} +---- + +- Pull browser docker image with `docker pull selenoid/vnc:firefox_57.0`. -. Run your tests against Selenoid like you do with regular Selenium hub: +=== Run binary - http://localhost:4444/wd/hub +- Download binary for your operating system from https://github.com/aerokube/selenoid/releases/latest[releases] page +and save it as `selenoid` (or `selenoid.exe` on windows). -. Selenoid was created to be run in big Selenium clusters and thus has no built-in user interface. This is why trying to open an URL above in browser returns *404* and this is the expected behavior. If something does not work, you can easily check that Selenoid is running with `curl`: +NOTE: Add execution permission in case of *nix os-type with `chmod +x selenoid`. - $ curl http://localhost:4444/status +- Then run: -+ -A successful request should return a JSON with browser usage statistics. -. You can additionally use http://github.com/aerokube/selenoid-ui[Selenoid UI] to see browser screen or consumption statistics. The simplest way is to download and run its binary from https://github.com/aerokube/selenoid-ui/releases[releases] page and start it: +.*nix +---- +./selenoid +---- - $ ./selenoid-ui +.Windows +---- +selenoid.exe +---- -+ -See http://aerokube.com/selenoid-ui/latest/[UI documentation] for more installation options. By default UI is listening on port 8080. To start using it open the following page in your browser: +It should write to console something like: - http://localhost:8080/ +---- +2017/11/26 21:23:43 Loading configuration files... +2017/11/26 21:23:43 Loaded configuration from [config/browsers.json] + +... + +2017/11/26 21:23:43 Listening on :4444 +---- + +=== Run selenoid with docker + +If you have https://docs.docker.com/engine/installation/[Docker] installed you can omit downloading binary and run it inside of container. +Prepare config, pull browser image, then run: + +.*nix +[source,bash,subs="attributes+"] +---- +docker run -d \ +--name selenoid \ +-p 4444:4444 \ +-v /var/run/docker.sock:/var/run/docker.sock \ +-v `pwd`/config/:/etc/selenoid/:ro \ +aerokube/selenoid:latest-release +---- + +.Windows PowerShell +[source,bash,subs="attributes+"] +---- +> $current = $PWD -replace "\\", "/" -replace "C", "c" <1> +> docker run -d ` +--name selenoid ` +-p 4444:4444 ` +-v //var/run/docker.sock:/var/run/docker.sock ` +-v ${current}/config/:/etc/selenoid/:ro ` +aerokube/selenoid:latest-release +---- +<1> Simple macros to get $PWD with compatible form assumed your directory located on `C:` drive + + +=== Use it for tests + +Run your tests against Selenoid like you do with regular Selenium hub: + +.Tests endpoint +---- +http://localhost:4444/wd/hub +---- + +Selenoid was created to be run in big Selenium clusters and thus has no built-in user interface. +This is why trying to open an URL above in browser returns *404* and this is the expected behavior. +If something does not work, you can easily check that Selenoid is running with opening *status* url: + +.Current selenoid status +---- +http://localhost:4444/status +---- + +A successful request should return a JSON with browser usage statistics. +. You can additionally use http://github.com/aerokube/selenoid-ui[Selenoid UI] to see browser screen or consumption statistics. +The simplest way is to download and run its binary from https://github.com/aerokube/selenoid-ui/releases[releases] page and start it: + +---- +./selenoid-ui +---- + +See http://aerokube.com/selenoid-ui/latest/[UI documentation] for more installation options. +By default UI is listening on port 8080. To start using it open the following page in your browser: + +.UI default page with separate binary +---- +http://localhost:8080/ +---- diff --git a/docs/reloading-configuration.adoc b/docs/reloading-configuration.adoc index a1525b62..133383a7 100644 --- a/docs/reloading-configuration.adoc +++ b/docs/reloading-configuration.adoc @@ -18,7 +18,11 @@ $ curl -s http://example.com:4444/ping .Result [source,javascript] ---- -{"uptime":"2m46.854829503s","lastReloadTime":"2017-05-12 12:33:06.322038542 +0300 MSK","numRequests":42} +{ + "uptime": "2m46.854829503s", + "lastReloadTime": "2017-05-12 12:33:06.322038542 +0300 MSK", + "numRequests": 42 +} ---- -It returns `200 OK` when Selenoid operates normally. Additionally server uptime, last quota reload time and overall number of session requests from service startup are returned in JSON format. \ No newline at end of file +It returns `200 OK` when Selenoid operates normally. Additionally server uptime, last quota reload time and overall number of session requests from service startup are returned in JSON format. diff --git a/docs/special-capabilities.adoc b/docs/special-capabilities.adoc index e8d570cb..52b87d0b 100644 --- a/docs/special-capabilities.adoc +++ b/docs/special-capabilities.adoc @@ -1,112 +1,119 @@ == Special Capabilities -=== Live Browser Screen +Selenoid can improve some automation aspects with custom capabilities. +You can pass it in tests to enable/disable some features. -Selenoid supports showing browser screen during test execution. This works with containers having https://en.wikipedia.org/wiki/Virtual_Network_Computing[VNC] server installed. To see browser screen: -. Pass ```enableVNC``` capability in tests: -+ -``` +=== Live Browser Screen: enableVNC + +Selenoid supports showing browser screen during test execution. +This works with containers having https://en.wikipedia.org/wiki/Virtual_Network_Computing[VNC] server installed (VNC column of <>). +To see browser screen: + +.Type: boolean +---- enableVNC: true -``` -+ -Value should be boolean, not string. +---- -. Launch http://aerokube.com/selenoid-ui/latest/[Selenoid UI] to see the screen. +Then launch http://aerokube.com/selenoid-ui/latest/[Selenoid UI] to see the screen. -This works by proxying VNC port from started container to ```http://localhost:4444/vnc/``` where `````` is Selenium session ID. +This works by proxying VNC port from started container to ```http://localhost:4444/vnc/``` over WebSocket, where `````` is Selenium session ID. -=== Custom Screen Resolution +=== Custom Screen Resolution: screenResolution -Selenoid allows you to set custom screen resolution in containers being run. To do that simply pass ```screenResolution``` capability in your tests in form ```width x height x color-depth```: +Selenoid allows you to set custom screen resolution in containers being run: -``` +.Type: string, format: xx +---- screenResolution: "1280x1024x24" -``` -[NOTE] +---- +[WARNING] ==== -. This capability sets only screen resolution - not browser window size. Most of browsers have some default window size value this is why your screenshot size can be smaller than screen resolution specified in capability. You should manually resize window to desired width and height. +- This capability sets only screen resolution - not browser window size. +Most of browsers have some default window size value this is why your screenshot size can be smaller than screen resolution specified in capability. +You should manually resize window to desired width and height. -. So far as our containers run headless browsers in Xvfb without installed window manager `maximize` operation does not work. You need to use `setSize` method instead. +- So far as our containers run headless browsers in Xvfb without installed window manager `maximize` operation does not work. +You need to use `setSize` method instead. ==== -=== Video Recording +=== Video Recording: enableVideo, videoName, videoScreenSize -NOTE: This feature only works when browsers are run in containers. +NOTE: This feature requires some preparation. Please refer <