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 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
