feat: documentation (#3)

Author: igortavtib

AppiumFlutterLibrary/__init__.py

@@ -13,10 +13,53 @@ class AppiumFlutterLibrary(
 	_RunOnFailureKeyWords,
 	_WaintingKeywords,
 ):
+	""" AppiumFlutterLibrary is a flutter testing library for Robot Framework
+	that uses FlutterDriver class and appium to test flutter mobile apps.
+
+	 The lib was inspired by AppiumLibrary.
+
+	== Flutter Finder ==
+
+	 All keywords that needs to interact with and element needs to find this element
+	first. For this prupose we have the locators that comunicate with FlutterDriver
+	findBy functions.
+
+	== Locators ==
+
+	 By default when passing a locator without a specifier the library will get this
+	locator as a FlutterDriver key. If you want to use a different locator you need to
+	set the specifier.
+
+	Example:
+
+	| Click Element		input-button
+	| Click Element 	text=Input
+
+	 Avalible locators:
+
+	| *Locator*    | *Description*              |
+	| key(default) | FlutterDriver element key. |
+	| text         | Element text.              |
+	"""
 	ROBOT_LIBRARY_SCOPE = 'GLOBAL'
 	ROBOT_LIBRARY_VERSION = VERSION
 
 	def __init__(self, timeout=5, run_on_failure='Capture Page Screenshot'):
+		"""AppiumFlutterLibrary can be imported with optional arguments.
+        ``timeout`` is the default timeout used to wait for all waiting actions.
+        It can be later set with `Set Appium Timeout`.
+
+        ``run_on_failure`` specifies the name of a keyword (from any available
+        libraries) to execute when a AppiumFlutterLibrary keyword fails.
+        By default `Capture Page Screenshot` will be used to take a screenshot of the current page.
+        Using the value `No Operation` will disable this feature altogether. See
+        `Register Keyword To Run On Failure` keyword for more information about this
+        functionality.
+		
+        Examples:
+        | Library | AppiumFlutterLibrary | 10 | # Sets default timeout to 10 seconds                                                                             |
+        | Library | AppiumFlutterLibrary | timeout=10 | run_on_failure=No Operation | # Sets default timeout to 10 seconds and does nothing on failure           |
+        """
 		for base in AppiumFlutterLibrary.__bases__:
 			base.__init__(self)
 		self.set_appium_timeout(timeout)

AppiumFlutterLibrary/keywords/_applicationmanagement.py

@@ -11,6 +11,21 @@ def __init__(self):
         self._timeout_in_secs = float(5)
 
     def open_application(self, remote_url, alias =None, **kwargs):
+        """Opens a new application to given Appium server.
+
+        *Note*: You must specify automationName capability as 'flutter', so the
+        FlutterDriver is enabled.
+
+        Capabilities of appium server, Android and iOS,
+        Please check https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/server-args.md
+        | *Option*            | *Man.* | *Description*     |
+        | remote_url          | Yes    | Appium server url |
+        | alias               | no     | alias             |
+
+        Examples:
+        | Open Application | http://localhost:4723/wd/hub | alias=Myapp1         | automationName=flutter | platformName=iOS       | platformVersion=7.0            | deviceName='iPhone Simulator'           | app=your.app                         |
+        | Open Application | http://localhost:4723/wd/hub | platformName=Android | automationName=flutter | platformVersion=4.2.2  | deviceName=192.168.56.101:5555 | app=${CURDIR}/demoapp/OrangeDemoApp.apk | appPackage=com.netease.qa.orangedemo | appActivity=MainActivity |
+        """
         desired_caps = kwargs
         if desired_caps['automationName'] != 'flutter':
             raise ValueError("Appium Flutter Library only suports flutter automation. Try changing automationName capability to 'flutter'")
@@ -23,26 +38,73 @@ def reset_application(self):
         self._current_application().reset()
 
     def close_all_applications(self):
+        """Closes all open applications.
+
+        This keyword is meant to be used in test or suite teardown to
+        make sure all the applications are closed before the test execution
+        finishes.
+
+        After this keyword, the application indices returned by `Open Application`
+        are reset and start from `1`.
+        """
         self._debug("Closing all applications")
         self._cache.close_all()
 
     def close_application(self):
+        """Closes the current application and also close webdriver session."""
         self._debug("Closing current apllication")
         self._cache.close()
 
     def background_app(self, seconds=5):
+        """
+        Puts the application in the background on the device for a certain
+        duration in seconds.
+        """
         self._current_application().background_app(seconds)
 
     def lock(self, seconds=5):
+        """
+        Lock the device for a certain period of time. iOS only.
+        """
         self._current_application().lock(robot.utils.timestr_to_secs(seconds))
 
     def portrait(self):
+        """
+        Set the device orientation to PORTRAIT
+        """
         self._rotate("PORTRAIT")
 
+    def landscape(self):
+        """
+        Set the device orientation to LANDSCAPE
+        """
+        self._rotate('LANDSCAPE')
+
     def touch_id(self, match = True):
+        """
+        Simulate Touch ID on iOS Simulator
+        `match` (boolean) whether the simulated fingerprint is valid (default true)
+
+        New in AppiumLibrary 1.5
+        """
         self._current_application().touch_id(match)
 
     def set_appium_timeout(self, seconds):
+        """Sets the timeout in seconds used by various keywords.
+
+        There are several `Wait ...` keywords that take timeout as an
+        argument. All of these timeout arguments are optional. The timeout
+        used by all of them can be set globally using this keyword.
+
+        The previous timeout value is returned by this keyword and can
+        be used to set the old value back later. The default timeout
+        is 5 seconds, but it can be altered in `importing`.
+        
+        Example:
+        | ${orig timeout} = | Set Appium Timeout | 15 seconds |
+        | Open page that loads slowly |
+        | Set Appium Timeout | ${orig timeout} |
+        """
         old_timeout = self.get_appium_timeout()
         self._timeout_in_secs = robot.utils.timestr_to_secs(seconds)
         return old_timeout

AppiumFlutterLibrary/keywords/_element.py

@@ -10,6 +10,11 @@ def __init__(self):
         self._element_finder = ElementFinder()
 
     def input_text(self, locator, text):
+        """Input text into the specified element.
+
+        If the element does not support text input an error
+        will be raised.
+        """
         element = self._find_element(locator)
         self._info("Typing text '%s' into component '%s'" % (text, locator))
         try:
@@ -18,6 +23,11 @@ def input_text(self, locator, text):
             raise err
 
     def clear_text(self, locator):
+        """Clear the text from specified element.
+
+        If the element does not support text clearing an error
+        will be raised.
+        """
         element = self._find_element(locator)
         self._info("Clearing text from element '%s'" % (locator))
         try:
@@ -26,6 +36,11 @@ def clear_text(self, locator):
             raise err
 
     def click_element(self, locator):
+        """Tap the specified element.
+
+        If the element does not support tapping an error
+        will be raised.
+        """
         element = self._find_element(locator)
         self._info("Clicking on element %s" % locator)
         try:
@@ -34,17 +49,29 @@ def click_element(self, locator):
             raise err
 
     def element_should_be_visible(self, locator):
+        """Verify if the element is visible using FlutterDriver.waitFor().
+
+        If the element isn't visible raise an Assertion Error.
+        """
         element = self._find_element(locator)
         if not self._is_visible(element):
             raise AssertionError("Element '%s' should be visible but not" % locator)
 
     def element_text_should_be(self, locator, text):
+        """Verify if the element text is equal to provided text.
+
+        If the text isn't equal raise an Assertion Error.
+
+        If the element does not support getText() raise an error.
+        """
         element = self._find_element(locator)
         if element.text != text:
             raise AssertionError("Element '%s' text should be '%s' but is '%s'." %
                                     (locator, text, element.text))
 
     def get_element(self, locator):
+        """Returns the element object.
+        """
         return self._find_element(locator)
 
     def get_element_text(self, locator):

AppiumFlutterLibrary/keywords/_screen.py

@@ -6,6 +6,8 @@ def __init__(self):
         self._element_finder = ElementFinder()
 
     def scroll_to_element(self, locator):
+        """ Uses FlutterDriver.scrollIntoView() to scroll until element is visible.
+        """
         application = self._current_application()
         element = self._element_finder.find(application, locator)
         self._info(element)

AppiumFlutterLibrary/keywords/_waiting.py

@@ -8,6 +8,11 @@ def __init__(self):
         self._element_finder = ElementFinder()
 
     def wait_for_element(self, locator, timeout=20):
+        """ Uses FlutterDriver.waitFor() to wait for an element by the
+        specified timeout duration.
+
+        By default the timeout is 20 seconds.
+        """
         application = self._current_application()
         element = self._element_finder.find(application, locator)
         if timeout == 0:

AppiumFlutterLibrary/version.py

@@ -1,2 +1,2 @@
 # -*- coding: utf-8 -*-
-VERSION = '1.0.0-alpha.3'
+VERSION = '1.0.0-alpha.4'