1 /*
2 * $Id$
3 *
4 * Copyright (c) 1996, 2009, Oracle and/or its affiliates. All rights reserved.
5 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
6 *
7 * This code is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License version 2 only, as
9 * published by the Free Software Foundation. Oracle designates this
10 * particular file as subject to the "Classpath" exception as provided
11 * by Oracle in the LICENSE file that accompanied this code.
12 *
13 * This code is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
15 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16 * version 2 for more details (a copy is included in the LICENSE file that
17 * accompanied this code).
18 *
19 * You should have received a copy of the GNU General Public License version
20 * 2 along with this work; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
22 *
23 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
24 * or visit www.oracle.com if you need additional information or have any
25 * questions.
26 */
27 package com.sun.javatest;
28
29 import java.util.Iterator;
30
31 import com.sun.javatest.util.BackupPolicy;
32
33 /**
34 * TestRunner is the abstract base class providing the ability to
35 * control how tests are run. A default is provided that executes
36 * each test by means of a script class.
37 * <p>If a test suite does not wish tom use the default test runner,
38 * it should provide its own implementation of this class. The primary
39 * method which should be implemented is {@link #runTests}.
40 */
41 public abstract class TestRunner
42 {
43 /**
44 * Set the work directory used to store the test results generated
45 * by this test runner.
46 * @param wd the work directory used to store the test results generated
47 * by this test runner
48 * @see #getWorkDirectory
49 */
50 void setWorkDirectory(WorkDirectory wd) {
51 workDir = wd;
52 }
53
54 /**
55 * Get the work directory to be used to store the test results generated
56 * by this test runner.
57 * @return the work directory used to store the test results generated
58 * by this test runner
59 */
60 public WorkDirectory getWorkDirectory() {
61 return workDir;
62 }
63
64 /**
65 * Get the test suite containing the tests to be run by this test runner.
66 * @return the test suite containing the tests to be run by this test runner
67 */
68 public TestSuite getTestSuite() {
69 return workDir.getTestSuite();
70 }
71
72 /**
73 * Set the backup policy to be used when creating the test result files
74 * generated by this test runner.
75 * @param backupPolicy the backup policy to be used when creating the
76 * test result files generated by this test runner
77 * @see #getBackupPolicy
78 * @see TestResult#writeResults(WorkDirectory, BackupPolicy)
79 */
80 void setBackupPolicy(BackupPolicy backupPolicy) {
81 this.backupPolicy = backupPolicy;
82 }
83
84 /**
85 * Get the backup policy to be used when creating the test result files
86 * generated by this test runner.
87 * @return the backup policy to be used when creating the
88 * test result files generated by this test runner
89 * @see TestResult#writeResults(WorkDirectory, BackupPolicy)
90 */
91 public BackupPolicy getBackupPolicy() {
92 return backupPolicy;
93 }
94
95 /**
96 * Set the test environment to be used to execute the tests that will
97 * be run by this test runner.
98 * @param env the test environment to be used to execute the tests that will
99 * be run by this test runner
100 * @see #getEnvironment
101 */
102 void setEnvironment(TestEnvironment env) {
103 this.env = env;
104 }
105
106 /**
107 * Get the test environment to be used to execute the tests that will
108 * be run by this test runner.
109 * @return the test environment to be used to execute the tests that will
110 * be run by this test runner
111 * @see #getEnvironment
112 */
113 public TestEnvironment getEnvironment() {
114 return env;
115 }
116
117 /**
118 * Set the exclude list to be used to identify the test cases to be
119 * excluded when running tests.
120 * @param excludeList the exclude list to be used to identify the test cases to be
121 * excluded when running tests
122 * @see #getExcludeList
123 * @see #getExcludedTestCases
124 */
125 void setExcludeList(ExcludeList excludeList) {
126 this.excludeList = excludeList;
127 }
128
129 /**
130 * Get the exclude list to be used to identify the test cases to be
131 * excluded when running tests.
132 * @return the exclude list to be used to identify the test cases to be
133 * excluded when running tests
134 * @see #getExcludedTestCases
135 */
136 public ExcludeList getExcludeList() {
137 return excludeList;
138 }
139
140 /**
141 * Get the names of the test cases to be excluded when running a specific test.
142 * @param td the test for which the excluded test cases should be obtained
143 * @return the names of the test cases to be excluded when running a specific test.
144 * The result is null if the test is not found or is
145 * completely excluded without specifying test cases. This may be
146 * a mix of single TC strings or a comma separated list of them.
147 */
148 public String[] getExcludedTestCases(TestDescription td) {
149 return excludeList.getTestCases(td);
150 }
151
152 /**
153 * Set the concurrency to be used when running the tests, if applicable.
154 * @param conc the concurrency to be used when running the tests, if applicable
155 * @see #getConcurrency
156 */
157 void setConcurrency(int conc) {
158 concurrency = conc;
159 }
160
161 /**
162 * Get the concurrency to be used when running the tests, if applicable.
163 * @return the concurrency to be used when running the tests, if applicable
164 * @see #getConcurrency
165 */
166 public int getConcurrency() {
167 return concurrency;
168 }
169
170
171 /**
172 * Set the notifier to be used when running the tests.
173 * @param notifier the notifier to be used when running the tests
174 * @see #notifyStartingTest
175 * @see #notifyFinishedTest
176 */
177 void setNotifier(Harness.Observer notifier) {
178 this.notifier = notifier;
179 }
180
181 /**
182 * Delegate the notifier to be used when running the tests to the Script
183 * @param script the script to be used to execute the test
184 */
185 void delegateNotifier(Script script) {
186 script.setNotifier(this.notifier);
187 }
188
189 /**
190 * Run the tests obtained from an iterator. The iterator returns
191 * TestDescription objects for the tests that have been selected to be run.
192 * The iterator supports the standard hasNext() and next() methods;
193 * it does not support remove(), which throws UnsupportedOperationException.
194 * Each test description gives the details of the test to be run.
195 * As each test is started, the implementation of this method must create
196 * a new TestResult object and call {@link #notifyStartingTest}.
197 * When the test completes (however it completes) the implementation of
198 * this method must call {@link #notifyFinishedTest}.
199 * @param testIter the iterator to be used to obtain the tests to be run
200 * @return true if and only if all the tests executed successfully and passed
201 * @throws InterruptedException if the test run was interrupted
202 */
203 protected abstract boolean runTests(Iterator testIter) throws InterruptedException;
204
205 /**
206 * This method must be called as each test is started, to notify any
207 * registered observers.
208 * @param tr the TestResult object for the test that has been started
209 * @see Harness.Observer
210 */
211 protected void notifyStartingTest(TestResult tr) {
212 notifier.startingTest(tr);
213 }
214
215 /**
216 * This method must be called when each test is finished, to notify any
217 * registered observers.
218 * @param tr the TestResult object for the test that has been started
219 * @see Harness.Observer
220 */
221 protected void notifyFinishedTest(TestResult tr) {
222 // this must do the following:
223 // numTestsDone++;
224 // resultTable.update(result);
225 // notify observers
226 notifier.finishedTest(tr);
227 }
228
229 private WorkDirectory workDir;
230 private BackupPolicy backupPolicy;
231 private TestEnvironment env;
232 private ExcludeList excludeList;
233 private int concurrency;
234 private Harness.Observer notifier;
235 }