Skip to content

Get started

Requirements

  • Python 3.8+
  • pip3 20.9+
  • Android SDK

Installation

pip3 install [--user] gmsaas

Upgrade

pip3 install [--user] --upgrade gmsaas

Warning

If you're working on Apple hardware using Apple Silicon CPU (M1/M2), you need to install Rosetta. If it is not already the case, this can be done with softwareupdate --install-rosetta. This is mandatory.

Warning

If you're using Python 3.12, then gmsaas 1.11.0 or above is mandatory.

Uninstallation

Python package

pip3 uninstall gmsaas

Local files

Remove the following directories to purge gmsaas:

  • Windows: %LOCALAPPDATA%\Genymobile\gmsaas
  • Linux: ~/.Genymobile/gmsaas and ~/gmsaas.tmp
  • macOS: ~/.Genymobile/gmsaas

Get notified when a new version is out

You can add the RSS feed https://pypi.org/rss/project/gmsaas/releases.xml to you favorite RSS feed reader or to your corporate communication solution (Slack, Microsoft Teams, Discord and so on). There is no other communication than new gmsaas releases.

Configuration

Prerequisites

Two steps are required to use gmsaas properly:

  1. Configure the path to your Android SDK:

    gmsaas config set android-sdk-path <sdk_path>

    Info

    <sdk_path> should point to the Android SDK installation directory, similar to the ANDROID_SDK_ROOT or deprecated ANDROID_HOME environment variables.

  2. Authenticate:

    1. Create an API Token here and copy it to your clipboard.
    2. Then, to use it with gmsaas, you can either run the following command in a terminal:
    gmsaas auth token <token>

    or you can store the API Token in the environment variable GENYMOTION_API_TOKEN.

    Warning

    Using credentials to authenticate gmsaas has been deprecated since the version 1.10.0.

    If you have existing automated tests, please consider using an API Token instead of the tuple email / password for security reasons.

    • gmsaas auth token should be used in place of gmsaas auth login command.

    • gmsaas auth reset should be used in place of gmsaas auth logout command.

    While these deprecated commands are still working with gmsaas 1.10.0, they are subject to removal in future versions.

Information

You can check if gmsaas is well configured by using the command gmsaas doctor, exit code will be 0 in case of success, 1 otherwise. 

$ gmsaas doctor
Check up finished:
- Authentication OK.
- Android SDK OK.

Output format

1.5.0

gmsaas exposes a global --format (text|json|compactjson) option for all commands.

Available formats are:

text

Plain text output. Default.

json

JSON-formatted output. While each command has specific data printed, it always contains exit_code information.

compactjson

Same thing as json format but one-lined.

You can set a default output format to use in configuration with:

gmsaas config set output-format json

Examples:

Successful command in JSON format

$ gmsaas --format json logzip
{
    "archive_path": "/home/me/projects/myapp/gmsaas-logs-20200605-092516.zip",
    "exit_code": 0,
    "exit_code_desc": "NO_ERROR"
}

Error in JSON format

$ gmsaas --format json instances list
{
    "error": {
        "message": "Error: unable to use the proxy",
        "details": "Failed to establish a new connection: [Errno 113] No route to host"
    },
    "exit_code": 15,
    "exit_code_desc": "REQUEST_ERROR"
}

Proxy

1.3.0

If you are behind a corporate proxy, gmsaas may not be able to access the Internet with its default settings.

SOCKS5

SOCKS5 proxy is only supported from gmsaas ver. 1.4.0 onwards.

Proxy settings can be configured via gmsaas config command.

gmsaas config set proxy (http[s]|socks5)://host:port

For an authenticated proxy, credentials can be passed in the URL:

gmsaas config set proxy (http[s]|socks5)://user:password@host:port

gmsaas config set proxy http[s]://host:port

For an authenticated proxy, credentials can be passed in the URL:

gmsaas config set proxy http[s]://user:password@host:port

Alternatively, to avoid having the proxy credentials stored in gmsaas configuration file, you can set the credentials using environment variables:

GMSAAS_PROXY_USERNAME: the username used to connect to the proxy
GMSAAS_PROXY_PASSWORD: the password of given user

Bash/Zsh auto-completion

gmsaas supports Bash and Zsh auto-completion. To activate it, you need to inform your shell that completion is available.

For Bash, add this to your .bashrc:

eval "$(_GMSAAS_COMPLETE=source gmsaas)"

For Zsh, add this to your .zshrc:

eval "$(_GMSAAS_COMPLETE=source_zsh gmsaas)"

Tip

You must type at least one dash to complete command-line options.

Back to top