1page.title=CTS Development
2@jd:body
3
4<!--
5    Copyright 2013 The Android Open Source Project
6
7    Licensed under the Apache License, Version 2.0 (the "License");
8    you may not use this file except in compliance with the License.
9    You may obtain a copy of the License at
10
11        http://www.apache.org/licenses/LICENSE-2.0
12
13    Unless required by applicable law or agreed to in writing, software
14    distributed under the License is distributed on an "AS IS" BASIS,
15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16    See the License for the specific language governing permissions and
17    limitations under the License.
18-->
19
20<h2 id="initializing-your-repo-client">Initializing Your Repo Client</h2>
21<p>Follow the <a href="{@docRoot}source/downloading.html">instructions</a>
22to get and build the Android source code but specify <code>-b android-4.3_r1</code>
23when issuing the <code>repo init</code> command. This assures that your CTS
24changes will be included in the next CTS release and beyond.</p>
25<h2 id="setting-up-eclipse">Setting Up Eclipse</h2>
26<p>Follow the <a href="{@docRoot}source/using-eclipse.html">instructions</a>
27to setup Eclipse but execute the following command to generate the
28<code>.classpath</code> file rather than copying the one from the development
29project:</p>
30<pre><code>cd /path/to/android/root
31./cts/development/ide/eclipse/genclasspath.sh &gt; .classpath
32chmod u+w .classpath
33</code></pre>
34<p>This <code>.classpath</code> file will contain both the Android framework
35packages and the CTS packages.</p>
36<h2 id="building-and-running-cts">Building and Running CTS</h2>
37<p>Execute the following commands to build CTS and start the interactive
38CTS console:</p>
39<pre><code>cd /path/to/android/root
40make cts
41cts-tradefed
42</code></pre>
43<p>At the cts-tf console, enter e.g.:</p>
44<pre><code>run cts --plan CTS
45</code></pre>
46<h2 id="writing-cts-tests">Writing CTS Tests</h2>
47<p>CTS tests use JUnit and the Android testing APIs. Review the
48<a href="https://developer.android.com/guide/topics/testing/testing_android.html">Testing and Instrumentation</a>
49tutorial while perusing the existing tests under the
50<code>cts/tests/tests</code> directory. You will see that CTS tests mostly follow the same
51conventions used in other Android tests.</p>
52<p>Since CTS runs across many production devices, the tests must follow
53these rules:</p>
54<ul>
55<li>Must take into account varying screen sizes, orientations, and keyboard layouts.</li>
56<li>Only use public API methods. In other words, avoid all classes, methods, and fields that are annotated with the "hide" annotation.</li>
57<li>Avoid relying upon particular view layouts or depend on the dimensions of assets that may not be on some device.</li>
58<li>Don't rely upon root privileges.</li>
59</ul>
60<h3 id="test-naming-and-location">Test Naming and Location</h3>
61<p>Most CTS test cases target a specific class in the Android API. These tests
62have Java package names with a <code>cts</code> suffix and class
63names with the <code>Test</code> suffix. Each test case consists of
64multiple tests, where each test usually exercises a particular API method of
65the API class being tested. These tests are arranged in a directory structure
66where tests are grouped into different categories like "widgets" and "views."</p>
67<p>For example, the CTS test for <code>android.widget.TextView</code> is
68<code>android.widget.cts.TextViewTest</code> found under the
69<code>cts/tests/tests/widget/src/android/widget/cts</code> directory with its
70Java package name as <code>android.widget.cts</code> and its class name as
71<code>TextViewTest</code>. The <code>TextViewTest</code> class has a test called <code>testSetText</code>
72that exercises the "setText" method and a test named "testSetSingleLine" that
73calls the <code>setSingleLine</code> method. Each of those tests have <code>@TestTargetNew</code>
74annotations indicating what they cover.</p>
75<p>Some CTS tests do not directly correspond to an API class but are placed in
76the most related package possible. For instance, the CTS test,
77<code>android.net.cts.ListeningPortsTest</code>, is in the <code>android.net.cts</code>, because it
78is network related even though there is no <code>android.net.ListeningPorts</code> class.
79You can also create a new test package if necessary. For example, there is an
80"android.security" test package for tests related to security. Thus, use your
81best judgement when adding new tests and refer to other tests as examples.</p>
82<p>Finally, a lot of tests are annotated with @TestTargets and @TestTargetNew.
83These are no longer necessary so do not annotate new tests with these.</p>
84<h3 id="new-test-packages">New Test Packages</h3>
85<p>When adding new tests, there may not be an existing directory to place your
86test. In that case, refer to the example under <code>cts/tests/tests/example</code> and
87create a new directory. Furthermore, make sure to add your new package's
88module name from its <code>Android.mk</code> to <code>CTS_COVERAGE_TEST_CASE_LIST</code> in
89<code>cts/CtsTestCaseList.mk</code>. This Makefile is used by <code>build/core/tasks/cts.mk</code>
90to glue all the tests together to create the final CTS package.</p>
91<h3 id="test-stubs-and-utilities">Test Stubs and Utilities</h3>
92<p>Some tests use additional infrastructure like separate activities
93and various utilities to perform tests. These are located under the
94<code>cts/tests/src</code> directory. These stubs aren't separated into separate test
95APKs like the tests, so the <code>cts/tests/src</code> directory does not have additional
96top level directories like "widget" or "view." Follow the same principle of
97putting new classes into a package with a name that correlates to the purpose
98of your new class. For instance, a stub activity used for testing OpenGL like
99<code>GLSurfaceViewStubActivity</code> belongs in the <code>android.opengl.cts</code> package under
100the <code>cts/tests/src/android/opengl</code> directory.</p>
101<h2 id="other-tasks">Other Tasks</h2>
102<p>Besides adding new tests there are other ways to contribute to CTS:</p>
103<ul>
104<li>Fix or remove tests annotated with BrokenTest and KnownFailure.</li>
105</ul>
106<h2 id="submitting-your-changes">Submitting Your Changes</h2>
107<p>Follow the <a href="{@docRoot}source/submit-patches.html">Android Contributors' Workflow</a>
108to contribute changes to CTS. A reviewer
109will be assigned to your change, and your change should be reviewed shortly!</p>
110