/*
|
* Copyright (C) The Android Open Source Project
|
*
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
* you may not use this file except in compliance with the License.
|
* You may obtain a copy of the License at
|
*
|
* http://www.apache.org/licenses/LICENSE-2.0
|
*
|
* Unless required by applicable law or agreed to in writing, software
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
* See the License for the specific language governing permissions and
|
* limitations under the License.
|
*/
|
import java.io.BufferedWriter;
|
import java.io.File;
|
import java.io.FileNotFoundException;
|
import java.io.FileOutputStream;
|
import java.io.FileWriter;
|
import java.io.IOException;
|
import java.util.ArrayList;
|
import java.util.Collection;
|
import java.util.Iterator;
|
import java.util.Set;
|
|
import javax.xml.parsers.DocumentBuilderFactory;
|
import javax.xml.parsers.ParserConfigurationException;
|
import javax.xml.transform.Transformer;
|
import javax.xml.transform.TransformerException;
|
import javax.xml.transform.TransformerFactory;
|
import javax.xml.transform.TransformerFactoryConfigurationError;
|
import javax.xml.transform.dom.DOMSource;
|
import javax.xml.transform.stream.StreamResult;
|
|
import org.w3c.dom.Attr;
|
import org.w3c.dom.Document;
|
import org.w3c.dom.Node;
|
import org.w3c.dom.NodeList;
|
|
import vogar.ExpectationStore;
|
import vogar.Expectation;
|
|
import com.sun.javadoc.AnnotationDesc;
|
import com.sun.javadoc.AnnotationTypeDoc;
|
import com.sun.javadoc.AnnotationValue;
|
import com.sun.javadoc.ClassDoc;
|
import com.sun.javadoc.Doclet;
|
import com.sun.javadoc.MethodDoc;
|
import com.sun.javadoc.RootDoc;
|
import com.sun.javadoc.AnnotationDesc.ElementValuePair;
|
|
/**
|
* This is only a very simple and brief JavaDoc parser for the CTS.
|
*
|
* Input: The source files of the test cases. It will be represented
|
* as a list of ClassDoc
|
* Output: Generate file description.xml, which defines the TestPackage
|
* TestSuite and TestCases.
|
*
|
* Note:
|
* 1. Since this class has dependencies on com.sun.javadoc package which
|
* is not implemented on Android. So this class can't be compiled.
|
* 2. The TestSuite can be embedded, which means:
|
* TestPackage := TestSuite*
|
* TestSuite := TestSuite* | TestCase*
|
*/
|
public class DescriptionGenerator extends Doclet {
|
static final String HOST_CONTROLLER = "dalvik.annotation.HostController";
|
static final String KNOWN_FAILURE = "dalvik.annotation.KnownFailure";
|
static final String SUPPRESSED_TEST = "android.test.suitebuilder.annotation.Suppress";
|
static final String CTS_EXPECTATION_DIR = "cts/tests/expectations";
|
|
static final String JUNIT_TEST_CASE_CLASS_NAME = "junit.framework.testcase";
|
static final String TAG_PACKAGE = "TestPackage";
|
static final String TAG_SUITE = "TestSuite";
|
static final String TAG_CASE = "TestCase";
|
static final String TAG_TEST = "Test";
|
static final String TAG_DESCRIPTION = "Description";
|
|
static final String ATTRIBUTE_NAME_VERSION = "version";
|
static final String ATTRIBUTE_VALUE_VERSION = "1.0";
|
static final String ATTRIBUTE_NAME_FRAMEWORK = "AndroidFramework";
|
static final String ATTRIBUTE_VALUE_FRAMEWORK = "Android 1.0";
|
|
static final String ATTRIBUTE_NAME = "name";
|
static final String ATTRIBUTE_ABIS = "abis";
|
static final String ATTRIBUTE_HOST_CONTROLLER = "HostController";
|
static final String ATTRIBUTE_TIMEOUT = "timeout";
|
|
static final String XML_OUTPUT_PATH = "./description.xml";
|
|
static final String OUTPUT_PATH_OPTION = "-o";
|
static final String ARCHITECTURE_OPTION = "-a";
|
|
/**
|
* Start to parse the classes passed in by javadoc, and generate
|
* the xml file needed by CTS packer.
|
*
|
* @param root The root document passed in by javadoc.
|
* @return Whether the document has been processed.
|
*/
|
public static boolean start(RootDoc root) {
|
ClassDoc[] classes = root.classes();
|
if (classes == null) {
|
Log.e("No class found!", null);
|
return true;
|
}
|
|
String outputPath = XML_OUTPUT_PATH;
|
String architecture = null;
|
String[][] options = root.options();
|
for (String[] option : options) {
|
if (option.length == 2) {
|
if (option[0].equals(OUTPUT_PATH_OPTION)) {
|
outputPath = option[1];
|
} else if (option[0].equals(ARCHITECTURE_OPTION)) {
|
architecture = option[1];
|
}
|
}
|
}
|
if (architecture == null || architecture.equals("")) {
|
Log.e("Missing architecture!", null);
|
return false;
|
}
|
|
XMLGenerator xmlGenerator = null;
|
try {
|
xmlGenerator = new XMLGenerator(outputPath);
|
} catch (ParserConfigurationException e) {
|
Log.e("Cant initialize XML Generator!", e);
|
return true;
|
}
|
|
ExpectationStore ctsExpectationStore = null;
|
try {
|
ctsExpectationStore = VogarUtils.provideExpectationStore("./" + CTS_EXPECTATION_DIR);
|
} catch (IOException e) {
|
Log.e("Couldn't load expectation store.", e);
|
return false;
|
}
|
|
for (ClassDoc clazz : classes) {
|
if ((!clazz.isAbstract()) && (isValidJUnitTestCase(clazz))) {
|
xmlGenerator.addTestClass(new TestClass(clazz, ctsExpectationStore, architecture));
|
}
|
}
|
|
try {
|
xmlGenerator.dump();
|
} catch (Exception e) {
|
Log.e("Can't dump to XML file!", e);
|
}
|
|
return true;
|
}
|
|
/**
|
* Return the length of any doclet options we recognize
|
* @param option The option name
|
* @return The number of words this option takes (including the option) or 0 if the option
|
* is not recognized.
|
*/
|
public static int optionLength(String option) {
|
if (option.equals(OUTPUT_PATH_OPTION)) {
|
return 2;
|
}
|
return 0;
|
}
|
|
/**
|
* Check if the class is valid test case inherited from JUnit TestCase.
|
*
|
* @param clazz The class to be checked.
|
* @return If the class is valid test case inherited from JUnit TestCase, return true;
|
* else, return false.
|
*/
|
static boolean isValidJUnitTestCase(ClassDoc clazz) {
|
while((clazz = clazz.superclass()) != null) {
|
if (JUNIT_TEST_CASE_CLASS_NAME.equals(clazz.qualifiedName().toLowerCase())) {
|
return true;
|
}
|
}
|
|
return false;
|
}
|
|
/**
|
* Log utility.
|
*/
|
static class Log {
|
private static boolean TRACE = true;
|
private static BufferedWriter mTraceOutput = null;
|
|
/**
|
* Log the specified message.
|
*
|
* @param msg The message to be logged.
|
*/
|
static void e(String msg, Exception e) {
|
System.out.println(msg);
|
|
if (e != null) {
|
e.printStackTrace();
|
}
|
}
|
|
/**
|
* Add the message to the trace stream.
|
*
|
* @param msg The message to be added to the trace stream.
|
*/
|
public static void t(String msg) {
|
if (TRACE) {
|
try {
|
if ((mTraceOutput != null) && (msg != null)) {
|
mTraceOutput.write(msg + "\n");
|
mTraceOutput.flush();
|
}
|
} catch (IOException e) {
|
e.printStackTrace();
|
}
|
}
|
}
|
|
/**
|
* Initialize the trace stream.
|
*
|
* @param name The class name.
|
*/
|
public static void initTrace(String name) {
|
if (TRACE) {
|
try {
|
if (mTraceOutput == null) {
|
String fileName = "cts_debug_dg_" + name + ".txt";
|
mTraceOutput = new BufferedWriter(new FileWriter(fileName));
|
}
|
} catch (IOException e) {
|
e.printStackTrace();
|
}
|
}
|
}
|
|
/**
|
* Close the trace stream.
|
*/
|
public static void closeTrace() {
|
if (mTraceOutput != null) {
|
try {
|
mTraceOutput.close();
|
mTraceOutput = null;
|
} catch (IOException e) {
|
e.printStackTrace();
|
}
|
}
|
}
|
}
|
|
static class XMLGenerator {
|
String mOutputPath;
|
|
/**
|
* This document is used to represent the description XML file.
|
* It is construct by the classes passed in, which contains the
|
* information of all the test package, test suite and test cases.
|
*/
|
Document mDoc;
|
|
XMLGenerator(String outputPath) throws ParserConfigurationException {
|
mOutputPath = outputPath;
|
|
mDoc = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();
|
|
Node testPackageElem = mDoc.appendChild(mDoc.createElement(TAG_PACKAGE));
|
|
setAttribute(testPackageElem, ATTRIBUTE_NAME_VERSION, ATTRIBUTE_VALUE_VERSION);
|
setAttribute(testPackageElem, ATTRIBUTE_NAME_FRAMEWORK, ATTRIBUTE_VALUE_FRAMEWORK);
|
}
|
|
void addTestClass(TestClass tc) {
|
appendSuiteToElement(mDoc.getDocumentElement(), tc);
|
}
|
|
void dump() throws TransformerFactoryConfigurationError,
|
FileNotFoundException, TransformerException {
|
//rebuildDocument();
|
|
Transformer t = TransformerFactory.newInstance().newTransformer();
|
|
// enable indent in result file
|
t.setOutputProperty("indent", "yes");
|
t.setOutputProperty("{http://xml.apache.org/xslt}indent-amount","4");
|
|
File file = new File(mOutputPath);
|
file.getParentFile().mkdirs();
|
|
t.transform(new DOMSource(mDoc),
|
new StreamResult(new FileOutputStream(file)));
|
}
|
|
/**
|
* Rebuild the document, merging empty suite nodes.
|
*/
|
void rebuildDocument() {
|
// merge empty suite nodes
|
Collection<Node> suiteElems = getUnmutableChildNodes(mDoc.getDocumentElement());
|
Iterator<Node> suiteIterator = suiteElems.iterator();
|
while (suiteIterator.hasNext()) {
|
Node suiteElem = suiteIterator.next();
|
|
mergeEmptySuites(suiteElem);
|
}
|
}
|
|
/**
|
* Merge the test suite which only has one sub-suite. In this case, unify
|
* the name of the two test suites.
|
*
|
* @param suiteElem The suite element of which to be merged.
|
*/
|
void mergeEmptySuites(Node suiteElem) {
|
Collection<Node> suiteChildren = getSuiteChildren(suiteElem);
|
if (suiteChildren.size() > 1) {
|
for (Node suiteChild : suiteChildren) {
|
mergeEmptySuites(suiteChild);
|
}
|
} else if (suiteChildren.size() == 1) {
|
// do merge
|
Node child = suiteChildren.iterator().next();
|
|
// update name
|
String newName = getAttribute(suiteElem, ATTRIBUTE_NAME) + "."
|
+ getAttribute(child, ATTRIBUTE_NAME);
|
setAttribute(child, ATTRIBUTE_NAME, newName);
|
|
// update parent node
|
Node parentNode = suiteElem.getParentNode();
|
parentNode.removeChild(suiteElem);
|
parentNode.appendChild(child);
|
|
mergeEmptySuites(child);
|
}
|
}
|
|
/**
|
* Get the unmuatable child nodes for specified node.
|
*
|
* @param node The specified node.
|
* @return A collection of copied child node.
|
*/
|
private Collection<Node> getUnmutableChildNodes(Node node) {
|
ArrayList<Node> nodes = new ArrayList<Node>();
|
NodeList nodelist = node.getChildNodes();
|
|
for (int i = 0; i < nodelist.getLength(); i++) {
|
nodes.add(nodelist.item(i));
|
}
|
|
return nodes;
|
}
|
|
/**
|
* Append a named test suite to a specified element. Including match with
|
* the existing suite nodes and do the real creation and append.
|
*
|
* @param elem The specified element.
|
* @param testSuite The test suite to be appended.
|
*/
|
void appendSuiteToElement(Node elem, TestClass testSuite) {
|
String suiteName = testSuite.mName;
|
Collection<Node> children = getSuiteChildren(elem);
|
int dotIndex = suiteName.indexOf('.');
|
String name = dotIndex == -1 ? suiteName : suiteName.substring(0, dotIndex);
|
|
boolean foundMatch = false;
|
for (Node child : children) {
|
String childName = child.getAttributes().getNamedItem(ATTRIBUTE_NAME)
|
.getNodeValue();
|
|
if (childName.equals(name)) {
|
foundMatch = true;
|
if (dotIndex == -1) {
|
appendTestCases(child, testSuite.mCases);
|
} else {
|
testSuite.mName = suiteName.substring(dotIndex + 1, suiteName.length());
|
appendSuiteToElement(child, testSuite);
|
}
|
}
|
|
}
|
|
if (!foundMatch) {
|
appendSuiteToElementImpl(elem, testSuite);
|
}
|
}
|
|
/**
|
* Get the test suite child nodes of a specified element.
|
*
|
* @param elem The specified element node.
|
* @return The matched child nodes.
|
*/
|
Collection<Node> getSuiteChildren(Node elem) {
|
ArrayList<Node> suites = new ArrayList<Node>();
|
|
NodeList children = elem.getChildNodes();
|
for (int i = 0; i < children.getLength(); i++) {
|
Node child = children.item(i);
|
|
if (child.getNodeName().equals(DescriptionGenerator.TAG_SUITE)) {
|
suites.add(child);
|
}
|
}
|
|
return suites;
|
}
|
|
/**
|
* Create test case node according to the given method names, and append them
|
* to the test suite element.
|
*
|
* @param elem The test suite element.
|
* @param cases A collection of test cases included by the test suite class.
|
*/
|
void appendTestCases(Node elem, Collection<TestMethod> cases) {
|
if (cases.isEmpty()) {
|
// if no method, remove from parent
|
elem.getParentNode().removeChild(elem);
|
} else {
|
for (TestMethod caze : cases) {
|
if (caze.mIsBroken || caze.mIsSuppressed || caze.mKnownFailure != null) {
|
continue;
|
}
|
Node caseNode = elem.appendChild(mDoc.createElement(TAG_TEST));
|
|
setAttribute(caseNode, ATTRIBUTE_NAME, caze.mName);
|
String abis = caze.mAbis.toString();
|
setAttribute(caseNode, ATTRIBUTE_ABIS, abis.substring(1, abis.length() - 1));
|
if ((caze.mController != null) && (caze.mController.length() != 0)) {
|
setAttribute(caseNode, ATTRIBUTE_HOST_CONTROLLER, caze.mController);
|
}
|
if (caze.mTimeoutInMinutes != 0) {
|
setAttribute(caseNode, ATTRIBUTE_TIMEOUT,
|
Integer.toString(caze.mTimeoutInMinutes));
|
}
|
|
if (caze.mDescription != null && !caze.mDescription.equals("")) {
|
caseNode.appendChild(mDoc.createElement(TAG_DESCRIPTION))
|
.setTextContent(caze.mDescription);
|
}
|
}
|
}
|
}
|
|
/**
|
* Set the attribute of element.
|
*
|
* @param elem The element to be set attribute.
|
* @param name The attribute name.
|
* @param value The attribute value.
|
*/
|
protected void setAttribute(Node elem, String name, String value) {
|
Attr attr = mDoc.createAttribute(name);
|
attr.setNodeValue(value);
|
|
elem.getAttributes().setNamedItem(attr);
|
}
|
|
/**
|
* Get the value of a specified attribute of an element.
|
*
|
* @param elem The element node.
|
* @param name The attribute name.
|
* @return The value of the specified attribute.
|
*/
|
private String getAttribute(Node elem, String name) {
|
return elem.getAttributes().getNamedItem(name).getNodeValue();
|
}
|
|
/**
|
* Do the append, including creating test suite nodes and test case nodes, and
|
* append them to the element.
|
*
|
* @param elem The specified element node.
|
* @param testSuite The test suite to be append.
|
*/
|
void appendSuiteToElementImpl(Node elem, TestClass testSuite) {
|
Node parent = elem;
|
String suiteName = testSuite.mName;
|
|
int dotIndex;
|
while ((dotIndex = suiteName.indexOf('.')) != -1) {
|
String name = suiteName.substring(0, dotIndex);
|
|
Node suiteElem = parent.appendChild(mDoc.createElement(TAG_SUITE));
|
setAttribute(suiteElem, ATTRIBUTE_NAME, name);
|
|
parent = suiteElem;
|
suiteName = suiteName.substring(dotIndex + 1, suiteName.length());
|
}
|
|
Node leafSuiteElem = parent.appendChild(mDoc.createElement(TAG_CASE));
|
setAttribute(leafSuiteElem, ATTRIBUTE_NAME, suiteName);
|
|
appendTestCases(leafSuiteElem, testSuite.mCases);
|
}
|
}
|
|
/**
|
* Represent the test class.
|
*/
|
static class TestClass {
|
String mName;
|
Collection<TestMethod> mCases;
|
|
/**
|
* Construct an test suite object.
|
*
|
* @param name Full name of the test suite, such as "com.google.android.Foo"
|
* @param cases The test cases included in this test suite.
|
*/
|
TestClass(String name, Collection<TestMethod> cases) {
|
mName = name;
|
mCases = cases;
|
}
|
|
/**
|
* Construct a TestClass object using ClassDoc.
|
*
|
* @param clazz The specified ClassDoc.
|
*/
|
TestClass(ClassDoc clazz, ExpectationStore expectationStore, String architecture) {
|
mName = clazz.toString();
|
mCases = getTestMethods(expectationStore, architecture, clazz);
|
}
|
|
/**
|
* Get all the TestMethod from a ClassDoc, including inherited methods.
|
*
|
* @param clazz The specified ClassDoc.
|
* @return A collection of TestMethod.
|
*/
|
Collection<TestMethod> getTestMethods(ExpectationStore expectationStore,
|
String architecture, ClassDoc clazz) {
|
Collection<MethodDoc> methods = getAllMethods(clazz);
|
|
ArrayList<TestMethod> cases = new ArrayList<TestMethod>();
|
Iterator<MethodDoc> iterator = methods.iterator();
|
|
while (iterator.hasNext()) {
|
MethodDoc method = iterator.next();
|
|
String name = method.name();
|
|
AnnotationDesc[] annotations = method.annotations();
|
String controller = "";
|
String knownFailure = null;
|
boolean isBroken = false;
|
boolean isSuppressed = false;
|
for (AnnotationDesc cAnnot : annotations) {
|
|
AnnotationTypeDoc atype = cAnnot.annotationType();
|
if (atype.toString().equals(HOST_CONTROLLER)) {
|
controller = getAnnotationDescription(cAnnot);
|
} else if (atype.toString().equals(KNOWN_FAILURE)) {
|
knownFailure = getAnnotationDescription(cAnnot);
|
} else if (atype.toString().equals(SUPPRESSED_TEST)) {
|
isSuppressed = true;
|
}
|
}
|
|
if (VogarUtils.isVogarKnownFailure(expectationStore, clazz.toString(), name)) {
|
isBroken = true;
|
}
|
|
if (name.startsWith("test")) {
|
Expectation expectation = expectationStore.get(
|
VogarUtils.buildFullTestName(clazz.toString(), name));
|
Set<String> supportedAbis =
|
VogarUtils.extractSupportedAbis(architecture, expectation);
|
int timeoutInMinutes = VogarUtils.timeoutInMinutes(expectation);
|
cases.add(new TestMethod(
|
name, method.commentText(), controller, supportedAbis,
|
knownFailure, isBroken, isSuppressed, timeoutInMinutes));
|
}
|
}
|
|
return cases;
|
}
|
|
/**
|
* Get annotation description.
|
*
|
* @param cAnnot The annotation.
|
*/
|
String getAnnotationDescription(AnnotationDesc cAnnot) {
|
ElementValuePair[] cpairs = cAnnot.elementValues();
|
ElementValuePair evp = cpairs[0];
|
AnnotationValue av = evp.value();
|
String description = av.toString();
|
// FIXME: need to find out the reason why there are leading and trailing "
|
description = description.substring(1, description.length() -1);
|
return description;
|
}
|
|
/**
|
* Get all MethodDoc of a ClassDoc, including inherited methods.
|
*
|
* @param clazz The specified ClassDoc.
|
* @return A collection of MethodDoc.
|
*/
|
Collection<MethodDoc> getAllMethods(ClassDoc clazz) {
|
ArrayList<MethodDoc> methods = new ArrayList<MethodDoc>();
|
|
for (MethodDoc method : clazz.methods()) {
|
methods.add(method);
|
}
|
|
ClassDoc superClass = clazz.superclass();
|
while (superClass != null) {
|
for (MethodDoc method : superClass.methods()) {
|
methods.add(method);
|
}
|
|
superClass = superClass.superclass();
|
}
|
|
return methods;
|
}
|
|
}
|
|
/**
|
* Represent the test method inside the test class.
|
*/
|
static class TestMethod {
|
String mName;
|
String mDescription;
|
String mController;
|
Set<String> mAbis;
|
String mKnownFailure;
|
boolean mIsBroken;
|
boolean mIsSuppressed;
|
int mTimeoutInMinutes; // zero to use default timeout.
|
|
/**
|
* Construct an test case object.
|
*
|
* @param name The name of the test case.
|
* @param description The description of the test case.
|
* @param knownFailure The reason of known failure.
|
*/
|
TestMethod(String name, String description, String controller, Set<String> abis,
|
String knownFailure, boolean isBroken, boolean isSuppressed, int timeoutInMinutes) {
|
if (timeoutInMinutes < 0) {
|
throw new IllegalArgumentException("timeoutInMinutes < 0: " + timeoutInMinutes);
|
}
|
mName = name;
|
mDescription = description;
|
mController = controller;
|
mAbis = abis;
|
mKnownFailure = knownFailure;
|
mIsBroken = isBroken;
|
mIsSuppressed = isSuppressed;
|
mTimeoutInMinutes = timeoutInMinutes;
|
}
|
}
|
}
|
