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
17package android.test;
18
19import android.app.Application;
20import android.app.Instrumentation;
21import 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
65public abstract class ApplicationTestCase<T extends Application> extends AndroidTestCase {
66
67    Class<T> mApplicationClass;
68
69    private Context mSystemContext;
70
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     */
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
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     */
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     */
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     */
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
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     */
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     */
177    final public void testApplicationTestCaseSetUpProperly() throws Exception {
178        setupApplication();
179        assertNotNull("Application class could not be instantiated successfully", mApplication);
180    }
181}
182