Home | History | Annotate | Download | only in test
      1 /*
      2  * Copyright (C) 2008 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.test;
     18 
     19 import android.app.Application;
     20 import android.app.Instrumentation;
     21 import android.content.Context;
     22 
     23 /**
     24  * This test case provides a framework in which you can test Application classes in
     25  * a controlled environment.  It provides basic support for the lifecycle of a
     26  * Application, and hooks by which you can inject various dependencies and control
     27  * the environment in which your Application is tested.
     28  *
     29  * <p><b>Lifecycle Support.</b>
     30  * Every Application is designed to be accessed within a specific sequence of
     31  * method calls (see {@link android.app.Application} for more details).
     32  * In order to support the lifecycle of a Application, this test case will make the
     33  * following calls at the following times.
     34  *
     35  * <ul><li>The test case will not call onCreate() until your test calls
     36  * {@link #createApplication()}.  This gives you a chance
     37  * to set up or adjust any additional framework or test logic before
     38  * onCreate().</li>
     39  * <li>After your test completes, the test case {@link #tearDown} method is
     40  * automatically called, and it will stop & destroy your application by calling its
     41  * onDestroy() method.</li>
     42  * </ul>
     43  *
     44  * <p><b>Dependency Injection.</b>
     45  * Every Application has one inherent dependency, the {@link android.content.Context Context} in
     46  * which it runs.
     47  * This framework allows you to inject a modified, mock, or isolated replacement for this
     48  * dependencies, and thus perform a true unit test.
     49  *
     50  * <p>If simply run your tests as-is, your Application will be injected with a fully-functional
     51  * Context.
     52  * You can create and inject alternative types of Contexts by calling
     53  * {@link AndroidTestCase#setContext(Context) setContext()}.  You must do this <i>before</i> calling
     54  * {@link #createApplication()}.  The test framework provides a
     55  * number of alternatives for Context, including {@link android.test.mock.MockContext MockContext},
     56  * {@link android.test.RenamingDelegatingContext RenamingDelegatingContext}, and
     57  * {@link android.content.ContextWrapper ContextWrapper}.
     58  */
     59 public abstract class ApplicationTestCase<T extends Application> extends AndroidTestCase {
     60 
     61     Class<T> mApplicationClass;
     62 
     63     private Context mSystemContext;
     64 
     65     public ApplicationTestCase(Class<T> applicationClass) {
     66         mApplicationClass = applicationClass;
     67     }
     68 
     69     private T mApplication;
     70     private boolean mAttached = false;
     71     private boolean mCreated = false;
     72 
     73     /**
     74      * @return Returns the actual Application under test.
     75      */
     76     public T getApplication() {
     77         return mApplication;
     78     }
     79 
     80     /**
     81      * This will do the work to instantiate the Application under test.  After this, your test
     82      * code must also start and stop the Application.
     83      */
     84     @Override
     85     protected void setUp() throws Exception {
     86         super.setUp();
     87 
     88         // get the real context, before the individual tests have a chance to muck with it
     89         mSystemContext = getContext();
     90     }
     91 
     92     /**
     93      * Load and attach the application under test.
     94      */
     95     private void setupApplication() {
     96         mApplication = null;
     97         try {
     98             mApplication = (T) Instrumentation.newApplication(mApplicationClass, getContext());
     99         } catch (Exception e) {
    100             assertNotNull(mApplication);
    101         }
    102         mAttached = true;
    103     }
    104 
    105     /**
    106      * Start the Application under test, in the same way as if it was started by the system.
    107      * If you use this method to start the Application, it will automatically
    108      * be stopped by {@link #tearDown}.  If you wish to inject a specialized Context for your
    109      * test, by calling {@link AndroidTestCase#setContext(Context) setContext()},
    110      * you must do so  before calling this method.
    111      */
    112     final protected void createApplication() {
    113         assertFalse(mCreated);
    114 
    115         if (!mAttached) {
    116             setupApplication();
    117         }
    118         assertNotNull(mApplication);
    119 
    120         mApplication.onCreate();
    121         mCreated = true;
    122     }
    123 
    124     /**
    125      * This will make the necessary calls to terminate the Application under test (it will
    126      * call onTerminate().  Ordinarily this will be called automatically (by {@link #tearDown}, but
    127      * you can call it directly from your test in order to check for proper shutdown behaviors.
    128      */
    129     final protected void terminateApplication() {
    130         if (mCreated) {
    131             mApplication.onTerminate();
    132         }
    133     }
    134 
    135     /**
    136      * Shuts down the Application under test.  Also makes sure all resources are cleaned up and
    137      * garbage collected before moving on to the next
    138      * test.  Subclasses that override this method should make sure they call super.tearDown()
    139      * at the end of the overriding method.
    140      *
    141      * @throws Exception
    142      */
    143     @Override
    144     protected void tearDown() throws Exception {
    145         terminateApplication();
    146         mApplication = null;
    147 
    148         // Scrub out members - protects against memory leaks in the case where someone
    149         // creates a non-static inner class (thus referencing the test case) and gives it to
    150         // someone else to hold onto
    151         scrubClass(ApplicationTestCase.class);
    152 
    153         super.tearDown();
    154     }
    155 
    156     /**
    157      * Return a real (not mocked or instrumented) system Context that can be used when generating
    158      * Mock or other Context objects for your Application under test.
    159      *
    160      * @return Returns a reference to a normal Context.
    161      */
    162     public Context getSystemContext() {
    163         return mSystemContext;
    164     }
    165 
    166     /**
    167      * This test simply confirms that the Application class can be instantiated properly.
    168      *
    169      * @throws Exception
    170      */
    171     final public void testApplicationTestCaseSetUpProperly() throws Exception {
    172         setupApplication();
    173         assertNotNull("Application class could not be instantiated successfully", mApplication);
    174     }
    175 }
    176