1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 /* 19 * $Id$ 20 */ 21 22 /* 23 * 24 * Test.java 25 * 26 */ 27 package org.apache.qetest; 28 29 import java.util.Properties; 30 31 /** 32 * Minimal interface defining a test. 33 * Supplying a separate interface from the most common default 34 * implementation makes it simpler for external harnesses or 35 * automation methods to handle lists of Tests. 36 * @author Shane_Curcuru@lotus.com 37 * @version $Id$ 38 */ 39 public interface Test 40 { 41 42 /** 43 * Accesor method for the name of this test. 44 * 45 * NEEDSDOC ($objectName$) @return 46 */ getTestName()47 public abstract String getTestName(); 48 49 /** 50 * Accesor method for a brief description of this test. 51 * 52 * NEEDSDOC ($objectName$) @return 53 */ getTestDescription()54 public abstract String getTestDescription(); 55 56 /** 57 * Accesor methods for our Reporter. 58 * Tests will either have a Logger (for very simple tests) 59 * or a Reporter (for most tests). 60 * <p>Providing both API's in the interface allows us to run 61 * the two styles of tests nearly interchangeably.</p> 62 * @todo document this better; how to harnesses know which to use? 63 * @param r the Reporter to have this test use for logging results 64 */ setReporter(Reporter r)65 public abstract void setReporter(Reporter r); 66 67 /** 68 * Accesor methods for our Reporter. 69 * 70 * NEEDSDOC ($objectName$) @return 71 */ getReporter()72 public abstract Reporter getReporter(); 73 74 /** 75 * Accesor methods for our Logger. 76 * Tests will either have a Logger (for very simple tests) 77 * or a Reporter (for most tests). 78 * <p>Providing both API's in the interface allows us to run 79 * the two styles of tests nearly interchangeably.</p> 80 * @todo document this better; how to harnesses know which to use? 81 * @param l the Logger to have this test use for logging results 82 */ setLogger(Logger l)83 public abstract void setLogger(Logger l); 84 85 /** 86 * Accesor methods for our Logger. 87 * 88 * NEEDSDOC ($objectName$) @return 89 */ getLogger()90 public abstract Logger getLogger(); 91 92 /** 93 * Accesor methods for our abort flag. 94 * If this flag is set during a test run, then we should simply 95 * not bother to run the rest of the test. In all other cases, 96 * harnesses or Tests should attempt to continue running the 97 * entire test including cleanup routines. 98 * @param a true if we should halt processing this test 99 */ setAbortTest(boolean a)100 public abstract void setAbortTest(boolean a); 101 102 /** 103 * Accesor methods for our abort flag. 104 * 105 * NEEDSDOC ($objectName$) @return 106 */ getAbortTest()107 public abstract boolean getAbortTest(); 108 109 /** 110 * Token used to pass command line as initializer. 111 * Commonly tests may be run as applications - this token is 112 * used as the name for the entry in the Properties block 113 * that will contain the array of Strings that was the command 114 * line for the application. 115 * <p>This allows external test harnesses or specific test 116 * implementations to easily pass in their command line using 117 * the Properties argument in many Test methods.</p> 118 */ 119 public static final String MAIN_CMDLINE = "test.CmdLine"; 120 121 /** 122 * Run this test: main interface to cause the test to run itself. 123 * A major goal of the Test class is to separate the act and 124 * process of writing a test from it's actual runtime 125 * implementation. Testwriters should not generally need to 126 * know how their test is being executed. 127 * <ul>They should simply focus on defining: 128 * <li>doTestFileInit: what setup has to be done before running 129 * the testCases: initializing the product under test, etc.</li> 130 * <li>testCase1, 2, ... n: individual, independent test cases</li> 131 * <li>doTestFileClose: what cleanup has to be done after running 132 * the test, like restoring product state or freeing test resources</li> 133 * </ul> 134 * <p>This method returns a simple boolean status as a convenience. 135 * In cases where you have a harness that runs a great many 136 * tests that normally pass, the harness can simply check this 137 * value for each test: if it's true, you could even delete any 138 * result logs then, and simply print out a meta-log stating 139 * that the test passed. Note that this does not provide any 140 * information about why a test failed (or caused an error, or 141 * whatever) - that's what the info in any reports/logs are for.</p> 142 * <p>If a test is aborted, then any containing harness needs not 143 * finish executing the test. Otherwise, even if part of a test fails, 144 * you should let the whole test run through. Note that aborting 145 * a test may result in the reporter or logger output being 146 * incomplete, which may make an invalid report file (in the case 147 * of XMLFileLogger, for example).</p> 148 * @todo Maybe return TestResult instead of boolean flag? 149 * @todo pass in a set of options for the test 150 * @author Shane_Curcuru@lotus.com 151 * @param Properties block used for initialization 152 * 153 * NEEDSDOC @param p 154 * @return status - true if test ran to completion and <b>all</b> 155 * cases passed, false otherwise 156 */ runTest(Properties p)157 public abstract boolean runTest(Properties p); 158 159 /** 160 * Initialize this test - called once before running testcases. 161 * @todo does this need to be in the interface? Shouldn't external 162 * callers simply use the runTest() interface? 163 * @author Shane_Curcuru@lotus.com 164 * @param Properties block used for initialization 165 * 166 * NEEDSDOC @param p 167 * @return true if setup and Reporter creation successful, false otherwise 168 */ testFileInit(Properties p)169 public abstract boolean testFileInit(Properties p); 170 171 /** 172 * Run all of our testcases. 173 * This should cause each testCase in the test to be executed 174 * independently, and then return true if and only if all 175 * testCases passed successfully. If any testCase failed or 176 * caused any unexpected errors, exceptions, etc., it should 177 * return false. 178 * @todo Maybe return TestResult instead of boolean flag? 179 * @todo does this need to be in the interface? Shouldn't external 180 * callers simply use the runTest() interface? 181 * @author Shane_Curcuru@lotus.com 182 * @param Properties block used for initialization 183 * 184 * NEEDSDOC @param p 185 * @return true if all testCases passed, false otherwise 186 */ runTestCases(Properties p)187 public abstract boolean runTestCases(Properties p); 188 189 /** 190 * Cleanup this test - called once after running testcases. 191 * @todo does this need to be in the interface? Shouldn't external 192 * callers simply use the runTest() interface? 193 * @author Shane_Curcuru@lotus.com 194 * @param Properties block used for initialization 195 * 196 * NEEDSDOC @param p 197 * @return true if cleanup successful, false otherwise 198 */ testFileClose(Properties p)199 public abstract boolean testFileClose(Properties p); 200 } // end of class Test 201 202