org.safs.ios

Class Utilities

java.lang.Object

org.safs.ios.Utilities

public class Utilities
extends java.lang.Object

Utilities for the IOS testing environment including the preparation, launch, and monitoring of UIAutomation using the Instruments SDK tool.

Author:

Carl Nagle

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Utilities.ResultsFileFilter Used internally when seeking Instruments active output.
static class	Utilities.RunDirFilter Used internally when deleting and opening Instruments active output.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CAPTURE_INSTRUMENTS_HOTSPOT_ASCRIPT "Instruments/captureInstrumentsHotspot.scpt" Normally appended to ROOT_ASCRIPTS_DIR
static java.lang.String	CAPTURE_INSTRUMENTS_HOTSPOT_DIR default: ROOT_ASCRIPTS_DIR
static java.lang.String	CAPTURE_INSTRUMENTS_HOTSPOT_EDITORMENU_FILE "editormenuhotspot.txt"
static java.lang.String	CAPTURE_INSTRUMENTS_HOTSPOT_EDITORMENU_MODE "editormenu"
static java.lang.String	CLOSE_ARRAY_LC "</array>" UIAutomation lower-case close tag for an array, usually of log messages.
static java.lang.String	CLOSE_DATE_LC "</date>" UIAutomation lower-case close tag for enclosed timestamp data.
static java.lang.String	CLOSE_DICT_LC "</dict>" UIAutomation lower-case close tag for the wrapper of log message data.
static java.lang.String	CLOSE_INTEGER_LC "</integer>" UIAutomation lower-case close tag for enclosed integer data.
static java.lang.String	CLOSE_STRING_LC "</string>" UIAutomation lower-case close tag for enclosed log message.
static java.lang.String	COMMENT_TAG_LC ":comment:" SAFS comment message prefix (lower-case) tagging a message to be used for SAFS execution status.
static java.lang.String	COMPLETE_TAG_LC ">script completed.<" UIAutomation lower-case message substring indicating a script has completed execution.
static int	currentobjectdepth
static java.lang.String	DEBUG_TAG_LC ":debug:" SAFS debug message prefix (lower-case) tagging a message to be delivered to the SAFS Debug Log.
static java.lang.String	DEFAULT_INSTRUMENTS_TEMPLATE null until set.
static java.lang.String	DEFAULT_JSSTARTUP_IMPORT "Utilities/startup.js"
static java.lang.String	DEFAULT_PROCESSCONTAINER_SCRIPT "ProcessContainer.js"
static java.lang.String	DEFAULT_SAFSRUNTIME_SCRIPT "SAFSRuntime.js"
static java.lang.String	DETAIL_TAG_LC ":detail:" SAFS comment details message prefix (lower-case) tagging a message to be used for SAFS execution status.
static java.lang.String	EXCEPTION_TAG_LC
(package private) static java.lang.String	indent
static java.lang.String	INSTRUMENTS_APPLICATIONSUPPORT_DIR "/Users/[username]/Library/Application Support/Instruments/"
static java.lang.String	INSTRUMENTS_BACKUPSCRIPTS_FILE "SAFSBackupScripts" Name of file used by SAFS to store original script preferences for restore.
static int	INSTRUMENTS_LAUNCH_TIMEOUT 20.
static java.lang.String	INSTRUMENTS_PREVIOUSSCRIPTS_FILE "PreviousScripts" Name of file used by Instruments to store script preferences
static boolean	IS_LION
static boolean	IS_OSX
static boolean	IS_SNOWLEOPARD
static java.lang.String	JSCRIPTS_ABSOLUTE_PATH "IS_ABSOLUTE_PATH" SubDir spec saying the item file path provided is NOT relative.
static java.lang.String	JSCRIPTS_HOOK "hook.js"
static java.lang.String	JSCRIPTS_IOSPCDATA "iospcdata.js"
static java.lang.String	JSCRIPTS_TRD "trd.js"
static java.lang.String	LAUNCH_INSTRUMENTS_ASCRIPT "Instruments/launchInstrumentsTemplate.scpt" Normally appended to ROOT_ASCRIPTS_DIR The default script requires 1 argument for the Instruments TraceTemplate to use.
static java.lang.String	LOOP_INSTRUMENTS_ASCRIPT "Instruments/restartInstrumentsScript.scpt" Normally appended to ROOT_ASCRIPTS_DIR
static java.lang.String	LOOP_INSTRUMENTS5_ASCRIPT "Instruments/restartInstruments5Script.scpt" Normally appended to ROOT_ASCRIPTS_DIR
static java.lang.String	LOOP_INSTRUMENTS5LION_ASCRIPT "Instruments/restartInstruments5LionScript.scpt" Normally appended to ROOT_ASCRIPTS_DIR
static int	MAJOR_VERSION
static java.lang.String	MESSAGE_TAG_LC ">message<" UIAutomation lower-case log key tag identifying a Message String follows.
static int	MINOR_RELEASE_VERSION
static int	MINOR_VERSION
static int	newobjectdepth
static java.lang.String	OPEN_ARRAY_LC "<array>" UIAutomation lower-case open tag for an array, usually of log messages.
static java.lang.String	OPEN_DATE_LC "<date>" UIAutomation lower-case open tag for enclosed timestamp data.
static java.lang.String	OPEN_DICT_LC "<dict>" UIAutomation lower-case close tag for the wrapper of log message data.
static java.lang.String	OPEN_INTEGER_LC "<integer>" UIAutomation lower-case open tag for enclosed integer data.
static java.lang.String	OPEN_STRING_LC "<string>" UIAutomation lower-case open tag for enclosed log message.
static java.lang.String	OS_VERSION Retrieved from System.getProperty("os.version");
static java.lang.String	PATH_SELECT_RECENT_SCRIPT_ASCRIPT "Instruments/selectRecentScript.scpt" Default applescript relative to overall SAFS applescript root directory.
static java.lang.String	PROCESSCONTAINER_INSTRUMENTS_PREFS "recent/ProcessContainer"
static java.lang.String	ROOT_ASCRIPTS_DIR "/Library/SAFS/IOS/ascript/"
static java.lang.String	ROOT_IBT_IMAGES_DIR "/Library/SAFS/IOS/ibt/images/"
static java.lang.String	ROOT_INSTRUMENTS_DIR "/Library/SAFS/IOS/instruments/"
static java.lang.String	ROOT_INSTRUMENTS_OUTPUT_DIR null until set.
static java.lang.String	ROOT_INSTRUMENTS_PROJECT_DIR null until set.
static java.lang.String	ROOT_JSCRIPTS_DIR "/Library/SAFS/IOS/jscript/"
static java.lang.String	rootRunDir SAFSDIR variable export from STAFEnv.sh script
static java.lang.String	SAFSRUNTIME_INSTRUMENTS_PREFS "recent/SAFSRuntime"
static java.io.BufferedWriter	spcAppMapWriter Used internally for appending process container App Map information to output file.
static java.lang.String	SPCMAP_TAG_LC ":spcmap:" IOS Process Container app map output message prefix (lower-case) tagging a message to be used for IOS Process Container App Map output.
static java.lang.String	SPCOUT_TAG_LC ":spcout:" IOS Process Container output message prefix (lower-case) tagging a message to be used for IOS Process Container output.
static java.io.BufferedWriter	spcOutputWriter Used internally for writing process container object information to output file.
static boolean	spcOutputXML true if object information to output file should be in XML format.
static java.lang.String	START_INSTRUMENTS_ASCRIPT "Instruments/startInstrumentsTrace.scpt" Normally appended to ROOT_ASCRIPTS_DIR
static java.lang.String	STARTSCRIPT_IMAGE "startscript/StartScript.bmp" Normally appended to ROOT_IBT_IMAGES_DIR
static int	STATE_APP
static int	STATE_CHILD
static int	STATE_CHILD_COMPLETE
static int	STATE_CHILD_PROP
static int	STATE_INIT
static int	STATE_SYSTEM
static int	STATE_WIN
static int	STATE_WIN_PROP
static java.lang.String	STATUS_TAG_LC ":status:" SAFS status message prefix (lower-case) tagging a message to be used for SAFS statusCode.
static java.lang.String	STOP_INSTRUMENTS_ASCRIPT "Instruments/stopInstrumentsTrace.scpt" Normally appended to ROOT_ASCRIPTS_DIR
static java.lang.String	TAG_USERNAME "[username]"
static java.lang.String	TIME_TAG_LC ">timestamp<" UIAutomation lower-case message substring indicating a date/time timestamp is next to be logged.
static java.lang.String	TYPE_TAG_LC ">type<" UIAutomation lower-case message substring indicating the type or level of the log message.
static java.lang.String	UNCAUGHT_ERROR_TAG_LC
static java.lang.String	USER_STOPPED_SCRIPT_TAG_LC
static int	xmlstate -1: init state; 0: system out state; 1: app out state; 2: win out state; 3: child out state;

Constructor Summary

Constructors

Constructor and Description
Utilities()

Method Summary

Modifier and Type	Method and Description
protected static void	addXMLAttribute(java.lang.String msgtext) Assumes a node has already been started.
protected static void	addXMLProperty(java.lang.String msgtext) Assumes a property node has already been started.
protected static void	closeXMLState(int toState) output whatever is required to close the current xml for the current xml state.
static void	copyFile(java.io.File source, java.io.File target) Copy the bytes of one file overwriting or creating a new file.
(package private) static void	debug(java.lang.String message) Writes to SAFS Debug "Log" at this time.
static void	deletePreviousRuns() calls deletePreviousRun with null for default operation.
static void	deletePreviousRuns(java.lang.String rootRunDir) Delete all previous Instruments test output results files and directories.
static void	executeNextInstrumentsTest(java.lang.String script) calls the following routines using all defaults except the varying script to run: prepareNextInstruments(script); nextInstrumentsTest(); waitScriptComplete(); The routine expects that Instruments is already running and Record Trace has already been started.
static void	findRunningLastLine(java.lang.String rootRunDir) Process the assumed to be running Instruments Log file to identify the last valid Script Completed message.
(package private) static IStatus	getIStatus() Return the current/last IStatus object generated from execution of an Instruments Script.
static void	killAllInstruments() Attempt to kill all "Instruments" processes using "killall".
static void	killAllSimulators() Attempt to kill all IOS "Simulator" processes using "killall".
static ProcessCapture	launchInstrumentsTest(java.lang.String template) Launch the Instruments SDK tool with the specified template using other default parameters.
static ProcessCapture	launchInstrumentsTest(java.lang.String sourcedir, java.lang.String script, java.lang.String template) Launch the Instruments SDK tool with the specified template.
static void	main(java.lang.String[] args) Original POC execution.
protected static java.lang.String	makePCIndent()
static ProcessCapture	nextInstrumentsTest() Activates the Instruments application and attempts to find and click the "Start Script" button using default settings.
static ProcessCapture	nextInstrumentsTest(java.lang.String ascriptdir, java.lang.String script) Activates the Instruments application and attempts to find and click the "Start Script" button.
protected static void	openXMLState(int state) calls closeXMLState prior to its own output.
static void	prepareNewAutomationTest() Convenience routine to delete all logs from previous runs, reset the Instruments log line counter, and preset the correct Instruments "recent" scripts for a test automation run.
static void	prepareNewAutomationTest(java.lang.String projectpath) Convenience routine to optionally change the Instruments Project, delete all logs from previous runs, reset the Instruments log line counter, and preset the correct Instruments "recent" scripts for a test automation run.
static void	prepareNextInstrumentsTest(java.lang.String script) calls prepareNexInstrumentsTest with null for sourcedir and targetdir for default operation.
static void	prepareNextInstrumentsTest(java.lang.String sourcedir, java.lang.String script, java.lang.String targetdir) Copy/Rename a JavaScript snippet to JSCRIPTS_HOOK and store for the next script execution.
static void	prepareNextProcessContainerData(java.lang.String targetdir, boolean doChildren, boolean doProperties, boolean appendMap, boolean addInfo, boolean doShortStrings, java.lang.String windowName, java.lang.String windowRec, java.lang.String objectRec) Outputs
static void	prepareNextTestRecordData(TestRecordData trd) Copy TestRecordHelper data to JSCRIPTS_TRD and store for the next script execution.
static void	prepareNextTestRecordData(TestRecordData trd, java.lang.String targetdir) Copy TestRecordHelper data to JSCRIPTS_TRD and store for the next script execution.
static void	presetInstrumentsScript(java.lang.String sourcedir, java.lang.String sourcepreference, java.lang.String supportdir, java.lang.String supportpreference) Set the Instruments tools preferred script.
static void	presetProcessContainerInstrumentsScript() calls presetInstrumentsScript for ProcessContainer using all other defaults.
static void	presetWrapperInstrumentsScript() calls presetInstrumentsScript using all default parameters.
static void	resetInstrumentsLogCounter() reset our Instruments log parser to monitor the beginning of the log.
(package private) static void	resetIStatus() Reset the collection of fields used for a single call to execute an Instruments script. rc reset to SCRIPT_NOT_EXECUTED.
static void	restoreInstrumentsScript() call restoreInstrumentsScript with nulls to use defaults.
static void	restoreInstrumentsScript(java.lang.String supportdir, java.lang.String supportpreference, java.lang.String supportbackup) Restore the Instruments tools preferred script from its backup.
static ProcessCapture	runAppleScript(java.lang.String sourcedir, java.lang.String script, java.lang.String arguments, boolean wait, long secstimeout) Run an AppleScript via osascript.
static ProcessCapture	startInstrumentsTest() calls startInstrumentsTest with null to use defaults.
static ProcessCapture	startInstrumentsTest(java.lang.String sourcedir, java.lang.String script) Start the Instruments SDK tool Record Trace.
static ProcessCapture	stopInstrumentsTest() calls stopInstrumentsTest with nulls to use defaults.
static ProcessCapture	stopInstrumentsTest(java.lang.String sourcedir, java.lang.String script) Stop the Instruments SDK tool Record Trace.
static java.io.File	verifyInstrumentsRecording(java.lang.String rootRunDir) Locate and return a File reference to the most recent Results file from an active Instruments Script.
static void	waitScriptComplete() calls waitScriptComplete with null to use preset ROOT_INSTRUMENTS_PROJECT_DIR.
static void	waitScriptComplete(java.lang.String rootRunDir) Repetitively monitor the active "Automation Results" file for "Script Complete" during Instruments script execution.
static void	writeDataToFile(java.lang.String data, java.lang.String targetdir, java.lang.String filename, boolean append) Write data to filename in optional targetdir.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

rootRunDir

public static java.lang.String rootRunDir

SAFSDIR variable export from STAFEnv.sh script

ROOT_ASCRIPTS_DIR

public static java.lang.String ROOT_ASCRIPTS_DIR

"/Library/SAFS/IOS/ascript/"

ROOT_JSCRIPTS_DIR

public static java.lang.String ROOT_JSCRIPTS_DIR

"/Library/SAFS/IOS/jscript/"

PATH_SELECT_RECENT_SCRIPT_ASCRIPT

public static java.lang.String PATH_SELECT_RECENT_SCRIPT_ASCRIPT

"Instruments/selectRecentScript.scpt" Default applescript relative to overall SAFS applescript root directory. This is used to set IOS Instruments execution script. Primarily for IOS 5 and later.

JSCRIPTS_ABSOLUTE_PATH

public static final java.lang.String JSCRIPTS_ABSOLUTE_PATH

"IS_ABSOLUTE_PATH" SubDir spec saying the item file path provided is NOT relative. It is absolute.

See Also:

Constant Field Values

JSCRIPTS_HOOK

public static java.lang.String JSCRIPTS_HOOK

"hook.js"

JSCRIPTS_TRD

public static java.lang.String JSCRIPTS_TRD

"trd.js"

JSCRIPTS_IOSPCDATA

public static java.lang.String JSCRIPTS_IOSPCDATA

"iospcdata.js"

DEFAULT_JSSTARTUP_IMPORT

public static java.lang.String DEFAULT_JSSTARTUP_IMPORT

"Utilities/startup.js"

DEFAULT_SAFSRUNTIME_SCRIPT

public static java.lang.String DEFAULT_SAFSRUNTIME_SCRIPT

"SAFSRuntime.js"

DEFAULT_PROCESSCONTAINER_SCRIPT

public static java.lang.String DEFAULT_PROCESSCONTAINER_SCRIPT

"ProcessContainer.js"

TAG_USERNAME

public static final java.lang.String TAG_USERNAME

"[username]"

See Also:

Constant Field Values

INSTRUMENTS_APPLICATIONSUPPORT_DIR

public static java.lang.String INSTRUMENTS_APPLICATIONSUPPORT_DIR

"/Users/[username]/Library/Application Support/Instruments/"

INSTRUMENTS_PREVIOUSSCRIPTS_FILE

public static java.lang.String INSTRUMENTS_PREVIOUSSCRIPTS_FILE

"PreviousScripts" Name of file used by Instruments to store script preferences

INSTRUMENTS_BACKUPSCRIPTS_FILE

public static java.lang.String INSTRUMENTS_BACKUPSCRIPTS_FILE

"SAFSBackupScripts" Name of file used by SAFS to store original script preferences for restore.

ROOT_INSTRUMENTS_DIR

public static java.lang.String ROOT_INSTRUMENTS_DIR

"/Library/SAFS/IOS/instruments/"

SAFSRUNTIME_INSTRUMENTS_PREFS

public static java.lang.String SAFSRUNTIME_INSTRUMENTS_PREFS

"recent/SAFSRuntime"

PROCESSCONTAINER_INSTRUMENTS_PREFS

public static java.lang.String PROCESSCONTAINER_INSTRUMENTS_PREFS

"recent/ProcessContainer"

ROOT_IBT_IMAGES_DIR

public static java.lang.String ROOT_IBT_IMAGES_DIR

"/Library/SAFS/IOS/ibt/images/"

ROOT_INSTRUMENTS_PROJECT_DIR

public static java.lang.String ROOT_INSTRUMENTS_PROJECT_DIR

null until set. Set to the root directory where the Instruments project files are located.

ROOT_INSTRUMENTS_OUTPUT_DIR

public static java.lang.String ROOT_INSTRUMENTS_OUTPUT_DIR

null until set. Set to the active Instruments output directory: where the Instruments Automation Results and screenshots are actively being written.

DEFAULT_INSTRUMENTS_TEMPLATE

public static java.lang.String DEFAULT_INSTRUMENTS_TEMPLATE

null until set. Not really used yet. Set to the Trace Template that should be loaded into Instruments upon launch.

LAUNCH_INSTRUMENTS_ASCRIPT

public static java.lang.String LAUNCH_INSTRUMENTS_ASCRIPT

"Instruments/launchInstrumentsTemplate.scpt"
Normally appended to ROOT_ASCRIPTS_DIR
The default script requires 1 argument for the Instruments TraceTemplate to use.

START_INSTRUMENTS_ASCRIPT

public static java.lang.String START_INSTRUMENTS_ASCRIPT

"Instruments/startInstrumentsTrace.scpt"
Normally appended to ROOT_ASCRIPTS_DIR

LOOP_INSTRUMENTS_ASCRIPT

public static java.lang.String LOOP_INSTRUMENTS_ASCRIPT

"Instruments/restartInstrumentsScript.scpt"
Normally appended to ROOT_ASCRIPTS_DIR

LOOP_INSTRUMENTS5_ASCRIPT

public static java.lang.String LOOP_INSTRUMENTS5_ASCRIPT

"Instruments/restartInstruments5Script.scpt"
Normally appended to ROOT_ASCRIPTS_DIR

LOOP_INSTRUMENTS5LION_ASCRIPT

public static java.lang.String LOOP_INSTRUMENTS5LION_ASCRIPT

"Instruments/restartInstruments5LionScript.scpt"
Normally appended to ROOT_ASCRIPTS_DIR

CAPTURE_INSTRUMENTS_HOTSPOT_ASCRIPT

public static java.lang.String CAPTURE_INSTRUMENTS_HOTSPOT_ASCRIPT

"Instruments/captureInstrumentsHotspot.scpt"
Normally appended to ROOT_ASCRIPTS_DIR

CAPTURE_INSTRUMENTS_HOTSPOT_EDITORMENU_MODE

public static java.lang.String CAPTURE_INSTRUMENTS_HOTSPOT_EDITORMENU_MODE

"editormenu"

CAPTURE_INSTRUMENTS_HOTSPOT_DIR

public static java.lang.String CAPTURE_INSTRUMENTS_HOTSPOT_DIR

default: ROOT_ASCRIPTS_DIR

CAPTURE_INSTRUMENTS_HOTSPOT_EDITORMENU_FILE

public static java.lang.String CAPTURE_INSTRUMENTS_HOTSPOT_EDITORMENU_FILE

"editormenuhotspot.txt"

STOP_INSTRUMENTS_ASCRIPT

public static java.lang.String STOP_INSTRUMENTS_ASCRIPT

"Instruments/stopInstrumentsTrace.scpt"
Normally appended to ROOT_ASCRIPTS_DIR

STARTSCRIPT_IMAGE

public static java.lang.String STARTSCRIPT_IMAGE

"startscript/StartScript.bmp"
Normally appended to ROOT_IBT_IMAGES_DIR

MESSAGE_TAG_LC

public static final java.lang.String MESSAGE_TAG_LC

">message<" UIAutomation lower-case log key tag identifying a Message String follows.

See Also:

Constant Field Values

OPEN_STRING_LC

public static final java.lang.String OPEN_STRING_LC

"<string>" UIAutomation lower-case open tag for enclosed log message.

See Also:

Constant Field Values

CLOSE_STRING_LC

public static final java.lang.String CLOSE_STRING_LC

"</string>" UIAutomation lower-case close tag for enclosed log message.

See Also:

Constant Field Values

EXCEPTION_TAG_LC

public static final java.lang.String EXCEPTION_TAG_LC

See Also:

Constant Field Values

UNCAUGHT_ERROR_TAG_LC

public static final java.lang.String UNCAUGHT_ERROR_TAG_LC

See Also:

Constant Field Values

USER_STOPPED_SCRIPT_TAG_LC

public static final java.lang.String USER_STOPPED_SCRIPT_TAG_LC

See Also:

Constant Field Values

DEBUG_TAG_LC

public static final java.lang.String DEBUG_TAG_LC

":debug:" SAFS debug message prefix (lower-case) tagging a message to be delivered to the SAFS Debug Log.

See Also:

Constant Field Values

COMMENT_TAG_LC

public static final java.lang.String COMMENT_TAG_LC

":comment:" SAFS comment message prefix (lower-case) tagging a message to be used for SAFS execution status.

See Also:

Constant Field Values

DETAIL_TAG_LC

public static final java.lang.String DETAIL_TAG_LC

":detail:" SAFS comment details message prefix (lower-case) tagging a message to be used for SAFS execution status.

See Also:

Constant Field Values

STATUS_TAG_LC

public static final java.lang.String STATUS_TAG_LC

":status:" SAFS status message prefix (lower-case) tagging a message to be used for SAFS statusCode. Sample message: ":STATUS:-1"
When seen in Results log: "<string>:STATUS:-1</string>"

See Also:

Constant Field Values

SPCOUT_TAG_LC

public static final java.lang.String SPCOUT_TAG_LC

":spcout:" IOS Process Container output message prefix (lower-case) tagging a message to be used for IOS Process Container output.

See Also:

Constant Field Values

SPCMAP_TAG_LC

public static final java.lang.String SPCMAP_TAG_LC

":spcmap:" IOS Process Container app map output message prefix (lower-case) tagging a message to be used for IOS Process Container App Map output.

See Also:

Constant Field Values

COMPLETE_TAG_LC

public static final java.lang.String COMPLETE_TAG_LC

">script completed.<" UIAutomation lower-case message substring indicating a script has completed execution.

See Also:

Constant Field Values

TIME_TAG_LC

public static final java.lang.String TIME_TAG_LC

">timestamp<" UIAutomation lower-case message substring indicating a date/time timestamp is next to be logged.

See Also:

Constant Field Values

OPEN_DATE_LC

public static final java.lang.String OPEN_DATE_LC

"<date>" UIAutomation lower-case open tag for enclosed timestamp data.

See Also:

Constant Field Values

CLOSE_DATE_LC

public static final java.lang.String CLOSE_DATE_LC

"</date>" UIAutomation lower-case close tag for enclosed timestamp data.

See Also:

Constant Field Values

TYPE_TAG_LC

public static final java.lang.String TYPE_TAG_LC

">type<" UIAutomation lower-case message substring indicating the type or level of the log message.

See Also:

Constant Field Values

OPEN_INTEGER_LC

public static final java.lang.String OPEN_INTEGER_LC

"<integer>" UIAutomation lower-case open tag for enclosed integer data.

See Also:

Constant Field Values

CLOSE_INTEGER_LC

public static final java.lang.String CLOSE_INTEGER_LC

"</integer>" UIAutomation lower-case close tag for enclosed integer data.

See Also:

Constant Field Values

OPEN_ARRAY_LC

public static final java.lang.String OPEN_ARRAY_LC

"<array>" UIAutomation lower-case open tag for an array, usually of log messages.

See Also:

Constant Field Values

CLOSE_ARRAY_LC

public static final java.lang.String CLOSE_ARRAY_LC

"</array>" UIAutomation lower-case close tag for an array, usually of log messages.

See Also:

Constant Field Values

OPEN_DICT_LC

public static final java.lang.String OPEN_DICT_LC

"<dict>" UIAutomation lower-case close tag for the wrapper of log message data.

See Also:

Constant Field Values

CLOSE_DICT_LC

public static final java.lang.String CLOSE_DICT_LC

"</dict>" UIAutomation lower-case close tag for the wrapper of log message data.

See Also:

Constant Field Values

INSTRUMENTS_LAUNCH_TIMEOUT

public static int INSTRUMENTS_LAUNCH_TIMEOUT

20. Default timeout in seconds to wait for Instruments log commencement.

spcOutputWriter

public static java.io.BufferedWriter spcOutputWriter

Used internally for writing process container object information to output file. An external ProcessContainer-type class should set this to a valid open BufferedWriter to capture the Instruments output into the external file. (Re)Set it to null when it is not in use.

spcOutputXML

public static boolean spcOutputXML

true if object information to output file should be in XML format.

STATE_INIT

public static final int STATE_INIT

See Also:

Constant Field Values

STATE_SYSTEM

public static final int STATE_SYSTEM

See Also:

Constant Field Values

STATE_APP

public static final int STATE_APP

See Also:

Constant Field Values

STATE_WIN

public static final int STATE_WIN

See Also:

Constant Field Values

STATE_CHILD

public static final int STATE_CHILD

See Also:

Constant Field Values

STATE_CHILD_COMPLETE

public static final int STATE_CHILD_COMPLETE

See Also:

Constant Field Values

STATE_WIN_PROP

public static final int STATE_WIN_PROP

See Also:

Constant Field Values

STATE_CHILD_PROP

public static final int STATE_CHILD_PROP

See Also:

Constant Field Values

xmlstate

public static int xmlstate

-1: init state;
0: system out state;
1: app out state;
2: win out state;
3: child out state;

newobjectdepth

public static int newobjectdepth

currentobjectdepth

public static int currentobjectdepth

OS_VERSION

public static java.lang.String OS_VERSION

Retrieved from System.getProperty("os.version");

IS_OSX

public static boolean IS_OSX

IS_LION

public static boolean IS_LION

IS_SNOWLEOPARD

public static boolean IS_SNOWLEOPARD

MAJOR_VERSION

public static int MAJOR_VERSION

MINOR_VERSION

public static int MINOR_VERSION

MINOR_RELEASE_VERSION

public static int MINOR_RELEASE_VERSION

spcAppMapWriter

public static java.io.BufferedWriter spcAppMapWriter

Used internally for appending process container App Map information to output file. An external ProcessContainer-type class should set this to a valid open BufferedWriter to capture the Instruments output into the external file. (Re)Set it to null when it is not in use.

indent

static java.lang.String indent

Constructor Detail

Utilities

public Utilities()

Method Detail

debug

static void debug(java.lang.String message)

Writes to SAFS Debug "Log" at this time. Initial POC debug logger wrote to System.out.

Parameters:

message -

resetIStatus

static void resetIStatus()

Reset the collection of fields used for a single call to execute an Instruments script.

rc reset to SCRIPT_NOT_EXECUTED.
comment reset to null.
detail reset to null.

getIStatus

static IStatus getIStatus()

Return the current/last IStatus object generated from execution of an Instruments Script.

Note: this status information is only valid and updated after a call to the waitScriptComplete methods.

Returns:

IStatus

See Also:

#waitScriptComplete(String),, waitScriptComplete()

copyFile

public static void copyFile(java.io.File source,
                            java.io.File target)

Copy the bytes of one file overwriting or creating a new file. Since bytes are copied, no character coding issues are expected. We do no error detection or checking here other than catching Exceptions and logging the information to debug().

Parameters:

source - File should already be known to exist

target - File should already be known to be writable.

writeDataToFile

public static void writeDataToFile(java.lang.String data,
                                   java.lang.String targetdir,
                                   java.lang.String filename,
                                   boolean append)
                            throws InstrumentsTestRecordDataException

Write data to filename in optional targetdir. Normally a JavaScript file needed by a keyword implementation. This would normally only be done between script executions. That is AFTER a Script Complete has been detected from the previous script execution. Or, before the Record Trace has been initiated. The primary execution script is static and imports JSCRIPTS_HOOK. It is that hook that imports the JSCRIPTS_TRD.

Parameters:

data - should not be null or zero-length. The String whose contents will be written to the file. If it is JavaScript, it should be valid including any or all line terminations.

targetdir - null or the root directory holding the primary execution script(s). If null, the routine will use ROOT_JSCRIPTS_DIR. If provided, the value should end with a valid file separator for the platform--normally "\" or "/".

filename - - the name of the file to create or append to. If the file already exists, it will be deleted before we attempt to write unless append (below) is true. We do not automatically add any suffix to the filename.

append - - if true, appends to the end of file instead of deleting and overwriting the file.

Throws:

InstrumentsTestRecordDataException - if we cannot write this file for any reason.

presetInstrumentsScript

public static void presetInstrumentsScript(java.lang.String sourcedir,
                                           java.lang.String sourcepreference,
                                           java.lang.String supportdir,
                                           java.lang.String supportpreference)

Set the Instruments tools preferred script. This must be done BEFORE the tool is launched. The routine will store a copy of the current script preference file then overwrite the original with the new preference file. The script preference file is assumed to be located at:
/Users/[username]/Library/Application Support/Instruments/PreviousScripts

Parameters:

sourcedir - null or path to root directory for stored preferences files. If null, the routine will use ROOT_INSTRUMENTS_DIR.

sourcepreference - null or alternate preference file to use for Instruments scripts. If null, the routine will use the default #WRAPPER_INSTRUMENTS_SCRIPT.

supportdir - null or alternate directory where Instruments stores its preference file. If null, the routine will use the default INSTRUMENTS_APPLICATIONSUPPORT_DIR.

supportpreference - null or alternate named preference file to overwrite. If null, the routine will overwrite the default INSTRUMENTS_PREVIOUSSCRIPTS_FILE.

presetWrapperInstrumentsScript

public static void presetWrapperInstrumentsScript()

calls presetInstrumentsScript using all default parameters. This sets Instruments to choose the default runtime wrapper script when launched.

presetProcessContainerInstrumentsScript

public static void presetProcessContainerInstrumentsScript()

calls presetInstrumentsScript for ProcessContainer using all other defaults. This sets Instruments to choose the ProcessContainer wrapper script when launched.

restoreInstrumentsScript

public static void restoreInstrumentsScript(java.lang.String supportdir,
                                            java.lang.String supportpreference,
                                            java.lang.String supportbackup)

Restore the Instruments tools preferred script from its backup. This must be done BEFORE the tool is launched. The routine will restore the original script preference file from any backup preference file. The script preference file is assumed to be located at:
/Users/[username]/Library/Application Support/Instruments/PreviousScripts The backup script preference file is assumed to be located at:
/Users/[username]/Library/Application Support/Instruments/SAFSBackupScripts

Parameters:

supportdir - null or alternate directory where Instruments stores its preference file. If null, the routine will use the default INSTRUMENTS_APPLICATIONSUPPORT_DIR.

supportpreference - null or alternate named preference file to overwrite. If null, the routine will restore the default INSTRUMENTS_PREVIOUSSCRIPTS_FILE.

supportbackup - null or alternate named backup file to restore. If null, the routine will restore from the default INSTRUMENTS_BACKUPSCRIPTS_FILE.

restoreInstrumentsScript

public static void restoreInstrumentsScript()

call restoreInstrumentsScript with nulls to use defaults.

killAllInstruments

public static void killAllInstruments()

Attempt to kill all "Instruments" processes using "killall". Should normally only be called if Instruments did not launch and execute properly, or does not seem to be shutting down as expected.

killAllSimulators

public static void killAllSimulators()

Attempt to kill all IOS "Simulator" processes using "killall". Should normally only be called if Simulator did not launch and execute properly, or does not seem to be shutting down as expected.

launchInstrumentsTest

public static ProcessCapture launchInstrumentsTest(java.lang.String sourcedir,
                                                   java.lang.String script,
                                                   java.lang.String template)
                                            throws java.lang.IllegalThreadStateException

Launch the Instruments SDK tool with the specified template. This is a convenience routine that really only calls the runAppleScript method with a secstimeout of 10. This does NOT start the Record Trace. Call startInstrumentsTest(String, String) to start the Record Trace--the actual execution of the test.

Parameters:

sourcedir - null or the root directory containing the script. If null, the routine will use ROOT_ASCRIPTS_DIR.

script - null or the script path to an alternate Instruments launch script to use in sourcedir. A null value will use the LAUNCH_INSTRUMENTS_ASCRIPT in sourcedir.

template - The default script expects this to be the full path to the Instruments trace template.

An alternate script can also use this argument, or the caller should set this value to null if none should be used in the alternate script.

Returns:

ProcessCapture provided by runAppleScript.

Throws:

java.lang.IllegalThreadStateException

See Also:

runAppleScript(String, String, String, boolean, long)

runAppleScript

public static ProcessCapture runAppleScript(java.lang.String sourcedir,
                                            java.lang.String script,
                                            java.lang.String arguments,
                                            boolean wait,
                                            long secstimeout)
                                     throws java.lang.IllegalThreadStateException

Run an AppleScript via osascript.

Parameters:

sourcedir - null or the root directory containing the script. If null, the routine will use ROOT_ASCRIPTS_DIR.

script - to use in sourcedir. A null value will use the LAUNCH_INSTRUMENTS_ASCRIPT in sourcedir.

optional - arguments needed by the script, or null.

wait - true if we should wait for the launched process to finish

secstimeout - maximum time in seconds to wait before throwing a timeout exception. If wait for secstimeout < 0 is specified, the routine will wait indefinitely (dangerous?).

Returns:

if successful, a ProcessCapture object will return allowing the caller to process the out and err streams of the AppleScript process.

Throws:

java.lang.IllegalThreadStateException - if a wait with timeout >= 0 was specified and exceeded.

launchInstrumentsTest

public static ProcessCapture launchInstrumentsTest(java.lang.String template)
                                            throws java.lang.IllegalThreadStateException

Launch the Instruments SDK tool with the specified template using other default parameters. This does NOT start the Record Trace. Call startInstrumentsTest(String, String) to start the Record Trace--the actual execution of the test.

Parameters:

template - The default script expects this to be the full path to the Instruments trace template.

An alternate script can also use this argument, or the caller should set this value to null if none should be used in the alternate script.

Returns:

ProcessCapture returned by runAppleScript

Throws:

java.lang.IllegalThreadStateException

See Also:

runAppleScript(String, String, String, boolean, long)

startInstrumentsTest

public static ProcessCapture startInstrumentsTest(java.lang.String sourcedir,
                                                  java.lang.String script)
                                           throws java.lang.IllegalThreadStateException

Start the Instruments SDK tool Record Trace. Assumes the Instruments tool is already up and running with the appropriate template. launchInstrumentsTest(String, String, String).

Parameters:

sourcedir - null or the root directory containing the script. If null, the routine will use ROOT_ASCRIPTS_DIR.

script - null or the script path to an alternate Instruments start script to use in sourcedir. A null value will use the START_INSTRUMENTS_ASCRIPT in sourcedir.

Returns:

ProcessCapture from runAppleScript

Throws:

java.lang.IllegalThreadStateException

See Also:

runAppleScript(String, String, String, boolean, long)

startInstrumentsTest

public static ProcessCapture startInstrumentsTest()
                                           throws java.lang.IllegalThreadStateException

calls startInstrumentsTest with null to use defaults.

Returns:

ProcessCapture from runAppleScript

Throws:

java.lang.IllegalThreadStateException

See Also:

runAppleScript(String, String, String, boolean, long)

prepareNextInstrumentsTest

public static void prepareNextInstrumentsTest(java.lang.String sourcedir,
                                              java.lang.String script,
                                              java.lang.String targetdir)

Copy/Rename a JavaScript snippet to JSCRIPTS_HOOK and store for the next script execution. The routine also presets empty imports trd.js and coords.js for default execution. For this reason, prepareNextTestRecordData must be called AFTER this method. This should only be done between script executions. That is AFTER a Script Complete has been detected from the previous script execution. Or, before the Record Trace has been initiated. The primary execution script is static and imports the hook. It is the hook that we dynamically alter/copy to change what the Instruments automation will do next. #nextInstrumentsTest(String, String, String, String).

Parameters:

sourcedir - null or the root directory containing the script. If null, the routine will use ROOT_JSCRIPTS_DIR. If JSCRIPTS_ABSOLUTE_PATH is specified then the routine will assume the script parameter is NOT relative and contains the full absolute path to the desired script.

script - cannot be null. The script name is expected to end with extension ".js". If it does not, the routine will add the ".js" extension for convenience.

targetdir - null or the root directory holding the primary execution script(s). If null, the routine will use ROOT_JSCRIPTS_DIR.

See Also:

prepareNextTestRecordData(TestRecordData, String)

prepareNextInstrumentsTest

public static void prepareNextInstrumentsTest(java.lang.String script)

calls prepareNexInstrumentsTest with null for sourcedir and targetdir for default operation.

See Also:

prepareNextInstrumentsTest(String, String, String)

prepareNextTestRecordData

public static void prepareNextTestRecordData(TestRecordData trd,
                                             java.lang.String targetdir)
                                      throws InstrumentsTestRecordDataException

Copy TestRecordHelper data to JSCRIPTS_TRD and store for the next script execution. This should only be done between script executions. That is AFTER a Script Complete has been detected from the previous script execution. Or, before the Record Trace has been initiated. The primary execution script is static and imports JSCRIPTS_HOOK. It is that hook that may or may not import the JSCRIPTS_TRD.

Parameters:

trd - cannot be null. The TestRecordData whose contents will be written to JSCRIPTS_TRD.

targetdir - null or the root directory holding the primary execution script(s). If null, the routine will use ROOT_JSCRIPTS_DIR.

Throws:

InstrumentsTestRecordDataException

prepareNextTestRecordData

public static void prepareNextTestRecordData(TestRecordData trd)
                                      throws InstrumentsTestRecordDataException

Copy TestRecordHelper data to JSCRIPTS_TRD and store for the next script execution. This should only be done between script executions. That is AFTER a Script Complete has been detected from the previous script execution. Or, before the Record Trace has been initiated. The primary execution script is static and imports JSCRIPTS_HOOK. It is that hook that may or may not import the JSCRIPTS_TRD.

Parameters:

trd - cannot be null. The TestRecordData whose contents will be written to JSCRIPTS_TRD.

targetdir - null or the root directory holding the primary execution script(s). If null, the routine will use ROOT_JSCRIPTS_DIR.

Throws:

InstrumentsTestRecordDataException

nextInstrumentsTest

public static ProcessCapture nextInstrumentsTest(java.lang.String ascriptdir,
                                                 java.lang.String script)
                                          throws InstrumentsStartScriptException,
                                                 java.lang.IllegalThreadStateException

Activates the Instruments application and attempts to find and click the "Start Script" button.

Activates Instruments with AppleScript, then uses AppleScript to click the "Start Script" button. On IOS 4 SDK this is on the main Instruments screen. On IOS 5 this is on the Script Editor pane.

OS X Lion has an additional defect of not properly locating the IOS 5 PopupMenu triggers "Trace Log", "Editor Log", and "Script". For this scenario we will use AppleScript to derive the Point location on the screen for these items and then use java.awt.Robot to activate the necessary menu.

Parameters:

sourcedir - null or the root directory containing the script. If null, the routine will use ROOT_ASCRIPTS_DIR.

script - null or the script path to an alternate Instruments loop script to use in sourcedir. A null value will use the LOOP_INSTRUMENTS_ASCRIPT in sourcedir.

Returns:

ProcessCapture from runAppleScript

Throws:

InstrumentsStartScriptException - if there is any problem with the SAFS IBT portion of clicking Instruments "Start Script".

java.lang.IllegalThreadStateException

See Also:

runAppleScript(String, String, String, boolean, long)

nextInstrumentsTest

public static ProcessCapture nextInstrumentsTest()
                                          throws java.lang.IllegalThreadStateException,
                                                 InstrumentsStartScriptException

Activates the Instruments application and attempts to find and click the "Start Script" button using default settings.

Throws:

InstrumentsStartScriptException - if there is any problem with the SAFS IBT portion of clicking Instruments "Start Script".

java.lang.IllegalThreadStateException

stopInstrumentsTest

public static ProcessCapture stopInstrumentsTest(java.lang.String sourcedir,
                                                 java.lang.String script)
                                          throws java.lang.IllegalThreadStateException

Stop the Instruments SDK tool Record Trace. The routine assumes the Instruments tool is already running and a Record Trace was already initiated.

Parameters:

sourcedir - null or the root directory containing the script. If null, the routine will use ROOT_ASCRIPTS_DIR.

script - null or the script path to an alternate Instruments stop script to use in sourcedir. A null value will use the STOP_INSTRUMENTS_ASCRIPT in sourcedir.

Throws:

java.lang.IllegalThreadStateException

stopInstrumentsTest

public static ProcessCapture stopInstrumentsTest()
                                          throws java.lang.IllegalThreadStateException

calls stopInstrumentsTest with nulls to use defaults.

Throws:

java.lang.IllegalThreadStateException

deletePreviousRuns

public static void deletePreviousRuns(java.lang.String rootRunDir)

Delete all previous Instruments test output results files and directories. Essentially, delete all the "Automation Results" and "Run" directories from previous runs.

Parameters:

rootRunDir - the full path to the Instruments project space where the Run subdirectories are located. If null, the routine will use ROOT_INSTRUMENTS_PROJECT_DIR. However, that default is null unless set by other means.

deletePreviousRuns

public static void deletePreviousRuns()

calls deletePreviousRun with null for default operation.

prepareNewAutomationTest

public static void prepareNewAutomationTest(java.lang.String projectpath)

Convenience routine to optionally change the Instruments Project, delete all logs from previous runs, reset the Instruments log line counter, and preset the correct Instruments "recent" scripts for a test automation run.

Parameters:

projectpath - if not null, overwrites ROOT_INSTRUMENTS_PROJECT_DIR with a new path to an Instruments Project.

See Also:

#ROOT_INSTRUMENTS_PROJECT_DIR,, #deletePreviousRuns(),, #resetInstrumentsLogCounter(),, presetWrapperInstrumentsScript()

prepareNewAutomationTest

public static void prepareNewAutomationTest()

Convenience routine to delete all logs from previous runs, reset the Instruments log line counter, and preset the correct Instruments "recent" scripts for a test automation run.

See Also:

#deletePreviousRuns(),, #resetInstrumentsLogCounter(),, presetWrapperInstrumentsScript()

resetInstrumentsLogCounter

public static void resetInstrumentsLogCounter()

reset our Instruments log parser to monitor the beginning of the log.

verifyInstrumentsRecording

public static java.io.File verifyInstrumentsRecording(java.lang.String rootRunDir)
                                               throws InstrumentsStartScriptException

Locate and return a File reference to the most recent Results file from an active Instruments Script. This assumes older files were previously deleted.

Parameters:

rootRunDir - Full path to Instruments Project space where "Run" output directories are written. If null, the routine will use ROOT_INSTRUMENTS_PROJECT_DIR. However, that default is null unless set by other means.

Returns:

File to the running results file, or an InstrumentsStartScriptException

Throws:

InstrumentsStartScriptException - if we could not locate a Run directory or active output file.

openXMLState

protected static void openXMLState(int state)
                            throws java.io.IOException

calls closeXMLState prior to its own output. output whatever is required to start the current xml node for the provided xml state.

Throws:

java.io.IOException

closeXMLState

protected static void closeXMLState(int toState)
                             throws java.io.IOException

output whatever is required to close the current xml for the current xml state.

Throws:

java.io.IOException

addXMLAttribute

protected static void addXMLAttribute(java.lang.String msgtext)
                               throws java.io.IOException

Assumes a node has already been started. Parses lines as: "ignore attributename: value".
Ex: "Window Class:UIAWindow",
Ex: "Application Name:UICatalog"

Parameters:

msgtext -

Throws:

java.io.IOException

addXMLProperty

protected static void addXMLProperty(java.lang.String msgtext)
                              throws java.io.IOException

Assumes a property node has already been started. Parses lines as: "property: 'name' == 'value'.

Parameters:

msgtext -

Throws:

java.io.IOException

makePCIndent

protected static java.lang.String makePCIndent()

findRunningLastLine

public static void findRunningLastLine(java.lang.String rootRunDir)
                                throws InstrumentsLaunchFailureException

Process the assumed to be running Instruments Log file to identify the last valid Script Completed message. This ensures the system is ready to start acting on the NEXT output messages.

Parameters:

rootRunDir -

Throws:

InstrumentsLaunchFailureException

waitScriptComplete

public static void waitScriptComplete(java.lang.String rootRunDir)
                               throws InstrumentsLaunchFailureException

Repetitively monitor the active "Automation Results" file for "Script Complete" during Instruments script execution. The call generally follows the call to startInstrumentsTest or nextInstrumentsTest. The call is also automatically invoked inside the convenience routine executeNextInstrumentsTest. Due to the nature of the output file, the routine must repetitively open new instances of the output file as the system provides temporary snapshots.

The routine can handle multiple script executions within a single "Record Trace" session by keeping track of which "script complete" is the newest.

While monitoring the log this routine intercepts Instruments log messages properly tagged for SAFS Debug logging. It also captures SAFS status, log comments, and log details when properly tagged for SAFS.

Message prefixes:

• ":DEBUG:" for a SAFS Debug log message
• ":STATUS:" for SAFS integer return code to be used by SAFS Engine
• ":COMMENT:" for SAFS String comment/warning/error to log
• ":DETAIL:" for SAFS String detail to log with the comment
• ":SPCOUT:" for Process Container Object info output
• ":SPCMAP:" for Process Container App Map info output

Parameters:

rootRunDir - Full path to Instruments Project space where "Run" output directories are written. If null, the routine will use ROOT_INSTRUMENTS_PROJECT_DIR. However, that default is null unless set by other means.

Throws:

InstrumentsLaunchFailureException

waitScriptComplete

public static void waitScriptComplete()
                               throws InstrumentsLaunchFailureException

calls waitScriptComplete with null to use preset ROOT_INSTRUMENTS_PROJECT_DIR.

Throws:

InstrumentsLaunchFailureException

See Also:

waitScriptComplete(String)

executeNextInstrumentsTest

public static void executeNextInstrumentsTest(java.lang.String script)
                                       throws InstrumentsLaunchFailureException

calls the following routines using all defaults except the varying script to run: prepareNextInstruments(script); nextInstrumentsTest(); waitScriptComplete(); The routine expects that Instruments is already running and Record Trace has already been started.

Parameters:

script - the script to run using all other defaults.

Throws:

java.lang.Exception

InstrumentsLaunchFailureException

main

public static void main(java.lang.String[] args)

Original POC execution. May not be up-to-date or maintained.

Parameters:

args - None

prepareNextProcessContainerData

public static void prepareNextProcessContainerData(java.lang.String targetdir,
                                                   boolean doChildren,
                                                   boolean doProperties,
                                                   boolean appendMap,
                                                   boolean addInfo,
                                                   boolean doShortStrings,
                                                   java.lang.String windowName,
                                                   java.lang.String windowRec,
                                                   java.lang.String objectRec)
                                            throws InstrumentsTestRecordDataException

Outputs

Parameters:

targetdir -

doChildren -

doProperties -

appendMap -

addInfo -

doShortStrings -

windowRec -

objectRec -

Throws:

InstrumentsTestRecordDataException