Add dartdoc comments to Dart testing infrastructure.

tools/testing/dart/test_suite.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 #library("test_suite");
 
 #import("dart:io");
 #import("status_file_parser.dart");
 #import("test_runner.dart");
 #import("multitest.dart");
 
 #source("browser_test.dart");
 
+/**
+ * Classes and methods for enumerating and preparing tests.
+ *
+ * This library includes:
+ *
+ * - Creating tests by listing all the Dart files in certain directories,
+ *   and creating [TestCase]s for those files that meet the relevant criteria.
+ * - Preparing tests, including copying files and frameworks to temporary
+ *   directories, and computing the command line and arguments to be run.
+ */
+
+/**
+ * A TestSuite represents a collection of tests.  It creates a [TestCase]
+ * object for each test to be run, and passes the test cases to a callback.
+ *
+ * Most TestSuites represent a directory or directory tree containing tests,
+ * and a status file containing the expected results when these tests are run.
+ */
 interface TestSuite {
+  /**
+   * Call the callback function onTest with a [TestCase] argument for each
+   * test in the suite.  When all tests have been processed, call [onDone].
+   *
+   * The [testCache] argument provides a persistent store that can be used to
+   * cache information about the test suite, so that directories do not need
+   * to be listed each time.  If the tests require a temporary directory for
+   * their files, they can get one from [globalTempDir].
+   */
   void forEachTest(Function onTest, Map testCache, String globalTempDir(),
                    [Function onDone]);
 }
 
-
 class CCTestListerIsolate extends Isolate {
   CCTestListerIsolate() : super.heavy();
 
   void main() {
     port.receive((String runnerPath, SendPort replyTo) {
       var p = new Process.start(runnerPath, ["--list"]);
       StringInputStream stdoutStream = new StringInputStream(p.stdout);
       List<String> tests = new List<String>();
       stdoutStream.lineHandler = () {
         String line = stdoutStream.readLine();
@@ skipping 15 matching lines @@
           replyTo.send(test);
         }
         replyTo.send("");
       };
       port.close();
     });
   }
 }
 
 
+/**
+ * A specialized [TestSuite] that runs tests written in C to unit test
+ * the Dart virtual machine and its API.
+ *
+ * The tests are compiled into a monolithic executable by the build step.
+ * The executable lists its tests when run with the --list command line flag.
+ * Individual tests are run by specifying them on the command line.
+ */
 class CCTestSuite implements TestSuite {
   Map configuration;
   final String suiteName;
   String runnerPath;
   final String dartDir;
   List<String> statusFilePaths;
   Function doTest;
   Function doDone;
   ReceivePort receiveTestName;
   TestExpectations testExpectations;
@@ skipping 76 matching lines @@
   Map optionsFromFile;
   bool isNegative;
   bool isNegativeIfChecked;
   bool hasFatalTypeErrors;
 
   TestInformation(this.filename, this.optionsFromFile, this.isNegative,
                   this.isNegativeIfChecked, this.hasFatalTypeErrors);
 }
 
 
+/**
+ * A standard [TestSuite] implementation that searches for tests in a
+ * directory, and creates [TestCase]s that compile and/or run them.
+ */
 class StandardTestSuite implements TestSuite {
   Map configuration;
   String suiteName;
   String directoryPath;
   List<String> statusFilePaths;
   Function doTest;
   Function doDone;
   int activeTestGenerators = 0;
   bool listingDone = false;
   TestExpectations testExpectations;
   List<TestInformation> cachedTests;
   final String dartDir;
   Function globalTemporaryDirectory;
 
   StandardTestSuite(Map this.configuration,
                     String this.suiteName,
                     String this.directoryPath,
                     List<String> this.statusFilePaths)
     : dartDir = TestUtils.dartDir();
 
+  /**
+   * The default implementation assumes a file is a test if
+   * it ends in "Test.dart".
+   */
   bool isTestFile(String filename) => filename.endsWith("Test.dart");
 
   bool listRecursively() => false;
 
   String shellPath() => TestUtils.dartShellFileName(configuration);
 
   List<String> additionalOptions(String filename) => [];
 
   void forEachTest(Function onTest, Map testCache, String globalTempDir(),
                    [Function onDone = null]) {
@@ skipping 37 matching lines @@
   void processDirectory() {
     directoryPath = '$dartDir/$directoryPath';
     Directory dir = new Directory(directoryPath);
     dir.errorHandler = (s) {
       throw s;
     };
     dir.existsHandler = (bool exists) {
       if (!exists) {
         print('Directory containing tests not found: $directoryPath');
         directoryListingDone(false);
-      } else {      
+      } else {
         dir.fileHandler = processFile;
         dir.doneHandler = directoryListingDone;
         dir.list(recursive: listRecursively());
       }
     };
     dir.exists();
   }
 
   void enqueueTestCaseFromTestInformation(TestInformation info) {
     var filename = info.filename;
@@ skipping 14 matching lines @@
       int middle = filename.lastIndexOf('_');
       testName = filename.substring(start + 1, middle) + '/' +
           filename.substring(middle + 1, filename.length - 5);
     } else {
       // This case is hit by the dartc client compilation
       // tests. These tests are pretty broken compared to the
       // rest. They use the .dart suffix in the status files. They
       // find tests in weird ways (testing that they contain "#").
       // They need to be redone.
       // TODO(1058): This does not work on Windows.
-      start = filename.indexOf(directoryPath);      
+      start = filename.indexOf(directoryPath);
       if (start != -1) {
         testName = filename.substring(start + directoryPath.length + 1);
       } else {
         testName = filename;
       }
 
       if (configuration['component'] != 'dartc') {
         if (testName.endsWith('.dart')) {
           testName = testName.substring(0, testName.length - 5);
         }
@@ skipping 73 matching lines @@
       DoMultitest(filename,
                   TestUtils.buildDir(configuration),
                   directoryPath,
                   createTestCase,
                   testGeneratorDone);
     } else {
       createTestCase(filename, optionsFromFile['isNegative']);
     }
   }
 
+  /**
+   * The [StandardTestSuite] has support for testing components that
+   * compile a test from Dart to Javascript, and then run the resulting
+   * Javascript.  This function creates a working directory to hold the
+   * Javascript version of the test, and copies the appropriate framework
+   * files to that directory.  It creates a [BrowserTestCase], which has
+   * two sequential steps to be run by the [ProcessQueue when] the test is
+   * executed: a compilation
+   * step and an execution step, both with the appropriate executable and
+   * arguments.
+   */
   void enqueueBrowserTest(String filename,
                           String testName,
                           Map optionsFromFile,
                           Set<String> expectations,
                           bool isNegative) {
     if (optionsFromFile['isMultitest']) return;
     bool isWebTest = optionsFromFile['containsDomImport'];
     bool isLibraryDefinition = optionsFromFile['isLibraryDefinition'];
     if (!isLibraryDefinition && optionsFromFile['containsSourceOrImport']) {
       print('Warning for $filename: Browser tests require #library ' +
@@ skipping 42 matching lines @@
             domLibraryImport,
             '$dartDir/tests/isolate/src/TestFramework.dart',
             dartLibraryFilename));
         dartWrapper.closeSync();
       } else {
         dartWrapperFilename = testPath;
         // TODO(whesse): Once test.py is retired, adjust the relative path in
         // the client/samples/dartcombat test to its css file, remove the
         // "../../" from this path, and move this out of the isWebTest guard.
         // Also remove getHtmlName, and just use test.html.
-        // TODO(efortuna): this shortening of htmlFilename is a band-aid until 
+        // TODO(efortuna): this shortening of htmlFilename is a band-aid until
         // the above TODO gets fixed. Windows cannot have paths that are longer
         // than 260 characters, and without this hack, we were running past the
         // the limit.
         String htmlFilename = getHtmlName(filename);
         while ('${tempDir.path}/../../$htmlFilename'.length >= 260) {
           htmlFilename = htmlFilename.substring(htmlFilename.length~/2);
         }
         htmlPath = '${tempDir.path}/../../$htmlFilename';
       }
       final String scriptPath = (component == 'dartium') ?
@@ skipping 43 matching lines @@
           // No compilation phase.
           compilerExecutable = null;
           compilerArgs = null;
           break;
         default:
           Expect.fail('unimplemented component $component');
       }
 
       List<String> args;
       if (component == 'webdriver') {
-        args = ['$dartDir/tools/testing/run_selenium.py', '--out=$htmlPath', 
+        args = ['$dartDir/tools/testing/run_selenium.py', '--out=$htmlPath',
             '--browser=${configuration["browser"]}'];
       } else {
         args = [
             '$dartDir/tools/testing/drt-trampoline.py',
             dumpRenderTreeFilename,
             '--no-timeout'
         ];
         if (component == 'dartium') {
           var dartFlags = ['--ignore-unrecognized-flags'];
           if (configuration["checked"]) {
@@ skipping 18 matching lines @@
           optionsFromFile['isNegative']);
       doTest(testCase);
     }
   }
 
   bool get requiresCleanTemporaryDirectory() =>
       configuration['component'] == 'dartc' ||
       configuration['component'] == 'chromium';
 
   /**
-   * Create a directory for the generated test.  Drop the path to the
-   * dart checkout and the final ".dart" from the test path, and replace
-   * all path separators with underscores.
+   * Create a directory for the generated test.  If a Dart language test
+   * needs to be run in a browser, the Dart test needs to be embedded in
+   * an HTML page, with a testing framework based on scripting and DOM events.
+   * These scripts and pages are written to a generated_test directory,
+   * usually inside the build directory of the checkout.
+   *
+   * Some tests, such as those using the dartc compiler, need to be run
+   * with an empty directory as the compiler's work directory.  These
+   * tests are copied to a subdirectory of a system-provided temporary
+   * directory, which is deleted at the end of the test run unless the
+   * --keep-temporary-files flag is given.
+   *
+   * Those tests which are already HTML web applications (web tests), with
+   * resources including CSS files and HTML files, need to be compiled into
+   * a work directory where the relative URLS to the resources work.
+   * We use a subdirectory of the build directory that is the same number
+   * of levels down in the checkout as the original path of the web test.
    */
   Directory createOutputDirectory(String testPath, String optionsName) {
     String testUniqueName =
         testPath.substring(dartDir.length + 1, testPath.length - 5);
     testUniqueName = testUniqueName.replaceAll('/', '_');
     testUniqueName += '-$optionsName';
 
     // Create '[build dir]/generated_tests/$component/$testUniqueName',
       // including any intermediate directories that don't exist.
     String debugMode =
@@ skipping 46 matching lines @@
       case 'frogium':
       case 'webdriver':
         return 'text/javascript';
       default:
         Expect.fail('Unimplemented component scriptType');
         return null;
     }
   }
 
   String getHtmlName(String filename) {
-    return filename.replaceAll('/', '_').replaceAll(':', '_') 
+    return filename.replaceAll('/', '_').replaceAll(':', '_')
         + configuration['component'] + '.html';
   }
 
   String get dumpRenderTreeFilename() {
     if (configuration['drt'] != '') {
       return configuration['drt'];
     }
     if (new Platform().operatingSystem() == 'macos') {
       return '$dartDir/client/tests/drt/DumpRenderTree.app/Contents/' +
           'MacOS/DumpRenderTree';
@@ skipping 155 matching lines @@
       directoryListingDone(true);
     }
   }
 
   String shellPath() => TestUtils.compilerPath(configuration);
 
   List<String> additionalOptions(String filename) {
     filename = new File(filename).fullPathSync().replaceAll('\\', '/');
     Directory tempDir = createOutputDirectory(filename, 'dartc-test');
     return
-        [ '--fatal-warnings', '--fatal-type-errors', 
+        [ '--fatal-warnings', '--fatal-type-errors',
           '-check-only', '-out', tempDir.path];
   }
 
   void processDirectory() {
     directoryPath = '$dartDir/$directoryPath';
     // Enqueueing the directory listers is an activity.
     activityStarted();
     for (String testDir in _testDirs) {
       Directory dir = new Directory("$directoryPath/$testDir");
       if (dir.existsSync()) {
@@ skipping 210 matching lines @@
   static String buildDir(Map configuration) {
     var buildDir = outputDir(configuration);
     buildDir += (configuration['mode'] == 'debug') ? 'Debug_' : 'Release_';
     buildDir += configuration['arch'];
     return buildDir;
   }
 
   static String dartDir() {
     String scriptPath = new Options().script.replaceAll('\\', '/');
     String toolsDir = scriptPath.substring(0, scriptPath.lastIndexOf('/'));
-    return new File('$toolsDir/..').fullPathSync().replaceAll('\\', '/');    
+    return new File('$toolsDir/..').fullPathSync().replaceAll('\\', '/');
   }
 
   static List<String> standardOptions(Map configuration) {
     List args = ["--ignore-unrecognized-flags"];
     if (configuration["checked"]) {
       args.add('--enable_asserts');
       args.add("--enable_type_checks");
     }
     if (configuration["component"] == "leg") {
       args.add("--verbose");
@@ skipping 47 matching lines @@
  * $noCrash tests are expected to be flaky but not crash
  * $pass tests are expected to pass
  * $failOk tests are expected to fail that we won't fix
  * $fail tests are expected to fail that we should fix
  * $crash tests are expected to crash that we should fix
  * $timeout tests are allowed to timeout
 """;
     print(report);
    }
 }