Merge pull request #267 from telekom/feature/doc-update

Feature/doc update

docs/src/docs/guielement.adoc

@@ -10,7 +10,6 @@ UiElements are *self refreshing*: Every action on it will trigger a find call, s
 
 include::guielement/guielement-creation.adoc[leveloffset=+1]
 include::guielement/xpath-builder.adoc[leveloffset=+1]
-include::guielement/guielement-checks.adoc[leveloffset=+1]
 include::guielement/guielement-assertions.adoc[leveloffset=+1]
 include::guielement/guielement-actions.adoc[leveloffset=+1]
 include::guielement/guielement-waiters.adoc[leveloffset=+1]

docs/src/docs/guielement/guielement-assertions.adoc

@@ -2,7 +2,48 @@
 
 UiElements provide many kinds of assertion methods to verify your elements.
 
-If an assertion fails, it will make the whole test fail and abort. You can control that by using a <<Assertion handling, TestController>>
+If an assertion fails, it will make the whole test fail and abort. You can control that by using a <<Test controlling, TestController>>
+
+== UiElement checks
+
+Checks are assertions which verify the condition of an UiElement.
+
+Checks if the element is present in the DOM
+[source,java]
+----
+element.expect().present(boolean);
+----
+
+Checks if the element is present in the Viewport,
+if it is visible by it's `display` and `visibility` style properties and if it's `width` and `height` are both greater than 0.
+[source,java]
+----
+element.expect().displayed(boolean);
+----
+
+Checks if the element is displayed and if it's partially or fully visible
+in the scroll area of the viewport.
+
+[source,java]
+----
+element.expect().visible(boolean fullyVisible).is(boolean);
+----
+
+NOTE: It doesn't relate to `opacity` or `z-index` style properties. If you need to test the perceptually visibility to the human eye, you should consider to implement an image based <<Layout Check>>.
+
+Some more WebElement checks
+
+[source,java]
+----
+// The following methods are calling the standard webelement method
+element.expect().enabled(boolean);
+element.expect().selected(boolean);
+
+// Tries to find out if an element could be selected.
+element.expect().selectable(boolean);
+----
+
+== Assertions of UiElement attributes
 
 [source,java]
 ----
@@ -59,3 +100,32 @@ image1.expect().bounds().fromBottom().toBottomOf(image3).is(0);
 // Assertions are false
 image1.expect().bounds().fromBottom().toBottomOf(image2).is(0);
 ----
+
+== Custom assertion message
+
+Testerra generates a readable assertion message with name of UiElement, page and checked attribute.
+
+.Example of a page and a test method
+[source,java]
+----
+public class DragAndDropPage extends Page {
+    ...
+    private UiElement columnA = find(By.id("column-a"));
+
+    public TestableUiElement getColumnA() {
+        return this.columnA;
+    }
+}
+...
+public MyTest extends TesterraTest implements PageFactoryProvider {
+    @Test
+    public void myTest() {
+        DragAndDropPage page = PAGE_FACTORY.createPage(DragAndDropPage.class);
+        page.getColumnA().expect().displayed().is(false); <1>
+        page.getColumnB().expect().displayed().is(false, "Foo"); <2>
+    }
+}
+----
+
+<1> Error message: `UiElementAssertionError: Expected that DragAndDropPage -> columnB displayed is false`
+<2> Error message: `UiElementAssertionError: Expected that Foo is false`

docs/src/docs/migration.adoc

@@ -21,7 +21,7 @@ When implementing the `PageFactoryProvider` interface, you get an `PAGE_FACTORY`
 ```java
 import eu.tsystems.mms.tic.testframework.testing.PageFactoryProvider;
 
-class MyTest extends TesterraTest implements PageFactoryProvider {
+class MyTest extends TesterraTest implements PageFactoryProvider, WebDriverManagerProvider {
 
     @Test
     public void test_MyPageTest() {
@@ -266,7 +266,7 @@ uiElement.expect().text()
 
 Custom failure messages
 ```java
-uiElement.expect().displayed(true, "Element is displayed");
+uiElement.expect().displayed().is(true, "Element is displayed");
 ```
 
 === Page assertions
@@ -374,11 +374,11 @@ CONTROL.collectAssertions(() -> {
 });
 ```
 
-For custom assertions
+For custom assertions using `AssertProvider`
 ```java
 CONTROL.collectAssertions(() -> {
     String data = loadSomeData();
-    Assert.assertEquals(data, "Hello World", "some data");
+    ASSERT.assertEquals(data, "Hello World", "some data");
 });
 ```
 
@@ -501,7 +501,7 @@ public void test_TestSomething_fast() {
 ```
 
 [NOTE]
-.Setting timeouts using static `POConfig` is now `@deprecated`
+.Setting timeouts using static `POConfig` was removed!
 ====
 ```java
 POConfig.setThreadLocalUiElementTimeoutInSeconds(1);

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

@@ -38,12 +38,10 @@ The annotation `Check` marks the UiElements as mandatory for the page. Testerra
 public class SearchPage extends Page {
 
     @Check
-    private final UiElement searchButton =
-            find(By.name("searchButton"));
+    private final UiElement searchButton = find(By.name("searchButton"));
 
     @Check
-    private final UiElement inputField =
-            find(By.name("inputField"));
+    private final UiElement inputField = find(By.name("inputField"));
 
     // constructor
     public SearchPage(WebDriver driver) {
@@ -67,7 +65,6 @@ public class TestClass extends TesterraTest implements PageFactoryProvider {
 
     @Test
     public void myTest() {
-        WebDriver driver = WebDriverManager.getWebDriver();
         HomePage homePage = PAGE_FACTORY.createPage(HomePage.class);
         SearchPage searchPage = homePage.openSearch();
         ResultPage resultPage = searchPage.search("search text");

docs/src/docs/webdrivermanager/webdrivermanager-config.adoc

@@ -36,6 +36,17 @@ myRequest.setWindowSize(new Dimension(2560,1440));
 WebDriver driver = WEB_DRIVER_MANAGER.getWebDriver(myRequest);
 ----
 
+Via the `SessionContext` you can get the current configuration of a WebDriver session:
+
+[source,java]
+----
+Optional<SessionContext> sessionContext = WEB_DRIVER_MANAGER.getSessionContext(webDriver);
+// In case of a desktop browser you can cast to 'DesktopWebDriverRequest'
+// Be careful if you are using Appium Connector!
+DesktopWebDriverRequest webDriverRequest
+    = (DesktopWebDriverRequest) sessionContext.get().getWebDriverRequest();
+----
+
 == Configure with WebDriverManagerConfig (`@deprecated`)
 
 Since this `WebDriverManagerConfig` is actually a `DesktopWebDriverRequest`, you should prefer using that when creating a new WebDriver.