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