WebKitTools/Scripts/webkitpy/layout_tests/port/base.py

   1 #!/usr/bin/env python
   2 # Copyright (C) 2010 Google Inc. All rights reserved.
   3 #
   4 # Redistribution and use in source and binary forms, with or without
   5 # modification, are permitted provided that the following conditions are
   6 # met:
   7 #
   8 #     * Redistributions of source code must retain the above copyright
   9 # notice, this list of conditions and the following disclaimer.
  10 #     * Redistributions in binary form must reproduce the above
  11 # copyright notice, this list of conditions and the following disclaimer
  12 # in the documentation and/or other materials provided with the
  13 # distribution.
  14 #     * Neither the Google name nor the names of its
  15 # contributors may be used to endorse or promote products derived from
  16 # this software without specific prior written permission.
  17 #
  18 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29
  30 """Abstract base class of Port-specific entrypoints for the layout tests
  31 test infrastructure (the Port and Driver classes)."""
  32
  33 import cgi
  34 import difflib
  35 import errno
  36 import os
  37 import shlex
  38 import sys
  39 import time
  40
  41 import apache_http_server
  42 import config as port_config
  43 import http_lock
  44 import http_server
  45 import test_files
  46 import websocket_server
  47
  48 from webkitpy.common import system
  49 from webkitpy.common.system import filesystem
  50 from webkitpy.common.system import logutils
  51 from webkitpy.common.system import path
  52 from webkitpy.common.system.executive import Executive, ScriptError
  53 from webkitpy.common.system.user import User
  54
  55
  56 _log = logutils.get_logger(__file__)
  57
  58
  59 class DummyOptions(object):
  60     """Fake implementation of optparse.Values. Cloned from
  61     webkitpy.tool.mocktool.MockOptions.
  62
  63     """
  64
  65     def __init__(self, **kwargs):
  66         # The caller can set option values using keyword arguments. We don't
  67         # set any values by default because we don't know how this
  68         # object will be used. Generally speaking unit tests should
  69         # subclass this or provider wrapper functions that set a common
  70         # set of options.
  71         for key, value in kwargs.items():
  72             self.__dict__[key] = value
  73
  74
  75 # FIXME: This class should merge with webkitpy.webkit_port at some point.
  76 class Port(object):
  77     """Abstract class for Port-specific hooks for the layout_test package."""
  78
  79     def __init__(self, port_name=None, options=None,
  80                  executive=None,
  81                  user=None,
  82                  filesystem=None,
  83                  config=None,
  84                  **kwargs):
  85         self._name = port_name
  86         self._options = options
  87         if self._options is None:
  88             # FIXME: Ideally we'd have a package-wide way to get a
  89             # well-formed options object that had all of the necessary
  90             # options defined on it.
  91             self._options = DummyOptions()
  92         self._executive = executive or Executive()
  93         self._user = user or User()
  94         self._filesystem = filesystem or system.filesystem.FileSystem()
  95         self._config = config or port_config.Config(self._executive,
  96                                                     self._filesystem)
  97         self._helper = None
  98         self._http_server = None
  99         self._webkit_base_dir = None
 100         self._websocket_server = None
 101         self._http_lock = None
 102
 103         # Python's Popen has a bug that causes any pipes opened to a
 104         # process that can't be executed to be leaked.  Since this
 105         # code is specifically designed to tolerate exec failures
 106         # to gracefully handle cases where wdiff is not installed,
 107         # the bug results in a massive file descriptor leak. As a
 108         # workaround, if an exec failure is ever experienced for
 109         # wdiff, assume it's not available.  This will leak one
 110         # file descriptor but that's better than leaking each time
 111         # wdiff would be run.
 112         #
 113         # http://mail.python.org/pipermail/python-list/
 114         #    2008-August/505753.html
 115         # http://bugs.python.org/issue3210
 116         self._wdiff_available = True
 117
 118         self._pretty_patch_path = self.path_from_webkit_base("BugsSite",
 119             "PrettyPatch", "prettify.rb")
 120         self._pretty_patch_available = True
 121         self.set_option_default('configuration', None)
 122         if self._options.configuration is None:
 123             self._options.configuration = self.default_configuration()
 124
 125     def default_child_processes(self):
 126         """Return the number of DumpRenderTree instances to use for this
 127         port."""
 128         return self._executive.cpu_count()
 129
 130     def default_worker_model(self):
 131         """Return the concurrency model the port should use."""
 132         return 'threads'
 133
 134     def baseline_path(self):
 135         """Return the absolute path to the directory to store new baselines
 136         in for this port."""
 137         raise NotImplementedError('Port.baseline_path')
 138
 139     def baseline_search_path(self):
 140         """Return a list of absolute paths to directories to search under for
 141         baselines. The directories are searched in order."""
 142         raise NotImplementedError('Port.baseline_search_path')
 143
 144     def check_build(self, needs_http):
 145         """This routine is used to ensure that the build is up to date
 146         and all the needed binaries are present."""
 147         raise NotImplementedError('Port.check_build')
 148
 149     def check_sys_deps(self, needs_http):
 150         """If the port needs to do some runtime checks to ensure that the
 151         tests can be run successfully, it should override this routine.
 152         This step can be skipped with --nocheck-sys-deps.
 153
 154         Returns whether the system is properly configured."""
 155         return True
 156
 157     def check_image_diff(self, override_step=None, logging=True):
 158         """This routine is used to check whether image_diff binary exists."""
 159         raise NotImplementedError('Port.check_image_diff')
 160
 161     def check_pretty_patch(self):
 162         """Checks whether we can use the PrettyPatch ruby script."""
 163
 164         # check if Ruby is installed
 165         try:
 166             result = self._executive.run_command(['ruby', '--version'])
 167         except OSError, e:
 168             if e.errno in [errno.ENOENT, errno.EACCES, errno.ECHILD]:
 169                 _log.error("Ruby is not installed; "
 170                            "can't generate pretty patches.")
 171                 _log.error('')
 172                 return False
 173
 174         if not self.path_exists(self._pretty_patch_path):
 175             _log.error('Unable to find %s .' % self._pretty_patch_path)
 176             _log.error("Can't generate pretty patches.")
 177             _log.error('')
 178             return False
 179
 180         return True
 181
 182     def compare_text(self, expected_text, actual_text):
 183         """Return whether or not the two strings are *not* equal. This
 184         routine is used to diff text output.
 185
 186         While this is a generic routine, we include it in the Port
 187         interface so that it can be overriden for testing purposes."""
 188         return expected_text != actual_text
 189
 190     def diff_image(self, expected_contents, actual_contents,
 191                    diff_filename=None, tolerance=0):
 192         """Compare two images and produce a delta image file.
 193
 194         Return True if the two images are different, False if they are the same.
 195         Also produce a delta image of the two images and write that into
 196         |diff_filename| if it is not None.
 197
 198         |tolerance| should be a percentage value (0.0 - 100.0).
 199         If it is omitted, the port default tolerance value is used.
 200
 201         """
 202         raise NotImplementedError('Port.diff_image')
 203
 204
 205     def diff_text(self, expected_text, actual_text,
 206                   expected_filename, actual_filename):
 207         """Returns a string containing the diff of the two text strings
 208         in 'unified diff' format.
 209
 210         While this is a generic routine, we include it in the Port
 211         interface so that it can be overriden for testing purposes."""
 212
 213         # The filenames show up in the diff output, make sure they're
 214         # raw bytes and not unicode, so that they don't trigger join()
 215         # trying to decode the input.
 216         def to_raw_bytes(str):
 217             if isinstance(str, unicode):
 218                 return str.encode('utf-8')
 219             return str
 220         expected_filename = to_raw_bytes(expected_filename)
 221         actual_filename = to_raw_bytes(actual_filename)
 222         diff = difflib.unified_diff(expected_text.splitlines(True),
 223                                     actual_text.splitlines(True),
 224                                     expected_filename,
 225                                     actual_filename)
 226         return ''.join(diff)
 227
 228     def driver_name(self):
 229         """Returns the name of the actual binary that is performing the test,
 230         so that it can be referred to in log messages. In most cases this
 231         will be DumpRenderTree, but if a port uses a binary with a different
 232         name, it can be overridden here."""
 233         return "DumpRenderTree"
 234
 235     def expected_baselines(self, filename, suffix, all_baselines=False):
 236         """Given a test name, finds where the baseline results are located.
 237
 238         Args:
 239         filename: absolute filename to test file
 240         suffix: file suffix of the expected results, including dot; e.g.
 241             '.txt' or '.png'.  This should not be None, but may be an empty
 242             string.
 243         all_baselines: If True, return an ordered list of all baseline paths
 244             for the given platform. If False, return only the first one.
 245         Returns
 246         a list of ( platform_dir, results_filename ), where
 247             platform_dir - abs path to the top of the results tree (or test
 248                 tree)
 249             results_filename - relative path from top of tree to the results
 250                 file
 251             (os.path.join of the two gives you the full path to the file,
 252                 unless None was returned.)
 253         Return values will be in the format appropriate for the current
 254         platform (e.g., "\\" for path separators on Windows). If the results
 255         file is not found, then None will be returned for the directory,
 256         but the expected relative pathname will still be returned.
 257
 258         This routine is generic but lives here since it is used in
 259         conjunction with the other baseline and filename routines that are
 260         platform specific.
 261         """
 262         testname = os.path.splitext(self.relative_test_filename(filename))[0]
 263
 264         baseline_filename = testname + '-expected' + suffix
 265
 266         baseline_search_path = self.baseline_search_path()
 267
 268         baselines = []
 269         for platform_dir in baseline_search_path:
 270             if self.path_exists(self._filesystem.join(platform_dir,
 271                                                       baseline_filename)):
 272                 baselines.append((platform_dir, baseline_filename))
 273
 274             if not all_baselines and baselines:
 275                 return baselines
 276
 277         # If it wasn't found in a platform directory, return the expected
 278         # result in the test directory, even if no such file actually exists.
 279         platform_dir = self.layout_tests_dir()
 280         if self.path_exists(self._filesystem.join(platform_dir,
 281                                                   baseline_filename)):
 282             baselines.append((platform_dir, baseline_filename))
 283
 284         if baselines:
 285             return baselines
 286
 287         return [(None, baseline_filename)]
 288
 289     def expected_filename(self, filename, suffix):
 290         """Given a test name, returns an absolute path to its expected results.
 291
 292         If no expected results are found in any of the searched directories,
 293         the directory in which the test itself is located will be returned.
 294         The return value is in the format appropriate for the platform
 295         (e.g., "\\" for path separators on windows).
 296
 297         Args:
 298         filename: absolute filename to test file
 299         suffix: file suffix of the expected results, including dot; e.g. '.txt'
 300             or '.png'.  This should not be None, but may be an empty string.
 301         platform: the most-specific directory name to use to build the
 302             search list of directories, e.g., 'chromium-win', or
 303             'chromium-mac-leopard' (we follow the WebKit format)
 304
 305         This routine is generic but is implemented here to live alongside
 306         the other baseline and filename manipulation routines.
 307         """
 308         platform_dir, baseline_filename = self.expected_baselines(
 309             filename, suffix)[0]
 310         if platform_dir:
 311             return self._filesystem.join(platform_dir, baseline_filename)
 312         return self._filesystem.join(self.layout_tests_dir(), baseline_filename)
 313
 314     def expected_checksum(self, test):
 315         """Returns the checksum of the image we expect the test to produce, or None if it is a text-only test."""
 316         path = self.expected_filename(test, '.checksum')
 317         if not self.path_exists(path):
 318             return None
 319         return self._filesystem.read_text_file(path)
 320
 321     def expected_image(self, test):
 322         """Returns the image we expect the test to produce."""
 323         path = self.expected_filename(test, '.png')
 324         if not self.path_exists(path):
 325             return None
 326         return self._filesystem.read_binary_file(path)
 327
 328     def expected_text(self, test):
 329         """Returns the text output we expect the test to produce."""
 330         # FIXME: DRT output is actually utf-8, but since we don't decode the
 331         # output from DRT (instead treating it as a binary string), we read the
 332         # baselines as a binary string, too.
 333         path = self.expected_filename(test, '.txt')
 334         if not self.path_exists(path):
 335             return ''
 336         text = self._filesystem.read_binary_file(path)
 337         return text.strip("\r\n").replace("\r\n", "\n") + "\n"
 338
 339     def filename_to_uri(self, filename):
 340         """Convert a test file (which is an absolute path) to a URI."""
 341         LAYOUTTEST_HTTP_DIR = "http/tests/"
 342         LAYOUTTEST_WEBSOCKET_DIR = "http/tests/websocket/tests/"
 343
 344         relative_path = self.relative_test_filename(filename)
 345         port = None
 346         use_ssl = False
 347
 348         if (relative_path.startswith(LAYOUTTEST_WEBSOCKET_DIR)
 349             or relative_path.startswith(LAYOUTTEST_HTTP_DIR)):
 350             relative_path = relative_path[len(LAYOUTTEST_HTTP_DIR):]
 351             port = 8000
 352
 353         # Make http/tests/local run as local files. This is to mimic the
 354         # logic in run-webkit-tests.
 355         #
 356         # TODO(dpranke): remove the media reference and the SSL reference?
 357         if (port and not relative_path.startswith("local/") and
 358             not relative_path.startswith("media/")):
 359             if relative_path.startswith("ssl/"):
 360                 port += 443
 361                 protocol = "https"
 362             else:
 363                 protocol = "http"
 364             return "%s://127.0.0.1:%u/%s" % (protocol, port, relative_path)
 365
 366         return path.abspath_to_uri(os.path.abspath(filename))
 367
 368     def tests(self, paths):
 369         """Return the list of tests found (relative to layout_tests_dir()."""
 370         return test_files.find(self, paths)
 371
 372     def test_dirs(self):
 373         """Returns the list of top-level test directories.
 374
 375         Used by --clobber-old-results."""
 376         layout_tests_dir = self.layout_tests_dir()
 377         return filter(lambda x: self._filesystem.isdir(self._filesystem.join(layout_tests_dir, x)),
 378                       self._filesystem.listdir(layout_tests_dir))
 379
 380     def path_isdir(self, path):
 381         """Return True if the path refers to a directory of tests."""
 382         # Used by test_expectations.py to apply rules to whole directories.
 383         return self._filesystem.isdir(path)
 384
 385     def path_exists(self, path):
 386         """Return True if the path refers to an existing test or baseline."""
 387         # Used by test_expectations.py to determine if an entry refers to a
 388         # valid test and by printing.py to determine if baselines exist.
 389         return self._filesystem.exists(path)
 390
 391     def driver_cmd_line(self):
 392         """Prints the DRT command line that will be used."""
 393         driver = self.create_driver(0)
 394         return driver.cmd_line()
 395
 396     def update_baseline(self, path, data, encoding):
 397         """Updates the baseline for a test.
 398
 399         Args:
 400             path: the actual path to use for baseline, not the path to
 401               the test. This function is used to update either generic or
 402               platform-specific baselines, but we can't infer which here.
 403             data: contents of the baseline.
 404             encoding: file encoding to use for the baseline.
 405         """
 406         # FIXME: remove the encoding parameter in favor of text/binary
 407         # functions.
 408         if encoding is None:
 409             self._filesystem.write_binary_file(path, data)
 410         else:
 411             self._filesystem.write_text_file(path, data)
 412
 413     def uri_to_test_name(self, uri):
 414         """Return the base layout test name for a given URI.
 415
 416         This returns the test name for a given URI, e.g., if you passed in
 417         "file:///src/LayoutTests/fast/html/keygen.html" it would return
 418         "fast/html/keygen.html".
 419
 420         """
 421         test = uri
 422         if uri.startswith("file:///"):
 423             prefix = path.abspath_to_uri(self.layout_tests_dir()) + "/"
 424             return test[len(prefix):]
 425
 426         if uri.startswith("http://127.0.0.1:8880/"):
 427             # websocket tests
 428             return test.replace('http://127.0.0.1:8880/', '')
 429
 430         if uri.startswith("http://"):
 431             # regular HTTP test
 432             return test.replace('http://127.0.0.1:8000/', 'http/tests/')
 433
 434         if uri.startswith("https://"):
 435             return test.replace('https://127.0.0.1:8443/', 'http/tests/')
 436
 437         raise NotImplementedError('unknown url type: %s' % uri)
 438
 439     def layout_tests_dir(self):
 440         """Return the absolute path to the top of the LayoutTests directory."""
 441         return self.path_from_webkit_base('LayoutTests')
 442
 443     def skips_layout_test(self, test_name):
 444         """Figures out if the givent test is being skipped or not.
 445
 446         Test categories are handled as well."""
 447         for test_or_category in self.skipped_layout_tests():
 448             if test_or_category == test_name:
 449                 return True
 450             category = self._filesystem.join(self.layout_tests_dir(),
 451                                              test_or_category)
 452             if (self._filesystem.isdir(category) and
 453                 test_name.startswith(test_or_category)):
 454                 return True
 455         return False
 456
 457     def maybe_make_directory(self, *path):
 458         """Creates the specified directory if it doesn't already exist."""
 459         self._filesystem.maybe_make_directory(*path)
 460
 461     def name(self):
 462         """Return the name of the port (e.g., 'mac', 'chromium-win-xp').
 463
 464         Note that this is different from the test_platform_name(), which
 465         may be different (e.g., 'win-xp' instead of 'chromium-win-xp'."""
 466         return self._name
 467
 468     def get_option(self, name, default_value=None):
 469         # FIXME: Eventually we should not have to do a test for
 470         # hasattr(), and we should be able to just do
 471         # self.options.value. See additional FIXME in the constructor.
 472         if hasattr(self._options, name):
 473             return getattr(self._options, name)
 474         return default_value
 475
 476     def set_option_default(self, name, default_value):
 477         if not hasattr(self._options, name):
 478             return setattr(self._options, name, default_value)
 479
 480     def path_from_webkit_base(self, *comps):
 481         """Returns the full path to path made by joining the top of the
 482         WebKit source tree and the list of path components in |*comps|."""
 483         return self._config.path_from_webkit_base(*comps)
 484
 485     def script_path(self, script_name):
 486         return self._config.script_path(script_name)
 487
 488     def path_to_test_expectations_file(self):
 489         """Update the test expectations to the passed-in string.
 490
 491         This is used by the rebaselining tool. Raises NotImplementedError
 492         if the port does not use expectations files."""
 493         raise NotImplementedError('Port.path_to_test_expectations_file')
 494
 495     def relative_test_filename(self, filename):
 496         """Relative unix-style path for a filename under the LayoutTests
 497         directory. Filenames outside the LayoutTests directory should raise
 498         an error."""
 499         assert filename.startswith(self.layout_tests_dir()), "%s did not start with %s" % (filename, self.layout_tests_dir())
 500         return filename[len(self.layout_tests_dir()) + 1:]
 501
 502     def results_directory(self):
 503         """Absolute path to the place to store the test results."""
 504         raise NotImplementedError('Port.results_directory')
 505
 506     def setup_test_run(self):
 507         """Perform port-specific work at the beginning of a test run."""
 508         pass
 509
 510     def setup_environ_for_server(self):
 511         """Perform port-specific work at the beginning of a server launch.
 512
 513         Returns:
 514            Operating-system's environment.
 515         """
 516         return os.environ.copy()
 517
 518     def show_results_html_file(self, results_filename):
 519         """This routine should display the HTML file pointed at by
 520         results_filename in a users' browser."""
 521         return self._user.open_url(results_filename)
 522
 523     def create_driver(self, worker_number):
 524         """Return a newly created base.Driver subclass for starting/stopping
 525         the test driver."""
 526         raise NotImplementedError('Port.create_driver')
 527
 528     def start_helper(self):
 529         """If a port needs to reconfigure graphics settings or do other
 530         things to ensure a known test configuration, it should override this
 531         method."""
 532         pass
 533
 534     def start_http_server(self):
 535         """Start a web server if it is available. Do nothing if
 536         it isn't. This routine is allowed to (and may) fail if a server
 537         is already running."""
 538         if self.get_option('use_apache'):
 539             self._http_server = apache_http_server.LayoutTestApacheHttpd(self,
 540                 self.get_option('results_directory'))
 541         else:
 542             self._http_server = http_server.Lighttpd(self,
 543                 self.get_option('results_directory'))
 544         self._http_server.start()
 545
 546     def start_websocket_server(self):
 547         """Start a websocket server if it is available. Do nothing if
 548         it isn't. This routine is allowed to (and may) fail if a server
 549         is already running."""
 550         self._websocket_server = websocket_server.PyWebSocket(self,
 551             self.get_option('results_directory'))
 552         self._websocket_server.start()
 553
 554     def acquire_http_lock(self):
 555         self._http_lock = http_lock.HttpLock(None)
 556         self._http_lock.wait_for_httpd_lock()
 557
 558     def stop_helper(self):
 559         """Shut down the test helper if it is running. Do nothing if
 560         it isn't, or it isn't available. If a port overrides start_helper()
 561         it must override this routine as well."""
 562         pass
 563
 564     def stop_http_server(self):
 565         """Shut down the http server if it is running. Do nothing if
 566         it isn't, or it isn't available."""
 567         if self._http_server:
 568             self._http_server.stop()
 569
 570     def stop_websocket_server(self):
 571         """Shut down the websocket server if it is running. Do nothing if
 572         it isn't, or it isn't available."""
 573         if self._websocket_server:
 574             self._websocket_server.stop()
 575
 576     def release_http_lock(self):
 577         if self._http_lock:
 578             self._http_lock.cleanup_http_lock()
 579
 580     def test_expectations(self):
 581         """Returns the test expectations for this port.
 582
 583         Basically this string should contain the equivalent of a
 584         test_expectations file. See test_expectations.py for more details."""
 585         raise NotImplementedError('Port.test_expectations')
 586
 587     def test_expectations_overrides(self):
 588         """Returns an optional set of overrides for the test_expectations.
 589
 590         This is used by ports that have code in two repositories, and where
 591         it is possible that you might need "downstream" expectations that
 592         temporarily override the "upstream" expectations until the port can
 593         sync up the two repos."""
 594         return None
 595
 596     def test_base_platform_names(self):
 597         """Return a list of the 'base' platforms on your port. The base
 598         platforms represent different architectures, operating systems,
 599         or implementations (as opposed to different versions of a single
 600         platform). For example, 'mac' and 'win' might be different base
 601         platforms, wherease 'mac-tiger' and 'mac-leopard' might be
 602         different platforms. This routine is used by the rebaselining tool
 603         and the dashboards, and the strings correspond to the identifiers
 604         in your test expectations (*not* necessarily the platform names
 605         themselves)."""
 606         raise NotImplementedError('Port.base_test_platforms')
 607
 608     def test_platform_name(self):
 609         """Returns the string that corresponds to the given platform name
 610         in the test expectations. This may be the same as name(), or it
 611         may be different. For example, chromium returns 'mac' for
 612         'chromium-mac'."""
 613         raise NotImplementedError('Port.test_platform_name')
 614
 615     def test_platforms(self):
 616         """Returns the list of test platform identifiers as used in the
 617         test_expectations and on dashboards, the rebaselining tool, etc.
 618
 619         Note that this is not necessarily the same as the list of ports,
 620         which must be globally unique (e.g., both 'chromium-mac' and 'mac'
 621         might return 'mac' as a test_platform name'."""
 622         raise NotImplementedError('Port.platforms')
 623
 624     def test_platform_name_to_name(self, test_platform_name):
 625         """Returns the Port platform name that corresponds to the name as
 626         referenced in the expectations file. E.g., "mac" returns
 627         "chromium-mac" on the Chromium ports."""
 628         raise NotImplementedError('Port.test_platform_name_to_name')
 629
 630     def version(self):
 631         """Returns a string indicating the version of a given platform, e.g.
 632         '-leopard' or '-xp'.
 633
 634         This is used to help identify the exact port when parsing test
 635         expectations, determining search paths, and logging information."""
 636         raise NotImplementedError('Port.version')
 637
 638     def test_repository_paths(self):
 639         """Returns a list of (repository_name, repository_path) tuples
 640         of its depending code base.  By default it returns a list that only
 641         contains a ('webkit', <webkitRepossitoryPath>) tuple.
 642         """
 643         return [('webkit', self.layout_tests_dir())]
 644
 645
 646     _WDIFF_DEL = '##WDIFF_DEL##'
 647     _WDIFF_ADD = '##WDIFF_ADD##'
 648     _WDIFF_END = '##WDIFF_END##'
 649
 650     def _format_wdiff_output_as_html(self, wdiff):
 651         wdiff = cgi.escape(wdiff)
 652         wdiff = wdiff.replace(self._WDIFF_DEL, "<span class=del>")
 653         wdiff = wdiff.replace(self._WDIFF_ADD, "<span class=add>")
 654         wdiff = wdiff.replace(self._WDIFF_END, "</span>")
 655         html = "<head><style>.del { background: #faa; } "
 656         html += ".add { background: #afa; }</style></head>"
 657         html += "<pre>%s</pre>" % wdiff
 658         return html
 659
 660     def _wdiff_command(self, actual_filename, expected_filename):
 661         executable = self._path_to_wdiff()
 662         return [executable,
 663                 "--start-delete=%s" % self._WDIFF_DEL,
 664                 "--end-delete=%s" % self._WDIFF_END,
 665                 "--start-insert=%s" % self._WDIFF_ADD,
 666                 "--end-insert=%s" % self._WDIFF_END,
 667                 actual_filename,
 668                 expected_filename]
 669
 670     @staticmethod
 671     def _handle_wdiff_error(script_error):
 672         # Exit 1 means the files differed, any other exit code is an error.
 673         if script_error.exit_code != 1:
 674             raise script_error
 675
 676     def _run_wdiff(self, actual_filename, expected_filename):
 677         """Runs wdiff and may throw exceptions.
 678         This is mostly a hook for unit testing."""
 679         # Diffs are treated as binary as they may include multiple files
 680         # with conflicting encodings.  Thus we do not decode the output.
 681         command = self._wdiff_command(actual_filename, expected_filename)
 682         wdiff = self._executive.run_command(command, decode_output=False,
 683             error_handler=self._handle_wdiff_error)
 684         return self._format_wdiff_output_as_html(wdiff)
 685
 686     def wdiff_text(self, actual_filename, expected_filename):
 687         """Returns a string of HTML indicating the word-level diff of the
 688         contents of the two filenames. Returns an empty string if word-level
 689         diffing isn't available."""
 690         if not self._wdiff_available:
 691             return ""
 692         try:
 693             # It's possible to raise a ScriptError we pass wdiff invalid paths.
 694             return self._run_wdiff(actual_filename, expected_filename)
 695         except OSError, e:
 696             if e.errno in [errno.ENOENT, errno.EACCES, errno.ECHILD]:
 697                 # Silently ignore cases where wdiff is missing.
 698                 self._wdiff_available = False
 699                 return ""
 700             raise
 701
 702     # This is a class variable so we can test error output easily.
 703     _pretty_patch_error_html = "Failed to run PrettyPatch, see error log."
 704
 705     def pretty_patch_text(self, diff_path):
 706         if not self._pretty_patch_available:
 707             return self._pretty_patch_error_html
 708         command = ("ruby", "-I", os.path.dirname(self._pretty_patch_path),
 709                    self._pretty_patch_path, diff_path)
 710         try:
 711             # Diffs are treated as binary (we pass decode_output=False) as they
 712             # may contain multiple files of conflicting encodings.
 713             return self._executive.run_command(command, decode_output=False)
 714         except OSError, e:
 715             # If the system is missing ruby log the error and stop trying.
 716             self._pretty_patch_available = False
 717             _log.error("Failed to run PrettyPatch (%s): %s" % (command, e))
 718             return self._pretty_patch_error_html
 719         except ScriptError, e:
 720             # If ruby failed to run for some reason, log the command
 721             # output and stop trying.
 722             self._pretty_patch_available = False
 723             _log.error("Failed to run PrettyPatch (%s):\n%s" % (command,
 724                        e.message_with_output()))
 725             return self._pretty_patch_error_html
 726
 727     def default_configuration(self):
 728         return self._config.default_configuration()
 729
 730     #
 731     # PROTECTED ROUTINES
 732     #
 733     # The routines below should only be called by routines in this class
 734     # or any of its subclasses.
 735     #
 736     def _webkit_build_directory(self, args):
 737         return self._config.build_directory(args[0])
 738
 739     def _path_to_apache(self):
 740         """Returns the full path to the apache binary.
 741
 742         This is needed only by ports that use the apache_http_server module."""
 743         raise NotImplementedError('Port.path_to_apache')
 744
 745     def _path_to_apache_config_file(self):
 746         """Returns the full path to the apache binary.
 747
 748         This is needed only by ports that use the apache_http_server module."""
 749         raise NotImplementedError('Port.path_to_apache_config_file')
 750
 751     def _path_to_driver(self, configuration=None):
 752         """Returns the full path to the test driver (DumpRenderTree)."""
 753         raise NotImplementedError('Port._path_to_driver')
 754
 755     def _path_to_webcore_library(self):
 756         """Returns the full path to a built copy of WebCore."""
 757         raise NotImplementedError('Port.path_to_webcore_library')
 758
 759     def _path_to_helper(self):
 760         """Returns the full path to the layout_test_helper binary, which
 761         is used to help configure the system for the test run, or None
 762         if no helper is needed.
 763
 764         This is likely only used by start/stop_helper()."""
 765         raise NotImplementedError('Port._path_to_helper')
 766
 767     def _path_to_image_diff(self):
 768         """Returns the full path to the image_diff binary, or None if it
 769         is not available.
 770
 771         This is likely used only by diff_image()"""
 772         raise NotImplementedError('Port.path_to_image_diff')
 773
 774     def _path_to_lighttpd(self):
 775         """Returns the path to the LigHTTPd binary.
 776
 777         This is needed only by ports that use the http_server.py module."""
 778         raise NotImplementedError('Port._path_to_lighttpd')
 779
 780     def _path_to_lighttpd_modules(self):
 781         """Returns the path to the LigHTTPd modules directory.
 782
 783         This is needed only by ports that use the http_server.py module."""
 784         raise NotImplementedError('Port._path_to_lighttpd_modules')
 785
 786     def _path_to_lighttpd_php(self):
 787         """Returns the path to the LigHTTPd PHP executable.
 788
 789         This is needed only by ports that use the http_server.py module."""
 790         raise NotImplementedError('Port._path_to_lighttpd_php')
 791
 792     def _path_to_wdiff(self):
 793         """Returns the full path to the wdiff binary, or None if it is
 794         not available.
 795
 796         This is likely used only by wdiff_text()"""
 797         raise NotImplementedError('Port._path_to_wdiff')
 798
 799     def _shut_down_http_server(self, pid):
 800         """Forcefully and synchronously kills the web server.
 801
 802         This routine should only be called from http_server.py or its
 803         subclasses."""
 804         raise NotImplementedError('Port._shut_down_http_server')
 805
 806     def _webkit_baseline_path(self, platform):
 807         """Return the  full path to the top of the baseline tree for a
 808         given platform."""
 809         return self._filesystem.join(self.layout_tests_dir(), 'platform',
 810                                      platform)
 811
 812
 813 class Driver:
 814     """Abstract interface for the DumpRenderTree interface."""
 815
 816     def __init__(self, port, worker_number):
 817         """Initialize a Driver to subsequently run tests.
 818
 819         Typically this routine will spawn DumpRenderTree in a config
 820         ready for subsequent input.
 821
 822         port - reference back to the port object.
 823         worker_number - identifier for a particular worker/driver instance
 824         """
 825         raise NotImplementedError('Driver.__init__')
 826
 827     def run_test(self, test_input):
 828         """Run a single test and return the results.
 829
 830         Note that it is okay if a test times out or crashes and leaves
 831         the driver in an indeterminate state. The upper layers of the program
 832         are responsible for cleaning up and ensuring things are okay.
 833
 834         Args:
 835           test_input: a TestInput object
 836
 837         Returns a TestOutput object.
 838         """
 839         raise NotImplementedError('Driver.run_test')
 840
 841     # FIXME: This is static so we can test it w/o creating a Base instance.
 842     @classmethod
 843     def _command_wrapper(cls, wrapper_option):
 844         # Hook for injecting valgrind or other runtime instrumentation,
 845         # used by e.g. tools/valgrind/valgrind_tests.py.
 846         wrapper = []
 847         browser_wrapper = os.environ.get("BROWSER_WRAPPER", None)
 848         if browser_wrapper:
 849             # FIXME: There seems to be no reason to use BROWSER_WRAPPER over --wrapper.
 850             # Remove this code any time after the date listed below.
 851             _log.error("BROWSER_WRAPPER is deprecated, please use --wrapper instead.")
 852             _log.error("BROWSER_WRAPPER will be removed any time after June 1st 2010 and your scripts will break.")
 853             wrapper += [browser_wrapper]
 854
 855         if wrapper_option:
 856             wrapper += shlex.split(wrapper_option)
 857         return wrapper
 858
 859     def poll(self):
 860         """Returns None if the Driver is still running. Returns the returncode
 861         if it has exited."""
 862         raise NotImplementedError('Driver.poll')
 863
 864     def stop(self):
 865         raise NotImplementedError('Driver.stop')