com.googlecode.autoandroid.positron
Interface PositronAPI

All Known Implementing Classes:
Positron, PositronClient, TestCase, TestCase

public interface PositronAPI

A portable interface defining positron's features.

Author:
philhsmith

Nested Class Summary
static interface PositronAPI.Intents
          Constants from Intent.
static interface PositronAPI.Key
          Constants from KeyEvent.
static interface PositronAPI.Menu
          Constants from Menu.
static interface PositronAPI.Motion
          Constants from MotionEvent.
 
Method Summary
 void backup()
          Backup all databases in the tested application.
 void backup(String database)
          Backup the given database.
 boolean booleanAt(int depth, String path)
          Evaluate the ViewShorthand path starting from the activity at the given depth.
 boolean booleanAt(String path)
          Evaluate the ViewShorthand path starting from the current activity.
 void click()
          sendKeyDownUp(KEYCODE_DPAD_CENTER)
 boolean contextMenu(int id)
          invokeContextMenuActionSync with the current activity.
 boolean contextMenu(int id, int flag)
          invokeContextMenuActionSync with the current activity.
 boolean contextMenu(int depth, int id, int flag)
          invokeContextMenuActionSync with the activity at the given depth on the stack, resuming momentarily if necessary.
 double doubleAt(int depth, String path)
          Evaluate the ViewShorthand path starting from the activity at the given depth.
 double doubleAt(String path)
          Evaluate the ViewShorthand path starting from the current activity.
 void drag(float startX, float startY, float endX, float endY)
          Drag from one point on the screen to another.
 void drag(String start, String end)
          Drag from the center of one view to the center of another.
 void finish()
          Finish the current activity.
 void finish(int depth)
          Activity.finish() the activity with the given depth on the stack.
 void finishAll()
          Finish all detected activities on the stack.
 void flick(float x, float y)
          Flick the trackball in the given direction.
 float floatAt(int depth, String path)
          Evaluate the ViewShorthand path starting from the activity at the given depth.
 float floatAt(String path)
          Evaluate the ViewShorthand path starting from the current activity.
 int intAt(int depth, String path)
          Evaluate the ViewShorthand path starting from the activity at the given depth.
 int intAt(String path)
          Evaluate the ViewShorthand path starting from the current activity.
 boolean menu(int id)
          invokeMenuAction with the current activity.
 boolean menu(int id, int flag)
          invokeMenuAction with the current activity.
 boolean menu(int depth, int id, int flag)
          invokeMenuActionSync with the activity at the given depth on the stack, resuming momentarily if necessary.
 void pause()
          Pause execution of the target package.
 boolean paused()
          Is the target package paused?
 void press(Object... keys)
          sendKeyDownUpSync on all keys in order, resuming momentarily if necessary.
 void quit()
          Stop the positron instrumentation and cleanup.
 void restore()
          Restore all databases in the tested application that have backups.
 void restore(String database)
          Restore the given database from a previous backup call.
 void resume()
          Resume executing the target package if it has been paused.
 void sendCharacter(int keyCode)
          sendCharacterSync, resuming momentarily if necessary.
 void sendKey(int action, int code)
          sendKeySync, resuming momentarily if necessary.
 void sendKey(long eventTimeAfterDown, int action, int code, int repeat)
          sendKeySync, resuming momentarily if necessary.
 void sendKey(long eventTimeAfterDown, int action, int code, int repeat, int metaState)
          sendKeySync, resuming momentarily if necessary.
 void sendKey(long eventTimeAfterDown, int action, int code, int repeat, int metaState, int device, int scancode)
          sendKeySync, resuming momentarily if necessary.
 void sendKey(long eventTimeAfterDown, int action, int code, int repeat, int metaState, int device, int scancode, int flags)
          sendKeySync, resuming momentarily if necessary.
 void sendKeyDownUp(int key)
          sendKeyDownUpSync, resuming momentarily if necessary.
 void sendPointer(int action, float x, float y)
          Send a MotionEvent via sendPointerSync, resuming momentarily if needed.
 void sendPointer(int action, float x, float y, int metaState)
          Send a MotionEvent via sendPointerSync, resuming momentarily if needed.
 void sendPointer(long eventTimeAfterDown, int action, float x, float y, float pressure, float size, int metaState, float xPrecision, float yPrecision, int deviceId, int edgeFlags)
          Send a MotionEvent via sendPointerSync, resuming momentarily if needed.
 void sendPointer(long eventTimeAfterDown, int action, float x, float y, int metaState)
          Send a MotionEvent via sendPointerSync, resuming momentarily if needed.
 void sendString(String text)
          sendStringSync, resuming momentarily if necessary.
 void sendTrackball(int action, float x, float y)
          Send a MotionEvent via sendTrackballEventSync, resuming momentarily if needed.
 void sendTrackball(int action, float x, float y, int metaState)
          Send a MotionEvent via sendTrackballEventSync, resuming momentarily if needed.
 void sendTrackball(long eventTimeAfterDown, int action, float x, float y, float pressure, float size, int metaState, float xPrecision, float yPrecision, int deviceId, int edgeFlags)
          Send a MotionEvent via sendTrackballEventSync, resuming momentarily if needed.
 void sendTrackball(long eventTimeAfterDown, int action, float x, float y, int metaState)
          Send a MotionEvent via sendTrackballEventSync, resuming momentarily if needed.
 void sql(String database, String script)
          Execute the given Sql script.
 void startActivity(String action)
          startActivitySync, resuming momentarily if necessary.
 void startActivity(String packageName, String className)
          startActivitySync, resuming momentarily if necessary.
 void startActivity(String action, String[] categories)
          startActivitySync, resuming momentarily if necessary.
 void startActivity(String action, String[] categories, int[] flags)
          startActivitySync, resuming momentarily if necessary.
 void startActivity(String action, String data, String type)
          startActivitySync, resuming momentarily if necessary.
 void startActivity(String action, String data, String type, String[] categories, int[] flags)
          startActivitySync, resuming momentarily if necessary.
 String stringAt(int depth, String path)
          Evaluate the ViewShorthand path starting from the activity at the given depth.
 String stringAt(String path)
          Evaluate the ViewShorthand path starting from the current activity.
 void touch(float x, float y)
          Touch the screen (or click the pointer) at the given location.
 void touch(String path)
          Touch the screen (or click the pointer) at the center of the view with the given path.
 boolean waitFor(int depth, String path, String value, long timeout)
          Wait until value.equals(stringAt(depth, path)) or the given timeout expires, then pause().
 boolean waitFor(String path, String value, long timeout)
          Wait until value.equals(stringAt(path)) or the given timeout expires, then pause().
 

Method Detail

backup

void backup()
Backup all databases in the tested application.


backup

void backup(String database)
Backup the given database.


booleanAt

boolean booleanAt(int depth,
                  String path)
Evaluate the ViewShorthand path starting from the activity at the given depth.

Returns:
The result as a boolean.

booleanAt

boolean booleanAt(String path)
Evaluate the ViewShorthand path starting from the current activity.

Returns:
The result as a boolean.

click

void click()
sendKeyDownUp(KEYCODE_DPAD_CENTER)


doubleAt

double doubleAt(int depth,
                String path)
Evaluate the ViewShorthand path starting from the activity at the given depth.

Returns:
The result as a double.

doubleAt

double doubleAt(String path)
Evaluate the ViewShorthand path starting from the current activity.

Returns:
The result as a double.

sql

void sql(String database,
         String script)
Execute the given Sql script.


finish

void finish()
Finish the current activity.


finish

void finish(int depth)
Activity.finish() the activity with the given depth on the stack.


finishAll

void finishAll()
Finish all detected activities on the stack.


floatAt

float floatAt(int depth,
              String path)
Evaluate the ViewShorthand path starting from the activity at the given depth.

Returns:
The result as a float.

floatAt

float floatAt(String path)
Evaluate the ViewShorthand path starting from the current activity.

Returns:
The result as a float.

intAt

int intAt(int depth,
          String path)
Evaluate the ViewShorthand path starting from the activity at the given depth.

Returns:
The result as an int.

intAt

int intAt(String path)
Evaluate the ViewShorthand path starting from the current activity.

Returns:
The result as an int.

menu

boolean menu(int id)
invokeMenuAction with the current activity.


menu

boolean menu(int id,
             int flag)
invokeMenuAction with the current activity.


menu

boolean menu(int depth,
             int id,
             int flag)
invokeMenuActionSync with the activity at the given depth on the stack, resuming momentarily if necessary.


contextMenu

boolean contextMenu(int id)
invokeContextMenuActionSync with the current activity.


contextMenu

boolean contextMenu(int id,
                    int flag)
invokeContextMenuActionSync with the current activity.


contextMenu

boolean contextMenu(int depth,
                    int id,
                    int flag)
invokeContextMenuActionSync with the activity at the given depth on the stack, resuming momentarily if necessary.


pause

void pause()
Pause execution of the target package. This is useful for inspecting the view state of the target package, since doing so while it is running can create race conditions. Inspect this state using the various 'at' methods. Resume execution with resume(). Pausing an already-paused application is a safe no-op. Paused applications can't respond to events, nor execute synchronous commands such as sendStringSync (or any *Sync.) Keep this in mind when writing tests. Pausing is done by asynchronously calling Instrumentation.runOnMainSync on a blocking operation.


paused

boolean paused()
Is the target package paused?


press

void press(Object... keys)
sendKeyDownUpSync on all keys in order, resuming momentarily if necessary. Combined with the renamed constants available in positron.TestCase, this enables things like press(UP, UP, DOWN, DOWN, LEFT, RIGHT, LEFT, RIGHT, "ba") which may otherwise be cumbersome.

Parameters:
keys - A mixture of ints and Strings. ints are sent with sendKeyDownUpSync, Strings are send with sendStringSync.
Throws:
IllegalArgumentException - if something other than an int or String was passed.

quit

void quit()
Stop the positron instrumentation and cleanup.


resume

void resume()
Resume executing the target package if it has been paused. Resuming an unpaused package is a safe noop.


restore

void restore(String database)
Restore the given database from a previous backup call. This deletes the backup as well.


restore

void restore()
Restore all databases in the tested application that have backups.


sendCharacter

void sendCharacter(int keyCode)
sendCharacterSync, resuming momentarily if necessary.


sendKey

void sendKey(int action,
             int code)
sendKeySync, resuming momentarily if necessary.


sendKey

void sendKey(long eventTimeAfterDown,
             int action,
             int code,
             int repeat)
sendKeySync, resuming momentarily if necessary. KeyEvents (within the android api) take a downTime which needs to be given as milliseconds from system start, from the uptimeMillis() call. Since stories won't likely have that number around, positron uses the current uptimeMillis for the downTime. An eventTime may be given as milliseconds relative to downTime; the downTime will be added.


sendKey

void sendKey(long eventTimeAfterDown,
             int action,
             int code,
             int repeat,
             int metaState)
sendKeySync, resuming momentarily if necessary. KeyEvents (within the android api) take a downTime which needs to be given as milliseconds from system start, from the uptimeMillis() call. Since stories won't likely have that number around, positron uses the current uptimeMillis for the downTime. An eventTime may be given as milliseconds relative to downTime; the downTime will be added.


sendKey

void sendKey(long eventTimeAfterDown,
             int action,
             int code,
             int repeat,
             int metaState,
             int device,
             int scancode)
sendKeySync, resuming momentarily if necessary. KeyEvents (within the android api) take a downTime which needs to be given as milliseconds from system start, from the uptimeMillis() call. Since stories won't likely have that number around, positron uses the current uptimeMillis for the downTime. An eventTime may be given as milliseconds relative to downTime; the downTime will be added.


sendKey

void sendKey(long eventTimeAfterDown,
             int action,
             int code,
             int repeat,
             int metaState,
             int device,
             int scancode,
             int flags)
sendKeySync, resuming momentarily if necessary. KeyEvents (within the android api) take a downTime which needs to be given as milliseconds from system start, from the uptimeMillis() call. Since stories won't likely have that number around, positron uses the current uptimeMillis for the downTime. An eventTime may be given as milliseconds relative to downTime; the downTime will be added.


sendKeyDownUp

void sendKeyDownUp(int key)
sendKeyDownUpSync, resuming momentarily if necessary.


sendString

void sendString(String text)
sendStringSync, resuming momentarily if necessary.


startActivity

void startActivity(String action)
startActivitySync, resuming momentarily if necessary.


startActivity

void startActivity(String packageName,
                   String className)
startActivitySync, resuming momentarily if necessary.


startActivity

void startActivity(String action,
                   String data,
                   String type)
startActivitySync, resuming momentarily if necessary.


startActivity

void startActivity(String action,
                   String data,
                   String type,
                   String[] categories,
                   int[] flags)
startActivitySync, resuming momentarily if necessary.


startActivity

void startActivity(String action,
                   String[] categories)
startActivitySync, resuming momentarily if necessary.


startActivity

void startActivity(String action,
                   String[] categories,
                   int[] flags)
startActivitySync, resuming momentarily if necessary.


stringAt

String stringAt(int depth,
                String path)
Evaluate the ViewShorthand path starting from the activity at the given depth.

Returns:
The result as a String.

stringAt

String stringAt(String path)
Evaluate the ViewShorthand path starting from the current activity.

Returns:
The result as a String.

touch

void touch(float x,
           float y)
Touch the screen (or click the pointer) at the given location. This uses sendPointer to send an ACTION_DOWN, and an ACTION_UP a little later.


touch

void touch(String path)
Touch the screen (or click the pointer) at the center of the view with the given path. Once the center of the view is found, this behaves as touch(float, float).


drag

void drag(float startX,
          float startY,
          float endX,
          float endY)
Drag from one point on the screen to another. This uses sendPointer to send an ACTION_DOWN at (startX, startY), followed by an ACTION_MOVE to (endX, endY), and finally an ACTION_UP.


drag

void drag(String start,
          String end)
Drag from the center of one view to the center of another. Once the centers have been found, this behaves as drag(float, float, float, float).


sendPointer

void sendPointer(int action,
                 float x,
                 float y)
Send a MotionEvent via sendPointerSync, resuming momentarily if needed. The eventTimeAfterDown and metaState are both taken to be 0.


sendPointer

void sendPointer(int action,
                 float x,
                 float y,
                 int metaState)
Send a MotionEvent via sendPointerSync, resuming momentarily if needed. The eventTimeAfterDown is taken to be 0.


sendPointer

void sendPointer(long eventTimeAfterDown,
                 int action,
                 float x,
                 float y,
                 int metaState)
Send a MotionEvent via sendPointerSync, resuming momentarily if needed. MotionEvents (within the android api) take a downTime which needs to be given as milliseconds from system start, from the uptimeMillis() call. Since stories won't likely have that number around, positron uses the current uptimeMillis for the downTime. An eventTime may be given as milliseconds relative to downTime; the downTime will be added.

Parameters:
eventTimeAfterDown - Time in milliseconds since the initial down event.
action - One of the MotionEvent action constants.
x - The x coordinate.
y - The y coordinate.
metaState - Any meta / modifier keys to hold while the sending the event.

sendPointer

void sendPointer(long eventTimeAfterDown,
                 int action,
                 float x,
                 float y,
                 float pressure,
                 float size,
                 int metaState,
                 float xPrecision,
                 float yPrecision,
                 int deviceId,
                 int edgeFlags)
Send a MotionEvent via sendPointerSync, resuming momentarily if needed. MotionEvents (within the android api) take a downTime which needs to be given as milliseconds from system start, from the uptimeMillis() call. Since stories won't likely have that number around, positron uses the current uptimeMillis for the downTime. An eventTime may be given as milliseconds relative to downTime; the downTime will be added.


flick

void flick(float x,
           float y)
Flick the trackball in the given direction.


sendTrackball

void sendTrackball(int action,
                   float x,
                   float y)
Send a MotionEvent via sendTrackballEventSync, resuming momentarily if needed. The eventTimeAfterDown and metaState are both taken to be 0.


sendTrackball

void sendTrackball(int action,
                   float x,
                   float y,
                   int metaState)
Send a MotionEvent via sendTrackballEventSync, resuming momentarily if needed. The eventTimeAfterDown is taken to be 0.


sendTrackball

void sendTrackball(long eventTimeAfterDown,
                   int action,
                   float x,
                   float y,
                   int metaState)
Send a MotionEvent via sendTrackballEventSync, resuming momentarily if needed. MotionEvents (within the android api) take a downTime which needs to be given as milliseconds from system start, from the uptimeMillis() call. Since stories won't likely have that number around, positron uses the current uptimeMillis for the downTime. An eventTime may be given as milliseconds relative to downTime; the downTime will be added.

Parameters:
eventTimeAfterDown - Time in milliseconds since the initial down event.
action - One of the MotionEvent action constants.
x - The x coordinate.
y - The y coordinate.
metaState - Any meta / modifier keys to hold while the sending the event.

sendTrackball

void sendTrackball(long eventTimeAfterDown,
                   int action,
                   float x,
                   float y,
                   float pressure,
                   float size,
                   int metaState,
                   float xPrecision,
                   float yPrecision,
                   int deviceId,
                   int edgeFlags)
Send a MotionEvent via sendTrackballEventSync, resuming momentarily if needed. MotionEvents (within the android api) take a downTime which needs to be given as milliseconds from system start, from the uptimeMillis() call. Since stories won't likely have that number around, positron uses the current uptimeMillis for the downTime. An eventTime may be given as milliseconds relative to downTime; the downTime will be added.


waitFor

boolean waitFor(String path,
                String value,
                long timeout)
Wait until value.equals(stringAt(path)) or the given timeout expires, then pause(). If paused() initially, resume() before waiting. Handy for events (like those from the touch screen) that continue to have side-effects even after the initial event has been processed. This method necessarily polls state in a pause() / resume() cycle. It is possible for the condition to be missed if it is only briefly or intermittently true.

Parameters:
path - The view shorthand expression to watch.
value - The value to wait for.
timeout - Time in milliseconds to wait before giving up and pausing anyway.
Returns:
True if the condition was met before the timeout expired.

waitFor

boolean waitFor(int depth,
                String path,
                String value,
                long timeout)
Wait until value.equals(stringAt(depth, path)) or the given timeout expires, then pause(). If paused() initially, resume() before waiting. Handy for events (like those from the touch screen) that continue to have side-effects even after the initial event has been processed. This method necessarily polls state in a pause() / resume() cycle. It is possible for the condition to be missed if it is only briefly or intermittently true.

Parameters:
depth - The depth down the activity stack
path - The view shorthand expression to watch.
value - The value to wait for.
timeout - Time in milliseconds to wait before giving up and pausing anyway.
Returns:
True if the condition was met before the timeout expired.