diff options
| author | Omari Stephens <xsdg@android.com> | 2013-04-19 00:48:18 +0000 |
|---|---|---|
| committer | Android (Google) Code Review <android-gerrit@google.com> | 2013-04-19 00:48:18 +0000 |
| commit | 79b2e29f7e37e83bb9de5492d56e9fbc1402423f (patch) | |
| tree | 649260801eb9421a23b72403fb3111add720993d | |
| parent | df3e4389cc6ad5a07a6595a2b07cead847b0bead (diff) | |
| parent | 06f900177a95a45853639e6736d29262b88fdf8a (diff) | |
| download | source.android.com-79b2e29f7e37e83bb9de5492d56e9fbc1402423f.tar.gz | |
Merge "Disable the role-specific sections until they are complete" into jb-mr1.1-docs
11 files changed, 10 insertions, 602 deletions
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs index adbd573d..c66d8918 100644 --- a/src/devices/devices_toc.cs +++ b/src/devices/devices_toc.cs @@ -166,65 +166,16 @@ </a> </div> <ul> - <li class="nav-section"> - <div class="nav-section-header"> - <a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/index.html"> - <span class="en">Start Here</span> - </a> - </div> - <ul> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/machine_setup.html" - >Machine Setup</a></li> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/devices.html" - >Working with Devices</a></li> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/lifecycle.html" - >Test Lifecycle</a></li> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/options.html" - >Option Handling</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"> - <a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/developer/index.html"> - <span class="en">Developer Docs</span> - </a> - </div> - <ul> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/developer/unit_tests.html" - >Unit Testing TF Components</a></li> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/developer/utility_classes.html" - >Handy Utility Classes</a></li> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/developer/implementation.html" - >How To Write an I-Whatever</a></li> - </ul> - </li> - <li class="nav-section"> - <div class="nav-section-header"> - <a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/integrator/index.html"> - <span class="en">Integrator Docs</span> - </a> - </div> - <ul> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/integrator/config_xml_spec.html" - >XML Config Format Spec</a></li> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/integrator/commandfile_format.html" - >Command File Format</a></li> - </ul> - </li> - <li class="nav-section"> - <div class="nav-section-header"> - <a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/runner/index.html"> - <span class="en">Test Runner Docs</span> - </a> - </div> - <ul> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/runner/cli.html" - >Command Line Interaction</a></li> - <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/runner/debug.html" - >Debugging Unexpected Results</a></li> - </ul> - </li> + <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/index.html" + >Start Here</a></li> + <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/machine_setup.html" + >Machine Setup</a></li> + <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/devices.html" + >Working with Devices</a></li> + <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/lifecycle.html" + >Test Lifecycle</a></li> + <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/options.html" + >Option Handling</a></li> <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/full_example.html" >An End-to-End Example</a></li> <li id="tradefed-tree-list" class="nav-section"> diff --git a/src/devices/tech/test_infra/tradefed/developer/implementation.jd b/src/devices/tech/test_infra/tradefed/developer/implementation.jd deleted file mode 100644 index 3d6677f3..00000000 --- a/src/devices/tech/test_infra/tradefed/developer/implementation.jd +++ /dev/null @@ -1,24 +0,0 @@ -page.title=Template -@jd:body - -<!-- - Copyright 2013 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -<p>Write some stuff</p> - -<h2>Hey, it's a header!</h2> -<p>Write some more stuff</p> - diff --git a/src/devices/tech/test_infra/tradefed/developer/index.jd b/src/devices/tech/test_infra/tradefed/developer/index.jd deleted file mode 100644 index 3d6677f3..00000000 --- a/src/devices/tech/test_infra/tradefed/developer/index.jd +++ /dev/null @@ -1,24 +0,0 @@ -page.title=Template -@jd:body - -<!-- - Copyright 2013 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -<p>Write some stuff</p> - -<h2>Hey, it's a header!</h2> -<p>Write some more stuff</p> - diff --git a/src/devices/tech/test_infra/tradefed/developer/unit_tests.jd b/src/devices/tech/test_infra/tradefed/developer/unit_tests.jd deleted file mode 100644 index 3d6677f3..00000000 --- a/src/devices/tech/test_infra/tradefed/developer/unit_tests.jd +++ /dev/null @@ -1,24 +0,0 @@ -page.title=Template -@jd:body - -<!-- - Copyright 2013 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -<p>Write some stuff</p> - -<h2>Hey, it's a header!</h2> -<p>Write some more stuff</p> - diff --git a/src/devices/tech/test_infra/tradefed/developer/utility_classes.jd b/src/devices/tech/test_infra/tradefed/developer/utility_classes.jd deleted file mode 100644 index 3d6677f3..00000000 --- a/src/devices/tech/test_infra/tradefed/developer/utility_classes.jd +++ /dev/null @@ -1,24 +0,0 @@ -page.title=Template -@jd:body - -<!-- - Copyright 2013 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -<p>Write some stuff</p> - -<h2>Hey, it's a header!</h2> -<p>Write some more stuff</p> - diff --git a/src/devices/tech/test_infra/tradefed/integrator/commandfile_format.jd b/src/devices/tech/test_infra/tradefed/integrator/commandfile_format.jd deleted file mode 100644 index cd5102ae..00000000 --- a/src/devices/tech/test_infra/tradefed/integrator/commandfile_format.jd +++ /dev/null @@ -1,121 +0,0 @@ -page.title=Command File Format -@jd:body - -<!-- - Copyright 2010 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<p>A command file allows one to specify sets of TF commands (that is, configurations with their -associated arguments) to be specified all at once. Further, the format used in the command file -supports simple macro expansions, which makes it very useful without being unwieldy. You can see a -relatively involved example at the bottom of the page, as well as more gradual documentation -immediately below.</p> -<h2 id="lines">Lines</h2> -<p>The format is line-based.</p> -<ul> -<li>Each output line will be considered as the arguments for a single Configuration for Trade - Federation to run.</li> -<li>Each input line will turn into one or more output lines.</li> -</ul> -<p>In essence, the command file format combinatorially creates a sequence of Configuration specifications that it passes to Trade Federation to run. Blank lines are ignored. Comments are delimited by the "#" character and may only be preceded by whitespace.</p> -<h2 id="macros">Macros</h2> -<p>The specific syntax for defining a macro is discussed below in the Short Macro and Long Macro sections. The following rules apply to all macros</p> -<ul> -<li>The name of a macro must begin with an alpha character. Each subsequent character may be any - alphanumeric, an underscore, or a hyphen.</li> -<li>A macro with name "macro_name" is invoked by adding macro_name() as an argument on some subsequent - line.</li> -<li>The macro format does not support passing arguments to macros. It allows only concatenation.</li> -<li>A macro's expansion may contain invocations of other macros. Technically, a macro's expansion may - contain invocations of itself, but in that case, the macro will never fully expand.</li> -<li>The parser currently has a hard limit of 10 iterations of expansion. This will be made - configurable at some point.</li> -<li>During a single iteration of expansion:<ul> -<li>All short macro invocations on a line will be expanded a single level — macro invocations - embedded within the first-level expansions will not be expanded yet</li> -<li>Only one long macro invocation on a line will be expanded. This will be the left-most long - macro invocation.</li> -</ul> -</li> -</ul> -<h2 id="short-macros">Short Macros</h2> -<p>A short macro can be defined with the syntax:</p> -<pre><code>MACRO macro_name = this is the macro expansion -</code></pre> -<p>The macro expansion terminates at the end of the line. For multi-line expansion, see Long Macros -below.</p> -<h3 id="short-macro-expansion">Short Macro Expansion</h3> -<ul> -<li><code>a macro_name() invocation</code><br /> - will be replaced by<br /> - <code>a this is the macro expansion invocation</code></li> -<li><code>three macro_name() A macro_name() B macro_name()</code><br /> - will be replaced by (all during the first iteration)<br /> - <code>three this is the macro expansion A this is the macro expansion B this is the macro expansion</code></li> -</ul> -<h2 id="long-macros">Long Macros</h2> -<p>A long macro can be defined with the syntax:</p> -<pre><code>LONG MACRO macro_name - expansion line 1 - expansion line 2 - expansion line 3 -END MACRO -</code></pre> -<p>The macro is then invoked with th enormal <code>macro_name()</code> syntax. Leading whitespace/indentation -will be ignored.</p> -<h3 id="long-macro-expansion">Long Macro Expansion</h3> -<p>The output of a single input line will include one line for each combination of macro expansions on -that line. That is, the number of output lines is multiplicatively related to the number of macro -expansions on that line:</p> -<ul> -<li>Only a single long macro invocation per line will be expanded during a single iteration. This - means that a line may only contain 10 long macro invocations to stay under the iteration count - limit.</li> -<li> -<p>A single invocation of a long macro on a single line will cause that line to expand to the number - of lines of the long macro's expansion. On each expanded line, the invocation will be replaced - by the corresponding line of the macro's expansion.</p> -</li> -<li> -<p>Example 1:</p> -<pre><code>a macro_name() invocation -</code></pre> -<p>will be replaced by (in a single iteration)</p> -<pre><code>a expansion line 1 invocation -a expansion line 2 invocation -a expansion line 3 invocation -</code></pre> -</li> -<li> -<p>Example 2:</p> -<pre><code>alpha macro_name() beta macro_name() -</code></pre> -<p>will be replaced by (during the first iteration)</p> -<pre><code>alpha expansion line 1 beta macro_name() -alpha expansion line 2 beta macro_name() -alpha expansion line 3 beta macro_name() -</code></pre> -<p>which will be replaced by (during the second iteration)</p> -<pre><code>alpha expansion line 1 beta expansion line 1 -alpha expansion line 1 beta expansion line 2 -alpha expansion line 1 beta expansion line 3 -alpha expansion line 2 beta expansion line 1 -alpha expansion line 2 beta expansion line 2 -alpha expansion line 2 beta expansion line 3 -alpha expansion line 3 beta expansion line 1 -alpha expansion line 3 beta expansion line 2 -alpha expansion line 3 beta expansion line 3 -</code></pre> -</li> -</ul> diff --git a/src/devices/tech/test_infra/tradefed/integrator/config_xml_spec.jd b/src/devices/tech/test_infra/tradefed/integrator/config_xml_spec.jd deleted file mode 100644 index 3d6677f3..00000000 --- a/src/devices/tech/test_infra/tradefed/integrator/config_xml_spec.jd +++ /dev/null @@ -1,24 +0,0 @@ -page.title=Template -@jd:body - -<!-- - Copyright 2013 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -<p>Write some stuff</p> - -<h2>Hey, it's a header!</h2> -<p>Write some more stuff</p> - diff --git a/src/devices/tech/test_infra/tradefed/integrator/index.jd b/src/devices/tech/test_infra/tradefed/integrator/index.jd deleted file mode 100644 index 69fc41b2..00000000 --- a/src/devices/tech/test_infra/tradefed/integrator/index.jd +++ /dev/null @@ -1,24 +0,0 @@ -page.title=Getting Started as a Developer -@jd:body - -<!-- - Copyright 2013 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -<p>Write some stuff</p> - -<h2>Hey, it's a header!</h2> -<p>Write some more stuff</p> - diff --git a/src/devices/tech/test_infra/tradefed/runner/cli.jd b/src/devices/tech/test_infra/tradefed/runner/cli.jd deleted file mode 100644 index d5e9265b..00000000 --- a/src/devices/tech/test_infra/tradefed/runner/cli.jd +++ /dev/null @@ -1,26 +0,0 @@ -page.title=Command Line Interaction -@jd:body - -<!-- - Copyright 2013 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -<p>Talk about the difference between the command line command line -and the TF cmdline. This should specifically mention useful features -for running TF synchronously.</p> - -<h2>Hey, it's a header!</h2> -<p>Write some more stuff</p> - diff --git a/src/devices/tech/test_infra/tradefed/runner/debug.jd b/src/devices/tech/test_infra/tradefed/runner/debug.jd deleted file mode 100644 index 3d6677f3..00000000 --- a/src/devices/tech/test_infra/tradefed/runner/debug.jd +++ /dev/null @@ -1,24 +0,0 @@ -page.title=Template -@jd:body - -<!-- - Copyright 2013 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> - -<p>Write some stuff</p> - -<h2>Hey, it's a header!</h2> -<p>Write some more stuff</p> - diff --git a/src/devices/tech/test_infra/tradefed/runner/index.jd b/src/devices/tech/test_infra/tradefed/runner/index.jd deleted file mode 100644 index f541ac43..00000000 --- a/src/devices/tech/test_infra/tradefed/runner/index.jd +++ /dev/null @@ -1,228 +0,0 @@ -page.title=Getting Started -@jd:body - -<!-- - Copyright 2010 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<h2 id="using-the-console">Using the console</h2> -<p>Trade Federation is based around an interactive console. You can fire up the console by -downloading TF or building it from source, and then going to the <code>tradefederation/</code> -directory and running</p> -<pre><code>$ ./tradefed.sh -</code></pre> -<p>You should end up at a <code>tf ></code> prompt.</p> -<p>The console is self-documenting. Try entering "help"</p> -<pre><code>tf >help -Enter 'q' or 'exit' to exit. Use '--wait-for-command|-c' to exit only after all commands have executed. -Enter 'kill' to attempt to forcibly exit, by shutting down adb - -Enter 'help all' to see all embedded documentation at once. - -Enter 'help list' for help with 'list' commands -[...] -</code></pre> - -<p>As the help text suggests, the help menus are organized hierarchically</p> -<pre><code>tf >help list -l(?:ist)? help: - i[nvocations] List all invocation threads - d[evices] List all detected or known devices -[...] -</code></pre> - -<p>The majority of commands have a convenient short form, which the help text displays. The -<code>l(?:ist)?</code> is a regular expression. As an example, here are the four equivalent ways to list -invocations: -<ul> -<li><code>list invocations</code></li> -<li><code>list i</code></li> -<li><code>l invocations</code></li> -<li><code>l i</code></li> -</ul> - -<h2 id="running-a-command">Running a command</h2> -<p>This is documented by the <code>help run</code> command in the console.</p> -<p>As a reminder, a <em>command</em> is a config along with all of its command-line arguments. A command <em>must</em> -begin with the name of the respective config.</p> - -<p>As a quick example, you could run the calculator unit tests like so:</p> -<pre><code>$ ./tradefed.sh -tf >run instrument --package com.android.calculator2.tests -</code></pre> - -<p>As a shortcut, if you specify any arguments to the <code>tradefed.sh</code> script, it will attempt to execute them as if -they were typed on the commandline. So a shorter version of the above would be</p> -<pre><code>$./tradefed.sh run instrument --package com.android.calculator2.tests -</code></pre> -<p>In both of these cases, the name of the config is "instrument", and -"--class com.android.calculator2.tests" is a command-line argument. The command that is being run -is "instrument --class com.android.calculator2.tests".</p> -<p>TF can run both configs that are compiled in (such as the "instrument" config above), as well as -configs that exist as xml files on the local filesystem. You can see a list of compiled-in configs -with the <code>list configs</code> console command. Furthermore, you can investigate any config (compiled-in -or local) by passing the "--help" or "--help-all" command-line arguments. The "--help" argument -will only show "important" arguments, and "--help-all" will show all arguments, regardless of -whether they've been marked as "important" or not. To take the final step, you can tell TF to print -the contents of any config (compiled-in or local) with the <code>dump config <configname></code> console -command.</p> - -<h3 id="run-tests-self-help">So, let's say you want to run the calculator instrumentation tests, but don't know where to start.</h3> -<p>You could try something like this sequence of steps. First, look for a config that looks like it -might do what you want:</p> -<pre><code>tf >list configs -Use 'run command <configuration_name> --help' to get list of options for a configuration -Use 'dump config <configuration_name>' to display the configuration's XML content. - -Available configurations include: -[...] - instrument: Runs a single Android instrumentation test on an existing device -[...] -</code></pre> - -<p>Now that you've found something reasonable-looking, see what options it takes. The <code>list configs</code> output suggests trying <code>run command instrument --help</code></p> -<pre><code>tf >run command instrument --help -'instrument' configuration: Runs a single Android instrumentation test on an existing device - -Printing help for only the important options. To see help for all options, use the --help-all flag -[...] - 'instrumentation' test options: - -p, --package The manifest package name of the Android test application to run. -</code></pre> - -<p>As the message suggests, if you need more options, use the "--help-all" flag instead of "--help". In this case, we've got all we need. You could figure out the package by checking with <code>runtest</code>, or reading testdefs.xml directly. We use <code>runtest -n</code> to simply show what would be run without actually running it:</p> -<pre><code>$ runtest -n calculator -adb root -ONE_SHOT_MAKEFILE="packages/apps/Calculator/Android.mk" make -j4 -C "/path/to/tree" all_modules -adb shell am instrument -w com.android.calculator2.tests/android.test.InstrumentationTestRunner -</code></pre> - -<p>The argument to <code>am instrument</code> that comes before the slash is the manifest package. <code>android.test.InstrumentationTestRunner</code> is the default runner, so no need to set it if that's the -right one. Otherwise, using "--help-all" will tell you about the "--runner" argument, which you can -use to specify an alternate runner.</p> - -<p>Ok, finally, we've come up with the following command, which you'll recognize from above.</p> -<pre><code>tf >run instrument --package com.android.calculator2.tests -</code></pre> - -<h2 id="interacting-with-a-device">Interacting with a device</h2> -<h3 id="generic-device-behavior-in-tf">Generic device behavior in TF</h3> -<p>The running version of a command is called an <code>invocation</code>. First and foremost, every invocation -requires a device before it can run. In addition to physical Android devices, TF can run tests with -a mock device (by specifying the "-n" argument for the command), or with an Android emulator instance (by -specifying the "-e" argument").</p> - -<p>The primary console command to figure out what devices are up to is <code>list devices</code>:</p> -<pre><code>$ ./tradefed.sh -06-07 17:03:22 I/: Detected new device 016B756E03018007 -06-07 17:03:22 I/: Detected new device 1700614743c14397 -06-07 17:03:22 I/: Detected new device 3531C342606300EC -tf >l d -Serial State Product Variant Build Battery -016B756E03018007 Available tuna toro MASTER 100 -1700614743c14397 Available stingray stingray MASTER 100 -3531C342606300EC Available herring crespo4g MASTER 92 -</code></pre> -<p>As far as the invocations are concerned, there are three device states: available, unavailable, and -allocated. An <em>Available</em> device is ready to be allocated for an invocation. An <em>Unavailable</em> -device is not ready for allocation, for any of a variety of reasons — TF may have deemed to the -device as unstable, the device may be critically low on storage, or something else may be amiss. -Finally, an <em>Allocated</em> device is a device that is already being used by an invocation.</p> - -<p>When you start TF, all detected physical devices will be checked for responsiveness with a simple -shell command. If the command completes successfully, the device will be listed as Available. If -the command fails, the device state will be shown as Unavailable. Thereafter, a device will typically bounce between the Available and Allocated states as invocation requirements dictate.</p> - -<p>Finally, once invocations are already underway, you can see what's going on with the <code>list -invocations</code> command</p> -<pre><code>tf >run instrument --package com.android.calculator2.tests -06-07 17:18:31 I/TestInvocation: Starting invocation for 'stub' on build '0' on device 1700614743c14397 -[...] -tf >l d -Serial State Product Variant Build Battery -1700614743c14397 Allocated stingray stingray MASTER 100 -3531C342606300EC Available herring crespo4g JRN11 93 -016B756E03018007 Available tuna toro MASTER 100 - -tf >l i -Command Id Exec Time Device State -1 0m:02 1700614743c14397 running stub on build 0 -</code></pre> - -<h3 id="running-invocations-on-specific-devices">Running invocations on specific devices</h3> -<p>TF supports a number of filtering mechanisms for specifying which device or devices to use for a -particular invocation. Since the filtering mechanisms are evaluated before a command turns into an -invocation, you can find all of the filtering options in the help for any config:</p> -<pre><code>tf >run instrument --help-all -[...] - device_requirements options: - -s, --serial run this test on a specific device with given serial number(s). - --exclude-serial run this test on any device except those with this serial number(s). - --product-type run this test on device with this product type(s). May also filter by variant using product:variant. - --property run this test on device with this property value. Expected format <propertyname>=<propertyvalue>. - -e, --[no-]emulator force this test to run on emulator. Default: false. - -d, --[no-]device force this test to run on a physical device, not an emulator. Default: false. - --[no-]new-emulator allocate a placeholder emulator. Should be used when config intends to launch an emulator Default: false. - -n, --[no-]null-device - do not allocate a device for this test. Default: false. - --min-battery only run this test on a device whose battery level is at least the given amount. Scale: 0-100 - --max-battery only run this test on a device whose battery level is strictly less than the given amount. Scale: 0-100 -[...]</code></pre> - -<p>The built-in help will hopefully be pretty self-explanatory. All of the filtering options excluding "-n", -"-e", and "-d" may be specified as many times as needed. So, for instance, to run an invocation -using any Verizon Galaxy Nexus, you could do the following:</p> <!-- FIXME probably use Mako here --> -<pre><code>tf >run instrument --package com.android.calculator2.tests --product-type tuna:toro -</code></pre> -<p>As another example, to run on a GSM device with a SIM, you could do the following:</p> -<pre><code>tf >run instrument --package com.android.calculator2.tests --property gsm.sim.state=READY -</code></pre> -<p>The filtering works by exclusion from the pool of Available devices, so the "--serial" option simply -excludes devices that aren't in the list of required serials, and --exclude-serial excludes devices -that <em>are</em> in its list. As such, an argument like --exclude-serial XXX --serial XXX will simply -make the respective command un-runnable — it will never match any device, since all devices are -excluded.</p> - -<h2 id="logging">Logging</h2> -<p>There are a few different aspects to logging in TF. First and foremost, TF has a built-in logging -infrastructure that's based on DDMLib's Log class. For the common case, where the log tag is just -the classname of the current class, you can use our CLog convenience shim. In short, if you might -have originally done this:</p> -<pre><code>class ClassName { -private static final LOG_TAG = "ClassName"; -[...] -Log.v(LOG_TAG, "This is a simple verbose log message"); -Log.w(LOG_TAG, String.format("This warning message brought to you by the number %d", 17)); -</code></pre> - -<p>You can now accomplish the same thing with the shim like this:</p> -<pre><code>class ClassName { -[...] -CLog.v("This is a simple verbose log message"); -CLog.w("This warning message brought to you by the number %d", 17); -</code></pre> - -<p>Each Invocation has its own ThreadGroup. Any host-side logging that happens inside of that thread -group is associated with the Invocation, and will be reported as that invocation's "host_log" after -the Invocation completes.</p> - -<p>Device logging is performed as part of TF's device wrapper. We keep a buffer of up to 20 MB -that captures log data as the device churns it out. In particular, we are not limited by the size -of the on-device logcat buffer.</p> - -<p>The next important piece is the ITestInvocationListener. This is one of the components of an -Invocation that handles results reporting. Each reporter has the option to implement the <code>#testLog</code> -method, which will be used to pass logfiles to that result reporter. Among the files that are -passed by TF itself will be the aforementioned host_log, as well as the device logcat for the device -associated with the Invocation.</p> |