mtaf


Namemtaf JSON
Version 1.0.18 PyPI version JSON
download
home_pagehttps://github.com/mccrorey48/mtaf
SummaryMobile Test Automation Framework
upload_time2018-01-17 16:22:27
maintainer
docs_urlNone
authorMartin McCrorey
requires_python
licenseMIT
keywords python android appium selenium adb uiautomator viewer inspector gui locator screenshot xpath resource_id page object model
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            Mobile Test Automation Framework (MTAF)
---------------------------------------

The Mobile Test Automation Framework (MTAF) supports end-to-end regression
tests of web and Android applications. It provides unit test and
Behavior-Driven Development (BDD) test case organization using a Python Page
Object Model architecture. User interaction with the application under test
(AUT) is simulated using Selenium Webdriver (for web applications) and the
Appium Python Client (for Android applications). Support for iOS (also using
Appium) is planned for future development.

The first release of the MTAF includes only the MTAF Inspector, a tool to
help test programmers create automated tests that use Appium to interact with
Android applications. The remaining framework components will be included
once they have been refactored for general release.

MTAF Inspector creates a graphical user interface (GUI) to capture application
screenshots and calculate unique partial xpaths for displayed elements. The
resulting xpaths are converted to an abbreviated format called "zpath" to make
them shorter (Android xpaths can be quite long).

The user can select elements individually with a mouse click, or click and
drag a selection rectangle on the displayed screenshot to narrow down the
list of partial zpaths shown on the screen. Resource ID's are also displayed,
but some elements won't have one, and a resource ID may not represent a unique
element on the screenshot.

Clicking on an ID or xpath will outline the corresponding element(s) on the
screenshot, and copy the ID or zpath value to the main GUI.

The main GUI can use Appium to find elements matching the ID or zpath
value, and show information about the elements.

----

Features
========
**MTAF Inspector:**
    - Graphical tool to assist in designing end-to-end tests on Android devices
    - Works with Android device emulators, or Android devices via USB connection
    - Interactively determines valid locators for screen elements, for use with
      Appium
    - When no Appium server is present, grabs screenshots and xml using adb
    - When used with Appium server, finds and manipulates visible screen
      elements
    - Records Appium interactions in a log file
    - Loads plugins to extend menus, zpaths and GUI elements for specific
      applications (see github.com/mccrorey48/mtaf_plugins for examples)

**MTAF Library Modules (Python):**
    - ADB
        For using ADB from Python, the pyand (https://github.com/ardevd/pyand)
        ADB module is included (which avoids the problem of "pip install" not
        recognizing modules hosted on github)
    - selenium_actions
        Defines SeleniumActions class for using Selenium methods
    - android_actions
        Defines AndroidActions class for using Appium Python Client methods
    - ios_actions (future)
        Defines IosActions class for using Appium Python Client methods
    - android_zpath
        Defines abbreviations used to convert Android xpaths to zpaths, a
        short format that makes working with locators a lot easier
    - ios_zpath (future)
        Defines abbreviations used to convert iOS xpaths to zpaths
    - filters.py
        Filter functions used to narrow down lists of screen elements returned
        by the Appium Python Client search methods
    - mtaf_logging
        Wrapper for Python logging
    - prune_logs
        Utility to limit number and/or age of timestamped logs retained
    - trace
        Decorators for logging method calls and return values
    - user_exception
        Defines UserException class for graceful exception handling in test code
    - softphone (future)
        Creates and manages SIP softphones to make and receive calls for testing
        devices that support voice calls

**Page Object Model (future):**
    - Each visible view (called a "page") displayed by an application under test
      has a Python class which contains locators for that page, and methods to
      be called while that page is displayed
    - Locators for visible elements on the page are given names that convey the
      element's function
    - Each page class represents a separate namespace for locator names, so that
      names can be re-used on other pages without conflict
    - Test steps are generally implemented by calling methods belonging to the
      current page's class, and these methods obtain locators from the locator
      namespace belonging to their class
    - Pages can inherit from a common base page class when they share common
      elements and functionality; in this case, methods and locators are
      inherited from the base class unless overridden in the current page class

**Python Unit Test (future):**
    - Test suite classes are structured using the Python unittest module
      conventions
    - Custom logging, and method call tracing using decorators

**Python Feature Test (future):**
    - Uses the Python "behave" framework
    - Tests are written in "feature" files, using Gherkin BDD language
    - Feature files describe tests in feature/scenario/step format, using "plain language" phrases to describe user interaction with the application
    - Test step phrases are implemented in Python
    - Test results are saved in a MongoDB database and available for review using a web browser

**Report Single Page Application (future):**
    - AngularJS application displays test results saved by Python Feature Test

----

Running Inspector
=================

Once mtaf has been installed, Inspector can be run from a script if the
following requirements are met:

- adb can be found on the current path
- Python and Tkinter are installed on the local machine
- an Appium server is running on the local machine (optional)
- the script has permission to write in the temporary files directory (default value is '.MtafInspector' in the user's home directory)

Inspector can be started with these two Python script lines::

    from mtaf.inspector import start
    start()


Inspector presents a GUI with these components (from top to bottom):

- a menu bar with drop-down menus for both Appium and ADB operations
- buttons and other controls for performing various operations that require Appium
- a input field for entering arbitrary Python commands that will be run in the global context when the "exec" button is clicked
- a scrolling text window that displays captured standard output
- a scrolling text window that displays recorded commands
- a bar with "screenshot" and "quit" buttons

The buttons and controls requiring Appium, along with the Appium drop-down menu,
are disabled until Appium is started. To start Appium, run an Appium server
instance on the local machine, and click "Start Appium" on the menu
bar.

Click the "screenshot" button to capture a screenshot and the xml
representation of the current display.  This does not require Appium to be
started, since Inspector will use ADB if Appium has not been started.
Inspector will display the screenshot, and a column of minimum unique relative
zpaths for each element on the display; these are translated by MTAF methods
into the shortest xpaths that Appium can use to find that individual element.
Some elements may have resource id's, which will be
displayed in a separate column. Clicking a resource id will highlight one or
more elements on the screenshot (preloading the "find element" locator field in
the main GUI), and corresponding zpaths will be highlighted. Clicking a zpath
will highlight one element (highlighting the corresponding resource ID if the
element has one) and preload the zpath into the "find element" locator field.



            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": "", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "keywords": "python,android,appium,selenium,adb,uiautomator,viewer,inspector,gui,locator,screenshot,xpath,resource_id,page object model", 
    "upload_time": "2018-01-17 16:22:27", 
    "author": "Martin McCrorey", 
    "home_page": "https://github.com/mccrorey48/mtaf", 
    "github_user": "mccrorey48", 
    "download_url": "", 
    "platform": "", 
    "version": "1.0.18", 
    "cheesecake_documentation_id": null, 
    "description": "Mobile Test Automation Framework (MTAF)\n---------------------------------------\n\nThe Mobile Test Automation Framework (MTAF) supports end-to-end regression\ntests of web and Android applications. It provides unit test and\nBehavior-Driven Development (BDD) test case organization using a Python Page\nObject Model architecture. User interaction with the application under test\n(AUT) is simulated using Selenium Webdriver (for web applications) and the\nAppium Python Client (for Android applications). Support for iOS (also using\nAppium) is planned for future development.\n\nThe first release of the MTAF includes only the MTAF Inspector, a tool to\nhelp test programmers create automated tests that use Appium to interact with\nAndroid applications. The remaining framework components will be included\nonce they have been refactored for general release.\n\nMTAF Inspector creates a graphical user interface (GUI) to capture application\nscreenshots and calculate unique partial xpaths for displayed elements. The\nresulting xpaths are converted to an abbreviated format called \"zpath\" to make\nthem shorter (Android xpaths can be quite long).\n\nThe user can select elements individually with a mouse click, or click and\ndrag a selection rectangle on the displayed screenshot to narrow down the\nlist of partial zpaths shown on the screen. Resource ID's are also displayed,\nbut some elements won't have one, and a resource ID may not represent a unique\nelement on the screenshot.\n\nClicking on an ID or xpath will outline the corresponding element(s) on the\nscreenshot, and copy the ID or zpath value to the main GUI.\n\nThe main GUI can use Appium to find elements matching the ID or zpath\nvalue, and show information about the elements.\n\n----\n\nFeatures\n========\n**MTAF Inspector:**\n    - Graphical tool to assist in designing end-to-end tests on Android devices\n    - Works with Android device emulators, or Android devices via USB connection\n    - Interactively determines valid locators for screen elements, for use with\n      Appium\n    - When no Appium server is present, grabs screenshots and xml using adb\n    - When used with Appium server, finds and manipulates visible screen\n      elements\n    - Records Appium interactions in a log file\n    - Loads plugins to extend menus, zpaths and GUI elements for specific\n      applications (see github.com/mccrorey48/mtaf_plugins for examples)\n\n**MTAF Library Modules (Python):**\n    - ADB\n        For using ADB from Python, the pyand (https://github.com/ardevd/pyand)\n        ADB module is included (which avoids the problem of \"pip install\" not\n        recognizing modules hosted on github)\n    - selenium_actions\n        Defines SeleniumActions class for using Selenium methods\n    - android_actions\n        Defines AndroidActions class for using Appium Python Client methods\n    - ios_actions (future)\n        Defines IosActions class for using Appium Python Client methods\n    - android_zpath\n        Defines abbreviations used to convert Android xpaths to zpaths, a\n        short format that makes working with locators a lot easier\n    - ios_zpath (future)\n        Defines abbreviations used to convert iOS xpaths to zpaths\n    - filters.py\n        Filter functions used to narrow down lists of screen elements returned\n        by the Appium Python Client search methods\n    - mtaf_logging\n        Wrapper for Python logging\n    - prune_logs\n        Utility to limit number and/or age of timestamped logs retained\n    - trace\n        Decorators for logging method calls and return values\n    - user_exception\n        Defines UserException class for graceful exception handling in test code\n    - softphone (future)\n        Creates and manages SIP softphones to make and receive calls for testing\n        devices that support voice calls\n\n**Page Object Model (future):**\n    - Each visible view (called a \"page\") displayed by an application under test\n      has a Python class which contains locators for that page, and methods to\n      be called while that page is displayed\n    - Locators for visible elements on the page are given names that convey the\n      element's function\n    - Each page class represents a separate namespace for locator names, so that\n      names can be re-used on other pages without conflict\n    - Test steps are generally implemented by calling methods belonging to the\n      current page's class, and these methods obtain locators from the locator\n      namespace belonging to their class\n    - Pages can inherit from a common base page class when they share common\n      elements and functionality; in this case, methods and locators are\n      inherited from the base class unless overridden in the current page class\n\n**Python Unit Test (future):**\n    - Test suite classes are structured using the Python unittest module\n      conventions\n    - Custom logging, and method call tracing using decorators\n\n**Python Feature Test (future):**\n    - Uses the Python \"behave\" framework\n    - Tests are written in \"feature\" files, using Gherkin BDD language\n    - Feature files describe tests in feature/scenario/step format, using \"plain language\" phrases to describe user interaction with the application\n    - Test step phrases are implemented in Python\n    - Test results are saved in a MongoDB database and available for review using a web browser\n\n**Report Single Page Application (future):**\n    - AngularJS application displays test results saved by Python Feature Test\n\n----\n\nRunning Inspector\n=================\n\nOnce mtaf has been installed, Inspector can be run from a script if the\nfollowing requirements are met:\n\n- adb can be found on the current path\n- Python and Tkinter are installed on the local machine\n- an Appium server is running on the local machine (optional)\n- the script has permission to write in the temporary files directory (default value is '.MtafInspector' in the user's home directory)\n\nInspector can be started with these two Python script lines::\n\n    from mtaf.inspector import start\n    start()\n\n\nInspector presents a GUI with these components (from top to bottom):\n\n- a menu bar with drop-down menus for both Appium and ADB operations\n- buttons and other controls for performing various operations that require Appium\n- a input field for entering arbitrary Python commands that will be run in the global context when the \"exec\" button is clicked\n- a scrolling text window that displays captured standard output\n- a scrolling text window that displays recorded commands\n- a bar with \"screenshot\" and \"quit\" buttons\n\nThe buttons and controls requiring Appium, along with the Appium drop-down menu,\nare disabled until Appium is started. To start Appium, run an Appium server\ninstance on the local machine, and click \"Start Appium\" on the menu\nbar.\n\nClick the \"screenshot\" button to capture a screenshot and the xml\nrepresentation of the current display.  This does not require Appium to be\nstarted, since Inspector will use ADB if Appium has not been started.\nInspector will display the screenshot, and a column of minimum unique relative\nzpaths for each element on the display; these are translated by MTAF methods\ninto the shortest xpaths that Appium can use to find that individual element.\nSome elements may have resource id's, which will be\ndisplayed in a separate column. Clicking a resource id will highlight one or\nmore elements on the screenshot (preloading the \"find element\" locator field in\nthe main GUI), and corresponding zpaths will be highlighted. Clicking a zpath\nwill highlight one element (highlighting the corresponding resource ID if the\nelement has one) and preload the zpath into the \"find element\" locator field.\n\n\n", 
    "lcname": "mtaf", 
    "bugtrack_url": null, 
    "github": true, 
    "coveralls": false, 
    "name": "mtaf", 
    "license": "MIT", 
    "travis_ci": false, 
    "github_project": "mtaf", 
    "summary": "Mobile Test Automation Framework", 
    "split_keywords": [
        "python", 
        "android", 
        "appium", 
        "selenium", 
        "adb", 
        "uiautomator", 
        "viewer", 
        "inspector", 
        "gui", 
        "locator", 
        "screenshot", 
        "xpath", 
        "resource_id", 
        "page object model"
    ], 
    "author_email": "martin.mccrorey@verizon.net", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2018-01-17T16:22:27", 
            "comment_text": "", 
            "python_version": "py2.py3", 
            "url": "https://pypi.python.org/packages/2c/f4/4b4b5eb6eb9c155460d660e2a5cad9f6567bb5048d32c0a4cdb2a8c1ba6b/mtaf-1.0.18-py2.py3-none-any.whl", 
            "md5_digest": "7544410dac762be5062b0307bf40ca9b", 
            "downloads": 0, 
            "filename": "mtaf-1.0.18-py2.py3-none-any.whl", 
            "packagetype": "bdist_wheel", 
            "path": "2c/f4/4b4b5eb6eb9c155460d660e2a5cad9f6567bb5048d32c0a4cdb2a8c1ba6b/mtaf-1.0.18-py2.py3-none-any.whl", 
            "size": 41227
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}