diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 3dca3d7f..69db6281 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -70,6 +70,10 @@ jobs: if: ${{ matrix.os == 'ubuntu' }} run: sudo apt-get -y install x11-utils + - name: Install Linux Windows Manager + if: ${{ matrix.os == 'ubuntu' }} + run: sudo apt-get -y install fluxbox + - uses: actions/checkout@v3 - name: Clojure deps cache diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index cd4b8cac..961da943 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -8,6 +8,8 @@ A release with an intentional breaking changes is marked with: == Unreleased * https://github.com/clj-commons/etaoin/issues/503[#503]: Address Clojure interop issue introduced by new Thread/sleep signature in JDK 19 +* docs: +** https://github.com/clj-commons/etaoin/issues/447[#447]: Describe testing without a display in the link:doc/01-user-guide.adoc#headless-testing[user guide], including a new requirement for a windows manager when using a virtual display on Linux == v1.0.38 [minor breaking] diff --git a/Dockerfile b/Dockerfile index 044804fc..15b0bc20 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -FROM eclipse-temurin:8 +FROM clojure:temurin-17-tools-deps RUN apt-get -yqq update && \ apt-get -yqq upgrade && \ @@ -9,6 +9,7 @@ RUN apt-get -yqq update && \ apt-get -yqq install git xvfb curl unzip && \ apt-get -yqq install fonts-ipafont-gothic xfonts-100dpi xfonts-75dpi xfonts-scalable xfonts-cyrillic && \ apt-get install -y ca-certificates jq libfontconfig libgconf-2-4 && \ + apt-get install -y fluxbox && \ rm -rf /var/lib/apt/lists/* # This dockerfile is not amenable to layer updates because nothing changes diff --git a/bb.edn b/bb.edn index 005941b1..2eb06d8d 100644 --- a/bb.edn +++ b/bb.edn @@ -51,6 +51,7 @@ "docker run -it --rm -v" (str (fs/cwd) ":/etaoin") "-w" "/etaoin" + "--entrypoint" "/bin/bash" "etaoin:latest" *command-line-args*)} ci-release {:doc "release tasks, use --help for args" diff --git a/doc/01-user-guide.adoc b/doc/01-user-guide.adoc index 75ee66de..00482202 100644 --- a/doc/01-user-guide.adoc +++ b/doc/01-user-guide.adoc @@ -2410,7 +2410,46 @@ Once you've got a profile path, launch a driver with the `:profile` key as follo (def firefox-driver (e/firefox {:profile ff-profile})) ---- -== Writing Integration Tests For Your Application +== Writing and Running Integration Tests For Your Application + +=== Headless Testing [[headless-testing]] +Is is not unusual for Continuous Integration services to have no display. +This seems to be especially true for Linux runners. + +When running your tests on Linux with no display, you have 2 choices: + +* run the WebDriver in <> mode +* use a virtual display + +NOTE: Things being what they are, WebDrivers can behave differently when run headless. + +The technologies we use for Etaoin's CI testing on GitHub Actions for Linux are: + +* Xvfb - acts as an X virtual display +* fluxbox - a lightweight windows manager (needed by geckodriver/Firefox to support window positioning operations) + +You can see how we make use of these tools in the Etaoin link:/script/test.clj[test script], but in a nutshell: + +To install: +[source,shell] +---- +sudo apt get install -y xvfb fluxbox +---- + +TIP: As of this writing Xvfb is pre-installed on the linux runner on GitHub Actions, but fluxbox is not. + +Ensure `DISPLAY` env var is set: +[source,shell] +---- +export DISPLAY=:99.0 +---- + +Launch the virtual display and fluxbox: +[source,shell] +---- +Xvfb :99 -screen 0 1024x768x24 & +fluxbox -display :99 & +---- === Basic Fixture diff --git a/script/test.clj b/script/test.clj index 4437197e..86f9278e 100644 --- a/script/test.clj +++ b/script/test.clj @@ -63,6 +63,12 @@ (Thread/sleep 500) (recur)))))))) +(defn- launch-fluxbox [] + (if (fs/which "fluxbox") + (process/process "fluxbox -display :99" {:out (fs/file "/dev/null") + :err (fs/file "/dev/null")}) + (status/die 1 "fluxbox not found"))) + (defn- running-in-docker? [] (fs/exists? "/.dockerenv")) @@ -148,7 +154,8 @@ Notes: test-cmd-args (concat cp-args test-runner-args)] (when virtual-display? (status/line :head "Launching virtual display") - (launch-xvfb)) + (launch-xvfb) + (launch-fluxbox)) (status/line :head "Running %s tests on %s%s" test-id platform