Documentation refactoring because of changes to the Browser Factories

Author: slu-it

documentation/README.md

@@ -4,6 +4,7 @@
 
 - [Getting Started](chapters/gettingstarted.md)
 - [Browser](chapters/browser.md)
+- [Browser Factories](chapters/browser-factories.md)
 - [Configuration](chapters/configuration.md)
 - [Event System](chapters/event-system.md)
 - [Pages](chapters/page.md)
@@ -28,12 +29,7 @@
   - Assertions
     - [AssertJ](chapters/support-assertj3.md)
     - [Hamcrest](chapters/support-hamcrest.md)
-  - Browser
-    - [Chrome](chapters/support-chrome.md)
-    - [Firefox](chapters/support-firefox.md)
-    - [Firefox (Marionette)](chapters/support-marionette.md)
-    - [Internet Explorer](chapters/support-ie.md)
-  - Testing
+  - Test Runner
     - [JUnit 4.x](chapters/support-junit4.md)
     - [JUnit 5.x](chapters/support-junit5.md)
   - Integration

documentation/chapters/browser-factories.md

@@ -0,0 +1,97 @@
+[Home](../README.md)
+
+# Browser Factories
+
+A `BrowserFactory` creates an abstraction over the `Browser` initialization based on project-global settings.
+They are intended to allow easy browser initialization and encapsulation of the underlying configuration / initialization
+processes. Most projects implement their own factories according to their specific environment.
+In case you just want to get started, we provide factories for the most common browsers:
+
+- `ChromeFactory`
+- `FirefoxFactory`
+- `MarionetteFactory` (new Firefox driver)
+- `InternetExplorerFactory`
+
+All of these are provided by the `webtester-core` module, but need you to provide the corresponding Selenium `WebDriver` dependencies yourself.
+
+## 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();
+```
+
+
+## ChromeFactory
+
+This `BrowserFactory` uses the `selenium-chrome-driver` to create new Chrome `Browser` instances.
+
+### Default Driver Configuration
+In order to optimize testing the following properties are set when creating a `WebDriver` using the `ChromeFactory`:
+
+- Native events are disabled -> Selenium does not simulate human typing.
+- Untrusted certificates are always accepted.
+
+### Additional Service Executable
+The 'ChromeDriver' needs an additional executable to communicate with a Chrome browser.
+It can be downloaded [here](https://sites.google.com/a/chromium.org/chromedriver/downloads).
+
+The path to the executable must be declared as a system or environment property named: `webdriver.chrome.driver`
+
+**Additional Information:**
+- https://github.com/SeleniumHQ/selenium/wiki/ChromeDriver
+
+
+## FirefoxFactory and MarionetteFactory
+
+These `BrowserFactory` implementations use the `selenium-firefox-driver` to create new Firefox `Browser` instances.
+To drive Firefox browsers up to version 46, the `FirefoxFactory` *can* be used.
+In order to drive newer versions (47++), the `MarionetteFactory` *must* be used.
+The only real difference between these two factories is the activation of the `marionnette` capability.
+
+### Default Driver Configuration
+In order to optimize testing the following properties are set when creating a `WebDriver` using the `FirefoxFactory`:
+
+- Native events are disabled -> Selenium does not simulate human typing.
+- Untrusted certificates are always accepted.
+
+### Additional Service Executable
+
+Using the Marionette-activated `WebDriver` will force you to also specify the location of a `GeckoDriver` instance.
+This is basically a proxy between Selenium and the actual Firefox (like with the `ChromeDriver`).
+it can be downloaded [here](https://github.com/mozilla/geckodriver/releases)
+
+The path to the executable must be declared as a system or environment property named: `webdriver.gecko.driver`
+
+**Additional Information:**
+- https://github.com/SeleniumHQ/selenium/wiki/FirefoxDriver
+- https://github.com/mozilla/geckodriver
+- https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette
+
+
+## InternetExplorerFactory
+
+This `BrowserFactory` uses the `selenium-ie-driver` to create new Internet Explorer `Browser` instances.
+
+### Default Driver Configuration
+In order to optimize testing the following properties are set when creating a `WebDriver` using the `InternetExplorerFactory`:
+
+- Native events are disabled -> Selenium does not simulate human typing.
+- Untrusted certificates are always accepted.
+
+### Additional Service Executable
+The `InternetExplorerDriver` needs an additional executable to communicate with a IE browser.
+It can be downloaded [here](http://selenium-release.storage.googleapis.com/index.html).
+
+The path to the executable must be declared as a system or environment property named: `webdriver.ie.driver`
+
+**Additional Information:**
+- https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver
+
+# Linked Documentation
+
+- [Browser](browser.md)
+

documentation/chapters/browser.md

@@ -14,30 +14,6 @@ It is the main entry point to the framework.
 A `BrowserBuilder` provides a builder API for initializing `Browser` instances and setting custom service implementations 
 like the [`Configuration`](configuration.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)
-- [`MarionetteFactory`](support-marionette.md)
-- [`InternetExplorerFactory`](support-ie.md)
-
-Each of them comes in their own support module. The Firefox's and Internet Explorer's factory implementations are optimized 
-for 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 Web Driver 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:
@@ -74,6 +50,4 @@ Browser browser = new WebDriverBrowserBuilder(webDriver)
 # Linked Documentation
 
 - [Configuration](configuration.md)
-- [Chrome Support](support-chrome.md)
-- [Firefox Support](support-firefox.md)
-- [Internet Explorer Support](support-ie.md)
+- [Browser Factories](browser-factories.md)