Implemented some more features and improved documentation

Author: mreiche

README.md

@@ -77,6 +77,37 @@ I added two examples.
 2. [test_todo_mvc.py](examples/test_todo_mvc.py): are re-implemented test cases from the [Robot Framework TodoMVC](https://docs.robotframework.org/docs/examples/todo) example. It's IMHO developer friendly, better readable and less code. 
 
 
+## Comparison
+
+Comparison of the syntax with other frameworks.
+
+**Pylenium**
+```python
+py.get("a[href='/about']").should().have_text("About")
+```
+```python
+find("a[href='/about']").expect.text.be("About")
+```
+**SeleniumBase**
+```python
+self.assert_text_not_visible("Thanks for your purchase.", "#app .success")
+```
+```python
+find("#app .success").expect.text.not_be("Thanks for your purchase.")
+```
+**Selene**
+```python
+browser.all('#rso>div').should(have.size_greater_than(5)) \
+    .first.should(have.text('Selenium automates browsers'))
+```
+```python
+div = find("#rso>div")
+div.expect.count.greater_than(5).be(True)
+div.first.expect.text.be("Selenium automates browsers")
+```
+
+References: https://www.nextgenerationautomation.com/post/python-test-automation-frameworks
+
 ## Developer area
 ### Run the tests
 ```shell

doc/uielement.md

@@ -66,9 +66,12 @@ ui_element.expect.enabled.be(True)
 # Element is selected
 ui_element.expect.selected.be(True)
 
-# Element text equals a string
+# Element text equals a case sensitive string
 ui_element.expect.text.be("Hello")
 
+# Element text equals a lower case string
+ui_element.expect.text.map(str.lower).be("hello")
+
 # Element text contains a string
 ui_element.expect.text.contains("World").be(True)
 
@@ -81,6 +84,9 @@ ui_element.expect.text.matches("d\sW").be(True)
 # Element's CSS property equals a value
 ui_element.expect.css("display").be("block")
 
+# Element has classes "main" and "nav"
+ui_element.expect.classes("main", "nav").be(True)
+
 # Element's "max-length" attribute is greater or equal than 3
 ui_element.expect.attribute("max-length").greater_equal_than(3).be(True)
 
@@ -97,6 +103,17 @@ ui_element.expect.fully_visible.be(True)
 path = ui_element.take_screenshot()
 ```
 
+The advantage of this chained assertion API is,
+that you can easily perform multiple assertions on the same property.
+```python
+text = ui_element.expect.text
+
+text.not_be("Wrong")
+text.starts_with("Hello").be(True)
+text.map(str.upper).ends_with("WELCOME").be(True)
+text.length.between(10, 20).be(True)
+```
+
 ## Waiting for conditions
 
 Instead of `expect`, use write `wait_for` to prevent raising `AssertionError`.

paf/assertion.py

@@ -5,7 +5,7 @@
 
 from paf.common import Rect
 from paf.control import Control, RetryException
-from paf.types import Supplier, Predicate, Number
+from paf.types import Supplier, Predicate, Number, Mapper
 
 ACTUAL_TYPE = TypeVar("ACTUAL_TYPE")
 
@@ -95,6 +95,12 @@ def be(self, expected: any) -> bool:
 
 
 class QuantityAssertion(Generic[ACTUAL_TYPE], BinaryAssertion[ACTUAL_TYPE]):
+    def map(self, mapper: Mapper):
+        return self.__class__(
+            parent=self,
+            actual=lambda: mapper(self._actual()),
+            subject=lambda: "mapped",
+        )
 
     def not_be(self, expected: any) -> bool:
         return self._test_sequence(lambda actual: actual != expected, lambda: f" not to be {Format.param(expected)}")

paf/page.py

@@ -37,6 +37,10 @@ def _find(self, by: Locator):
     def name(self):
         return self.__class__.__name__
 
+    @property
+    def webdriver(self):
+        return self._webdriver
+
 
 class FinderPage(BasePage):
     def find(self, by: Locator):
@@ -65,10 +69,6 @@ def expect(self):
     def wait_for(self):
         return PageAssertion(self, self._webdriver, raise_exception=False)
 
-    @property
-    def webdriver(self):
-        return self._webdriver
-
     def scroll_by(self, x: int = 0, y: int = 0):
         actions = ActionChains(self._webdriver)
         actions.scroll_by_amount(x, y).perform()

paf/uielement.py

@@ -16,6 +16,7 @@
 from paf.assertion import StringAssertion, Format, BinaryAssertion, QuantityAssertion, RectAssertion
 from paf.common import HasParent, Locator, Point, Rect, Property, Formatter
 from paf.control import Control
+from paf.dom import Attribute
 from paf.locator import By
 from paf.types import Mapper, Consumer, R
 from paf.xpath import XPath
@@ -59,6 +60,10 @@ def type(self, value: str):
     def clear(self):
         pass
 
+    @abstractmethod
+    def submit(self):
+        pass
+
 
 T = TypeVar('T')
 
@@ -284,6 +289,10 @@ def clear(self):
         self._action_sequence(lambda web_element: web_element.clear())
         return self
 
+    def submit(self):
+        self._action_sequence(lambda web_element: web_element.submit())
+        return self
+
     def __str__(self):
         return self.name
 
@@ -387,18 +396,24 @@ def _map(web_element: WebElement):
 
         return self._map_web_element_property(StringAssertion, _map, "tag name")
 
-    def attribute(self, attribute: str):
+    def attribute(self, attribute: str|Attribute):
+        if isinstance(attribute, Attribute):
+            attribute = attribute.value
+
         def _map(web_element: WebElement):
             return web_element.get_attribute(attribute)
 
-        return self._map_web_element_property(StringAssertion, _map, f"attribute({attribute}")
+        return self._map_web_element_property(StringAssertion, _map, f"attribute({attribute})")
 
     def css(self, property_name: str):
         def _map(web_element: WebElement):
             return web_element.value_of_css_property(property_name)
 
         return self._map_web_element_property(StringAssertion, _map, f"css({property_name}")
 
+    def classes(self, *classes):
+        return self.attribute(Attribute.CLASS).has_words(*classes)
+
     @property
     def visible(self):
         return self._visible(False)

test/test_uielement.py

@@ -1,5 +1,6 @@
 import inject
 import pytest
+from selenium.webdriver.remote.webdriver import WebDriver, BaseWebDriver
 from selenium.webdriver.support.color import Color
 
 from paf.control import Control
@@ -29,6 +30,7 @@ def test_finder_page(finder: FinderPage):
     p = finder.find(By.id("para1"))
     assert p.name_path == 'UiElement(By.id(para1))[0]'
     assert p.name == p.name_path
+    assert isinstance(finder.webdriver, BaseWebDriver)
 
 
 # def test_rect():
@@ -41,15 +43,22 @@ def test_finder_page(finder: FinderPage):
 #     assert rect.width == 962
 #     assert rect.height == 27
 
-def test_text_assertions(finder: FinderPage):
+def test_assertions(finder: FinderPage):
     finder.open("https://testpages.herokuapp.com/styled/basic-web-page-test.html")
 
     p = finder.find("#para1")
 
+    # tag name
     p.expect.tag_name.be("p")
 
+    # classes
+    p.expect.classes("main").be(True)
+    p.expect.classes("sub").be(False)
+
     text = p.expect.text
     text.be("A paragraph of text")
+    text.map(str.upper).be("A PARAGRAPH OF TEXT")
+    text.not_be("Bla")
     text.contains("paragraph").be(True)
     text.has_words("paragraph", "text").be(True)
     text.starts_with("A").be(True)