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 * Testlet.java 25 * 26 */ 27 package org.apache.qetest; 28 29 /** 30 * Minimal interface defining a testlet, a sort of mini-test. 31 * A Testlet defines a single, simple test case that is completely 32 * independent. Commonly a Testlet will perform a single 33 * test operation and verify it, usually given a set of test 34 * data to perform the operation on. 35 * 36 * <p>This makes creating data-driven tests simpler, by separating 37 * the test algorithim from the definition of the test data. Note 38 * that logging what happened during the test is already separated 39 * out into the Logger interface.</p> 40 * 41 * <p>Testlets are used with Datalets, which provide a single set 42 * of data to execute this test case with. 43 * For example:</p> 44 * <ul> 45 * <li>We define a Testlet that processes an XML file with a 46 * stylesheet in a certain manner - perhaps using a specific 47 * set of SAX calls.</li> 48 * <li>The Testlet takes as an argument a matching Datalet, that 49 * defines any parameters that may change - like the names 50 * of the XML file and the stylesheet file to use.</li> 51 * <li>Test authors or users running a harness or the like can 52 * then easily define a large set of Datalets for various 53 * types of input files that they want to test, and simply 54 * iterate over the set of Datalets, repeatedly calling 55 * Testlet.execute(). Each execution of the Testlet will 56 * be independent.</li> 57 * </ul> 58 * 59 * <p>Testlets may provide additional worker methods that allow them 60 * to be easily run in varying situations; for example, a 61 * testwriter may have a Test object that calls a number of Testlets 62 * for it's test cases. If one of the Testlets finds a bug, the 63 * testwriter can simply reference the single Testlet and it's 64 * current Datalet in the bug report, without having to reference 65 * the enclosing Test file. This makes it easier for others to 66 * reproduce the problem with a minimum of overhead.</p> 67 * 68 * @author Shane_Curcuru@lotus.com 69 * @version $Id$ 70 */ 71 public interface Testlet 72 { 73 74 /** 75 * Accesor method for a brief description of this Testlet. 76 * <p>Testlet implementers should provide a brief, one line 77 * description of the algorithim of their test case.</p> 78 * //@todo do we need to define a setDescription() method? 79 * Since Testlets are pretty self-sufficient, implementers 80 * should always just define this, and not let callers 81 * re-set them. 82 * 83 * @return String describing what this Testlet does. 84 */ getDescription()85 public abstract String getDescription(); 86 87 88 /** 89 * Accesor methods for our Logger. 90 * <p>Testlets use simple Loggers that they rely on the caller 91 * to have setup. This frees the Testlet and the Logger from 92 * having to store any other state about the Testlet. It is 93 * the caller's responsibility to do any overall rolling-up 94 * or aggregating of results reporting, if needed.</p> 95 * 96 * @param l the Logger to have this test use for logging 97 * results; or null to use a default logger 98 */ setLogger(Logger l)99 public abstract void setLogger(Logger l); 100 101 102 /** 103 * Accesor methods for our Logger. 104 * 105 * @return Logger we tell all our secrets to; may be null 106 */ getLogger()107 public abstract Logger getLogger(); 108 109 110 /** 111 * Get a default Logger for use with this Testlet. 112 * <p>Provided to allow subclasses to override this in different 113 * ways. This would probably be called when setLogger(null) 114 * is called. The most common implementation would be to 115 * return a Logger.DEFAULT_LOGGER (which simply 116 * logs things to the console).</p> 117 * 118 * //@todo this sort of functionality should really be provided 119 * by the Logger class itself - any caller should be able to ask 120 * Logger (or a Logger factory, if you want to get fancy) for a 121 * default Logger for use without having to supply any params. 122 * 123 * @return Logger suitable for passing to setLogger() 124 */ getDefaultLogger()125 public abstract Logger getDefaultLogger(); 126 127 128 /** 129 * Return this Testlet's default Datalet. 130 * <p>Every Testlet should have created a default Datalet that can 131 * be used with this test: i.e. the test case itself has a 132 * default, or sample set of data to execute the test with. This 133 * way a user can simply execute the Testlet on the fly without 134 * having to provide any input data.</p> 135 * <p>If the Testlet can't provide a default Datalet, either 136 * the user must provide one somehow, or an error message 137 * should be printed out. Note that the Testlet must still 138 * return a Datalet of the correct class from this method, even 139 * if the Datalet returned has no data set into it. This would 140 * allow a harness with random test data generation capabilities 141 * to discover this Testlet, and then generate random Datalets to 142 * pass to it.</p> 143 * 144 * @return Datalet this Testlet can use as a default test case. 145 */ getDefaultDatalet()146 public abstract Datalet getDefaultDatalet(); 147 148 149 /** 150 * Run this Testlet: execute it's test and return. 151 * <p>The Testlet should perform it's test operation, logging 152 * information as needed to it's Logger, using the provided 153 * Datalet as a test point.</p> 154 * <p>If the Datalet passed is null, the Testlet should use 155 * it's default Datalet as the test point data.</p> 156 * <p>Testlets should not throw exceptions and should not 157 * return anything nor worry about checking their state or 158 * rolling up any overall results to their Logger. Testlets 159 * should simply focus on performing their one test operation 160 * and outputting any simple pass/fail/other results to their 161 * Logger. It is the responsibility of the caller to do any 162 * overall or rolled-up reporting that is desired.</p> 163 * 164 * @author Shane_Curcuru@lotus.com 165 * @param Datalet to use as data points for the test; if null, 166 * will attempt to use getDefaultDatalet() 167 */ execute(Datalet datalet)168 public abstract void execute(Datalet datalet); 169 170 171 } // end of class Testlet 172 173