JavadocTester.java revision 139:22c4c1143a3a
1/* 2 * Copyright 2002-2004 Sun Microsystems, Inc. All Rights Reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. 8 * 9 * This code is distributed in the hope that it will be useful, but WITHOUT 10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 12 * version 2 for more details (a copy is included in the LICENSE file that 13 * accompanied this code). 14 * 15 * You should have received a copy of the GNU General Public License version 16 * 2 along with this work; if not, write to the Free Software Foundation, 17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 18 * 19 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 20 * CA 95054 USA or visit www.sun.com if you need additional information or 21 * have any questions. 22 */ 23 24import com.sun.javadoc.*; 25import java.util.*; 26import java.io.*; 27 28 29/** 30 * Runs javadoc and then runs regression tests on the resulting output. 31 * This class currently contains three tests: 32 * <ul> 33 * <li> String search: Reads each file, complete with newlines, 34 * into a string. Lets you search for strings that contain 35 * newlines. String matching is case-sensitive. 36 * You can run javadoc multiple times with different arguments, 37 * generating output into different destination directories, and 38 * then perform a different array of tests on each one. 39 * To do this, the run method accepts a test array for testing 40 * that a string is found, and a negated test array for testing 41 * that a string is not found. 42 * <li> Run diffs: Iterate through the list of given file pairs 43 * and diff the pairs. 44 * <li> Check exit code: Check the exit code of Javadoc and 45 * record whether the test passed or failed. 46 * </ul> 47 * 48 * @author Doug Kramer 49 * @author Jamie Ho 50 * @since 1.4.2 51 */ 52public abstract class JavadocTester { 53 54 protected static final String FS = System.getProperty("file.separator"); 55 protected static final String PS = System.getProperty("path.separator"); 56 protected static final String NL = System.getProperty("line.separator"); 57 protected static final String SRC_DIR = System.getProperty("test.src", "."); 58 protected static final String JAVA_VERSION = System.getProperty("java.version"); 59 protected static final String[][] NO_TEST = new String[][] {}; 60 61 /** 62 * Use this as the file name in the test array when you want to search 63 * for a string in the error output. 64 */ 65 public static final String ERROR_OUTPUT = "ERROR_OUTPUT"; 66 67 /** 68 * Use this as the file name in the test array when you want to search 69 * for a string in the notice output. 70 */ 71 public static final String NOTICE_OUTPUT = "NOTICE_OUTPUT"; 72 73 /** 74 * Use this as the file name in the test array when you want to search 75 * for a string in the warning output. 76 */ 77 public static final String WARNING_OUTPUT = "WARNING_OUTPUT"; 78 79 /** 80 * Use this as the file name in the test array when you want to search 81 * for a string in standard output. 82 */ 83 public static final String STANDARD_OUTPUT = "STANDARD_OUTPUT"; 84 85 /** 86 * The default doclet. 87 */ 88 public static final String DEFAULT_DOCLET_CLASS = "com.sun.tools.doclets.formats.html.HtmlDoclet"; 89 public static final String DEFAULT_DOCLET_CLASS_OLD = "com.sun.tools.doclets.standard.Standard"; 90 91 /** 92 * The writer to write error messages. 93 */ 94 public StringWriter errors; 95 96 /** 97 * The writer to write notices. 98 */ 99 public StringWriter notices; 100 101 /** 102 * The writer to write warnings. 103 */ 104 public StringWriter warnings; 105 106 /** 107 * The buffer of warning output.. 108 */ 109 public StringBuffer standardOut; 110 111 /** 112 * The current subtest number. 113 */ 114 private static int numTestsRun = 0; 115 116 /** 117 * The number of subtests passed. 118 */ 119 private static int numTestsPassed = 0; 120 121 /** 122 * The current run of javadoc 123 */ 124 private static int javadocRunNum = 0; 125 126 /** 127 * Construct a JavadocTester. 128 */ 129 public JavadocTester() { 130 } 131 132 /** 133 * Return the bug id. 134 * @return the bug id 135 */ 136 public abstract String getBugId(); 137 138 /** 139 * Return the name of the bug. 140 * @return the name of the bug 141 */ 142 public abstract String getBugName(); 143 144 /** 145 * Execute the tests. 146 * 147 * @param tester the tester to execute 148 * @param args the arguments to pass to Javadoc 149 * @param testArray the array of tests 150 * @param negatedTestArray the array of negated tests 151 * @return the return code for the execution of Javadoc 152 */ 153 public static int run(JavadocTester tester, String[] args, 154 String[][] testArray, String[][] negatedTestArray) { 155 int returnCode = tester.runJavadoc(args); 156 tester.runTestsOnHTML(testArray, negatedTestArray); 157 return returnCode; 158 } 159 160 /** 161 * Execute Javadoc using the default doclet. 162 * 163 * @param args the arguments to pass to Javadoc 164 * @return the return code from the execution of Javadoc 165 */ 166 public int runJavadoc(String[] args) { 167 float javaVersion = Float.parseFloat(JAVA_VERSION.substring(0,3)); 168 String docletClass = javaVersion < 1.5 ? 169 DEFAULT_DOCLET_CLASS_OLD : DEFAULT_DOCLET_CLASS; 170 return runJavadoc(docletClass, args); 171 } 172 173 174 /** 175 * Execute Javadoc. 176 * 177 * @param docletClass the doclet being tested. 178 * @param args the arguments to pass to Javadoc 179 * @return the return code from the execution of Javadoc 180 */ 181 public int runJavadoc(String docletClass, String[] args) { 182 javadocRunNum++; 183 if (javadocRunNum == 1) { 184 System.out.println("\n" + "Running javadoc..."); 185 } else { 186 System.out.println("\n" + "Running javadoc (run " 187 + javadocRunNum + ")..."); 188 } 189 initOutputBuffers(); 190 191 ByteArrayOutputStream stdout = new ByteArrayOutputStream(); 192 PrintStream prev = System.out; 193 System.setOut(new PrintStream(stdout)); 194 int returnCode = com.sun.tools.javadoc.Main.execute( 195 getBugName(), 196 new PrintWriter(errors, true), 197 new PrintWriter(warnings, true), 198 new PrintWriter(notices, true), 199 docletClass, 200 getClass().getClassLoader(), 201 args); 202 System.setOut(prev); 203 standardOut = new StringBuffer(stdout.toString()); 204 printJavadocOutput(); 205 return returnCode; 206 } 207 208 /** 209 * Create new string writer buffers 210 */ 211 private void initOutputBuffers() { 212 errors = new StringWriter(); 213 notices = new StringWriter(); 214 warnings = new StringWriter(); 215 } 216 217 /** 218 * Run array of tests on the resulting HTML. 219 * This method accepts a testArray for testing that a string is found 220 * and a negatedTestArray for testing that a string is not found. 221 * 222 * @param testArray the array of tests 223 * @param negatedTestArray the array of negated tests 224 */ 225 public void runTestsOnHTML(String[][] testArray, String[][] negatedTestArray) { 226 runTestsOnHTML(testArray, false); 227 runTestsOnHTML(negatedTestArray, true); 228 } 229 230 /** 231 * Run the array of tests on the resulting HTML. 232 * 233 * @param testArray the array of tests 234 * @param isNegated true if test is negated; false otherwise 235 */ 236 private void runTestsOnHTML(String[][] testArray , boolean isNegated) { 237 for (int i = 0; i < testArray.length; i++) { 238 239 numTestsRun++; 240 241 System.out.print("Running subtest #" + numTestsRun + "... "); 242 243 // Get string to find 244 String stringToFind = testArray[i][1]; 245 246 // Read contents of file into a string 247 String fileString; 248 try { 249 fileString = readFileToString(testArray[i][0]); 250 } catch (Error e) { 251 if (isNegated) { 252 numTestsPassed += 1; 253 System.out.println("Passed\n not found:\n" 254 + stringToFind + " in non-existent " + testArray[i][0] + "\n"); 255 continue; 256 } 257 throw e; 258 } 259 // Find string in file's contents 260 boolean isFound = findString(fileString, stringToFind); 261 if ((isNegated && !isFound) || (!isNegated && isFound) ) { 262 numTestsPassed += 1; 263 System.out.println( "Passed" + "\n" 264 + (isNegated ? "not found:" : "found:") + "\n" 265 + stringToFind + " in " + testArray[i][0] + "\n"); 266 } else { 267 System.out.println( "FAILED" + "\n" 268 + "for bug " + getBugId() 269 + " (" + getBugName() + ")" + "\n" 270 + "when searching for:" + "\n" 271 + stringToFind 272 + " in " + testArray[i][0] + "\n"); 273 } 274 } 275 } 276 277 /** 278 * Iterate through the list of given file pairs and diff each file. 279 * 280 * @param filePairs the pairs of files to diff. 281 * @throws an Error is thrown if any differences are found between 282 * file pairs. 283 */ 284 public void runDiffs(String[][] filePairs) throws Error { 285 runDiffs(filePairs, true); 286 } 287 288 /** 289 * Iterate through the list of given file pairs and diff each file. 290 * 291 * @param filePairs the pairs of files to diff. 292 * @param throwErrorIFNoMatch flag to indicate whether or not to throw 293 * an error if the files do not match. 294 * 295 * @throws an Error is thrown if any differences are found between 296 * file pairs and throwErrorIFNoMatch is true. 297 */ 298 public void runDiffs(String[][] filePairs, boolean throwErrorIfNoMatch) throws Error { 299 for (int i = 0; i < filePairs.length; i++) { 300 diff(filePairs[i][0], filePairs[i][1], throwErrorIfNoMatch); 301 } 302 } 303 304 /** 305 * Check the exit code of Javadoc and record whether the test passed 306 * or failed. 307 * 308 * @param expectedExitCode The exit code that is required for the test 309 * to pass. 310 * @param actualExitCode The actual exit code from the previous run of 311 * Javadoc. 312 */ 313 public void checkExitCode(int expectedExitCode, int actualExitCode) { 314 numTestsRun++; 315 if (expectedExitCode == actualExitCode) { 316 System.out.println( "Passed" + "\n" + " got return code " + 317 actualExitCode); 318 numTestsPassed++; 319 } else { 320 System.out.println( "FAILED" + "\n" + "for bug " + getBugId() 321 + " (" + getBugName() + ")" + "\n" + "Expected return code " + 322 expectedExitCode + " but got " + actualExitCode); 323 } 324 } 325 326 /** 327 * Print a summary of the test results. 328 */ 329 protected void printSummary() { 330 if ( numTestsRun != 0 && numTestsPassed == numTestsRun ) { 331 // Test passed 332 System.out.println("\n" + "All " + numTestsPassed 333 + " subtests passed"); 334 } else { 335 // Test failed 336 throw new Error("\n" + (numTestsRun - numTestsPassed) 337 + " of " + (numTestsRun) 338 + " subtests failed for bug " + getBugId() 339 + " (" + getBugName() + ")" + "\n"); 340 } 341 } 342 343 /** 344 * Print the output stored in the buffers. 345 */ 346 protected void printJavadocOutput() { 347 System.out.println(STANDARD_OUTPUT + " : \n" + getStandardOutput()); 348 System.err.println(ERROR_OUTPUT + " : \n" + getErrorOutput()); 349 System.err.println(WARNING_OUTPUT + " : \n" + getWarningOutput()); 350 System.out.println(NOTICE_OUTPUT + " : \n" + getNoticeOutput()); 351 } 352 353 /** 354 * Read the file and return it as a string. 355 * 356 * @param fileName the name of the file to read 357 * @return the file in string format 358 */ 359 public String readFileToString(String fileName) throws Error { 360 if (fileName.equals(ERROR_OUTPUT)) { 361 return getErrorOutput(); 362 } else if (fileName.equals(NOTICE_OUTPUT)) { 363 return getNoticeOutput(); 364 } else if (fileName.equals(WARNING_OUTPUT)) { 365 return getWarningOutput(); 366 } else if (fileName.equals(STANDARD_OUTPUT)) { 367 return getStandardOutput(); 368 } 369 try { 370 File file = new File(fileName); 371 if ( !file.exists() ) { 372 System.out.println("\n" + "FILE DOES NOT EXIST: " + fileName); 373 } 374 BufferedReader in = new BufferedReader(new FileReader(file)); 375 376 // Create an array of characters the size of the file 377 char[] allChars = new char[(int)file.length()]; 378 379 // Read the characters into the allChars array 380 in.read(allChars, 0, (int)file.length()); 381 in.close(); 382 383 // Convert to a string 384 String allCharsString = new String(allChars); 385 return allCharsString; 386 } catch (FileNotFoundException e) { 387 System.err.println(e); 388 throw new Error("File not found: " + fileName); 389 } catch (IOException e) { 390 System.err.println(e); 391 throw new Error("Error reading file: " + fileName); 392 } 393 } 394 395 /** 396 * Compare the two given files. 397 * 398 * @param file1 the first file to compare. 399 * @param file2 the second file to compare. 400 * @param throwErrorIFNoMatch flag to indicate whether or not to throw 401 * an error if the files do not match. 402 * @return true if the files are the same and false otherwise. 403 */ 404 public boolean diff(String file1, String file2, boolean throwErrorIFNoMatch) throws Error { 405 String file1Contents = readFileToString(file1); 406 String file2Contents = readFileToString(file2); 407 numTestsRun++; 408 if (file1Contents.trim().compareTo(file2Contents.trim()) == 0) { 409 System.out.println("Diff successful: " + file1 + ", " + file2); 410 numTestsPassed++; 411 return true; 412 } else if (throwErrorIFNoMatch) { 413 throw new Error("Diff failed: " + file1 + ", " + file2); 414 } else { 415 return false; 416 } 417 } 418 419 /** 420 * Search for the string in the given file and return true 421 * if the string was found. 422 * 423 * @param fileString the contents of the file to search through 424 * @param stringToFind the string to search for 425 * @return true if the string was found 426 */ 427 private boolean findString(String fileString, String stringToFind) { 428 return fileString.indexOf(stringToFind) >= 0; 429 } 430 431 /** 432 * Return the standard output. 433 * @return the standard output 434 */ 435 public String getStandardOutput() { 436 return standardOut.toString(); 437 } 438 439 /** 440 * Return the error output. 441 * @return the error output 442 */ 443 public String getErrorOutput() { 444 return errors.getBuffer().toString(); 445 } 446 447 /** 448 * Return the notice output. 449 * @return the notice output 450 */ 451 public String getNoticeOutput() { 452 return notices.getBuffer().toString(); 453 } 454 455 /** 456 * Return the warning output. 457 * @return the warning output 458 */ 459 public String getWarningOutput() { 460 return warnings.getBuffer().toString(); 461 } 462 463 /** 464 * A utility to copy a directory from one place to another. 465 * We may possibly want to move this to our doclet toolkit in 466 * the near future and maintain it from there. 467 * 468 * @param targetDir the directory to copy. 469 * @param destDir the destination to copy the directory to. 470 */ 471 public static void copyDir(String targetDir, String destDir) { 472 if (targetDir.endsWith("SCCS")) { 473 return; 474 } 475 try { 476 File targetDirObj = new File(targetDir); 477 File destDirParentObj = new File(destDir); 478 File destDirObj = new File(destDirParentObj, targetDirObj.getName()); 479 if (! destDirParentObj.exists()) { 480 destDirParentObj.mkdir(); 481 } 482 if (! destDirObj.exists()) { 483 destDirObj.mkdir(); 484 } 485 String[] files = targetDirObj.list(); 486 for (int i = 0; i < files.length; i++) { 487 File srcFile = new File(targetDirObj, files[i]); 488 File destFile = new File(destDirObj, files[i]); 489 if (srcFile.isFile()) { 490 System.out.println("Copying " + srcFile + " to " + destFile); 491 copyFile(destFile, srcFile); 492 } else if(srcFile.isDirectory()) { 493 copyDir(srcFile.getAbsolutePath(), destDirObj.getAbsolutePath()); 494 } 495 } 496 } catch (IOException exc) { 497 throw new Error("Could not copy " + targetDir + " to " + destDir); 498 } 499 } 500 501 /** 502 * Copy source file to destination file. 503 * 504 * @throws SecurityException 505 * @throws IOException 506 */ 507 public static void copyFile(File destfile, File srcfile) 508 throws IOException { 509 byte[] bytearr = new byte[512]; 510 int len = 0; 511 FileInputStream input = new FileInputStream(srcfile); 512 File destDir = destfile.getParentFile(); 513 destDir.mkdirs(); 514 FileOutputStream output = new FileOutputStream(destfile); 515 try { 516 while ((len = input.read(bytearr)) != -1) { 517 output.write(bytearr, 0, len); 518 } 519 } catch (FileNotFoundException exc) { 520 } catch (SecurityException exc) { 521 } finally { 522 input.close(); 523 output.close(); 524 } 525 } 526} 527