feat: add documentation for playwright integration (#415)

Author: rgonalo

CHANGELOG.rst

@@ -1,11 +1,13 @@
 Toolium Changelog
 =================
 
-v3.3.2
+v3.4.0
 ------
 
 *Release date: In development*
 
+- Now Playwright is available to run web tests instead of Selenium
+
 v3.3.1
 ------
 

README.rst

@@ -3,7 +3,7 @@ Toolium
 
 |Build Status| |Coverage Status| |CodeClimate| |Documentation Status|
 
-Toolium is a Python wrapper tool of Selenium and Appium libraries to test web and mobile applications in a single
+Toolium is a Python wrapper tool of Selenium, Playwright and Appium libraries to test web and mobile applications in a single
 project. It provides a way of choosing and configuring the driver through a configuration file, implements a Page Object
 pattern and includes a simple visual testing solution.
 
@@ -26,6 +26,8 @@ The main dependencies are:
 
 - `Selenium <http://docs.seleniumhq.org/>`_: to test web applications in major browsers (Firefox, Chrome, Internet
   Explorer, Edge or Safari)
+- `Playwright <https://playwright.dev/>`_: to test web applications in major browsers (Firefox, Chrome, Edge or Safari)
+  as an alternative to Selenium (Beta integration in toolium)
 - `Appium-Python-Client <https://github.com/appium/python-client>`_: to test mobile applications (native, hybrid or web)
   in Android or iOS devices/emulators.
 - `requests <http://docs.python-requests.org>`_: to test APIs

docs/bdd_integration.rst

@@ -48,7 +48,7 @@ After initialization, the following attributes will be available in behave conte
 
 - :code:`context.toolium_config`: dictionary with Toolium configuration, readed from properties.cfg
 - :code:`context.driver_wrapper`: :ref:`DriverWrapper <driver_wrapper>` instance
-- :code:`context.driver`: Selenium or Appium driver instance
+- :code:`context.driver`: Selenium, Playwright or Appium driver instance
 - :code:`context.utils`: :ref:`Utils <utils>` instance
 
 Behave userdata properties

docs/browser_configuration.rst

@@ -6,8 +6,8 @@ Browser Configuration
 Common Configuration
 --------------------
 
-To choose the browser in which Selenium will execute the tests, configure *type* property in *[Driver]* section in
-properties.cfg file with one of these values: firefox, chrome, iexplore, edge or safari.
+To choose the browser in which Selenium or Playwright will execute the tests, configure *type* property in *[Driver]*
+section in properties.cfg file with one of these values: firefox, chrome, iexplore, edge or safari.
 
 The following example shows how to choose Firefox::
 

docs/driver_configuration.rst

@@ -3,10 +3,10 @@
 Driver Configuration
 ====================
 
-Toolium allows to run tests on web browsers (using Selenium) or on mobile devices (using Appium). To choose the browser
-or the mobile OS, configure :code:`type` property in :code:`[Driver]` section in :code:`conf/properties.cfg` file with
-one of these values: :code:`firefox`, :code:`chrome`, :code:`iexplore`, :code:`edge`, :code:`safari`, :code:`ios` or
-:code:`android`.
+Toolium allows to run tests on web browsers (using Selenium or Playwright) or on mobile devices (using Appium). To
+choose the browser or the mobile OS, configure :code:`type` property in :code:`[Driver]` section in
+:code:`conf/properties.cfg` file with one of these values: :code:`firefox`, :code:`chrome`, :code:`iexplore`,
+:code:`edge`, :code:`safari`, :code:`ios` or :code:`android`.
 
 The following example shows how to choose Firefox::
 
@@ -18,9 +18,9 @@ If driver is not needed, typically in API tests, disable it using an empty strin
     [Driver]
     type: api
 
-By default, Toolium configuration is loaded from :code:`conf/properties.cfg` and :code:`conf/local-properties.cfg` files. If
-different properties files are used for different environments, they can be selected using a system property named
-:code:`TOOLIUM_CONFIG_ENVIRONMENT`. For example, if :code:`TOOLIUM_CONFIG_ENVIRONMENT` value is :code:`android`,
+By default, Toolium configuration is loaded from :code:`conf/properties.cfg` and :code:`conf/local-properties.cfg`
+files. If different properties files are used for different environments, they can be selected using a system property
+named :code:`TOOLIUM_CONFIG_ENVIRONMENT`. For example, if :code:`TOOLIUM_CONFIG_ENVIRONMENT` value is :code:`android`,
 Toolium configuration will be loaded from :code:`conf/properties.cfg`, :code:`conf/android-properties.cfg` and
 :code:`local-android-properties.cfg` files:
 
@@ -45,6 +45,7 @@ Behave:
 - :ref:`Driver Configuration Modification <driver_configuration_modification>`
 - :ref:`Browser Configuration <browser_configuration>`
 - :ref:`Mobile Configuration <mobile_configuration>`
+- :ref:`Playwright Configuration <playwright_configuration>`
 - :ref:`Remote Driver Configuration <remote_configuration>`
 - :ref:`Multiple Simultaneous Drivers <multiple_drivers>`
 - :ref:`Reuse Driver <reuse_driver>`
@@ -55,6 +56,7 @@ Behave:
    Driver Configuration Modification <driver_configuration_modification.rst>
    Browser Configuration <browser_configuration.rst>
    Mobile Configuration <mobile_configuration.rst>
+   Playwright Configuration <playwright_configuration.rst>
    Remote Driver Configuration <remote_configuration.rst>
    Multiple Simultaneous Drivers <multiple_drivers.rst>
    Reuse Driver <reuse_driver.rst>

docs/mobile_configuration.rst

@@ -3,9 +3,9 @@
 Mobile Configuration
 ====================
 
-To choose mobile operating system in which Appium will execute the tests, configure *type* property in *[Driver]*
-section in properties.cfg file with one of these values: :code:`ios` or :code:`android`. Moreover, configure Appium
-properties in *[AppiumCapabilities]* section in properties.cfg file.
+To choose mobile operating system in which Appium will execute the tests, configure :code:`type` property in
+:code:`[Driver]` section in :code:`conf/properties.cfg` file with one of these values: :code:`ios` or :code:`android`.
+Moreover, configure Appium properties in :code:`[AppiumCapabilities]` section in :code:`conf/properties.cfg` file.
 
 The following example shows how to configure Appium to run tests over TestApp app on an iPhone 14 with iOS 16.1::
 

docs/page_objects.rst

@@ -6,8 +6,8 @@ Page Objects
 Toolium implements Page Object pattern, where a page object represents a web page or a mobile screen (or a part of them)
 and a page element is any of the elements contained in those pages (inputs, buttons, texts, ...).
 
-Toolium loads page elements in lazy loading, so they are searched in Selenium or Appium when they are used, not when
-they are defined.
+Toolium loads page elements in lazy loading, so they are searched in Selenium, Playwright or Appium when they are used,
+not when they are defined.
 
 Basic usage
 -----------
@@ -41,6 +41,8 @@ Example of a test using the previous page object:
         LoginPageObject().login('user', 'pass')
         ...
 
+.. _page_element_types:
+
 Page element types
 ------------------
 
@@ -68,8 +70,8 @@ element (Button), for example.
     username.text = 'username'
 
 Page elements only implement the most commonly used methods. When performing any other action with the element, get the
-web element of the page element and execute the action. *web_element* property returns the Selenium or Appium
-WebElement.
+web element of the page element and execute the action. *web_element* property returns the Selenium, Playwright or
+Appium WebElement.
 
 .. code-block:: python
 
@@ -78,6 +80,8 @@ WebElement.
     # Check if the element is enabled
     enabled = username.web_element.is_enabled()
 
+.. _page_element_parent:
+
 Parent
 ~~~~~~
 

docs/playwright_configuration.rst

@@ -0,0 +1,28 @@
+.. _playwright_configuration:
+
+Playwright Configuration
+========================
+
+Playwright is an alternative to Selenium to test web applications using toolium. This integration is currently in beta
+version.
+
+To choose Playwright instead of Selenium, configure :code:`web_library` property in :code:`[Driver]` section in
+:code:`conf/properties.cfg` file with :code:`playwright` and configure the browser in :code:`type` property as in
+Selenium tests.
+
+The following example shows how to configure toolium to run tests on Chrome using Playwright::
+
+    [Driver]
+    web_library: playwright
+    type: chrome
+
+Features not supported yet
+--------------------------
+
+The following toolium features are not supported yet when using Playwright:
+
+* :ref:`Page Elements <page_element_types>`: not all page elements are implemented for Playwright. Currently only
+  :ref:`Text <playwright_text_page_element>` and :ref:`Button <playwright_button_page_element>` page elements are
+  implemented.
+* :ref:`Element Parent <page_element_parent>`: elements can not be located inside another element using Playwright.
+* Locators: only :code:`id` and :code:`xpath` locators are implemented for Playwright.

docs/toolium.pageelements.playwright.rst

@@ -0,0 +1,42 @@
+Playwright pageelements
+=======================
+
+.. _playwright_page_element:
+
+playwright_page_element
+-----------------------
+
+.. automodule:: toolium.pageelements.playwright.page_element
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. _playwright_button_page_element:
+
+playwright_button_page_element
+------------------------------
+
+.. automodule:: toolium.pageelements.playwright.button_page_element
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. _playwright_checkbox_page_element:
+
+playwright_input_text_page_element
+----------------------------------
+
+.. automodule:: toolium.pageelements.playwright.input_text_page_element
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. _playwright_text_page_element:
+
+playwright_text_page_element
+----------------------------
+
+.. automodule:: toolium.pageelements.playwright.text_page_element
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/toolium.pageelements.rst

@@ -100,3 +100,7 @@ page_elements
     :members:
     :undoc-members:
     :show-inheritance:
+
+.. toctree::
+
+    toolium.pageelements.playwright