Metadata-Version: 2.1
Name: atomacos
Version: 0.2.0.dev82
Summary: Automated Testing on macOS
Home-page: https://github.com/daveenguyen/atomacos
License: UNKNOWN
Author: Davee Nguyen
Author-email: davee@daveenguyen.com
Description-Content-Type: text/markdown
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: MacOS X
Classifier: Environment :: MacOS X :: Cocoa
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Operating System :: MacOS
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Objective C
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: User Interfaces
Requires-Dist: pyobjc-core>=3.0.4
Requires-Dist: pyobjc-framework-Cocoa>=3.0.4
Requires-Dist: pyobjc-framework-Quartz>=3.0.4
Requires-Dist: pyobjc-framework-ApplicationServices>=3.0.4
Requires-Dist: pyobjc-framework-CoreText>=3.0.4
Requires-Dist: future
Requires-Dist: black; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: tox; extra == "dev"
Requires-Dist: bump2version; extra == "dev"
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: m2r; extra == "doc"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: dev
Provides-Extra: doc
Provides-Extra: test

# Atomacos - Automated Testing on macOS
[![pypi](https://img.shields.io/pypi/v/atomacos.svg?style=flat-square)](https://pypi.org/project/atomacos/)
[![Build Status](https://img.shields.io/travis/daveenguyen/atomacos.svg?style=flat-square)](https://travis-ci.org/daveenguyen/atomacos)
[![codecov](https://img.shields.io/codecov/c/github/daveenguyen/atomacos.svg?style=flat-square)](https://codecov.io/gh/daveenguyen/atomacos/)

This library is a fork of [atomac].
It was created to provide a release with python 3 support because
there has not been a release [since 2013](https://github.com/pyatom/pyatom/releases)


## Introduction
Atomacos is a library to enable GUI testing of macOS applications via the Apple Accessibility API.
Atomacos has direct access to the API via [pyobjc]. It's fast and easy to use to write tests.


## Getting started
Requirements
- macOS
- [pyobjc]
- Systemwide Accesibility enabled

On travis, it's only on 10.11 because we are able to enable accessibility API.

If you experience issues, please open a ticket in the [issue tracker][issues].

### Enabling Systemwide Accessibility
Check the checkbox:
`System Preferences > Universal Access > Enable access for assistive devices`
`System Preferences > Security & Privacy > Privacy > Accessibility`

Failure to enable this will result in `AXErrorAPIDisabled` exceptions during some module usage.


### Installing

For release
```bash
$ pip install atomacos
```

For pre-release
```bash
$ pip install --pre atomacos
```


## Usage
Once installed, you should be able to use it to launch an application:

```python
>>> import atomacos
>>> atomacos.launchAppByBundleId('com.apple.Automator')
```

This should launch Automator.


Next, get a reference to the UI Element for the application itself:

```python
>>> automator = atomacos.getAppRefByBundleId('com.apple.Automator')
>>> automator
<atomacos.AXClasses.NativeUIElement AXApplication Automator>
```


Now, we can find objects in the accessibility hierarchy:

```python
>>> window = automator.windows()[0]
>>> window.AXTitle
u'Untitled'
>>> sheet = window.sheets()[0]
```

Note that we retrieved an accessibility attribute from the Window object - `AXTitle`.
Atomacos supports reading and writing of most attributes.
Xcode's included `Accessibility Inspector` can provide a quick way to find these attributes.


There is a shortcut for getting the sheet object which
bypasses accessing it through the Window object.
Atomacos can search all objects in the hierarchy:

```python
>>> sheet = automator.sheetsR()[0]
```


There are search methods for most types of accessibility objects.
Each search method, such as `windows`,
has a corresponding recursive search function, such as `windowsR`.

The recursive search finds items that aren't just direct children, but children of children.
These search methods can be given terms to identify specific elements.
Note that `*` and `?` can be used as wildcard match characters in all search methods:

```python
>>> close = sheet.buttons('Close')[0]
```


There are methods to search for UI Elements that match any number of criteria.
The criteria are accessibility attributes:

```python
>>> close = sheet.findFirst(AXRole='AXButton', AXTitle='Close')
```

`findFirst` and `findFirstR` return the first item found to match the criteria or `None`.
`findAll` and `findAllR` return a list of all items that match the criteria or an empty list(`[]`).


Objects are fairly versatile.
You can get a list of supported attributes and actions on an object:

```python
>>> close.getAttributes()
[u'AXRole', u'AXRoleDescription', u'AXHelp', u'AXEnabled', u'AXFocused',
u'AXParent', u'AXWindow', u'AXTopLevelUIElement', u'AXPosition', u'AXSize',
u'AXTitle']
>>> close.AXTitle
u'Close'
>>> close.getActions()
[u'Press']
```


Performing an action is as natural as:

```python
>>> close.Press()
```

Any action can be triggered this way.



# Todo
- LDTP
    - Maybe extract into its own project and use atomacos at the backend.
- Better mouse handling.
    - For example, a method to smoothly drag from one UI Element to another.
- Cleanup the search methods
    - We could use currying to define all the search methods in AXClasses in a cleaner way.


# Links
- [License]
- [Issues]
- [Source] Code
- Changes
    - [Commits] page has all changes to the project.
    - [Release] page will also outline changes
- Thanks [ATOMac] and [PyObjC]


[source]:  https://github.com/daveenguyen/atomacos
[release]: https://github.com/daveenguyen/atomacos/releases
[commits]: https://github.com/daveenguyen/atomacos/commits
[license]: https://github.com/daveenguyen/atomacos/blob/master/LICENSE
[issues]:  https://github.com/daveenguyen/atomacos/issues
[atomac]:  https://github.com/pyatom/pyatom
[pyobjc]:  https://bitbucket.org/ronaldoussoren/pyobjc

