keycloak-aplcache

diff --git a/testsuite/integration-arquillian/README.md b/testsuite/integration-arquillian/README.md
index 7620d98..36a8252 100644
--- a/testsuite/integration-arquillian/README.md
+++ b/testsuite/integration-arquillian/README.md
@@ -1,61 +1,155 @@
-# Keycloak Integration Testsuite with Arquillian
+# Keycloak Arquillian Integration Testsuite
 
-## Structure
+## Container Lifecycles
 
-```
-integration-arquillian
-│
-├──servers  (submodules enabled via profiles)
-│  ├──wildfly
-│  └──eap6
-│
-└──tests
-   ├──base
-   └──adapters  (submodules enabled via profiles, all depend on base)
-      ├──wildfly
-      ├──wildfly-relative  (needs servers/wildfly)
-      ├──wildfly8
-      ├──as7
-      ├──tomcat
-      └──karaf
+### Keycloak Auth Server
 
-```
+There is only one instance of Keycloak server running during a single test run.
+It is automatically started by Arquillian on the `BeforeSuite` event and stopped `AfterSuite`.
+
+The type of container can be determined by property `-Dauth.server.container`. Default value is `auth-server-undertow`, 
+other options are: `auth-server-wildfly` and `auth-server-eap7`. The values correspond to Arquillian *container qualifiers* in `arquillian.xml` config file.
+
+**Note 1:** For the non-default options it's necessary to build a corresponding server module prior to running any of the test modules.
+This can be done by building the server module directly (from `servers/wildfly`/`servers/eap7`), 
+or by activating `auth-server-wildfly`/`auth-server-eap7` profile when building from the top level module.
+(The profiles will also set the proper value of the `auth.server.container` property.)
+
+**Note 2:** Most server-side configurations are done during the build of the server module
+and included in the output artifact - which is then consumed by the test modules( if a corresponding profile is activated).
+To reflect a change in server config in the test (e.g. a datasource) it's necessary to rebuild the server module after each change.
+
+### Migration
+
+Migration tests can be enabled by setting `-Dmigrated.auth.server.container` property or activating a corresponding profile.
+When enabled, the `AuthServerTestEnricher` class will start/stop the selected *migrated* instance 
+even **before** the *current* auth server instance is started.
+
+### App Servers
+
+Lifecycle of application server is always tied to a particular TestClass.
+
+Each *adapter* test class is annotated by `@AppServerContainer("app-server-*")` annotation 
+that links it to a particular Arquillian container in `arquillian.xml`.
+The `AppServerTestEnricher` then ensures the server is started before and stopped after all tests methods in the class.
+In case the `@AppServerContainer` annotation has no value it's assumed that the application container 
+is the same as the auth server container (a relative adapter test scenario).
+
+Adapter tests are separated into submodules because different app containers require different configurations 
+(installation of adapter libs, etc.).
+Container entries of app servers are not present in the main `arquillian.xml` in the `base` module.
+Each adapter submodule adds it's own entry before it runs the tests.
+
+## SuiteContext and TestContext
+
+These objects are injected into `AbstractKeycloakTest` class so they can be used everywhere.
+They can be used to get information about the tested containers, and to store information that won't survive across test classes or test methods.
+(Arquillian creates a new instance of test class for each test method run, so all data in the fields is always lost.)
+
+## REST Testing
+
+The `AbstractKeycloakTest` has an initialized instance of AdminClient. Subclasses can use it to access any REST subresources.
+
+## UI Testing
 
-## General Concepts
+PageObjects can be injected to tests by `@Page` annotation.
 
-The testsuite supports **multiple server runtimes** for the Keycloak server.
-The **default is Undertow** which is the fastest and easiest option, and runs in the same JVM as the tests.
+The base class for all page objects is `AbstractPage`.
 
-Other options are **Wildfly 9** and **EAP 6**. These have some additional requirements and limitations:
-1. The selected server module must be built before any tests can be run. 
-All server-side configuration is done during this build (e.g. datasource configuration).
-Once server artifact is built the tests modules can unpack it via `maven-dependency-plugin` into their working directory before running.
-2. Before the selected server module can be built the `keycloak/distribution` module also needs to be built.
+The default browser for UI testing is `phantomjs` 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.
 
-### Server Runtimes
 
-TODO: explain why separate module, list config options, note on migration modules
+## Test Modules
 
 ### Base Testsuite
 
-login flows + account management
+The base testsuite contains custom Arquillian extensions and most functional tests.
+The other test modules depend on this module.
 
-admin ui
+### Admin Console UI Tests
 
-abstract adapter tests
+Tests for Keycloak Admin Console are located in a separate module `tests/other/console` 
+and are **disabled** by default. Can be enabled by `-Pconsole-ui-tests`.
 
 ### Adapter Tests
 
-test servlets: demo, session
+Adapter tests are located in submodules of the `tests/other/adapters` module.
 
-examples
+They are **disabled** by default; they can be enabled by corresponding profiles.
+Multiple profiles can be enabled for a single test execution.
+
+#### Types of adapter tests
+
+1. Using *custom test servlets*
+2. Using *example demo apps* from `keycloak/examples` modules.
+
+#### Relative vs Non-relative scenario
+
+The test suite can handle both types.
+It automatically modifies imported test realms and deployments' adapter configs based on scenario type.
+
+| Scenario | Description | Realm config (server side) | Adapter config (client side) |
+| --- | --- | --- | --- |
+| **Relative** | auth server == app server | client `baseUrl`, `adminUrl` and `redirect-uris` can be relative | `auth-server-url` can be relative |
+| **Non-relative** | auth server != app server  | client `baseUrl`, `adminUrl` and `redirect-uris` need to include FQDN of the app server | `auth-server-url` needs to include FQDN of the auth server|
+
+
+
+#### Adapter Libs Mode
+
+1. **Provided** - By container, e.g. as a subsystem. **Default.**
+2. **Bundled** - In the deployed war in `/WEB-INF/libs`. Enable with `-Dadapter.libs.bundled`. *Wildfly only*.
+
+#### Adapter Config Mode
+
+1. ~~**Provided** - In `standalone.xml` using `secure-deployment`. *Wildfly only.*~~ WIP
+2. **Bundled** - In the deployed war in `/WEB-INF/keycloak.json`. **Default.**
+
+
+## Maven Modules Structure
+
+```
+integration-arquillian
+│
+├──servers
+│  ├──wildfly   (activated by -Pauth-server-wildfly)
+│  └──eap7      (activated by -Pauth-server-eap7)
+│
+└──tests   (common settings for all test modules)
+   ├──base    (custom ARQ extensions + base functional tests)
+   └──other   (common settings for all modules dependent on base)
+      │
+      ├──adapters         (common settings for all adapter submodules)
+      │  ├──wildfly           (activated by -Papp-server-wildfly)
+      │  ├──wildfly-relative  (activated by -Papp-server-wildfly-relative,auth-server-wildfly)
+      │  ├──...
+      │  ├──tomcat            (activated by -Papp-server-tomcat)
+      │  └──karaf             (activated by -Papp-server-karaf)
+      │
+      ├──console          (activated by -Pconsole-ui-tests)
+      ├──mod_auth_mellon  (activated by -Pmod_auth_mellon)
+      └──...
+```
 
-## Running the Tests
+## Custom Arquillian Extensions
 
-### Undertow
+Custom extensions are registered in `META-INF/services/org.jboss.arquillian.core.spi.LoadableExtension`.
 
-### Wildfly or EAP 6
+### MultipleContainersExtension
+ * Replaces Arquillian's default container handling.
+ * Allows to manage multiple container instances of different types within a single test run.
+ * Allows to skip loading disabled containers based on `enabled` config property in `arquillian.xml`.
 
-### Adapters
+### KeycloakArquillianExtension
+ * `AuthServerTestEnricher` - Handles lifecycle of auth server and migrated auth server.
+ * `AppServerTestEnricher` - Handles lifecycles of app servers.
+ * `CustomUndertowContainer` - Custom container controller for JAX-RS-enabled Undertow with Keycloak Server.
+ * `DeploymentArchiveProcessor` - Modifies adapter configs before test apps are deployed.
+ * `DeploymentTargetModifier` - Ensures all test app deployments are targeted at app server containers.
+ * `URLProvider` - Fixes URLs injected by Arquillian Graphene which contain value `127.0.0.1` instead of required `localhost`.
+ 
+### CustomKarafContainerExtension
 
-### Supported Browsers
\ No newline at end of file
+Extension for executing karaf commands after container is started. Used for installation of bundles (test apps and adapter libs).
\ No newline at end of file

diff --git a/testsuite/integration-arquillian/tests/base/src/test/resources/arquillian.xml b/testsuite/integration-arquillian/tests/base/src/test/resources/arquillian.xml
index 57e1692..555f3ce 100644
--- a/testsuite/integration-arquillian/tests/base/src/test/resources/arquillian.xml
+++ b/testsuite/integration-arquillian/tests/base/src/test/resources/arquillian.xml
@@ -181,5 +181,12 @@
         </configuration>
     </container>
     
+    <!--
+    
+     APP SERVER CONTAINERS ARE ADDED BY XSL TRANSFORMATIONS IN ADAPTER TEST SUBMODULES 
+     The configuration of various application containers had to be split into multiple 
+     maven submodules: tests/other/adapters, which are activated on demand by profiles.
+     
+    -->
 
 </arquillian>