Merge pull request #99 from telekom/feature/manual-improvements

Improvements of Testerra documentation

Author: martingrossmann

README.md

@@ -22,10 +22,17 @@
 </p>
 
 ## About Testerra
-Testerra is an integrated framework for automating tests for (web) applications. Testerra can also be understood as a building block for test automation projects with various basic components. It also includes a prepared "foundation" on which complex test automation environments can be built. Testerra is developed by our Test Automation Experts at T-Systems MMS GmbH Dresden (Website). In numerous projects Testerra is used as the standard test automation framework.
+
+<p align="center">
+    <img src="docs/src/images/s_Testerra_Logo_0256px.png" alt="Testerra logo">
+</p>
+
+It is an integrated Java framework for automating tests for (web) applications. Testerra can also be understood as a building block for test automation projects with various basic components.
 
 You may see Testerra as an open source test automation library for web frontend testing. It provides a tool suite for many use cases: a base API for Page Object Pattern (including responsive layouts) and GuiElements (smarter WebElements (Selenium)), enhanced reporting functionality, a utility collection and some additional helpful modules.
 
+Testerra is developed by our Test Automation Experts at T-Systems MMS in Dresden. In numerous projects Testerra is used as the standard test automation framework and includes the experience of more then 10 years of test automation.
+
 ## Setup
 
 Include the following dependency in your project. Please replace `1.0` with the latest version.

docs/build.gradle

@@ -53,7 +53,7 @@ asciidoctor {
             toclevels: 2,
             sectnums: '',
             sectanchors: '',
-            Author: 'The Testerra Team of T-Systems MMS GmbH',
+            Author: 'The Testerra Team of T-Systems MMS',
             revnumber: "${version}",
             'source-highlighter': 'highlightjs',
             'highlightjs-theme': 'atom-one-light',

docs/src/docs/browsercaps/local-caps.adoc

@@ -1,13 +1,19 @@
 = Setting local capabilities
 
-A local defined capability means its only available in the current test execution (current TestNG testmethod).
+A local defined capability means its only available in a specific browser session.
 
+.Set capabilities to a DesktopWebDriverRequest object
 [source,java]
 ----
-WebDriverManager.addThreadCapability(CapabilityType.ACCEPT_INSECURE_CERTS, true);
+DesktopWebDriverRequest request = new DesktopWebDriverRequest();
+DesiredCapabilities caps = request.getDesiredCapabilities();
+caps.setCapability(CapabilityType.ACCEPT_INSECURE_CERTS, true);
+
+// Start your session with the DesktopWebDriverRequest object
+WebDriver driver = WebDriverManager.getWebDriver(request);
 ----
 
 [NOTE]
 =====
-Have a look into <<Useful browser capabilities>> for specific browser options.
+Have a look into <<Browser specific knowledge>> for specific browser options.
 =====

docs/src/docs/execution/execution-highlighting.adoc

@@ -5,7 +5,7 @@ include::../properties/property-attributes.adoc[]
 In the demo mode actions on pages are marked with distinctive coloured frames around the element of the action. This mechanism is set by a property
 
 .test.properties
-[source, properties]
+[source, properties, subs="attributes"]
 ----
 # activate demo mode, default = false
 {demomode}=true

docs/src/docs/gettingstarted/manual-steps.adoc

@@ -85,14 +85,14 @@ Create a new file at `src/test/resources` with the name `test.properties`.
 [source, properties, subs="attributes"]
 ----
 # Setting the browser
-{browser}=chrome
+{browser_setting}=chrome
 
 # Setting the start page
 {baseurl}=http://example.org
 ----
 
-TIP: All defined properties can be overwritten later by adding system parameters to your command +
-(e.a `-D{browser}=firefox`)
+TIP: All defined properties can be overwritten later by adding system parameters to your command. +
+(e.a `-D{browser_setting}=firefox`)
 
 All supported browsers are listed in <<WebdriverManager properties>>
 

docs/src/docs/index.adoc

@@ -5,7 +5,6 @@ include::common-attributes.adoc[]
 
 :sectnums!:
 
-= What is Testerra?
 include::what-is-testerra.adoc[leveloffset=+1]
 
 :sectnums:

docs/src/docs/pageobject/pageobjects-overview.adoc

@@ -29,10 +29,10 @@ The annoation `Check` marks the GuiElements as mandatory for the page. Testerra
 public class SearchPage extends Page {
 
     @Check
-    private final GuiElement searchButton = new GuiElement(driver, By.name("searchButton"));
+    private final GuiElement searchButton = new GuiElement(this.getWebDriver(), By.name("searchButton"));
 
     @Check
-    private final GuiElement inputField = new GuiElement(driver, By.name("inputField"));
+    private final GuiElement inputField = new GuiElement(this.getWebDriver(), By.name("inputField"));
 
     // constructor
     public SearchPage(WebDriver driver) {
@@ -43,7 +43,7 @@ public class SearchPage extends Page {
     public ResultPage search(String text){
         inputField.type(text);
         searchButton.click();
-        return PageFactory.create(ResultPage.class, driver);
+        return PageFactory.create(ResultPage.class, this.getWebDriver());
     }
 }
 ----
@@ -58,6 +58,7 @@ public class TestClass extends TesterraTest {
 
     @Test
     public void myTest() {
+        WebDriver driver = WebDriverManager.getWebDriver();
         HomePage homePage = PageFactory.create(HomePage.class, driver);
         SearchPage searchPage = homePage.openSearch();
         ResultPage resultPage = searchPage.search("search text");

docs/src/docs/pageobject/pageobjects-responsive.adoc

@@ -42,7 +42,7 @@ In the test method only the base class will be instantiated. The `PageFactory` w
 
 [source,java]
 ----
-ResponsiveTestPage testPage = Pagefactory.create(ResponsiveTestPage.class, driver);
+ResponsiveTestPage testPage = Pagefactory.create(ResponsiveTestPage.class, this.getWebDriver());
 ----
 
 The parameters for the factory are the base class and the current webdriver instance.

docs/src/docs/properties/webdriver-props.adoc

@@ -5,8 +5,9 @@ include::property-attributes.adoc[]
 
 | Property | default | Description
 
-| {browser} | na.
-a| Browser label, the following browsers are possible
+| {browser_setting} | na.
+a| Define browser type and optional browser version as single string like `firefox` or `firefox:65` (overrides {browser} and {browser_version}) (recommended). +
+The following types of browsrs are supported:
 
 * firefox
 * chrome
@@ -17,9 +18,10 @@ a| Browser label, the following browsers are possible
 * htmlunit
 * chromeHeadless
 
-| {browser_version} | na. | Version label
-| {browser_setting} | | You can combine browser type and version as single string like `firefox:65` (overrides {browser} and {browser_version})
-| {baseurl} | na. | URL of the first site called in a new browser session
+| {browser} | na.
+a| Only defines the browser type, will be overwritten by {browser_setting}.
+| {browser_version} | na. | Only defines the browser version, will be overwritten by {browser_setting}.
+| {baseurl} | na. | URL of the first site called in a new browser session.
 | {webdriver_mode} | remote | Sets the webdriver mode. remote uses an external Selenium server
 | {selenium_server_url} | na. | The complete URL to a remote Selenium server. +
 (e.g.: `http://localhost:4444/wd/hub`)

docs/src/docs/webdrivermanager/webdrivermanager-sessions.adoc

@@ -48,20 +48,28 @@ You can also pass the wedriver by the command line using
 -Dwebdriver.gecko.driver=C:\absolute\path\to\your\geckodriver.exe
 ```
 
-== Usage of WebDriver sessions
+== Define browser type and version
 
 Before starting a `WebDriver` session, you should configure your desired browser like.
 
 [source,properties,subs="attributes"]
 ----
-# ...this way
-{browser}=firefox
-{browser_version}=65
+# Only browser type
+{browser_setting}=firefox
 
-# ... or that way
+# ... or with version
 {browser_setting}=firefox:65
 ----
 
+[NOTE]
+====
+You can also define browser config via the settings `{browser}` and `{browser_version}`, but the version is independent from browser type.
+
+If you have different browser configurations in your Selenium grid you have to take care about the correct combination!
+====
+
+== Usage of WebDriver sessions
+
 On the first call of
 
 [source,java]