1<!-- 2 Copyright 2010 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# CTS Development # 18 19## Initializing Your Repo Client ## 20 21Follow the [instructions](/source/downloading.html) 22to get and build the Android source code but specify `-b android-4.1.1_r1` 23when issuing the `repo init` command. This assures that your CTS 24changes will be included in the next CTS release and beyond. 25 26## Setting Up Eclipse ## 27 28Follow the [instructions](/source/using-eclipse.html) 29to setup Eclipse but execute the following command to generate the 30`.classpath` file rather than copying the one from the development 31project: 32 33 cd /path/to/android/root 34 ./cts/development/ide/eclipse/genclasspath.sh > .classpath 35 chmod u+w .classpath 36 37This `.classpath` file will contain both the Android framework 38packages and the CTS packages. 39 40## Building and Running CTS ## 41 42Execute the following commands to build CTS and start the interactive 43CTS console: 44 45 cd /path/to/android/root 46 make cts 47 cts 48 49Provide arguments to CTS to immediately start executing a test: 50 51 cts start --plan CTS -p android.os.cts.BuildVersionTest 52 53## Writing CTS Tests ## 54 55CTS tests use JUnit and the Android testing APIs. Review the 56[Testing and Instrumentation](https://developer.android.com/guide/topics/testing/testing_android.html) 57tutorial while perusing the existing tests under the 58`cts/tests/tests` directory. You will see that CTS tests mostly follow the same 59conventions used in other Android tests. 60 61Since CTS runs across many production devices, the tests must follow 62these rules: 63 64- Must take into account varying screen sizes, orientations, and keyboard layouts. 65- Only use public API methods. In other words, avoid all classes, methods, and fields that are annotated with the "hide" annotation. 66- Avoid relying upon particular view layouts or depend on the dimensions of assets that may not be on some device. 67- Don't rely upon root privileges. 68 69### Test Naming and Location ### 70 71Most CTS test cases target a specific class in the Android API. These tests 72have Java package names with a `cts` suffix and class 73names with the `Test` suffix. Each test case consists of 74multiple tests, where each test usually exercises a particular API method of 75the API class being tested. These tests are arranged in a directory structure 76where tests are grouped into different categories like "widgets" and "views." 77 78For example, the CTS test for `android.widget.TextView` is 79`android.widget.cts.TextViewTest` found under the 80`cts/tests/tests/widget/src/android/widget/cts` directory with its 81Java package name as `android.widget.cts` and its class name as 82`TextViewTest`. The `TextViewTest` class has a test called `testSetText` 83that exercises the "setText" method and a test named "testSetSingleLine" that 84calls the `setSingleLine` method. Each of those tests have `@TestTargetNew` 85annotations indicating what they cover. 86 87Some CTS tests do not directly correspond to an API class but are placed in 88the most related package possible. For instance, the CTS test, 89`android.net.cts.ListeningPortsTest`, is in the `android.net.cts`, because it 90is network related even though there is no `android.net.ListeningPorts` class. 91You can also create a new test package if necessary. For example, there is an 92"android.security" test package for tests related to security. Thus, use your 93best judgement when adding new tests and refer to other tests as examples. 94 95Finally, a lot of tests are annotated with @TestTargets and @TestTargetNew. 96These are no longer necessary so do not annotate new tests with these. 97 98### New Test Packages ### 99 100When adding new tests, there may not be an existing directory to place your 101test. In that case, refer to the example under `cts/tests/tests/example` and 102create a new directory. Furthermore, make sure to add your new package's 103module name from its `Android.mk` to `CTS_COVERAGE_TEST_CASE_LIST` in 104`cts/CtsTestCaseList.mk`. This Makefile is used by `build/core/tasks/cts.mk` 105to glue all the tests together to create the final CTS package. 106 107### Test Stubs and Utilities ### 108 109Some tests use additional infrastructure like separate activities 110and various utilities to perform tests. These are located under the 111`cts/tests/src` directory. These stubs aren't separated into separate test 112APKs like the tests, so the `cts/tests/src` directory does not have additional 113top level directories like "widget" or "view." Follow the same principle of 114putting new classes into a package with a name that correlates to the purpose 115of your new class. For instance, a stub activity used for testing OpenGL like 116`GLSurfaceViewStubActivity` belongs in the `android.opengl.cts` package under 117the `cts/tests/src/android/opengl` directory. 118 119## Other Tasks ## 120 121Besides adding new tests there are other ways to contribute to CTS: 122 123- Fix or remove tests annotated with BrokenTest and KnownFailure. 124 125## Submitting Your Changes ## 126 127Follow the [Android Contributors' Workflow](/source/submit-patches.html) 128to contribute changes to CTS. A reviewer 129will be assigned to your change, and your change should be reviewed shortly! 130 131