Add documentation as part of the code base. This is replacing the externally hosted Confluence system.

Author: slu-it

README.md

@@ -17,15 +17,14 @@ It is the product of years of consulting experience in various projects and aims
 - If you must, Selenium is always just a method call away.
 
 ### Get in touch
-Until our infrastructure is up and running you can send any questions to our technical lead: stefan.ludwig@novatec-gmbh.de
+You can reach contact us using [Gitter](https://gitter.im/testIT-WebTester/webtester-core) or create an [issue](https://github.com/testIT-WebTester/webtester-core/issues).
 
 ### Documentation
-The [user documentation](https://documentation.novatec-gmbh.de/display/TESTIT/WebTester) provides in-depth documentation on all the features.
+The [user documentation](documentation/README.md) is part of the repository and provides in-depth documentation on all the features.
 If you have further questions please get in touch with us.
 
 ### Contribute / Issues
-The contribution and bug processes are not defined, yet.
-For the mean time feel free to contact us with any problems or contributions you might have.
+The contribution process is not yet defined. But if you experience any issues please use GitHub's [issue](https://github.com/testIT-WebTester/webtester-core/issues) system to tell us about it!
 
 ### Licensing
 testIT WebTester is licensed under [The Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt).

documentation/README.md

@@ -0,0 +1,34 @@
+![testIT WebTester](images/logo-650x157.png)
+
+## Welcome to the testIT WebTester documentation!
+
+- [Browser](chapters/browser.md)
+- [Configuration](chapters/configuration.md)
+- [Event System](chapters/event-system.md)
+- [Page Objects](chapters/page-object.md)
+  - [Anatomy of Pages](chapters/page-object-anatomy.md)
+  - [Functional Page Objects](chapters/page-object-functional.md)
+  - [Generic Element](chapters/page-object-generic.md)
+  - [Page Object Factory](chapters/page-object-factory.md)
+- Utility Classes
+  - [Conditions](chapters/conditions.md)
+  - [Identifications](chapters/identifications.md)
+  - [Mouse](chapters/mouse.md)
+  - [Waits](chapters/waits.md)
+- Support Modules
+  - Assertions
+    - [AssertJ](chapters/support-assertj.md)
+    - [Hamcrest](chapters/support-hamcrest.md)
+  - Browser
+    - [Chrome](chapters/support-chrome.md)
+    - [Firefox](chapters/support-firefox.md)
+    - [Internet Explorer](chapters/support-ie.md)
+  - Testing
+    - [JUnit](chapters/support-junit.md)
+  - Integration
+    - [Spring 4](chapters/support-spring4.md)
+- Advanced Topics
+  - [Ad-Hoc finding of Page Objects](chapters/ad-hoc-find.md)
+
+
+

documentation/chapters/ad-hoc-find.md

@@ -0,0 +1,45 @@
+[Home](../README.md)
+
+# Ad-Hoc finding of Page Objects
+The `Browser` and `PageObject` classes provide entry points to the "ad-hoc finding" API.
+This allows you to apply a more script style approach to your tests.
+
+**Doing so might be useful in the following circumstances:**
+
+- You don't have an unique identification property for initializing a `PageObject` field and need to take a programmatic approach 
+- You want to rapidly prototype your tests scenarios
+- You want to execute some bordercases upon elements and don't like to declare those as fields in your page objects
+- Getting to a specific page object is not possible by using `@IdentifyUsing`, `@FindBy` or `@FindBys`
+
+## Examples
+```java
+// find an element by its ID 'fooId' as a GenericElement 
+GenericElement element = getBrowser()
+    .find("#fooId");
+
+// find many elements by their shared CSS class 'foo' as a list of GenericElement
+List<GenericElement> elements = getBrowser()
+    .findMany(".foo");
+    
+// find a TextField by it's ID - Identification first
+TextField textField = getBrowser()
+    .findBy(id("textField"))
+    .as(TextField.class);
+    
+// find a TextField by it's ID - class first
+TextField textField = getBrowser()
+    .find(TextField.class)
+    .by(id("textField"));
+
+// find all all elements with the CSS class 'foo' within an element with ID 'group' as TextFields
+List<TextField> textFields = getBrowser()
+    .find("#group")
+    .findBy(css(".foo"))
+    .asMany(TextField.class);
+```
+
+# Linked Documentation
+
+- [Conditions](conditions.md)
+- [Identifications](identifications.md)
+- [Generic Elements](page-object-generic.md)

documentation/chapters/browser.md

@@ -0,0 +1,78 @@
+[Home](../README.md)
+
+# Browser
+
+## Interfaces
+
+### Browser
+A `Browser` provides a streamlined and context centric API for the interaction with a web browser.
+
+### BrowserBuilder
+A `BrowserBuilder` provides the framework for initializing `Browser` instances and setting custom service implementations.
+Customizable services are:
+
+- [`Configuration`](configuration.md)
+- [`PageObjectFactory`](page-object-factory.md)
+
+### BrowserFactory
+A `BrowserFactory` creates an abstraction over the `Browser` initialisation based on project-global settings.
+They are intended to allow easy browser initialization and encapsulation of the underlying configuration / initialization
+processes.
+
+**Provided default BrowserFactory implementations:**
+
+- [`ChromeFactory`](support-chrome.md)
+- [`FirefoxFactory`](support-firefox.md)
+- [`InternetExplorerFactory`](support-ie.md)
+
+Each of them comes in their own support module. The Firefox's factory implementation is trimmed for optimal performance.
+
+### ProxyConfiguration
+In order to configure a proxy you can either configure it manually when initializing the `WebDriver` or
+you can implement a `ProxyConfiguration` and provide it to the `BrowserFactory` before creating a `Browser` instance.
+
+```java
+ProxyConfiguration pc = createProxyConfiguration();
+Browser browser = new FirefoxFactory().withProxyConfiguration(pc).createBrowser();
+```
+
+## The WebDriver Browser
+The `WebDriverBrowser` class implements `Browser` and is used to wrap a Selenium `WebDriver`.
+Instances can be created by using the `WebDriverBrowser's` factory methods:
+
+1. `WebDriverBrowser.forWebDriver(webDriver).build();`
+2. `WebDriverBrowser.buildForWebDriver(webDriver);`
+
+Both of these are equal. The first method can be used to customize same aspects of the browser before it is build.
+
+## Examples
+**Initialization of a new WebDriverBrowser instance:**
+```java
+WebDriver webDriver = createWebDriver();
+Browser browser = WebDriverBrowser.buildForWebDriver(webDriver);
+Browser browser = WebDriverBrowser.forWebDriver(webDriver).build();
+Browser browser = new WebDriverBrowserBuilder(webDriver).build();
+```
+**Initialization of a new WebDriverBrowser instance with custom service implementations:**
+```java
+Configuration config = createConfiguration();
+PageObjectFactory factory = createFactory();
+
+Browser browser = WebDriverBrowser.forWebDriver(webDriver)
+                        .withConfiguration(config)
+                        .withFactory(factory)
+                        .build();
+
+Browser browser = new WebDriverBrowserBuilder(webDriver)
+                        .withConfiguration(config)
+                        .withFactory(factory)
+                        .build();
+```
+
+# Linked Documentation
+
+- [Configuration](configuration.md)
+- [Page Object Factory](page-object-factory.md)
+- [Chrome Support](support-chrome.md)
+- [Firefox Support](support-firefox.md)
+- [Internet Explorer Support](support-ie.md)

documentation/chapters/conditions.md

@@ -0,0 +1,76 @@
+[Home](../README.md)
+
+# The Conditions Utility Class
+The utility class `Conditions` provides several factory methods for creating GUAVA `Predicate` instances.
+These can be (re-)used in the following sub-systems:
+
+- Filtering a [`PageObjectList`](page-object.md)
+- As a condition of `waitUntil(...)` operations from the [`Waits` API](waits.md)
+
+```java
+browser.findMany(".textfield").filter(Conditions.is(Conditions.visible()));
+Waits.waitUntil(textField, Conditions.has(Conditions.text("foo")));
+```
+
+Since all of these make use of GUAVA's `Predicate` interface it is easy to create your own conditions if need be.
+
+## Syntax
+
+Conditions are designed to be readable. They take a lot of inspiration from Hamecrest's `Matcher` API.
+It is generally recommended to use static imports when working with the `Conditions` class.
+
+We provide two kinds of classes in the `info.novatec.testit.webtester.utils.conditions` package:
+
+- Syntax operations like `Has`, `Is` and `Not` in order to make conditions more readable
+- Property conditions like `TextEquals`, `Visible`, `Writeable` etc. which are executing the real checks
+
+## List of current Conditions
+
+**Syntax:**
+
+- `Either`
+- `Has`
+- `Is`
+- `Not`
+
+**Checks:**
+
+- `AttributeWithValue`
+- `Disabled`
+- `Editable`
+- `Enabled`
+- `FileName`
+- `Interactable`
+- `Invisible`
+- `Label`
+- `Present`
+- `ReadOnly`
+- `Selected`
+- `SelectedIndex`
+- `SelectedIndices`
+- `SelectedText`
+- `SelectedTexts`
+- `SelectedValue`
+- `SelectedValues`
+- `SourcePath`
+- `TextContains`
+- `TextEquals`
+- `Value`
+- `Visible`
+- `VisibleTextContains`
+- `VisibleTextEquals`
+
+## Examples
+```java
+// ## Waits API ##
+Waits.waitUntil(textField, Conditions.has(Conditions.text("foo")));
+waitUntil(textField, has(text("foo")));
+ 
+// ## Ad-Hoc PageObject creation API
+browser.findMany(".textfield").filter(is(visible));
+```
+
+# Linked Documentation
+
+- [Ad-Hoc Finding of Page Objects](ad-hoc-find.md)
+- [Waits API](waits.md)

documentation/chapters/configuration.md

@@ -0,0 +1,134 @@
+[Home](../README.md)
+
+# Configuration
+
+The behavior of WebTester can be configured on a browser by browser basis
+by providing a `Configuration` instance while creating the `Browser`.
+
+A `Configuration` instance can be created by using a `ConfigurationBuilder` implementation.
+That instance can then be used to customize the browser's configuration using a `BrowserBuilder`.
+
+## BaseConfigurationBuilder
+The `BaseConfigurationBuilder` will use a `BaseConfiguration` instance as a starting point.
+It takes `ConfigurationAdapter` and `ConfigurationExporter` instances as options before the `build()` operation.
+
+## ConfigurationAdapter
+A `ConfigurationAdapter` is used to change properties of an existing `Configuration`.
+This is done using a callback method `adapt(Configuration c)`.
+
+The following adapters are provided by the `webtester-core` module:
+
+- `DefaultFileConfigurationAdapter`
+- `GlobalFileConfigurationAdapter`
+- `LocalFileConfigurationAdapter`
+- `TestItHomeFileConfigurationAdapter`
+
+**DefaultFileConfigurationAdapter**
+This adapter looks up a properties file called `testit-webtester-default.properties` on the classpath's root level
+and loads each contained key / value pair into the provided `Configuration` instance.
+
+**GlobalFileConfigurationAdapter**
+This adapter looks up a properties file called `testit-webtester-global.properties` on the classpath's root level
+and loads each contained key / value pair into the provided `Configuration` instance.
+
+**LocalFileConfigurationAdapter**
+This adapter looks up a properties file called `testit-webtester.properties` on the classpath's root level
+and loads each contained key / value pair into the provided `Configuration` instance.
+
+**TestItHomeFileConfigurationAdapter**
+This adapter looks up a properties file called `testit-webtester.properties` inside the `$TESTIT_HOME/config` folder
+and loads each contained key / value pair into the provided `Configuration` instance.
+
+## ConfigurationExporter
+A `ConfigurationExporter` is used to "export" a `Configuration` to another System.
+This is done by using a callback method `export(String key, Object value)` for each key / value pair of the `Configuration`.
+
+The following exporters are provided by the `webtester-core` module:
+
+- SystemPropertyConfigurationExporter
+
+**SystemPropertyConfigurationExporter**
+This exporter can be used to export each key / value pair as system properties in order to make them accessible using `System#getProperty(String key)`.
+
+## Default Configuration
+Since not everyone needs to customize the configuration in the context of his or her project
+a 'DefaultConfigurationBuilder' is provided which uses the following adapters (in order)
+and no exporters to build a Configuration :
+   
+- `DefaultFileConfigurationAdapter`
+- `GlobalFileConfigurationAdapter`
+- `LocalFileConfigurationAdapter`
+   
+**Note:** This builder is also used in case a `Browser` is [build](browser.md) without providing a custom `Configuration` instance.
+
+## Example
+```java
+ConfigurationAdapter adapter1 = ...;
+ConfigurationAdapter adapter2 = ...;
+ConfigurationExporter exporter = ...;
+ 
+// this will adapt a base configuration first with 'adapter1' and then with 'adapter2'
+// after that the final configuration will be exported using the 'exporter'
+Configuration config = new BaseConfigurationBuilder()
+                            .withAdapters(adapter1, adapter2)
+                            .withExporter(exporter)
+                            .build();
+```
+
+# Default Properties
+The following shows all default properties loaded by the `DefaultFileConfigurationAdapter`.
+The values are the same as the fallback values of the `BaseConfiguration` implementation.
+
+```properties
+# URL of the default entry point for the application under test.
+# TYPE: String [Resource URL]
+# browser.defaultEntryPoint =
+ 
+# Weather or not open browsers should be closed automatically when the JVM is shut down.
+# TYPE: boolean [true, false]
+browser.autoClose = false
+ 
+# Format pattern for timestamps to be used when printing timestamps.
+# TYPE: String [Java SimpleDateFormat style as described here: https://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html]
+timestamp.pattern = MMM dd HH:mm:ss yyyy
+ 
+# Folder in which to save screenshots if not otherwise specified.
+# TYPE: String [absolute or relative path to be initialized as a java.io.File instance]
+folders.screenshot = screenshots
+ 
+# Folder in which to save source code of pages if not otherwise specified.
+# TYPE: String [absolute or relative path to be initialized as a java.io.File instance]
+folders.sourcecode = sourcecode
+ 
+# Folder in which to save log files if not otherwise specified.
+# TYPE: String [absolute or relative path to be initialized as a java.io.File instance]
+folders.log = logs
+ 
+# Weather or not color highlighting of used elements should be active or not.
+# TYPE: boolean [true, false]
+markings.activated = false
+ 
+# Color to use for the background of used elements if color highlighting is active.
+# TYPE: String [HEX RGB code starting with'#']
+markings.color.used.background = #90ee90
+ 
+# Color to use for the outline of used elements if color highlighting is active.
+# TYPE: String [HEX RGB code starting with'#']
+markings.color.used.outline = #008000
+ 
+# Default timeout for wait operations.
+# TYPE: int [seconds]
+wait.timeout = 2
+ 
+# Default interval in which to check a condition for wait operations.
+# TYPE: int [miliseconds]
+wait.interval = 100
+ 
+# Whether or not page object's wrapped web elements will be cached or resolved for each action. Has a great impact on stability when testing AJAX heavy application at the cost of performance.
+# TYPE: boolean [true, false]
+pageobjects.caching = true
+```
+
+# Linked Documentation
+
+- [Browser](browser.md)