本教程指导您创建“hello world” Trade Federation（Tradefed 或 TF）测试配置，并为您提供 TF 框架的实践入门。从开发环境开始，您将创建一个简单的配置并添加功能。
本教程将测试开发过程呈现为一系列练习，每个练习包含若干步骤，演示如何构建和逐步完善您的配置。本教程提供了完成测试配置所需的所有示例代码，并且每个练习的标题都标有字母，描述该步骤中涉及的角色。
- D 代表开发者
- I 代表集成者
- R 代表测试运行者
完成本教程后，您将拥有一个可正常运行的 TF 配置，并理解 TF 框架中的许多重要概念。
设置 Trade Federation
有关设置 TF 开发环境的详细信息，请参阅机器设置。本教程的其余部分假设您已打开一个 shell，该 shell 已初始化为 TF 环境。
为简单起见，本教程演示如何将配置及其类添加到 TF 框架核心库。这可以扩展到在源代码树外部开发模块，方法是先编译 tradefed JAR，然后针对该 JAR 编译您的模块。
创建测试类 (D)
让我们创建一个 hello world 测试，它只是将消息转储到 stdout。Tradefed 测试通常实现 IRemoteTest 接口。以下是 HelloWorldTest 的实现：
package com.android.tradefed.example; import com.android.tradefed.device.DeviceNotAvailableException; import com.android.tradefed.invoker.TestInformation; import com.android.tradefed.log.LogUtil.CLog; import com.android.tradefed.result.ITestInvocationListener; import com.android.tradefed.testtype.IRemoteTest; public class HelloWorldTest implements IRemoteTest { @Override public void run(TestInformation testInfo, ITestInvocationListener listener) throws DeviceNotAvailableException { CLog.i("Hello, TF World!"); } }
将此示例代码保存到 <tree>/tools/tradefederation/core/src/com/android/tradefed/example/HelloWorldTest.java，并从您的 shell 重建 tradefed。
m -jN
请注意，上面的示例中使用了 CLog.i 来将输出定向到控制台。有关 Trade Federation 中日志记录的更多信息，请参阅日志记录 (D, I, R)。
如果构建未成功，请查阅机器设置，确保您没有遗漏任何步骤。
创建配置 (I)
Trade Federation 测试通过创建**配置**（一个 XML 文件）来使其可执行，该文件指示 tradefed 运行哪个测试（或哪些测试），以及执行哪些其他模块以及按什么顺序执行。
让我们为我们的 HelloWorldTest 创建一个新的配置（注意 HelloWorldTest 的完整类名）。
<configuration description="Runs the hello world test">
<test class="com.android.tradefed.example.HelloWorldTest" />
</configuration>将此数据保存到本地文件系统上任意位置的 helloworld.xml 文件（例如 /tmp/helloworld.xml）。TF 将解析配置 XML 文件（也称为**config**），使用反射加载指定的类，实例化它，将其强制转换为 IRemoteTest，并调用其 run 方法。
运行配置 (R)
从您的 shell 启动 tradefed 控制台。
tradefed.sh
确保设备已连接到主机，并且 tradefed 可见。
tf> list devices Serial State Product Variant Build Battery 004ad9880810a548 Available mako mako JDQ39 100
可以使用 run <config> 控制台命令执行配置。尝试
tf> run /tmp/helloworld.xml 05-12 13:19:36 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548 Hello, TF World!
您应该在终端上看到“Hello, TF World!”输出。
您可以使用控制台提示符中的 list invocations 或 l i 确认命令是否已完成运行，它应该不打印任何内容。如果命令当前正在运行，它们将显示如下：
tf >l i
Command Id Exec Time Device State
10 0m:00 [876X00GNG] running stub on build(s) 'BuildInfo{bid=0, target=stub, serial=876X00GNG}'
将配置添加到类路径 (D, I, R)
为了部署方便，您还可以将配置捆绑到 tradefed JAR 本身中。Tradefed 会自动识别类路径中 _config_ 文件夹中的所有配置。
为了说明这一点，将 helloworld.xml 文件移动到 tradefed 核心库（<tree>/tools/tradefederation/core/res/config/example/helloworld.xml）。重建 tradefed，重启 tradefed 控制台，然后要求 tradefed 显示类路径中的配置列表。
tf> list configs […] example/helloworld: Runs the hello world test
现在您可以使用以下命令运行 helloworld 配置：
tf> run example/helloworld 05-12 13:21:21 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548 Hello, TF World!
与设备 (D, R) 交互
到目前为止，我们的 HelloWorldTest 还没有做任何有趣的事情。Tradefed 的专长是使用 Android 设备运行测试，所以让我们在测试中添加一个 Android 设备。
测试可以通过使用 TestInformation 获取对 Android 设备的引用，该引用在调用 IRemoteTest#run 方法时由框架提供。
让我们修改 HelloWorldTest 打印消息以显示设备的序列号
@Override
public void run(TestInformation testInfo, ITestInvocationListener listener) throws DeviceNotAvailableException {
CLog.i("Hello, TF World! I have device " + testInfo.getDevice().getSerialNumber());
}现在重新构建 tradefed 并检查设备列表
tradefed.sh
tf> list devices Serial State Product Variant Build Battery 004ad9880810a548 Available mako mako JDQ39 100
记下标记为可用的序列号；这应该是分配给 HelloWorld 的设备
tf> run example/helloworld 05-12 13:26:18 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548 Hello, TF World! I have device 004ad9880810a548
您应该看到新的打印消息显示设备的序列号。
发送测试结果 (D)
IRemoteTest 通过调用 ITestInvocationListener 实例上的方法来报告结果，该实例提供给 #run 方法。TF 框架本身负责报告每次调用 (Invocation) 的开始（通过 ITestInvocationListener#invocationStarted）和结束（通过 ITestInvocationListener#invocationEnded）。
一个测试运行是测试的逻辑集合。为了报告测试结果，IRemoteTest 负责报告测试运行的开始、每个测试的开始和结束以及测试运行的结束。
以下是 HelloWorldTest 实现可能的样子，其中包含单个失败的测试结果。
@Override
public void run(TestInformation testInfo, ITestInvocationListener listener) throws DeviceNotAvailableException {
CLog.i("Hello, TF World! I have device " + testInfo.getDevice().getSerialNumber());
TestDescription testId = new TestDescription("com.example.TestClassName", "sampleTest");
listener.testRunStarted("helloworldrun", 1);
listener.testStarted(testId);
listener.testFailed(testId, "oh noes, test failed");
listener.testEnded(testId, Collections.emptyMap());
listener.testRunEnded(0, Collections.emptyMap());
}TF 包含多个 IRemoteTest 实现，您可以重用它们，而不是从头开始编写自己的实现。例如，InstrumentationTest 可以在 Android 设备上远程运行 Android 应用程序的测试，解析结果，并将这些结果转发到 ITestInvocationListener）。有关详细信息，请参阅 测试类型。
存储测试结果 (I)
TF 配置的默认测试监听器实现是 TextResultReporter，它将调用的结果转储到 stdout。为了说明这一点，运行上一节中的 HelloWorldTest 配置
./tradefed.sh
tf> run example/helloworld
04-29 18:25:55 I/TestInvocation: Invocation was started with cmd: /tmp/helloworld.xml
04-29 18:25:55 I/TestInvocation: Starting invocation for 'stub' with '[ BuildInfo{bid=0, target=stub, serial=876X00GNG} on device '876X00GNG']
04-29 18:25:55 I/HelloWorldTest: Hello, TF World! I have device 876X00GNG
04-29 18:25:55 I/InvocationToJUnitResultForwarder: Running helloworldrun: 1 tests
04-29 18:25:55 W/InvocationToJUnitResultForwarder:
Test com.example.TestClassName#sampleTest failed with stack:
oh noes, test failed
04-29 18:25:55 I/InvocationToJUnitResultForwarder: Run ended in 0 ms
要将调用的结果存储在其他位置，例如文件中，请使用配置中的 result_reporter 标记指定自定义 ITestInvocationListener 实现。
TF 还包括 XmlResultReporter 监听器，它以类似于 ant JUnit XML writer 使用的格式将测试结果写入 XML 文件。要在配置中指定 result_reporter，请编辑 …/res/config/example/helloworld.xml 配置
<configuration description="Runs the hello world test"> <test class="com.android.tradefed.example.HelloWorldTest" /> <result_reporter class="com.android.tradefed.result.XmlResultReporter" /> </configuration>
现在重新构建 tradefed 并重新运行 hello world 示例
tf> run example/helloworld 05-16 21:07:07 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548 Hello, TF World! I have device 004ad9880810a548 05-16 21:07:07 I/XmlResultReporter: Saved device_logcat log to /tmp/0/inv_2991649128735283633/device_logcat_6999997036887173857.txt 05-16 21:07:07 I/XmlResultReporter: Saved host_log log to /tmp/0/inv_2991649128735283633/host_log_6307746032218561704.txt 05-16 21:07:07 I/XmlResultReporter: XML test result file generated at /tmp/0/inv_2991649128735283633/test_result_536358148261684076.xml. Total tests 1, Failed 1, Error 0
请注意声明已生成 XML 文件的日志消息；生成的文件应如下所示
<?xml version='1.0' encoding='UTF-8' ?>
<testsuite name="stub" tests="1" failures="1" errors="0" time="9" timestamp="2011-05-17T04:07:07" hostname="localhost">
<properties />
<testcase name="sampleTest" classname="com.example.TestClassName" time="0">
<failure>oh noes, test failed
</failure>
</testcase>
</testsuite>您还可以编写自己的自定义调用监听器——它们只需要实现 ITestInvocationListener 接口。
Tradefed 支持多个调用监听器，因此您可以将测试结果发送到多个独立的目的地。为此，只需在您的配置中指定多个 <result_reporter> 标记。
日志记录设施 (D, I, R)
TF 的日志记录设施包括以下功能：
- 从设备捕获日志（又名设备 logcat）
- 记录来自主机机器上运行的 Trade Federation 框架的日志（又名主机日志）
TF 框架自动捕获来自已分配设备的 logcat，并将其发送到调用监听器进行处理。XmlResultReporter 然后将捕获的设备 logcat 保存为文件。
TF 主机日志使用 ddmlib Log 类的 CLog 包装器 报告。让我们将之前的 HelloWorldTest 中的 System.out.println 调用转换为 CLog 调用
@Override
public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
CLog.i("Hello, TF World! I have device %s", getDevice().getSerialNumber());CLog 直接处理字符串插值，类似于 String.format。当您重新构建并重新运行 TF 时，您应该在 stdout 上看到日志消息
tf> run example/helloworld … 05-16 21:30:46 I/HelloWorldTest: Hello, TF World! I have device 004ad9880810a548 …
默认情况下，tradefed 将主机日志消息输出到 stdout。TF 还包括一个将消息写入文件的日志实现：FileLogger。要添加文件日志记录，请将 logger 标记添加到配置中，指定 FileLogger 的完整类名
<configuration description="Runs the hello world test"> <test class="com.android.tradefed.example.HelloWorldTest" /> <result_reporter class="com.android.tradefed.result.XmlResultReporter" /> <logger class="com.android.tradefed.log.FileLogger" /> </configuration>
现在，重新构建并再次运行 helloworld 示例
tf >run example/helloworld … 05-16 21:38:21 I/XmlResultReporter: Saved device_logcat log to /tmp/0/inv_6390011618174565918/device_logcat_1302097394309452308.txt 05-16 21:38:21 I/XmlResultReporter: Saved host_log log to /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt …
日志消息指示主机日志的路径，查看该路径时，应该包含您的 HelloWorldTest 日志消息
more /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt
示例输出
… 05-16 21:38:21 I/HelloWorldTest: Hello, TF World! I have device 004ad9880810a548
处理选项 (D, I, R)
从 TF 配置加载的对象（又名配置对象）也可以通过使用 @Option 注解从命令行参数接收数据。
要参与，配置对象类将 @Option 注解应用于成员字段，并为其提供唯一的名称。这使得可以通过命令行选项填充该成员字段值（并且还会自动将该选项添加到配置帮助系统）。
注意：并非所有字段类型都受支持。有关支持类型的描述，请参阅 OptionSetter。
让我们向 HelloWorldTest 添加一个 @Option
@Option(name="my_option", shortName='m', description="this is the option's help text", // always display this option in the default help text importance=Importance.ALWAYS) private String mMyOption = "thisisthedefault";
接下来，让我们添加一个日志消息以显示 HelloWorldTest 中选项的值，以便我们可以演示它已正确接收
@Override
public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
…
CLog.logAndDisplay(LogLevel.INFO, "I received option '%s'", mMyOption);最后，重新构建 TF 并运行 helloworld；您应该看到带有 my_option 默认值的日志消息
tf> run example/helloworld … 05-24 18:30:05 I/HelloWorldTest: I received option 'thisisthedefault'
从命令行传递值
传入 my_option 的值；您应该看到 my_option 已填充该值
tf> run example/helloworld --my_option foo … 05-24 18:33:44 I/HelloWorldTest: I received option 'foo'
TF 配置还包括一个帮助系统，该系统自动显示 @Option 字段的帮助文本。现在尝试一下，您应该看到 my_option 的帮助文本
tf> run example/helloworld --help
Printing help for only the important options. To see help for all options, use the --help-all flag
cmd_options options:
--[no-]help display the help text for the most important/critical options. Default: false.
--[no-]help-all display the full help text for all options. Default: false.
--[no-]loop keep running continuously. Default: false.
test options:
-m, --my_option this is the option's help text Default: thisisthedefault.
'file' logger options:
--log-level-display the minimum log level to display on stdout. Must be one of verbose, debug, info, warn, error, assert. Default: error.
请注意关于“仅打印重要选项”的消息。为了减少选项帮助混乱，TF 使用 Option#importance 属性来确定在指定 --help 时是否显示特定 @Option 字段帮助文本。--help-all 始终显示所有 @Option 字段的帮助，无论重要性如何。有关详细信息，请参阅 Option.Importance。
从配置传递值
您还可以在配置中通过添加 <option name="" value=""> 元素来指定 Option 值。使用 helloworld.xml 进行测试
<test class="com.android.tradefed.example.HelloWorldTest" >
<option name="my_option" value="fromxml" />
</test>重新构建并运行 helloworld 现在应该产生此输出
05-24 20:38:25 I/HelloWorldTest: I received option 'fromxml'
配置帮助也应该更新以指示 my_option 的默认值
tf> run example/helloworld --help
test options:
-m, --my_option this is the option's help text Default: fromxml.
helloworld 配置中包含的其他配置对象（例如 FileLogger）也接受选项。选项 --log-level-display 很有趣，因为它会过滤显示在 stdout 上的日志。在教程的早期，您可能已经注意到在切换到使用 FileLogger 后，“Hello, TF World! I have device …” 日志消息停止显示在 stdout 上。您可以通过传入 --log-level-display 参数来增加 stdout 日志记录的详细程度。
现在尝试一下，您应该看到 “I have device” 日志消息重新出现在 stdout 上，并记录到文件中
tf> run example/helloworld --log-level-display info … 05-24 18:53:50 I/HelloWorldTest: Hello, TF World! I have device 004ad9880810a548
就这样，各位！
提醒一下，如果您在某些方面遇到困难，Trade Federation 源代码 包含许多有用的信息，这些信息未在文档中公开。如果所有其他方法都失败了，请尝试在 android-platform Google Group 上提问，并在邮件主题中包含 “Trade Federation”。