Merge pull request #3932 from vmuzikar/KEYCLOAK-4169

KEYCLOAK-4169 Instructions on how to run UI and Welcome Page tests

testsuite/integration-arquillian/HOW-TO-RUN.md

@@ -205,6 +205,38 @@ This will start latest Keycloak and import the realm JSON file, which was previo
       -Dmigrated.auth.server.version=1.9.8.Final
 
 
+## UI tests
+The UI tests are real-life, UI focused integration tests. Hence they do not support the default HtmlUnit browser. Only the following real-life browsers are supported: Mozilla Firefox, Google Chrome and Internet Explorer. For details on how to run the tests with these browsers, please refer to [Different Browsers](#different-browsers) chapter.
+
+The UI tests are focused on the Admin Console as well as on some login scenarios. They are placed in the `console` module and are disabled by default.
+
+The tests also use some constants placed in [test-constants.properties](tests/base/src/test/resources/test-constants.properties). A different file can be specified by `-Dtestsuite.constants=path/to/different-test-constants.properties`
+
+#### Execution example
+```
+mvn -f testsuite/integration-arquillian/tests/other/console/pom.xml \
+    clean test \
+    -Dbrowser=firefox \
+    -Dfirefox_binary=/opt/firefox-45.1.1esr/firefox
+```
+
+## Welcome Page tests
+The Welcome Page tests need to be run on WildFly/EAP and with `-Dskip.add.user.json` switch. So that they are disabled by default and are meant to be run separately.
+
+```
+# Prepare servers
+mvn -f testsuite/integration-arquillian/servers/pom.xml \
+    clean install \
+    -Pauth-server-wildfly \
+    -Papp-server-wildfly
+
+# Run tests
+mvn -f testsuite/integration-arquillian/tests/base/pom.xml \
+    clean test \
+    -Dtest=WelcomePageTest \
+    -Dskip.add.user.json \
+    -Pauth-server-wildfly
+```
 
 ## Social Login
 The social login tests require setup of all social networks including an example social user. These details can't be 
@@ -250,8 +282,17 @@ To run the tests run:
 
 ## Different Browsers
  
-To run with Chrome add `-Dbrowser=chrome`. Depending on the Chrome version you have you may need to download the latest
+#### Mozilla Firefox
-chromedriver from https://sites.google.com/a/chromium.org/chromedriver/downloads and point to it with 
+* **Supported version:** [latest ESR](https://www.mozilla.org/en-US/firefox/organizations/) (Extended Support Release)
-`-Dwebdriver.chrome.driver=/path/to/chromedriver`.
+* **Driver download required:** no
- 
+* **Run with:** `-Dbrowser=firefox`; optionally you can specify `-Dfirefox_binary=path/to/firefox/binary`
-    
+
+#### Google Chrome
+* **Supported version:** latest stable
+* **Driver download required:** [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/) which corresponds with your version of the browser
+* **Run with:** `-Dbrowser=chrome -Dwebdriver.chrome.driver=path/to/chromedriver`
+
+#### Internet Explorer
+* **Supported version:** 11
+* **Driver download required:** [Internet Explorer Driver Server](http://www.seleniumhq.org/download/); recommended version [2.53.1 32-bit](http://selenium-release.storage.googleapis.com/2.53/IEDriverServer_Win32_2.53.1.zip)
+* **Run with:** `-Dbrowser=internetExplorer -Dwebdriver.ie.driver=path/to/IEDriverServer.exe`

testsuite/integration-arquillian/README.md

@@ -29,7 +29,7 @@ Testsuite supports running server on Wildfly/EAP. For this it's necessary to:
 
 The cluster setup for server can be enabled by activating profile `auth-server-cluster`.
 
-The cluster setup is not supported for server on Undetow. Profile `auth-server-wildfly` or `auth-server-eap` needs to be activated.
+The cluster setup is not supported for server on Undertow. Profile `auth-server-wildfly` or `auth-server-eap` needs to be activated.
 
 The setup includes:
 - a `mod_cluster` load balancer on Wildfly
@@ -84,9 +84,12 @@ and the URL hierarchy is modeled by the class inheritance hierarchy (subclasses/
 
 ### Browsers
 
-The default browser for UI testing is `phantomjs` which is used for fast "headless" testing.
+The default browser for UI testing is `htmlunit` which is used for fast "headless" testing.
 Other browsers can be selected with the `-Dbrowser` property, for example `firefox`.
-See Arquillian Graphene documentation for more details.
+See [HOW-TO-RUN.md](HOW-TO-RUN.md) and Arquillian Graphene documentation for more details.
+
+### Utils classes
+UI testing is sometimes very tricky due to different demands and behaviours of different browsers and their drivers. So there are some very useful Utils classes which are already dealing with some common stability issues while testing. See `UIUtils`, `URLUtils` and `WaitUtils` classes in the Base Testsuite.
 
 
 ## Test Modules