Instrumentation框架分析及其使用

static public IActivityManager getDefault() {
    return gDefault.get();
}

private static final Singleton<IActivityManager> gDefault = new Singleton<IActivityManager>() {
    protected IActivityManager create() {
        IBinder b = ServiceManager.getService("activity");
        if (false) {
            Log.v("ActivityManager", "default service binder = " + b);
        }
        IActivityManager am = asInterface(b);
        if (false) {
            Log.v("ActivityManager", "default service = " + am);
        }
        return am;
    }
};

static public IActivityManager asInterface(IBinder obj) {
    if (obj == null) {
        return null;
    }
    IActivityManager in =
        (IActivityManager)obj.queryLocalInterface(descriptor);
    if (in != null) {
        return in;
    }
}

public boolean startInstrumentation(ComponentName className, String profileFile,
        int flags, Bundle arguments, IInstrumentationWatcher watcher,
        IUiAutomationConnection connection, int userId, String instructionSet)
        throws RemoteException {
    Parcel data = Parcel.obtain();
    Parcel reply = Parcel.obtain();
    data.writeInterfaceToken(IActivityManager.descriptor);
    ComponentName.writeToParcel(className, data);
    data.writeString(profileFile);
    data.writeInt(flags);
    data.writeBundle(arguments);
    data.writeStrongBinder(watcher != null ? watcher.asBinder() : null);
    data.writeStrongBinder(connection != null ? connection.asBinder() : null);
    data.writeInt(userId);
    data.writeString(instructionSet);
    mRemote.transact(START_INSTRUMENTATION_TRANSACTION, data, reply, 0);
    reply.readException();
    boolean res = reply.readInt() != 0;
    reply.recycle();
    data.recycle();
    return res;
}

public static IBinder getService(String name) {
    try {
        IBinder service = sCache.get(name);
        if (service != null) {
            return service;
        } else {
            return getIServiceManager().getService(name);
        }
    } catch (RemoteException e) {
        Log.e(TAG, "error in getService", e);
    }
    return null;
}

public final boolean transact(int code, Parcel data, Parcel reply,
        int flags) throws RemoteException {
    if (false) Log.v("Binder", "Transact: " + code + " to " + this);
    if (data != null) {
        data.setDataPosition(0);
    }
    boolean r = onTransact(code, data, reply, flags);
    if (reply != null) {
        reply.setDataPosition(0);
    }
    return r;
}

public boolean onTransact(int code, Parcel data, Parcel reply, int flags)
        throws RemoteException {
    if (code == SYSPROPS_TRANSACTION) {
        // We need to tell all apps about the system property change.
        ArrayList<IBinder> procs = new ArrayList<IBinder>();
        synchronized(this) {
            final int NP = mProcessNames.getMap().size();
            for (int ip=0; ip<NP; ip++) {
                SparseArray<ProcessRecord> apps = mProcessNames.getMap().valueAt(ip);
                final int NA = apps.size();
                for (int ia=0; ia<NA; ia++) {
                    ProcessRecord app = apps.valueAt(ia);
                    if (app.thread != null) {
                        procs.add(app.thread.asBinder());
                    }
                }
            }
        }
}

case START_INSTRUMENTATION_TRANSACTION: {
    data.enforceInterface(IActivityManager.descriptor);
    ComponentName className = ComponentName.readFromParcel(data);
    String profileFile = data.readString();
    int fl = data.readInt();
    Bundle arguments = data.readBundle();
    IBinder b = data.readStrongBinder();
    IInstrumentationWatcher w = IInstrumentationWatcher.Stub.asInterface(b);
    b = data.readStrongBinder();
    IUiAutomationConnection c = IUiAutomationConnection.Stub.asInterface(b);
    int userId = data.readInt();
    String abiOverride = data.readString();
    boolean res = startInstrumentation(className, profileFile, fl, arguments, w, c, userId,
            abiOverride);
    reply.writeNoException();
    reply.writeInt(res ? 1 : 0);
    return true;
}

public static void main(String[] args) {
    SamplingProfilerIntegration.start();

    // CloseGuard defaults to true and can be quite spammy.  We
    // disable it here, but selectively enable it later (via
    // StrictMode) on debug builds, but using DropBox, not logs.
    CloseGuard.setEnabled(false);

    Environment.initForCurrentUser();

    // Set the reporter for event logging in libcore
    EventLogger.setReporter(new EventLoggingReporter());

    Security.addProvider(new AndroidKeyStoreProvider());

    // Make sure TrustedCertificateStore looks in the right place for CA certificates
    final File configDir = Environment.getUserConfigDirectory(UserHandle.myUserId());
    TrustedCertificateStore.setDefaultUserDirectory(configDir);

    Process.setArgV0("<pre-initialized>");

    Looper.prepareMainLooper();

    ActivityThread thread = new ActivityThread();
    thread.attach(false);

    if (sMainThreadHandler == null) {
        sMainThreadHandler = thread.getHandler();
    }

    if (false) {
        Looper.myLooper().setMessageLogging(new
                LogPrinter(Log.DEBUG, "ActivityThread"));
    }

    Looper.loop();

    throw new RuntimeException("Main thread loop unexpectedly exited");
}

final IActivityManager mgr = ActivityManagerNative.getDefault();

mgr.attachApplication(mAppThread);

public final void attachApplication(IApplicationThread thread) {
    synchronized (this) {
        int callingPid = Binder.getCallingPid();
        final long origId = Binder.clearCallingIdentity();
        attachApplicationLocked(thread, callingPid);
        Binder.restoreCallingIdentity(origId);
    }
}

thread.bindApplication(processName, appInfo, providers, app.instrumentationClass,
        profilerInfo, app.instrumentationArguments, app.instrumentationWatcher,
        app.instrumentationUiAutomationConnection, testMode, enableOpenGlTrace,
        isRestrictedBackupMode || !normalMode, app.persistent,
        new Configuration(mConfiguration), app.compat,
        getCommonServicesLocked(app.isolated),
        mCoreSettingsObserver.getCoreSettingsLocked());

AppBindData data = new AppBindData();
data.processName = processName;
data.appInfo = appInfo;
data.providers = providers;
data.instrumentationName = instrumentationName;
data.instrumentationArgs = instrumentationArgs;
data.instrumentationWatcher = instrumentationWatcher;
data.instrumentationUiAutomationConnection = instrumentationUiConnection;
data.debugMode = debugMode;
data.enableOpenGlTrace = enableOpenGlTrace;
data.restrictedBackupMode = isRestrictedBackupMode;
data.persistent = persistent;
data.config = config;
data.compatInfo = compatInfo;
data.initProfilerInfo = profilerInfo;
sendMessage(H.BIND_APPLICATION, data);

case BIND_APPLICATION:
    Trace.traceBegin(Trace.TRACE_TAG_ACTIVITY_MANAGER, "bindApplication");
    AppBindData data = (AppBindData)msg.obj;
    handleBindApplication(data);
    Trace.traceEnd(Trace.TRACE_TAG_ACTIVITY_MANAGER);
    break;

if (data.instrumentationName != null) {
    InstrumentationInfo ii = null;
    try {
        ii = appContext.getPackageManager().
            getInstrumentationInfo(data.instrumentationName, 0);
    } catch (PackageManager.NameNotFoundException e) {
    }
    if (ii == null) {
        throw new RuntimeException(
            "Unable to find instrumentation info for: "
            + data.instrumentationName);
    }

    mInstrumentationPackageName = ii.packageName;
    mInstrumentationAppDir = ii.sourceDir;
    mInstrumentationSplitAppDirs = ii.splitSourceDirs;
    mInstrumentationLibDir = ii.nativeLibraryDir;
    mInstrumentedAppDir = data.info.getAppDir();
    mInstrumentedSplitAppDirs = data.info.getSplitAppDirs();
    mInstrumentedLibDir = data.info.getLibDir();

    ApplicationInfo instrApp = new ApplicationInfo();
    instrApp.packageName = ii.packageName;
    instrApp.sourceDir = ii.sourceDir;
    instrApp.publicSourceDir = ii.publicSourceDir;
    instrApp.splitSourceDirs = ii.splitSourceDirs;
    instrApp.splitPublicSourceDirs = ii.splitPublicSourceDirs;
    instrApp.dataDir = ii.dataDir;
    instrApp.nativeLibraryDir = ii.nativeLibraryDir;
    LoadedApk pi = getPackageInfo(instrApp, data.compatInfo,
            appContext.getClassLoader(), false, true, false);
    ContextImpl instrContext = ContextImpl.createAppContext(this, pi);

    try {
        java.lang.ClassLoader cl = instrContext.getClassLoader();
        mInstrumentation = (Instrumentation)
            cl.loadClass(data.instrumentationName.getClassName()).newInstance();
    } catch (Exception e) {
        throw new RuntimeException(
            "Unable to instantiate instrumentation "
            + data.instrumentationName + ": " + e.toString(), e);
    }

    mInstrumentation.init(this, instrContext, appContext,
           new ComponentName(ii.packageName, ii.name), data.instrumentationWatcher,
           data.instrumentationUiAutomationConnection);

    if (mProfiler.profileFile != null && !ii.handleProfiling
            && mProfiler.profileFd == null) {
        mProfiler.handlingProfiling = true;
        File file = new File(mProfiler.profileFile);
        file.getParentFile().mkdirs();
        Debug.startMethodTracing(file.toString(), 8 * 1024 * 1024);
    }

} else {
    mInstrumentation = new Instrumentation();
}

if ((data.appInfo.flags&ApplicationInfo.FLAG_LARGE_HEAP) != 0) {
    dalvik.system.VMRuntime.getRuntime().clearGrowthLimit();
}

// Allow disk access during application and provider setup. This could
// block processing ordered broadcasts, but later processing would
// probably end up doing the same disk access.
final StrictMode.ThreadPolicy savedPolicy = StrictMode.allowThreadDiskWrites();
try {
    // If the app is being launched for full backup or restore, bring it up in
    // a restricted environment with the base application class.
    Application app = data.info.makeApplication(data.restrictedBackupMode, null);
    mInitialApplication = app;

    // don't bring up providers in restricted mode; they may depend on the
    // app's custom Application class
    if (!data.restrictedBackupMode) {
        List<ProviderInfo> providers = data.providers;
        if (providers != null) {
            installContentProviders(app, providers);
            // For process that contains content providers, we want to
            // ensure that the JIT is enabled "at some point".
            mH.sendEmptyMessageDelayed(H.ENABLE_JIT, 10*1000);
        }
    }

    // Do this after providers, since instrumentation tests generally start their
    // test thread at this point, and we don't want that racing.
    try {
        mInstrumentation.onCreate(data.instrumentationArgs);
    }
    catch (Exception e) {
        throw new RuntimeException(
            "Exception thrown in onCreate() of "
            + data.instrumentationName + ": " + e.toString(), e);
    }

    try {
        mInstrumentation.callApplicationOnCreate(app);
    } catch (Exception e) {
        if (!mInstrumentation.onException(app, e)) {
            throw new RuntimeException(
                "Unable to create application " + app.getClass().getName()
                + ": " + e.toString(), e);
        }
    }
} finally {
    StrictMode.setThreadPolicy(savedPolicy);
}

java.lang.ClassLoader cl = instrContext.getClassLoader();
mInstrumentation = (Instrumentation)
    cl.loadClass(data.instrumentationName.getClassName()).newInstance();

mInstrumentation.init(this, instrContext, appContext,
       new ComponentName(ii.packageName, ii.name), data.instrumentationWatcher,
       data.instrumentationUiAutomationConnection);

mInstrumentation.onCreate(data.instrumentationArgs);

mInstrumentation.callApplicationOnCreate(app);

public void start() {
    if (mRunner != null) {
        throw new RuntimeException("Instrumentation already started");
    }
    mRunner = new InstrumentationThread("Instr: " + getClass().getName());
    mRunner.start();
}

private final class InstrumentationThread extends Thread {
    public InstrumentationThread(String name) {
        super(name);
    }
    public void run() {
        try {
            Process.setThreadPriority(Process.THREAD_PRIORITY_URGENT_DISPLAY);
        } catch (RuntimeException e) {
            Log.w(TAG, "Exception setting priority of instrumentation thread "                                            
                    + Process.myTid(), e);                                                                             
        }
        if (mAutomaticPerformanceSnapshots) {
            startPerformanceSnapshot();
        }
        onStart();
    }
}

/**
 * Method where the instrumentation thread enters execution.  This allows
 * you to run your instrumentation code in a separate thread than the
 * application, so that it can perform blocking operation such as
 * {@link #sendKeySync} or {@link #startActivitySync}.
 * 
 * <p>You will typically want to call finish() when this function is done,
 * to end your instrumentation.
 */

/**
 * The test is starting.
 */
public static final int REPORT_VALUE_RESULT_START = 1;
/**
 * The test completed successfully.
 */
public static final int REPORT_VALUE_RESULT_OK = 0;
/**
 * The test completed with an error.
 */
public static final int REPORT_VALUE_RESULT_ERROR = -1;
/**
 * The test completed with a failure.
 */
public static final int REPORT_VALUE_RESULT_FAILURE = -2;

public void finish(int resultCode, Bundle results) {
    if (mAutomaticPerformanceSnapshots) {
        endPerformanceSnapshot();
    }
    if (mPerfMetrics != null) {
        if (results == null) {
            results = new Bundle();
        }
        results.putAll(mPerfMetrics);
    }
    if (mUiAutomation != null) {
        mUiAutomation.disconnect();
        mUiAutomation = null;
    }
    mThread.finishInstrumentation(resultCode, results);
}

int mResultCode;
Intent mResultData;

private final IntentFilter mWhich;    //IntentFilter，被监视的Acitivity的条件
private final String mClass;    //被监视的Acitivity类名
private final ActivityResult mResult;    //如果monitor符合条件，返回的ActivityResult
private final boolean mBlock;    //决定monitor是否会阻止activity的启动（使用mResult启动，true时阻止），或者继续activity的启动
int mHits = 0;    //记录被监视的Activity的启动次数
Activity mLastActivity = null;    //最后匹配成功的Activity

public ActivityMonitor(
    IntentFilter which, ActivityResult result, boolean block) {
    mWhich = which;
    mClass = null;
    mResult = result;
    mBlock = block;
}

public ActivityMonitor(
    String cls, ActivityResult result, boolean block) {
    mWhich = null;
    mClass = cls;
    mResult = result;
    mBlock = block;
}

final boolean match(Context who, Activity activity, Intent intent) {
    synchronized (this) {
        if (mWhich != null
            && mWhich.match(who.getContentResolver(), intent,
                            true, "Instrumentation") < 0) {
            return false;
        }
        if (mClass != null) {
            String cls = null;
            if (activity != null) {
                cls = activity.getClass().getName();
            } else if (intent.getComponent() != null) {
                cls = intent.getComponent().getClassName();
            }
            if (cls == null || !mClass.equals(cls)) {
                return false;
            }
        }
        if (activity != null) {
            mLastActivity = activity;
            notifyAll();
        }
        return true;
    }
}

/**
 * Block until an Activity is created that matches this monitor,
 * returning the resulting activity.
 *
 * @return Activity
 */
public final Activity waitForActivity() {
    synchronized (this) {
        while (mLastActivity == null) {
            try {
                wait();
            } catch (InterruptedException e) {
            }
        }
        Activity res = mLastActivity;
        mLastActivity = null;
        return res;
    }
}

/**
 * Block until an Activity is created that matches this monitor, 
 * returning the resulting activity or till the timeOut period expires.
 * If the timeOut expires before the activity is started, return null. 
 * 
 * @param timeOut Time to wait before the activity is created.
 * 
 * @return Activity
 */
public final Activity waitForActivityWithTimeout(long timeOut) {
    synchronized (this) {
        if (mLastActivity == null) {
            try {
                wait(timeOut);
            } catch (InterruptedException e) {
            }
        }
        if (mLastActivity == null) {
            return null;
        } else {
            Activity res = mLastActivity;
            mLastActivity = null;
            return res;
        }
    }
}

```

#### ActivityWaiter

一个数据结构，包含了一个Intent和一个Activity，主要作用是用于判断Intent是否能被Activity处理

#### ActivityGoing

实现了MessageQueue.IdleHandler接口，带有一个ActivityWaiter的成员，queueIdle方法的实现是将这个ActivityWaiter的从mWaitingActivities列表中移除

    private static final class SyncRunnable implements Runnable {
        private final Runnable mTarget;
        private boolean mComplete;

        public SyncRunnable(Runnable target) {
            mTarget = target;
        }

        public void run() {
            mTarget.run();
            synchronized (this) {
                mComplete = true;
                notifyAll();
            }
        }

        public void waitForComplete() {
            synchronized (this) {
                while (!mComplete) {
                    try {
                        wait();
                    } catch (InterruptedException e) {
                    }
                }
            }
        }
    }

#### Idler

实现了MessageQueue.IdleHandler接口，检测线程是否处于idle状态并做相应操作

### Instrumentation中一些公有方法的介绍

#### 性能相关

Profiling是一个Android系统自带的用于性能分析的系统，这里暂不介绍，仅记录功能入口，如果后期有性能同学对此做了深入研究会链接到相关页面

*   public boolean isProfiling()：判断是否开启了Profiling模式
*   public void startProfiling()：生成Profiling相关文件，并开始记录每个方法执行
*   public void stopProfiling()：停止Profiling模式\
    PerformanceSnapshots没有找到相关的文档信息，从其关键类PerformanceCollector的注释来看是记录一些性能数据用的
*   public void setAutomaticPerformanceSnapshots()：
*   public void startPerformanceSnapshot()：
*   public void endPerformanceSnapshot()：

#### 线程相关

以下三个方法贴了原文注释，主要是不知道如何合适的翻译，大体上前两个方法用于等待被测Activity处于idle状态（一个同步，一个异步），然后做相应操作，第三个方法是在被测Activity主线程做指定的操作

*   public void waitForIdle(Runnable recipient)：Schedule a callback for when the application's main thread goes idle(has no more events to process)
*   public void waitForIdleSync()：Synchronously wait for the application to be idle. Can not be called from the main application thread -- use start() to execute instrumentation in its own thread.
*   public void runOnMainSync(Runnable runner)：Execute a call on the application's main thread, blocking until it is complete. Useful for doing things that are not thread-safe, such as looking at or modifying the view hierarchy.

#### 启动Activity

*   public Activity startActivitySync(Intent intent)\
    这是是通过Instrumentation启动Activity的主要方法,我们先来看看源码及注释是怎样的,再来对着源码分析下Activity是如何启动的

从官方注释我们可以看到,startActivitySync方法的功能也是启动Activity,同Context.startActivity方法不同的是,startActivitySync是无法启动进程外的Activity的。另外，如果用于启动的Intent可以被多个Activity接受，该方法会直接抛出异常而不是弹出选择对话框让用户选择需要使用的程序。本方法作为一个同步方法，在Activity启动后处于idle状态时返回，意味着Activity会走完onCreate,onStart,onResume的方法，并完成UI初始化。

下面我们看看这个方法的具体实现

*   首先会获取到被测APK的ActivityInfo（可以通过其获取到相关的Activity）
*   然后判断是否是运行在同一进程（具体实现不是很明白，有兴趣的调研下补充上来？）
*   再将从Activity中提取的Component信息设置给Intent（决定谁来处理Intent）
*   之后使用该Intent初始化一个ActivityWaiter对象，并加入到mWaitingActivities列表中
*   获取目标的Context并通过intent启动Acticity
*   在之前生成的ActivityWaiter对象从mWaitingActivities中移除之前一直会处于阻塞状态\
    那么问题来了，这个ActivityWaiter对象是何时被移除的呢？Instrumentation提供了操作Activity生命周期的方法（下面也会提到），使用Instrumentation启动Activity时会调用callActivityOnCreate方法，处理Acticity的onCreate，而callActivityOnCreate分成了3个步骤

在prePerformCreate方法中

针对mWaitingActivities列表中已加入的每一个ActivityWaiter，判断intent是否符合目标Activity，如果符合则将目标Activity绑定到ActivityWaiter对象。然后发送消息，在空闲时调用这个以aw为参数的ActivityGoing对象，上文中我们介绍过ActivityGoing类，其功能是在目标Activity空闲后将指定的ActivityWaiter从mWaitingActivities列表中移除。

至此就实现了启动Activity并阻塞到Activity启动的全过程

下面的一系列方法是通过Instrumentation启动Activity的，具体使用场景暂未分析

*   public ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, Activity target, Intent intent, int requestCode, Bundle options)
*   public void execStartActivities(Context who, IBinder contextThread, IBinder token, Activity target, Intent\[] intents, Bundle options)
*   public void execStartActivitiesAsUser(Context who, IBinder contextThread, IBinder token, Activity target, Intent\[] intents, Bundle options, int userId)
*   public ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, Fragment target, Intent intent, int requestCode, Bundle options)
*   public ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, Activity target, Intent intent, int requestCode, Bundle options, UserHandle user)
*   public ActivityResult execStartActivityAsCaller(Context who, IBinder contextThread, IBinder token, Activity target, Intent intent, int requestCode, Bundle options, int userId)
*   public void execStartActivityFromAppTask(Context who, IBinder contextThread, IAppTask appTask,Intent intent, Bundle options)

#### ActivityMonitor相关

addMonitor共有三种重载，作用都是增加向当前Instrumentation添加一个ActivityMonitor，其中后两种会同时返回构造出的ActivityMonitor对象

*   public void addMonitor(ActivityMonitor monitor)
*   public ActivityMonitor addMonitor(IntentFilter filter, ActivityResult result, boolean block)
*   public ActivityMonitor addMonitor(String cls, ActivityResult result, boolean block)

其他相关的还有如下的方法，其中waitForMonitorWithTimeout（waitForMonitor，可能会造成程序阻塞，不推荐使用）可以用于检测是否启动了符合指定ActivityMonitor的Activity，来验证某些操作是否启动了正确的Activity：

*   public boolean checkMonitorHit(ActivityMonitor monitor, int minHits)：检查指定的ActivityMonitor的匹配次数是否达到minHits，minHits会在各种execStartActivity（上一节）中intent和ActivityMonitor匹配时+1。
*   public Activity waitForMonitor(ActivityMonitor monitor)：等待指定的ActivityMonitor被命中（符合ActivityMonitor条件的Activity被启动），并返回启动的Activity对象，同时将该ActivityMonitor从mActivityMonitors列表中移除，如果没有等到会一直阻塞，代码如下：

*   public Activity waitForMonitorWithTimeout(ActivityMonitor monitor, long timeOut)：等待指定的ActivityMonitor被命中（符合ActivityMonitor条件的Activity被启动），并返回启动的Activity对象，同时将该ActivityMonitor从mActivityMonitors列表中移除，在计时器结束前没有等到会一直阻塞，代码类似，不贴了。
*   public void removeMonitor(ActivityMonitor monitor)：从mActivityMonitors列表中移除指定的ActivityMonitor

#### 操作按键

以下这个方法提供了在主线程中的一些操作按键的方法，方法名都很直白，不用一一解释了吧

*   public boolean invokeMenuActionSync(Activity targetActivity, int id, int flag)
*   public boolean invokeContextMenuAction(Activity targetActivity, int id, int flag)
*   public void sendStringSync(String text)
*   public void sendKeySync(KeyEvent event)
*   public void sendKeyDownUpSync(int key)
*   public void sendCharacterSync(int keyCode)
*   public void sendPointerSync(MotionEvent event)
*   public void sendTrackballEventSync(MotionEvent event)

#### 处理Activity生命周期相关

以下的方法提供了各种操纵Activity生命周期的方法，通过重写这些方法可以修改Activity在每个生命周期方法被调用时的行为。

*   public void callActivityOnCreate(Activity activity, Bundle icicle)
*   public void callActivityOnCreate(Activity activity, Bundle icicle, PersistableBundle persistentState)
*   public void callActivityOnDestroy(Activity activity)
*   public void callActivityOnRestoreInstanceState(Activity activity, Bundle savedInstanceState)
*   public void callActivityOnRestoreInstanceState(Activity activity, Bundle savedInstanceState, PersistableBundle persistentState)
*   public void callActivityOnPostCreate(Activity activity, Bundle icicle)
*   public void callActivityOnPostCreate(Activity activity, Bundle icicle, PersistableBundle persistentState)
*   public void callActivityOnNewIntent(Activity activity, Intent intent)
*   public void callActivityOnNewIntent(Activity activity, ReferrerIntent intent)
*   public void callActivityOnStart(Activity activity)
*   public void callActivityOnRestart(Activity activity)
*   public void callActivityOnResume(Activity activity)
*   public void callActivityOnStop(Activity activity)
*   public void callActivityOnSaveInstanceState(Activity activity, Bundle outState)
*   public void callActivityOnSaveInstanceState(Activity activity, Bundle outState, PersistableBundle outPersistentState)
*   public void callActivityOnPause(Activity activity)
*   public void callActivityOnUserLeaving(Activity activity)

#### 其他

*   public void setInTouchMode(boolean inTouch)：Set to true to be in touch mode, false to be in focus mode.
*   public void startAllocCounting(): Starts allocation counting. This triggers a gc and resets the counts.
*   public void stopAllocCounting(): Stops allocation counting.
*   public Bundle getAllocCounts(): Returns a bundle with the current results from the allocation counting.
*   public Bundle getBinderCounts(): Returns a bundle with the counts for various binder counts for this process. Currently the only two that are reported are the number of send and the number of received transactions.
*   public UiAutomation getUiAutomation():获取UiAutomation对象，UI自动化测试相关
*   public Application newApplication(ClassLoader cl, String className, Context context)：新建Application，测试Application时可用，我们通常不会使用到
*   static public Application newApplication(Class\<?> clazz, Context context)：静态类，新建Application，在ApplicationTestCase中被使用
*   public void callApplicationOnCreate(Application app)：启动指定的Application

## InstrumentationTestRunner源码分析

InstrumentationTestRunner实际上是继承自Instrumentation，所以上面所有对Instrumentation类的分析都适用于它，我们在这里主要要看的是它多了些什么新玩意，按照之前的逻辑我们先来看流程控制函数

### InstrumentationTestRunner流程控制函数分析

#### onCreate方法

InstrumentationTestRunner重写了onCreate，在之前的启动流程分析中我们也知道，Instrumentation启动的入口即是onCreate方法：

    public void onCreate(Bundle arguments) {
        super.onCreate(arguments);
        mArguments = arguments;

        // Apk paths used to search for test classes when using TestSuiteBuilders.
        String[] apkPaths =
                {getTargetContext().getPackageCodePath(), getContext().getPackageCodePath()};
        ClassPathPackageInfoSource.setApkPaths(apkPaths);

        Predicate<TestMethod> testSizePredicate = null;
        Predicate<TestMethod> testAnnotationPredicate = null;
        Predicate<TestMethod> testNotAnnotationPredicate = null;
        String testClassesArg = null;
        boolean logOnly = false;

        if (arguments != null) {
            // Test class name passed as an argument should override any meta-data declaration.
            testClassesArg = arguments.getString(ARGUMENT_TEST_CLASS);
            mDebug = getBooleanArgument(arguments, "debug");
            mJustCount = getBooleanArgument(arguments, "count");
            mSuiteAssignmentMode = getBooleanArgument(arguments, "suiteAssignment");
            mPackageOfTests = arguments.getString(ARGUMENT_TEST_PACKAGE);
            testSizePredicate = getSizePredicateFromArg(
                    arguments.getString(ARGUMENT_TEST_SIZE_PREDICATE));
            testAnnotationPredicate = getAnnotationPredicate(
                    arguments.getString(ARGUMENT_ANNOTATION));
            testNotAnnotationPredicate = getNotAnnotationPredicate(
                    arguments.getString(ARGUMENT_NOT_ANNOTATION));

            logOnly = getBooleanArgument(arguments, ARGUMENT_LOG_ONLY);
            mCoverage = getBooleanArgument(arguments, "coverage");
            mCoverageFilePath = arguments.getString("coverageFile");

            try {
                Object delay = arguments.get(ARGUMENT_DELAY_MSEC);  // Accept either string or int
                if (delay != null) mDelayMsec = Integer.parseInt(delay.toString());
            } catch (NumberFormatException e) {
                Log.e(LOG_TAG, "Invalid delay_msec parameter", e);
            }
        }

        TestSuiteBuilder testSuiteBuilder = new TestSuiteBuilder(getClass().getName(),
                getTargetContext().getClassLoader());

        if (testSizePredicate != null) {
            testSuiteBuilder.addRequirements(testSizePredicate);
        }
        if (testAnnotationPredicate != null) {
            testSuiteBuilder.addRequirements(testAnnotationPredicate);
        }
        if (testNotAnnotationPredicate != null) {
            testSuiteBuilder.addRequirements(testNotAnnotationPredicate);
        }

        //判断是否传入了参数指定测试类，并做相应处理
        if (testClassesArg == null) {
            if (mPackageOfTests != null) {
                testSuiteBuilder.includePackages(mPackageOfTests);
            } else {
                TestSuite testSuite = getTestSuite();
                if (testSuite != null) {
                    testSuiteBuilder.addTestSuite(testSuite);
                } else {
                    // no package or class bundle arguments were supplied, and no test suite
                    // provided so add all tests in application
                    testSuiteBuilder.includePackages("");
                }
            }
        } else {
            parseTestClasses(testClassesArg, testSuiteBuilder);
        }

        testSuiteBuilder.addRequirements(getBuilderRequirements());

        mTestRunner = getAndroidTestRunner();
        mTestRunner.setContext(getTargetContext());
        mTestRunner.setInstrumentation(this);
        mTestRunner.setSkipExecution(logOnly);
        mTestRunner.setTest(testSuiteBuilder.build());
        mTestCount = mTestRunner.getTestCases().size();
        if (mSuiteAssignmentMode) {
            mTestRunner.addTestListener(new SuiteAssignmentPrinter());
        } else {
            WatcherResultPrinter resultPrinter = new WatcherResultPrinter(mTestCount);
            mTestRunner.addTestListener(new TestPrinter("TestRunner", false));
            mTestRunner.addTestListener(resultPrinter);
            mTestRunner.setPerformanceResultsWriter(resultPrinter);
        }
        start();
    }

可以看到方法根据的参数arguments做了一系列的处理，这些arguments即是在am instrument命令中传入的各种-e后的键值对参数，初始化mTestRunner,然后调用start函数

mTestRunner是一个AndroidTestRunner对象，主要用于记录TestCase和TestResult，同时维护了一个TestListener类型的List，然后用mTestRunner.setTest(testSuiteBuilder.build())获取测试用例集并传递给mTestRunner。关于AndroidTestRunner和TestSuite相关的内容我们后续分析。

#### onStart方法

InstrumentationTestRunner并没有重写start方法，所以start方法会调用父类Instrumentation的start，启动一个InstrumentationThread，调用onStart方法，onStart方法是被重写过了的：

    public void onStart() {
        prepareLooper();

        if (mJustCount) {
            mResults.putString(Instrumentation.REPORT_KEY_IDENTIFIER, REPORT_VALUE_ID);
            mResults.putInt(REPORT_KEY_NUM_TOTAL, mTestCount);
            finish(Activity.RESULT_OK, mResults);
        } else {
            if (mDebug) {
                Debug.waitForDebugger();
            }

            ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();
            PrintStream writer = new PrintStream(byteArrayOutputStream);
            try {
                StringResultPrinter resultPrinter = new StringResultPrinter(writer);

                mTestRunner.addTestListener(resultPrinter);

                long startTime = System.currentTimeMillis();
                mTestRunner.runTest();
                long runTime = System.currentTimeMillis() - startTime;

                resultPrinter.printResult(mTestRunner.getTestResult(), runTime);
            } catch (Throwable t) {
                // catch all exceptions so a more verbose error message can be outputted
                writer.println(String.format("Test run aborted due to unexpected exception: %s",
                                t.getMessage()));
                t.printStackTrace(writer);
            } finally {
                mResults.putString(Instrumentation.REPORT_KEY_STREAMRESULT,
                        String.format("\nTest results for %s=%s",
                        mTestRunner.getTestClassName(),
                        byteArrayOutputStream.toString()));

                if (mCoverage) {
                    generateCoverageReport();
                }
                writer.close();

                finish(Activity.RESULT_OK, mResults);
            }
        }
    }

可以看到方法中先是增加了一个StringResultPrinter类型的TestListener，然后调用了mTestRunner的runTest方法执行测试用例，如果设置生成覆盖率报告则调用generateCoverageReport方法生成覆盖率报告，最后调用finish方法返回测试结果并停止被测app的运行。

## 测试集与测试用例（TestSuite相关）

在前文中我们看到了Instrumentation执行测试用例的过程，那么这些测试用例是如何被框架识别的呢？

我们记得在InstrumentationTestRunner的onCreate方法中有这样一句：

是用来设定测试用例集的，我们就从这里出发看看如何从测试脚本中找到测试用例集的：

### TestGrouping类

#### TestGrouping类的成员变量

#### TestGrouping类的构造函数

InstrumentationTestRunner中调用的构造函数，其中SORT\_BY\_c\_QUALIFIED\_NAME是一个实现了Comparotor接口的SortByFullyQualifiedName对象，提供根据Class类名排序的功能:

对应的构造函数，使用指定的comparator初始化一个TreeSet用于存储TestCase

#### TestGrouping类的共有函数

##### getTests方法

将所有的testcase以List的形式返回

遍历所有的测试类，然后将每个测试方法加入到testMethods列表中，getTestMethods用于筛选测试方法

通过反射获得测试类的所有方法后使用selcet方法进行过滤，过滤器为TestMethodPredicate，我们先看selcet方法：

可以看到实际上是针对所有的方法使用过滤器的aplly方法做检验，通过的就可以加入到返回的列表中，那么TestMethodPredicate的apply方法是怎么过滤的呢？

可以看到设定了3个条件：

*   无参数
*   方法名以test开头
*   返回值类型为void\
    至此为什么在写测试用例时有这些要求就找到根源了，通过一顿扫描会把所有符合要求的测试方法形成一个TestMethod类型的List

##### addPackagesRecursive方法

将指定的package（包含其子package）中的所有测试类加入到当前TestGrouping中，每个给出的package至少要包含一个测试类，同时将第一个处理的package包名赋给firstIncludedPackage

下面是其中的私有方法testCaseClassesInPackage，其中ClassPathPackageInfo一个用于列举给定package内的类和子package的工具类，ClassPathPackageInfoSource类负责通过扫描APK路径，获取ClassPathPackageInfo。

    public TestGrouping addPackagesRecursive(String... packageNames) {
        for (String packageName : packageNames) {
            List<Class<? extends TestCase>> addedClasses = testCaseClassesInPackage(packageName);
            if (addedClasses.isEmpty()) {
                Log.w(LOG_TAG, "Invalid Package: '" + packageName
                        + "' could not be found or has no tests");
            }
            testCaseClasses.addAll(addedClasses);
            if (firstIncludedPackage == null) {
                firstIncludedPackage = packageName;
            }
        }
        return this;
    }

其中的私有方法selectTestClasses，从给定的测试类集合中挑选出符合要求的测试类列表：

其中的select方法，按照指定的要求（predicate）挑选item并返回列表：

Predicate是一个只定义了apply一个方法的接口，实现该接口能够使对象能够用于判断目标是否满足指定的要求，我们看下TestCasePredicate的具体实现：

    private static class TestCasePredicate implements Predicate<Class<?>> {

        public boolean apply(Class aClass) {
            int modifiers = ((Class<?>) aClass).getModifiers();
            return TestCase.class.isAssignableFrom((Class<?>) aClass)
                    && Modifier.isPublic(modifiers)
                    && !Modifier.isAbstract(modifiers)
                    && hasValidConstructor((Class<?>) aClass);
        }

        @SuppressWarnings("unchecked")
        private boolean hasValidConstructor(java.lang.Class<?> aClass) {
            // The cast below is not necessary with the Java 5 compiler, but necessary with the Java 6 compiler,
            // where the return type of Class.getDeclaredConstructors() was changed
            // from Constructor<T>[] to Constructor<?>[]
            Constructor<? extends TestCase>[] constructors
                    = (Constructor<? extends TestCase>[]) aClass.getConstructors();
            for (Constructor<? extends TestCase> constructor : constructors) {
                if (Modifier.isPublic(constructor.getModifiers())) {
                    java.lang.Class[] parameterTypes = constructor.getParameterTypes();
                    if (parameterTypes.length == 0 ||
                            (parameterTypes.length == 1 && parameterTypes[0] == String.class)) {
                        return true;
                    }
                }
            }
            Log.i(LOG_TAG, String.format(
                    "TestCase class %s is missing a public constructor with no parameters " +
                    "or a single String parameter - skipping",
                    aClass.getName()));
            return false;
        }
    }

我们看到在这个条件限制有有4个：

*   目标class可以被转换为TestCase
*   是一个public类
*   不是abstrarct类
*   有符合要求的构造函数（存在至少一个public构造方法，没有参数或者有一个参数也参数类型为String）

##### removePackagesRecursive方法

从当前TestGrouping中移除指定package及其子package内的测试类

调用的私有方法testCaseClassesInPackage，同selectTestClasses只不过这次的源是package包名：

    private List<Class<? extends TestCase>> testCaseClassesInPackage(String packageName) {
        ClassPathPackageInfoSource source = PackageInfoSources.forClassPath(classLoader);
        ClassPathPackageInfo packageInfo = source.getPackageInfo(packageName);

        return selectTestClasses(packageInfo.getTopLevelClassesRecursive());
    }

### TestSuiteBuilder类

#### TestSuiteBuilder类的成员变量

#### onCreate方法中调用的构造函数

对应的构造函数，将suiteName设置为TestRunner的类名，初始化testCases列表：

#### 其他公有方法

##### build方法

TestCase分成了两部分，一部分是获取TestGrouping后，根据每一个TestMethod是否能够满足所有的Predicates筛选出后加入列表，另一部分是通过addTestClassByName和addTestSuite直接加入的case（存储于testCases中），同样会判断是否满足所有的Predicates

    public final TestSuite build() {
        rootSuite = new TestSuite(getSuiteName());

        // Keep track of current class so we know when to create a new sub-suite.
        currentClassname = null;
        try {
            for (TestMethod test : testGrouping.getTests()) {
                if (satisfiesAllPredicates(test)) {
                    addTest(test);
                }
            }
            if (testCases.size() > 0) {
                for (TestCase testCase : testCases) {
                    if (satisfiesAllPredicates(new TestMethod(testCase))) {
                        addTest(testCase);
                    }
                }
            }
        } catch (Exception exception) {
            Log.i("TestSuiteBuilder", "Failed to create test.", exception);
            TestSuite suite = new TestSuite(getSuiteName());
            suite.addTest(new FailedToCreateTests(exception));
            return suite;
        }
        return rootSuite;
    }

##### addTestClassByName方法

通过指定的类名和方法名添加测试类

    public TestSuiteBuilder addTestClassByName(String testClassName, String testMethodName,
            Context context) {

        AndroidTestRunner atr = new AndroidTestRunner();
        atr.setContext(context);
        atr.setTestClassName(testClassName, testMethodName);

        this.testCases.addAll(atr.getTestCases());
        return this;
    }

##### addTestSuite方法

将testSuite中的测试类加入进来

## AndroidTestRunner

### AndroidTestRunner类

#### 成员变量

#### 几个常用的公有方法

##### setTest方法

调用私有方法

从给定的Test中获取Cases，分为两种情况：单独的Test和TestSuite

##### runTest方法

runTest方法是调用执行测试用例的入口

调用私有方法

    public void runTest(TestResult testResult) {
        mTestResult = testResult;

        for (TestListener testListener : mTestListeners) {
            mTestResult.addListener(testListener);
        }

        Context testContext = mInstrumentation == null ? mContext : mInstrumentation.getContext();
        for (TestCase testCase : mTestCases) {
            setContextIfAndroidTestCase(testCase, mContext, testContext);
            setInstrumentationIfInstrumentationTestCase(testCase, mInstrumentation);
            setPerformanceWriterIfPerformanceCollectorTestCase(testCase, mPerfWriter);
            testCase.run(mTestResult);
        }
    }

设定了mTestResult，并将所有已注册的TestListener传递给mTestResult（关于TestListener如何被使用我们下面再聊），然后又是三个私有方法：

setContextIfAndroidTestCase方法用于对每一个可以转化为AndroidTestCase的Case设定context

setInstrumentationIfInstrumentationTestCase方法用于对每一个可以转化为InstrumentationTestCase的Case注入instrumentation

setPerformanceWriterIfPerformanceCollectorTestCase方法用于对每一个可以转化为PerformanceCollectorTestCase的Case注入PerformanceResultsWriter

最后执行testCase的run方法，执行测试并将结果存储在mTestResult中返回，查看TestCase源码找到run方法，发现是实际调用的传入的TestResult的run方法：

转回头看看我们传入的TestResult：

即如果设定了忽略异常会使用NoExecTestResult，否则使用TestResult，我们分别看一下这两个类

### TestResult类

执行测试会调用TestResult的run方法，我们先来看下这个方法：

分别调用了startTest，runProtected，endTest完成预处理，执行和收尾工作，依次看下做了什么

#### startTest方法

可以看到实现中将测试类中的测试用例数，并针对每一个已注册的TestListener执行startTest方法

#### runProtected方法

这里通过runProtected方法执行test.runBare()，并处理异常分发给addFailure和addError方法，最后看test.runBare()的执行，先来看下这两个异常处理做了什么

##### addFailure方法

实际上同startTest，针对每一个已注册的TestListener执行addFailure方法

##### addError方法

##### test.runBare()

实际上这是JUINT的TestCase的实现了，理论上和Android无关了，我们也可以看看：

会分别调用setUp，runTest，tearDown方法，是不是很熟悉啊，那runTest做了什么呢，只是通过反射运行testMethod啦：

#### endTest方法

实际也上同startTest，针对每一个已注册的TestListener执行endTest方法