Adds support for layout tests.

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.
 
 /**
  * Classes and methods for enumerating and preparing tests.
  *
  * This library includes:
  *
  * - Creating tests by listing all the Dart files in certain directories,
@@ skipping 525 matching lines @@
 
       String htmlPath = '$tempDir/test.html';
       if (!isWebTest) {
         // test.dart will import the dart test directly, if it is a library,
         // or indirectly through test_as_library.dart, if it is not.
         Path dartLibraryFilename = filePath;
         if (!isLibraryDefinition) {
           dartLibraryFilename = new Path('test_as_library.dart');
           File file = new File('$tempDir/$dartLibraryFilename');
           RandomAccessFile dartLibrary = file.openSync(FileMode.WRITE);
-          dartLibrary.writeStringSync(WrapDartTestInLibrary(filePath));
+          dartLibrary.writeStringSync(wrapDartTestInLibrary(filePath));
           dartLibrary.closeSync();
         }
 
         File file = new File(dartWrapperFilename);
         RandomAccessFile dartWrapper = file.openSync(FileMode.WRITE);
         dartWrapper.writeStringSync(
-            DartTestWrapper(dartDir, dartLibraryFilename));
+            dartTestWrapper(dartDir, dartLibraryFilename));
         dartWrapper.closeSync();
       } else {
         dartWrapperFilename = filename;
         // 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
         // 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/../$htmlFilename'.length >= 260) {
           htmlFilename = htmlFilename.substring(htmlFilename.length~/2);
         }
         htmlPath = '$tempDir/../$htmlFilename';
       }
       final String scriptPath = (compiler == 'none') ?
           dartWrapperFilename : compiledDartWrapperFilename;
       // Create the HTML file for the test.
       RandomAccessFile htmlTest = new File(htmlPath).openSync(FileMode.WRITE);
       String filePrefix = '';
       if (Platform.operatingSystem == 'windows') {
         // Firefox on Windows does not like absolute file path names that start
         // with 'C:' adding 'file:///' solves the problem.
         filePrefix = 'file:///';
       }
-      htmlTest.writeStringSync(GetHtmlContents(
+      String content = null;
+      Path dir = filePath.directoryPath;
+      String nameNoExt = filePath.filenameWithoutExtension;
+      Path pngPath = dir.append('$nameNoExt.png');
+      Path txtPath = dir.append('$nameNoExt.txt');
+      Path expectedOutput = null;
+      if (new File.fromPath(pngPath).existsSync()) {
+        expectedOutput = pngPath;
+        content = getHtmlLayoutContents(scriptType, '$filePrefix$scriptPath');
+      } else if (new File.fromPath(txtPath).existsSync()) {
+        expectedOutput = txtPath;
+        content = getHtmlLayoutContents(scriptType, '$filePrefix$scriptPath');
+      } else {
+        content = getHtmlContents(
           filename,
           '$filePrefix${dartDir.append("lib/unittest/test_controller.js")}',
           scriptType,
-          '$filePrefix$scriptPath'));
+          '$filePrefix$scriptPath');
+      }
+      htmlTest.writeStringSync(content);
       htmlTest.closeSync();
 
       // Construct the command(s) that compile all the inputs needed by the
       // browser test. For running Dart in DRT, this will be noop commands.
       List<Command> commands = [];
       if (compiler != 'none') {
         commands.add(_compileCommand(
             dartWrapperFilename, compiledDartWrapperFilename,
             compiler, tempDir, vmOptions));
 
@@ skipping 30 matching lines @@
         if (runtime == 'drt' && compiler == 'none') {
           var dartFlags = ['--ignore-unrecognized-flags'];
           if (configuration["checked"]) {
             dartFlags.add('--enable_asserts');
             dartFlags.add("--enable_type_checks");
           }
           dartFlags.addAll(vmOptions);
           args.add('--dart-flags=${Strings.join(dartFlags, " ")}');
         }
         args.add(htmlPath);
+        if (expectedOutput != null) {
+          args.add('--out-expectation=$expectedOutput');
+        }
       }
       commands.add(new Command('python', args));
 
       // Create BrowserTestCase and queue it.
       var testCase = new BrowserTestCase('$suiteName/$testName',
           commands, configuration, completeHandler, expectations,
           optionsFromFile['isNegative']);
       doTest(testCase);
     }
   }
@@ skipping 176 matching lines @@
     Expect.isFalse(vmOptionsList.isEmpty(), "empty vmOptionsList");
     for (var vmOptions in vmOptionsList) {
       var options = new List<String>.from(vmOptions);
       options.addAll(args);
       result.add(options);
     }
 
     return result;
   }
 
+  /**
+   * Special options for individual tests are currently specified in various
+   * ways: with comments directly in test files, by using certain imports, or by
+   * creating additional files in the test directories.
+   *
+   * Here is a list of options that are used by 'test.dart' today:
+   *   - Flags can be passed to the vm or dartium process that runs the test by
+   *   adding a comment to the test file:
+   *
+   *     // VMOptions=--flag1 --flag2
+   *
+   *   - Flags can be passed to the dart script that contains the test also
+   *   using comments, as follows:
+   *
+   *     // DartOptions=--flag1 --flag2
+   *
+   *   - For tests that depend on compiling other files with dart2js (e.g.
+   *   isolate tests that use multiple source scripts), you can specify
+   *   additional files to compile using a comment too, as follows:
+   *
+   *     // OtherScripts=file1.dart file2.dart
+   *
+   *   - You can indicate whether a test is treated as a web-only test by
+   *   using an explicit import to the dart:html library:
+   *
+   *     #import('dart:html');
+   *
+   *   Most tests are not web tests, but can (and will be) wrapped within
+   *   another script file to test them also on browser environments (e.g.
+   *   language and corelib tests are run this way). We deduce that if this
+   *   import is specified, the test was intended to be a web test and no
+   *   wrapping is necessary.
+   *
+   *   - You can convert DRT web-tests into layout-web-tests by specifying a
+   *   test expectation file. An expectation file is located in the same
+   *   location as the test, it has the same file name, except for the extension
+   *   (which can be either .txt or .png).
+   *
+   *   When there are no expectation files, 'test.dart' assumes tests fail if
+   *   the process return a non-zero exit code (in the case of web tests, we
+   *   check for PASS/FAIL indications in the test output).
+   *
+   *   When there is an expectation file, tests are run differently: the test
+   *   code is run to the end of the event loop and 'test.dart' takes a snapshot
+   *   of what is rendered in the page at that moment. This snapshot is
+   *   represented either in text form, if the expectation ends in .txt, or as
+   *   an image, if the expectation ends in .png. 'test.dart' will compare the
+   *   snapshot to the expectation file. When tests fail, 'test.dart' saves the
+   *   new snapshot into a file so it can be visualized or copied over.
+   *   Expectations can be recorded for the first time by creating an empty file
+   *   with the right name (touch test_name_test.png), running the test, and
+   *   executing the copy command printed by the test script.
+   */
   Map readOptionsFromFile(Path filePath) {
     RegExp testOptionsRegExp = const RegExp(@"// VMOptions=(.*)");
     RegExp dartOptionsRegExp = const RegExp(@"// DartOptions=(.*)");
     RegExp otherScriptsRegExp = const RegExp(@"// OtherScripts=(.*)");
     RegExp multiTestRegExp = const RegExp(@"/// [0-9][0-9]:(.*)");
     RegExp staticTypeRegExp =
         const RegExp(@"/// ([0-9][0-9]:){0,1}\s*static type warning");
     RegExp compileTimeRegExp =
         const RegExp(@"/// ([0-9][0-9]:){0,1}\s*compile-time error");
     RegExp staticCleanRegExp = const RegExp(@"// @static-clean");
@@ skipping 481 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);
    }
 }