1 <html devsite> 2 <head> 3 <title>Option Handling</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <p>Option handling lies at the heart of Trade Federation's modular approach. In particular, options 27 are the mechanism by which the Developer, Integrator, and Test Runner can work together without 28 having to duplicate each-other's work. Put simply, our implementation of option handling allows the 29 Developer to mark a Java class member as being configurable, at which point the value of that member 30 may be augmented or overridden by the Integrator, and may be subsequently augmented or overridden by 31 the Test Runner. This mechanism works for all Java intrinsic types, as well as for any 32 <code>Map</code>s or <code>Collection</code>s of intrinsic types.</p> 33 34 <p class="note"><strong>Note:</strong> The option-handling mechanism only works for classes implementing one of the 35 interfaces included in the <a href="lifecycle.html">Test Lifecycle</a>, and only when that class is 36 <em>instantiated</em> by the lifecycle machinery.</p> 37 38 <h2 id="developer">Developer</h2> 39 <p>To start off, the developer marks a member with the 40 <code><a href="https://android.googlesource.com/platform/tools/tradefederation/+/master/src/com/android/tradefed/config/Option.java" 41 >@Option</a></code> annotation. <!-- note: javadoc for the Option class is broken --> 42 They specify (at a minimum) the <code>name</code> and <code>description</code> values, which 43 specify the argument name associated with that Option, and the description that will be displayed on 44 the TF console when the command is run with <code>--help</code> or <code>--help-all</code>.</p> 45 46 <p>As an example, let's say we want to build a functional phone test which will dial a variety of 47 phone numbers, and will expect to receive a sequence of DTMF tones from each number after it 48 connects.</p> 49 <pre class="prettyprint"> 50 public class PhoneCallFuncTest extends IRemoteTest { 51 @Option(name = "timeout", description = "How long to wait for connection, in millis") 52 private long mWaitTime = 30 * 1000; // 30 seconds 53 54 @Option(name = "call", description = "Key: Phone number to attempt. " + 55 "Value: DTMF to expect. May be repeated.") 56 private Map<String, String> mCalls = new HashMap<String, String>; 57 58 public PhoneCallFuncTest() { 59 mCalls.add("123-456-7890", "01134"); // default 60 } 61 </pre> 62 63 <p>That's all that's required for the Developer to set up two points of configuration for that 64 test. They could then go off and use <code>mWaitTime</code> and <code>mCalls</code> as normal, 65 without paying much attention to the fact that they're configurable. Because the 66 <code>@Option</code> fields are set after the class is instantiated, but before the 67 <code>run</code> method is called, that provides an easy way for implementors to set up defaults for 68 or perform some kind of filtering on <code>Map</code> and <code>Collection</code> fields, which are 69 otherwise append-only.</p> 70 71 <h2 id="integrator">Integrator</h2> 72 <p>The Integrator works in the world of Configurations, which are written in XML. The config format 73 allows the Integrator to set (or append) a value for any <code>@Option</code> field. For instance, 74 suppose the Integrator wanted to define a lower-latency test that calls the default number, as well 75 as a long-running test that calls a variety of numbers. They could create a pair of configurations 76 that might look like the following:</p> 77 78 <pre class="prettyprint"> 79 <?xml version="1.0" encoding="utf-8"?> 80 <configuration description="low-latency default test; low-latency.xml"> 81 <test class="com.example.PhoneCallFuncTest"> 82 <option name="timeout" value="5000" /> 83 </test> 84 </configuration></pre> 85 86 <pre class="prettyprint"> 87 <?xml version="1.0" encoding="utf-8"?> 88 <configuration description="call a bunch of numbers; many-numbers.xml"> 89 <test class="com.example.PhoneCallFuncTest"> 90 <option name="call" key="111-111-1111" value="#*#*TEST1*#*#" /> 91 <option name="call" key="222-222-2222" value="#*#*TEST2*#*#" /> 92 <!-- ... --> 93 </test> 94 </configuration> 95 </pre> 96 97 <h2 id="testrunner">Test Runner</h2> 98 <p>The Test Runner also has access to these configuration points via the Trade Federation console. 99 First and foremost, they will run a Command (that is, a config and all of its arguments) with the 100 <code>run command <name></code> instruction (or <code>run <name></code> for short). 101 Beyond that, they can specify any list of arguments are part of the command, which may replace or 102 append to fields specified by Lifecycle Objects within each config.</p> 103 104 <p>To run the low-latency test with the <code>many-numbers</code> phone numbers, the Test Runner 105 could execute:</p> 106 <pre class="devsite-click-to-copy"> 107 tf> run low-latency.xml --call 111-111-1111 #*#*TEST1*#*# --call 222-222-2222 #*#*TEST2*#*# 108 </pre> 109 110 <p>Or, to get a similar effect from the opposite direction, the Test Runner could reduce the wait time 111 for the <code>many-numbers</code> test:</p> 112 <pre class="devsite-click-to-copy"> 113 tf> run many-numbers.xml --timeout 5000</pre> 114 115 </body> 116 </html> 117
