[Docs] Jenkins Guide

docker/README.md

@@ -80,3 +80,7 @@ The following command will start a bash session in the container.
 ```
 docker run --rm -v $(pwd):/src -it --entrypoint=bash backstopjs/backstopjs
 ```
+
+
+## Jenkins Guide
+You could get a Jenkins Guide here: [Jenkins Guide](../examples/Jenkins)

examples/Jenkins/README.md

@@ -0,0 +1,161 @@
+# Jenkins Integration
+
+Here, we use the DooD (Docker-outside-of-Docker) to run the jenkins.
+
+For more info about DooD, we **HIGHLY** suggest to read [the blog](https://container-solutions.com/running-docker-in-jenkins-in-docker/) first.
+
+## Content
+- [Pre Conditions](#pre-conditions)
+- [Jenkins Master](#jenkins-master)
+- [Jenkins Slave](#jenkins-slave)
+- [Run BackstopJS](#run-backstopjs)
+
+## Pre Conditions
+1. Download docker bin file to the **HOST Machine**, from here: [Linux](https://download.docker.com/linux/static/stable/x86_64/), [Mac](https://download.docker.com/mac/static/stable/x86_64/)
+2. Download & Install docker to the **HOST Machine**: [Linux](https://docs.docker.com/install/linux/docker-ce/centos/), [Mac](https://download.docker.com/mac/stable/Docker.dmg)
+
+## Jenkins Master
+1. Pull the latest Jenkins LTS: 
+   ```
+   docker pull jenkins/jenkins:lts
+   ```
+2. Use RebuildJenkins/Dockerfile to rebuild image as "jenkins/jenkins2:lts": 
+   ```
+   docker build -t jenkins/jenkins2:lts .
+   ```
+3. Run Jenkins - Master
+
+   For more info about how to use the jenkins/jenkins:lts, please refer to: [https://github.com/jenkinsci/docker/blob/master/README.md](https://github.com/jenkinsci/docker/blob/master/README.md)
+
+   Here, create a '~/jenkins_home' docker volume on the HOST machine, that will survive the container stop/restart/deletion.
+
+   ``` 
+   docker run \
+       -p 8080:8080 \
+       -p 50000:50000 \
+       -v ~/jenkins_home:/var/jenkins_home \
+       -v /var/run/docker.sock:/var/run/docker.sock \
+       -v ~/Downloads/docker/docker:/usr/bin/docker \
+       --name jenkins2 \
+       -d \
+       --rm \
+       jenkins/jenkins2:lts
+   ```
+4. Open [http://127.0.0.1:8080/](http://127.0.0.1:8080/), and follow the jenkins guid to finish the installation.
+5. Install Additional Plugins in [http://127.0.0.1:8080/pluginManager/available](http://127.0.0.1:8080/pluginManager/available) with "Install without restart":
+   - HTML Publisher
+   - Post build task
+6. Go to [http://127.0.0.1:8080/script](http://127.0.0.1:8080/script), and execute the command to avoid blank html report issue.
+    ```
+    System.setProperty("hudson.model.DirectoryBrowserSupport.CSP"," ")
+    ```
+7. Create a Slave node
+   - Go to [http://127.0.0.1:8080/computer/](http://127.0.0.1:8080/computer/)
+   - Click "New Node", enter "Slave 1" to set as following: 
+     ![Screenshot](Attachments/Jenkins_NewNodeName.png)
+   - Set "Remote root directory" to "/home/jenkins", and set "Launch agent via Java Web Start" as following:
+     ![Screenshot](Attachments/Jenkins_ConfigNewNode.png)
+   - Click Save, and mark the secret for later use as following:
+     ![Screenshot](Attachments/Jenkins_AgentSecret.png)
+
+## Jenkins Slave
+1. Pull the latest Jenkins jnlp-slave: 
+   ```
+   docker pull jenkins/jnlp-slave
+   ```
+2. Use RebuildJenkinsJnlpSlave/Dockerfile to rebuild image as "jenkins/jnlp-slave2:latest": 
+   ```
+   docker build -t jenkins/jnlp-slave2 .
+   ```
+3. Start container for agent:
+   For more info about how to use jenkins/jnlp-slave2, please refer to: [https://github.com/jenkinsci/docker-jnlp-slave](https://github.com/jenkinsci/docker-jnlp-slave)
+   > Note: The master url should be **172.17.0.1:8080** between the docker containers
+   ```
+   docker run \
+        -v ~/jenkins_home:/home/jenkins \
+        -v /var/run/docker.sock:/var/run/docker.sock \
+        -v YOUR_DOCKER_BIN_FILE:/usr/bin/docker \
+        --name jenkins_agent_1 \
+        -d \
+        --rm \
+        jenkins/jnlp-slave2 -url http://172.17.0.1:8080 YOUR_SECRET Slave1
+   ```
+   For example:
+   ```
+   docker run \
+        -v ~/jenkins_home:/home/jenkins \
+        -v /var/run/docker.sock:/var/run/docker.sock \
+        -v ~/Downloads/docker/docker:/usr/bin/docker \
+        --name jenkins_agent_1 \
+        -d \
+        --rm \
+        jenkins/jnlp-slave2 -url http://172.17.0.1:8080 127b664578e071d8c5f78bc1f7c43500d1acefc043bff3572f880919a4595010 Slave1
+   ```
+4. You could see your agent working as below.
+   ![Screenshot](Attachments/Jenkins_SlaveReady.png)
+
+## Run BackstopJS
+1. Go to [http://127.0.0.1:8080/newJob](http://127.0.0.1:8080/newJob), and select a "Freestyle project" to create a job
+   ![Screenshot](Attachments/Jenkins_BackstopJob.png)
+2. Configure
+   - General: Set a project name **Backstop**, and set "Restrict where this project can be run" to "visual-regression-testing"
+     ![Screenshot](Attachments/Jenkins_General.png)
+   - Source Code Management: For a instance, you could clone or folk [https://github.com/garris/BackstopJS](https://github.com/garris/BackstopJS), and then set as following with your own git credential
+     ![Screenshot](Attachments/Jenkins_SourceControlManagement.png)
+   - Build Triggers: For examples, 
+     1) You could run daily test by setting: **Build periodically** to **H 08 * * 1-5**
+     2) You could Select **Poll SCM** and write "H/5 * * * *". This tells Jenkins to “ask” your repository every 5 minutes if there are changes. If there are any, trigger the job.
+   - Build: Add **Execute Shell**, and add following for a sample.
+     > Note: 
+     > 1) Please use sudo docker to run test. This is a security risk for DooD.
+     > 2) You mount any volumes to the container by using --volumes-from \<container name\>
+
+     ```
+     set +x
+     sudo docker pull backstopjs/backstopjs:latest
+     sudo docker run \
+         --workdir ${WORKSPACE} \
+         --volumes-from jenkins_agent_1 \
+         --rm \
+         --shm-size 2048m \
+         --name backstopjs \
+         --entrypoint=sh \
+         backstopjs/backstopjs:latest \
+         -c "cd docker/Jenkins/Sample/; backstop test"
+
+     # Debug Purpose: It will keep container there until job aborted
+     # sudo docker run \
+     #    --workdir ${WORKSPACE} \
+     #    --volumes-from jenkins_agent_1 \
+     #    --rm \
+     #    --shm-size 2048m \
+     #    --name backstopjs \
+     #    --entrypoint=sh \
+     #    backstopjs/backstopjs:latest \
+     #    -c "cd docker/Jenkins/Sample/; while true; do sleep 1; done"
+     ```
+   - Post-build Actions: 
+     1) Add **Post build task** to delete the not exiting container
+        ```
+        if [ "$(sudo docker ps -q -f name=backstopjs)" ]; then
+            sudo docker rm -f backstopjs
+        fi
+        ```
+        ![Screenshot](Attachments/Jenkins_PostBuildActions_DeleteContainer.png)
+
+     2) Add **Post build task** to avoid JUnite Test Report issue "Test reports were found but none of them are new. Did tests run?"
+        ``` 
+        cd docker/Jenkins/Sample/backstop_data/ci_report
+        touch *.xml
+        ```
+        ![Screenshot](Attachments/Jenkins_PostBuildActions_AvoidJUnitReportIssue.png)
+
+     3) Add **Publish HTML reports**, and set as following.
+        Note: The **HTML directory to archive** is: docker/Jenkins/Sample/backstop_data/ 
+        ![Screenshot](Attachments/Jenkins_PostBuildActions_PublishHTML.png)
+
+     4) Add **Publish JUnit test result report**, and set as following
+        ![Screenshot](Attachments/Jenkins_PostBuildActions_PublishJUnit.png)
+
+3. Run build - Get the HTML Report & JUnit Report
+   ![Screenshot](Attachments/Jenkins_Report.png)

examples/Jenkins/RebuildJenkins/Dockerfile

@@ -0,0 +1,11 @@
+FROM jenkins/jenkins:lts
+
+USER root
+RUN apt-get update \
+      && apt-get install -y sudo \
+      && rm -rf /var/lib/apt/lists/* \
+      && echo "jenkins ALL=NOPASSWD: ALL" >> /etc/sudoers
+
+USER jenkins
+#COPY plugins.txt /usr/share/jenkins/plugins.txt
+#RUN /usr/local/bin/plugins.sh /usr/share/jenkins/plugins.txt

examples/Jenkins/RebuildJenkins/plugins.txt

@@ -0,0 +1,71 @@
+script-security: 1.44
+command-launcher: 1.2
+cloudbees-folder: 6.4
+bouncycastle-api: 2.16.2
+structs: 1.14
+workflow-step-api: 2.15
+scm-api: 2.2.7
+workflow-api: 2.27
+junit: 1.24
+antisamy-markup-formatter: 1.5
+token-macro: 2.5
+build-timeout: 1.19
+credentials: 2.1.16
+ssh-credentials: 1.13
+plain-credentials: 1.4
+credentials-binding: 1.16
+timestamper: 1.8.10
+workflow-support: 2.18
+durable-task: 1.22
+workflow-durable-task-step: 2.19
+matrix-project: 1.13
+resource-disposer: 0.8
+ws-cleanup: 0.34
+ant: 1.8
+gradle: 1.28
+pipeline-milestone-step: 1.3.1
+jquery-detached: 1.2.1
+jackson2-api: 2.8.11.2
+ace-editor: 1.1
+workflow-scm-step: 2.6
+workflow-cps: 2.53
+pipeline-input-step: 2.8
+pipeline-stage-step: 2.3
+workflow-job: 2.21
+pipeline-graph-analysis: 1.6
+pipeline-rest-api: 2.10
+handlebars: 1.1.1
+momentjs: 1.1.1
+pipeline-stage-view: 2.10
+pipeline-build-step: 2.7
+pipeline-model-api: 1.2.9
+pipeline-model-extensions: 1.2.9
+apache-httpcomponents-client-4-api: 4.5.5-2.1
+jsch: 0.1.54.2
+git-client: 2.7.2
+git-server: 1.7
+workflow-cps-global-lib: 2.9
+display-url-api: 2.2.0
+mailer: 1.21
+branch-api: 2.0.20
+workflow-multibranch: 2.19
+authentication-tokens: 1.3
+docker-commons: 1.13
+workflow-basic-steps: 2.7
+docker-workflow: 1.17
+pipeline-stage-tags-metadata: 1.2.9
+pipeline-model-declarative-agent: 1.1.1
+pipeline-model-definition: 1.2.9
+workflow-aggregator: 2.5
+github-api: 1.90
+git: 3.9.0
+github: 1.29.0
+github-branch-source: 2.3.4
+pipeline-github-lib: 1.0
+mapdb-api: 1.0.9.0
+subversion: 2.10.6
+ssh-slaves: 1.26
+matrix-auth: 2.2
+pam-auth: 1.3
+ldap: 1.20
+email-ext: 2.62

examples/Jenkins/RebuildJenkinsJnlpSlave/Dockerfile

@@ -0,0 +1,9 @@
+FROM jenkins/jnlp-slave:latest
+
+USER root
+RUN apt-get update \
+      && apt-get install -y sudo \
+      && rm -rf /var/lib/apt/lists/* \
+      && echo "jenkins ALL=NOPASSWD: ALL" >> /etc/sudoers
+
+USER jenkins

examples/Jenkins/Sample/backstop.json

@@ -0,0 +1,62 @@
+{
+  "id": "demo",
+  "viewports": [
+    {
+      "label": "PC",
+      "width": 1920,
+      "height": 1080
+    },
+    {
+      "label": "iPhone6,6s,7,8",
+      "width": 375,
+      "height": 667
+    }
+  ],
+  "onBeforeScript": "puppet/onBefore.js",
+  "onReadyScript": "puppet/onReady.js",
+  "scenarios": [
+    {
+      "label": "demo",
+      "cookiePath": "",
+      "url": "https://garris.github.io/BackstopJS/",
+      "referenceUrl": "",
+      "readyEvent": "",
+      "readySelector": "",
+      "delay": 1000,
+      "hideSelectors": [],
+      "removeSelectors": [],
+      "hoverSelector": "",
+      "clickSelector": "",
+      "postInteractionWait": 1000,
+      "selectors": [],
+      "selectorExpansion": true,
+      "misMatchThreshold": 0.1,
+      "requireSameDimensions": true
+    }
+  ],
+  "paths": {
+    "bitmaps_reference": "backstop_data/bitmaps_reference",
+    "bitmaps_test": "backstop_data/bitmaps_test",
+    "engine_scripts": "backstop_data/engine_scripts",
+    "html_report": "backstop_data/html_report",
+    "ci_report": "backstop_data/ci_report"
+  },
+  "report": ["CI"],
+  "engine": "puppeteer",
+  "engineOptions": {
+    "ignoreHTTPSErrors": true,
+    "slowMo": 500,
+    "args": [
+      "--no-sandbox",
+      "--disable-setuid-sandbox",
+      "--disable-gpu",
+      "--force-device-scale-factor=1",
+      "--disable-infobars=true",
+      "--hide-scrollbars"
+    ]
+  },
+  "asyncCaptureLimit": 2,
+  "asyncCompareLimit": 20,
+  "debug": false,
+  "debugWindow": false
+}

examples/Jenkins/Sample/backstop_data/engine_scripts/puppet/clickAndHoverHelper.js

@@ -0,0 +1,19 @@
+module.exports = async (page, scenario) => {
+  var hoverSelector = scenario.hoverSelector;
+  var clickSelector = scenario.clickSelector;
+  var postInteractionWait = scenario.postInteractionWait; // selector [str] | ms [int]
+
+  if (hoverSelector) {
+    await page.waitFor(hoverSelector)
+    await page.hover(hoverSelector);
+  }
+
+  if (clickSelector) {
+    await page.waitFor(clickSelector)
+    await page.click(clickSelector);
+  }
+
+  if (postInteractionWait) {
+    await page.waitFor(postInteractionWait);
+  }
+};