Custom Parameters for Android Automation
You can enter custom parameters when automating Android systems under test (SUTs), both via Android Gateway and via the command line. In both cases, you pass these parameters through SystemNative2 (SN2), an on-device process that enables Android automation.
How to Use Parameters
First, install SN2 on your Android SUT. Open Android Gateway, connect an Android device, and click Start in the Android Gateway interface. Android Gateway installs and launches SN2 on the connected device. After you install SN2 on an Android device, you can automate that device using Android Gateway or the command line.
Automating with Android Gateway
If you're using Android Gateway, enter parameters only in the Custom Parameters field in the Android Gateway GUI.
Automating with the Command Line
If you're automating Android devices using the command line, use this syntax to open SN2 and begin automation:
SystemNative2 --parameters
.
The available parameters are described below:
Connection Parameters
These parameters apply to Android connections.
| Parameter | Definition |
|---|---|
--port NNNN | Specifies the port number. The default is 5900. |
--reverse <ip_address> | Specifies the IP address for a reverse connection. |
--rc-port NNNN | Specifies the port number for a reverse connection. The default is 5500. |
--always-share--may-share--never-share | Specifies whether or not the server can work with multiple clients. The default value is --always-share. When --may-share is specified, client settings determine whether or not to share the server. See also --keep-connected. |
--keep-connected--replace-connected | Chooses what to do when the server is not being shared between clients, but a second client tries to connect. See also --never-share. |
--forward <Address> <Port> | Forwards messages to a different server. This is useful when working with LG G5 devices. |
--no-forwarding | Switches off forwarding. |
--java-port <INT> | Uses the specified port for internal communication between SN2 and EggSensor. Note that this option is the same as --es-ports NNN NNN. |
--es-ports <Min> <Max> | Iterates through the specified range to find an available TCP port on the phone, and uses that port for internal communication between SN2 and EggSensor. The default range is 6000-6050. |
--zc <host> <port> | Enables Zeroconf. The host can be either a symbolic name or a dot-separated IP address. |
Debugging Parameters
These parameters apply to debugging.
| Parameter | Definition |
|---|---|
--trace-client | Prints debugging information related to receiving and parsing messages. |
--trace-client-config | Prints debugging information related to client configuration. |
--trace-client-manager | Prints debugging information related to processing messages. |
--trace-connection | Displays connection messages. |
--trace-core | Turns on all VNC/core traces. |
--trace-file-transfer | Traces file transfers from the SUT. |
--trace-inbound | Displays inbound messages. |
--trace-outbound | Displays outbound messages, except screen update messages. |
--trace-performance | Prints a table every 10 seconds that shows how much time was spent on different sections of code. |
--trace-procedural | Displays procedural messages. |
--trace-screen | Displays outbound screen update messages. |
--trace-es-connection | Switches on traces for the connection between SN2 and EggSensor. |
--trace-es-other | Switches on less verbose traces related to EggSensor. |
--trace-keyboard | Traces keyboard events. |
--trace-eggboard | Traces the Unicode keyboard (Eggboard). |
--trace-mouse-config | Traces mouse detection and configuration. |
--trace-screen-config | Traces the configuration of the screen capture method. |
--trace-android | Traces functionality specific to Android. Using this trace with --trace-core enables all available traces. |
General Parameters
These are general parameters for Android testing.
| Parameter | Definition |
|---|---|
--help | Displays this help file. |
--version | Displays the version information, then exits immediately. |
--empty-password | Sets the password to be an empty string. |
--interactive | Makes SN2 read commands from stdin. |
--password password | Specifies the password. "WordToPass" is the default. |
--no-eggsensor | Does not start EggSensor. Set device orientation will not work, and change device orientation notifications will not be sent. This option can help when EggSensor is not compatible with the SUT system. |
--enable-unicode | Establishes a socket connection to Eggboard, which can enter Unicode strings. Disabled by default. |
--disable-unicode | Does not establish a socket connection to Eggboard. Unicode characters will not be available. Use this option if Eggboard is not working or is causing issues. |
Mouse Parameters
These parameters apply to touch gestures.
| Parameter | Description |
|---|---|
--mouse-device <PATH> | Selects a path for the mouse device. This value is only used with --power-mouse. This option should be used only when the program detects the device incorrectly. In all other cases, use --mouse-device-auto. |
--power-mouse--scaled-mouse--portable-mouse | Chooses the algorithm for controlling the mouse. Portable supports only taps and swipes, not long holds or multitouch gestures. Power mouse supports long holds and pinches. Scaled mouse is similar to power mouse, except it expects different IDs for mouse coordinates. SN2 defaults to power mouse mode; if that fails, SN2 switches to portable mouse mode. |
--mouse-device-auto | Enabled by default. Runs in power mouse mode, and tries to automatically detect the path for the mouse , and whether it is a button mouse. |
--button-mouse | Tweaks the --power-mouse algorithm to make it work with a few devices that need this option. |
--no-button-mouse | Tweaks the --power-mouse algorithm to make it work with certain devices. Most devices work with this option. |
--detect-button-mouse | Attempts to detect the type of mouse (button or non-button) using the --power-mouse setting. This option is enabled by default. |
--timeless-mouse | Doesn't send timestamps to the mouse. This option can be useful when testing older devices. |
--backward-mouse | Flips the coordinates for the mouse. This command is deprecated; use --mouse-rot instead. |
--mouse-rot 0--mouse-rot 1--mouse-rot 2--mouse-rot 3 | Turns the mouse coordinates by 0, 90, 180, or 270 degrees, respectively. This can help if the screen displays incorrectly in the Eggplant Functional Viewer window. |
--message-spacing <#Nanoseconds> | This command affects how Android Gateway processes mouse events. It should only be used while working with Eggplant support. |
Screen Parameters
These parameters apply to screen specifications including size, colors, and rotation.
| Parameter | Definition |
|---|---|
--scale-screen <INT> | Scales down the screen size by a given factor to enable faster screen updates. For example, --scale-screen 2 reports a screen resolution of half the actual width and height, and transmits only a quarter of the original number of pixels. This option is useful when working with high resolution screens. |
--blend | Blends the pixels on a scaled screen instead of dropping them. Blending provides a better image, but can be slower to load. |
--max-fps <number> | Limits how many screenshots the VNC server takes per second. The default is 5. This value can be a float number. A high frame rate can drain the device battery even if the device is connected to a power source. A lower frame rate also allows more processor time to be spent executing the test. |
--screen-slicing NX NY | Define screen slicing. By default, NX and NY are 8. |
--enable-jpeg--disable-jpeg | Enables or disables TightVNC encoding, which compresses screenshots using JPEG formatting. |
--enable-zlib--disable-zlib | Enables or disables compression using the zlib standard. |
--jpeg-compress-level L | Sets the compression level for JPEG encoding. For good quality source images, the default (75) is the best choice. The valid range is 0 to 100. For more information see the JPEG image compression FAQ. |
--zlib-compress-level L | Sets the compression level for zlib encoding. |
--rgb-auto--rgb-reverse--rgb-straight | In --rgb-auto mode, the default, the server decides whether to reverse the byte order in the pixel according to the pixel format requested by the client. |
--force-rot | Forces SN2 to rotate the image. Prior to Android 6.0, the image that came from Android OS to SN2 was not rotated, and SN2 had to rotate it, so it would appeared readable in Eggplant Functional. In Android 6.0 and later, SN2 receives an already rotated image. This option forces SN2 to rotate images even on Android 6.0 and later. This option is implemented in case some devices do not have this updated behavior. |
--screen-rot 0--screen-rot 1--screen-rot 2--screen-rot 3 | Turns the screen by 0, 90, 180, or 270 degrees, respectively. |
--screencap-use-popen--screencap-use-socket--screencap-use-pipe--screencap-use-pipe-sys2 | Selects a method for screen capture. The default is --screencap-use-pipe. This method works on most devices, but not on LG H831. Methods using ...-pipe are the best to use, because they can handle hangs in screen capture. |
--screencap-use-pipe-test | Enable other algorithms for screen capture. |
--screencap-dummy | Used for testing and VNC forwarding. |
--hack-orientation | Enables an alternative algorithm for changing screen orientation. This option can have unexpected side effects, so do not use unless you have to. |
--force-ts-range <X> <Y> | Defines the touch screen range. For use with devices (i.e., MC9200), where the dimensions of the touch screen can't be figured out automatically. |