* Tests are typically written as subtypes of JavadocTester, with a main * method that creates an instance of the test class and calls the runTests() * method. The runTests() methods calls all the test methods declared in the class, * and then calls a method to print a summary, and throw an exception if * any of the test methods reported a failure. * *
* Test methods are identified with a @Test annotation. They have no parameters. * The name of the method is not important, but if you have more than one, it is * recommended that the names be meaningful and suggestive of the test case * contained therein. * *
* Typically, a test method will invoke javadoc, and then perform various * checks on the results. The standard checks are: * *
* public class MyTester extends JavadocTester {
* public static void main(String... args) throws Exception {
* MyTester tester = new MyTester();
* tester.runTests();
* }
*
* // test methods...
* @Test
* void test() {
* javadoc(args);
* checkExit(Exit.OK);
* checkOutput(file, true,
* strings-to-find);
* checkOutput(file, false,
* strings-to-not-find);
* }
* }
* * If javadoc is run more than once in a test method, you can compare the * results that are generated with the diff method. Since files written by * javadoc typically contain a timestamp, you may want to use the -notimestamp * option if you are going to compare the results from two runs of javadoc. * *
* If you have many calls of checkOutput that are very similar, you can write * your own check... method to reduce the amount of duplication. For example, * if you want to check that many files contain the same string, you could * write a method that takes a varargs list of files and calls checkOutput * on each file in turn with the string to be checked. * *
* You can also write you own custom check methods, which can use * readFile to get the contents of a file generated by javadoc, * and then use pass(...) or fail(...) to report whether the check * succeeded or not. * *
* You can have many separate test methods, each identified with a @Test
* annotation. However, you should not assume they will be called
* in the order declared in your source file. If the order of a series
* of javadoc invocations is important, do that within a single method.
* If the invocations are independent, for better clarity, use separate
* test methods, each with their own set of checks on the results.
*
* @author Doug Kramer
* @author Jamie Ho
* @author Jonathan Gibbons (rewrite)
*/
public abstract class JavadocTester {
public static final String FS = System.getProperty("file.separator");
public static final String PS = System.getProperty("path.separator");
public static final String NL = System.getProperty("line.separator");
public enum Output {
/** The name of the output stream from javadoc. */
OUT,
/** The name for any output written to System.out. */
STDOUT,
/** The name for any output written to System.err. */
STDERR
}
/** The output directory used in the most recent call of javadoc. */
protected File outputDir;
/** The exit code of the most recent call of javadoc. */
private int exitCode;
/** The output generated by javadoc to the various writers and streams. */
private final Map
*
* @param args the arguments to pass to javadoc
*/
public void javadoc(String... args) {
outputMap.clear();
fileContentCache.clear();
javadocRunNum++;
if (javadocRunNum == 1) {
out.println("Running javadoc...");
} else {
out.println("Running javadoc (run "
+ javadocRunNum + ")...");
}
outputDir = new File(".");
for (int i = 0; i < args.length - 2; i++) {
if (args[i].equals("-d")) {
outputDir = new File(args[++i]);
break;
}
}
out.println("args: " + Arrays.toString(args));
// log.setOutDir(outputDir);
outputDirectoryCheck.check(outputDir);
// This is the sole stream used by javadoc
WriterOutput outOut = new WriterOutput();
// These are to catch output to System.out and System.err,
// in case these are used instead of the primary streams
StreamOutput sysOut = new StreamOutput(System.out, System::setOut);
StreamOutput sysErr = new StreamOutput(System.err, System::setErr);
try {
exitCode = jdk.javadoc.internal.tool.Main.execute(args, outOut.pw);
} finally {
outputMap.put(Output.STDOUT, sysOut.close());
outputMap.put(Output.STDERR, sysErr.close());
outputMap.put(Output.OUT, outOut.close());
}
outputMap.forEach((name, text) -> {
if (!text.isEmpty()) {
out.println("javadoc " + name + ":");
out.println(text);
}
});
}
/**
* Set the kind of check for the initial contents of the output directory
* before javadoc is run.
* The filter should return true for files that should not appear.
* @param c the kind of check to perform
*/
public void setOutputDirectoryCheck(DirectoryCheck c) {
outputDirectoryCheck = c;
}
public enum Exit {
OK(0),
FAILED(1);
Exit(int code) {
this.code = code;
}
final int code;
}
/**
* Check the exit code of the most recent call of javadoc.
*
* @param expected the exit code that is required for the test
* to pass.
*/
public void checkExit(Exit expected) {
checking("check exit code");
if (exitCode == expected.code) {
passed("return code " + exitCode);
} else {
failed("return code " + exitCode +"; expected " + expected.code + " (" + expected + ")");
}
}
/**
* Check for content in (or not in) the generated output.
* Within the search strings, the newline character \n
* will be translated to the platform newline character sequence.
* @param path a path within the most recent output directory
* or the name of one of the output buffers, identifying
* where to look for the search strings.
* @param expectedFound true if all of the search strings are expected
* to be found, or false if all of the strings are expected to be
* not found
* @param strings the strings to be searched for
*/
public void checkOutput(String path, boolean expectedFound, String... strings) {
// Read contents of file
String fileString;
try {
fileString = readFile(outputDir, path);
} catch (Error e) {
if (!expectedFound) {
failed("Error reading file: " + e);
return;
}
throw e;
}
checkOutput(path, fileString, expectedFound, strings);
}
/**
* Check for content in (or not in) the one of the output streams written by
* javadoc. Within the search strings, the newline character \n
* will be translated to the platform newline character sequence.
* @param output the output stream to check
* @param expectedFound true if all of the search strings are expected
* to be found, or false if all of the strings are expected to be
* not found
* @param strings the strings to be searched for
*/
public void checkOutput(Output output, boolean expectedFound, String... strings) {
checkOutput(output.toString(), outputMap.get(output), expectedFound, strings);
}
private void checkOutput(String path, String fileString, boolean expectedFound, String... strings) {
for (String stringToFind : strings) {
// log.logCheckOutput(path, expectedFound, stringToFind);
checking("checkOutput");
// Find string in file's contents
boolean isFound = findString(fileString, stringToFind);
if (isFound == expectedFound) {
passed(path + ": " + (isFound ? "found:" : "not found:") + "\n"
+ stringToFind + "\n");
} else {
failed(path + ": " + (isFound ? "found:" : "not found:") + "\n"
+ stringToFind + "\n");
}
}
}
/**
* Check for files in (or not in) the generated output.
* @param expectedFound true if all of the files are expected
* to be found, or false if all of the files are expected to be
* not found
* @param paths the files to check, within the most recent output directory.
* */
public void checkFiles(boolean expectedFound, String... paths) {
for (String path: paths) {
// log.logCheckFile(path, expectedFound);
checking("checkFile");
File file = new File(outputDir, path);
boolean isFound = file.exists();
if (isFound == expectedFound) {
passed(path + ": " + (isFound ? "found:" : "not found:") + "\n");
} else {
failed(path + ": " + (isFound ? "found:" : "not found:") + "\n");
}
}
}
/**
* Check that a series of strings are found in order in a file in
* the generated output.
* @param path the file to check
* @param strings the strings whose order to check
*/
public void checkOrder(String path, String... strings) {
String fileString = readOutputFile(path);
int prevIndex = -1;
for (String s : strings) {
s = s.replace("\n", NL); // normalize new lines
int currentIndex = fileString.indexOf(s);
checking(s + " at index " + currentIndex);
if (currentIndex == -1) {
failed(s + " not found.");
continue;
}
if (currentIndex > prevIndex) {
passed(s + " is in the correct order");
} else {
failed("file: " + path + ": " + s + " is in the wrong order.");
}
prevIndex = currentIndex;
}
}
/**
* Ensures that a series of strings appear only once, in the generated output,
* noting that, this test does not exhaustively check for all other possible
* duplicates once one is found.
* @param path the file to check
* @param strings ensure each are unique
*/
public void checkUnique(String path, String... strings) {
String fileString = readOutputFile(path);
for (String s : strings) {
int currentIndex = fileString.indexOf(s);
checking(s + " at index " + currentIndex);
if (currentIndex == -1) {
failed(s + " not found.");
continue;
}
int nextindex = fileString.indexOf(s, currentIndex + s.length());
if (nextindex == -1) {
passed(s + " is unique");
} else {
failed(s + " is not unique, found at " + nextindex);
}
}
}
/**
* Compare a set of files in each of two directories.
*
* @param baseDir1 the directory containing the first set of files
* @param baseDir2 the directory containing the second set of files
* @param files the set of files to be compared
*/
public void diff(String baseDir1, String baseDir2, String... files) {
File bd1 = new File(baseDir1);
File bd2 = new File(baseDir2);
for (String file : files) {
diff(bd1, bd2, file);
}
}
/**
* A utility to copy a directory from one place to another.
*
* @param targetDir the directory to copy.
* @param destDir the destination to copy the directory to.
*/
// TODO: convert to using java.nio.Files.walkFileTree
public void copyDir(String targetDir, String destDir) {
try {
File targetDirObj = new File(targetDir);
File destDirParentObj = new File(destDir);
File destDirObj = new File(destDirParentObj, targetDirObj.getName());
if (! destDirParentObj.exists()) {
destDirParentObj.mkdir();
}
if (! destDirObj.exists()) {
destDirObj.mkdir();
}
String[] files = targetDirObj.list();
for (String file : files) {
File srcFile = new File(targetDirObj, file);
File destFile = new File(destDirObj, file);
if (srcFile.isFile()) {
out.println("Copying " + srcFile + " to " + destFile);
copyFile(destFile, srcFile);
} else if(srcFile.isDirectory()) {
copyDir(srcFile.getAbsolutePath(), destDirObj.getAbsolutePath());
}
}
} catch (IOException exc) {
throw new Error("Could not copy " + targetDir + " to " + destDir);
}
}
/**
* Copy source file to destination file.
*
* @param destfile the destination file
* @param srcfile the source file
* @throws IOException
*/
public void copyFile(File destfile, File srcfile) throws IOException {
Files.copy(srcfile.toPath(), destfile.toPath());
}
/**
* Read a file from the output directory.
*
* @param fileName the name of the file to read
* @return the file in string format
*/
public String readOutputFile(String fileName) throws Error {
return readFile(outputDir, fileName);
}
protected String readFile(String fileName) throws Error {
return readFile(outputDir, fileName);
}
protected String readFile(String baseDir, String fileName) throws Error {
return readFile(new File(baseDir), fileName);
}
/**
* Read the file and return it as a string.
*
* @param baseDir the directory in which to locate the file
* @param fileName the name of the file to read
* @return the file in string format
*/
private String readFile(File baseDir, String fileName) throws Error {
try {
File file = new File(baseDir, fileName);
SoftReference
* javadoc("-d", "out",
* "-sourcepath", testSrc,
* "-notimestamp",
* "pkg1", "pkg2", "pkg3/C.java");
*