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  * @deprecated Use
60  * <a href="{@docRoot}reference/android/support/test/InstrumentationRegistry.html">
61  * InstrumentationRegistry</a> instead. New tests should be written using the
62  * <a href="{@docRoot}tools/testing-support-library/index.html">Android Testing Support Library</a>.
63  */
64 @Deprecated
65 public abstract class ApplicationTestCase<T extends Application> extends AndroidTestCase {
66 
67     Class<T> mApplicationClass;
68 
69     private Context mSystemContext;
70 
ApplicationTestCase(Class<T> applicationClass)71     public ApplicationTestCase(Class<T> applicationClass) {
72         mApplicationClass = applicationClass;
73     }
74 
75     private T mApplication;
76     private boolean mAttached = false;
77     private boolean mCreated = false;
78 
79     /**
80      * @return Returns the actual Application under test.
81      */
getApplication()82     public T getApplication() {
83         return mApplication;
84     }
85 
86     /**
87      * This will do the work to instantiate the Application under test.  After this, your test
88      * code must also start and stop the Application.
89      */
90     @Override
setUp()91     protected void setUp() throws Exception {
92         super.setUp();
93 
94         // get the real context, before the individual tests have a chance to muck with it
95         mSystemContext = getContext();
96     }
97 
98     /**
99      * Load and attach the application under test.
100      */
setupApplication()101     private void setupApplication() {
102         mApplication = null;
103         try {
104             mApplication = (T) Instrumentation.newApplication(mApplicationClass, getContext());
105         } catch (Exception e) {
106             assertNotNull(mApplication);
107         }
108         mAttached = true;
109     }
110 
111     /**
112      * Start the Application under test, in the same way as if it was started by the system.
113      * If you use this method to start the Application, it will automatically
114      * be stopped by {@link #tearDown}.  If you wish to inject a specialized Context for your
115      * test, by calling {@link AndroidTestCase#setContext(Context) setContext()},
116      * you must do so  before calling this method.
117      */
createApplication()118     final protected void createApplication() {
119         assertFalse(mCreated);
120 
121         if (!mAttached) {
122             setupApplication();
123         }
124         assertNotNull(mApplication);
125 
126         mApplication.onCreate();
127         mCreated = true;
128     }
129 
130     /**
131      * This will make the necessary calls to terminate the Application under test (it will
132      * call onTerminate().  Ordinarily this will be called automatically (by {@link #tearDown}, but
133      * you can call it directly from your test in order to check for proper shutdown behaviors.
134      */
terminateApplication()135     final protected void terminateApplication() {
136         if (mCreated) {
137             mApplication.onTerminate();
138         }
139     }
140 
141     /**
142      * Shuts down the Application under test.  Also makes sure all resources are cleaned up and
143      * garbage collected before moving on to the next
144      * test.  Subclasses that override this method should make sure they call super.tearDown()
145      * at the end of the overriding method.
146      *
147      * @throws Exception
148      */
149     @Override
tearDown()150     protected void tearDown() throws Exception {
151         terminateApplication();
152         mApplication = null;
153 
154         // Scrub out members - protects against memory leaks in the case where someone
155         // creates a non-static inner class (thus referencing the test case) and gives it to
156         // someone else to hold onto
157         scrubClass(ApplicationTestCase.class);
158 
159         super.tearDown();
160     }
161 
162     /**
163      * Return a real (not mocked or instrumented) system Context that can be used when generating
164      * Mock or other Context objects for your Application under test.
165      *
166      * @return Returns a reference to a normal Context.
167      */
getSystemContext()168     public Context getSystemContext() {
169         return mSystemContext;
170     }
171 
172     /**
173      * This test simply confirms that the Application class can be instantiated properly.
174      *
175      * @throws Exception
176      */
testApplicationTestCaseSetUpProperly()177     final public void testApplicationTestCaseSetUpProperly() throws Exception {
178         setupApplication();
179         assertNotNull("Application class could not be instantiated successfully", mApplication);
180     }
181 }
182