2010-11-17 Hayato Ito <hayato@chromium.org>
[WebKit-https.git] / 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 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             (os.path.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 = os.path.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         # FIXME: DRT output is actually utf-8, but since we don't decode the
327         # output from DRT (instead treating it as a binary string), we read the
328         # baselines as a binary string, too.
329         path = self.expected_filename(test, '.txt')
330         if not self.path_exists(path):
331             return ''
332         text = self._filesystem.read_binary_file(path)
333         return text.strip("\r\n").replace("\r\n", "\n") + "\n"
334
335     def filename_to_uri(self, filename):
336         """Convert a test file (which is an absolute path) to a URI."""
337         LAYOUTTEST_HTTP_DIR = "http/tests/"
338         LAYOUTTEST_WEBSOCKET_DIR = "http/tests/websocket/tests/"
339
340         relative_path = self.relative_test_filename(filename)
341         port = None
342         use_ssl = False
343
344         if (relative_path.startswith(LAYOUTTEST_WEBSOCKET_DIR)
345             or relative_path.startswith(LAYOUTTEST_HTTP_DIR)):
346             relative_path = relative_path[len(LAYOUTTEST_HTTP_DIR):]
347             port = 8000
348
349         # Make http/tests/local run as local files. This is to mimic the
350         # logic in run-webkit-tests.
351         #
352         # TODO(dpranke): remove the media reference and the SSL reference?
353         if (port and not relative_path.startswith("local/") and
354             not relative_path.startswith("media/")):
355             if relative_path.startswith("ssl/"):
356                 port += 443
357                 protocol = "https"
358             else:
359                 protocol = "http"
360             return "%s://127.0.0.1:%u/%s" % (protocol, port, relative_path)
361
362         return path.abspath_to_uri(os.path.abspath(filename))
363
364     def tests(self, paths):
365         """Return the list of tests found (relative to layout_tests_dir()."""
366         return test_files.find(self, paths)
367
368     def test_dirs(self):
369         """Returns the list of top-level test directories.
370
371         Used by --clobber-old-results."""
372         layout_tests_dir = self.layout_tests_dir()
373         return filter(lambda x: self._filesystem.isdir(self._filesystem.join(layout_tests_dir, x)),
374                       self._filesystem.listdir(layout_tests_dir))
375
376     def path_isdir(self, path):
377         """Return True if the path refers to a directory of tests."""
378         # Used by test_expectations.py to apply rules to whole directories.
379         return self._filesystem.isdir(path)
380
381     def path_exists(self, path):
382         """Return True if the path refers to an existing test or baseline."""
383         # Used by test_expectations.py to determine if an entry refers to a
384         # valid test and by printing.py to determine if baselines exist.
385         return self._filesystem.exists(path)
386
387     def update_baseline(self, path, data, encoding):
388         """Updates the baseline for a test.
389
390         Args:
391             path: the actual path to use for baseline, not the path to
392               the test. This function is used to update either generic or
393               platform-specific baselines, but we can't infer which here.
394             data: contents of the baseline.
395             encoding: file encoding to use for the baseline.
396         """
397         # FIXME: remove the encoding parameter in favor of text/binary
398         # functions.
399         if encoding is None:
400             self._filesystem.write_binary_file(path, data)
401         else:
402             self._filesystem.write_text_file(path, data)
403
404     def uri_to_test_name(self, uri):
405         """Return the base layout test name for a given URI.
406
407         This returns the test name for a given URI, e.g., if you passed in
408         "file:///src/LayoutTests/fast/html/keygen.html" it would return
409         "fast/html/keygen.html".
410
411         """
412         test = uri
413         if uri.startswith("file:///"):
414             prefix = path.abspath_to_uri(self.layout_tests_dir()) + "/"
415             return test[len(prefix):]
416
417         if uri.startswith("http://127.0.0.1:8880/"):
418             # websocket tests
419             return test.replace('http://127.0.0.1:8880/', '')
420
421         if uri.startswith("http://"):
422             # regular HTTP test
423             return test.replace('http://127.0.0.1:8000/', 'http/tests/')
424
425         if uri.startswith("https://"):
426             return test.replace('https://127.0.0.1:8443/', 'http/tests/')
427
428         raise NotImplementedError('unknown url type: %s' % uri)
429
430     def layout_tests_dir(self):
431         """Return the absolute path to the top of the LayoutTests directory."""
432         return self.path_from_webkit_base('LayoutTests')
433
434     def skips_layout_test(self, test_name):
435         """Figures out if the givent test is being skipped or not.
436
437         Test categories are handled as well."""
438         for test_or_category in self.skipped_layout_tests():
439             if test_or_category == test_name:
440                 return True
441             category = self._filesystem.join(self.layout_tests_dir(),
442                                              test_or_category)
443             if (self._filesystem.isdir(category) and
444                 test_name.startswith(test_or_category)):
445                 return True
446         return False
447
448     def maybe_make_directory(self, *path):
449         """Creates the specified directory if it doesn't already exist."""
450         self._filesystem.maybe_make_directory(*path)
451
452     def name(self):
453         """Return the name of the port (e.g., 'mac', 'chromium-win-xp').
454
455         Note that this is different from the test_platform_name(), which
456         may be different (e.g., 'win-xp' instead of 'chromium-win-xp'."""
457         return self._name
458
459     def get_option(self, name, default_value=None):
460         # FIXME: Eventually we should not have to do a test for
461         # hasattr(), and we should be able to just do
462         # self.options.value. See additional FIXME in the constructor.
463         if hasattr(self._options, name):
464             return getattr(self._options, name)
465         return default_value
466
467     def set_option_default(self, name, default_value):
468         if not hasattr(self._options, name):
469             return setattr(self._options, name, default_value)
470
471     def path_from_webkit_base(self, *comps):
472         """Returns the full path to path made by joining the top of the
473         WebKit source tree and the list of path components in |*comps|."""
474         return self._config.path_from_webkit_base(*comps)
475
476     def script_path(self, script_name):
477         return self._config.script_path(script_name)
478
479     def path_to_test_expectations_file(self):
480         """Update the test expectations to the passed-in string.
481
482         This is used by the rebaselining tool. Raises NotImplementedError
483         if the port does not use expectations files."""
484         raise NotImplementedError('Port.path_to_test_expectations_file')
485
486     def relative_test_filename(self, filename):
487         """Relative unix-style path for a filename under the LayoutTests
488         directory. Filenames outside the LayoutTests directory should raise
489         an error."""
490         #assert(filename.startswith(self.layout_tests_dir()))
491         return filename[len(self.layout_tests_dir()) + 1:]
492
493     def results_directory(self):
494         """Absolute path to the place to store the test results."""
495         raise NotImplementedError('Port.results_directory')
496
497     def setup_test_run(self):
498         """Perform port-specific work at the beginning of a test run."""
499         pass
500
501     def setup_environ_for_server(self):
502         """Perform port-specific work at the beginning of a server launch.
503
504         Returns:
505            Operating-system's environment.
506         """
507         return os.environ.copy()
508
509     def show_results_html_file(self, results_filename):
510         """This routine should display the HTML file pointed at by
511         results_filename in a users' browser."""
512         return self._user.open_url(results_filename)
513
514     def create_driver(self, image_path, options):
515         """Return a newly created base.Driver subclass for starting/stopping
516         the test driver."""
517         raise NotImplementedError('Port.create_driver')
518
519     def start_helper(self):
520         """If a port needs to reconfigure graphics settings or do other
521         things to ensure a known test configuration, it should override this
522         method."""
523         pass
524
525     def start_http_server(self):
526         """Start a web server if it is available. Do nothing if
527         it isn't. This routine is allowed to (and may) fail if a server
528         is already running."""
529         if self.get_option('use_apache'):
530             self._http_server = apache_http_server.LayoutTestApacheHttpd(self,
531                 self.get_option('results_directory'))
532         else:
533             self._http_server = http_server.Lighttpd(self,
534                 self.get_option('results_directory'))
535         self._http_server.start()
536
537     def start_websocket_server(self):
538         """Start a websocket server if it is available. Do nothing if
539         it isn't. This routine is allowed to (and may) fail if a server
540         is already running."""
541         self._websocket_server = websocket_server.PyWebSocket(self,
542             self.get_option('results_directory'))
543         self._websocket_server.start()
544
545     def acquire_http_lock(self):
546         self._http_lock = http_lock.HttpLock(None)
547         self._http_lock.wait_for_httpd_lock()
548
549     def stop_helper(self):
550         """Shut down the test helper if it is running. Do nothing if
551         it isn't, or it isn't available. If a port overrides start_helper()
552         it must override this routine as well."""
553         pass
554
555     def stop_http_server(self):
556         """Shut down the http server if it is running. Do nothing if
557         it isn't, or it isn't available."""
558         if self._http_server:
559             self._http_server.stop()
560
561     def stop_websocket_server(self):
562         """Shut down the websocket server if it is running. Do nothing if
563         it isn't, or it isn't available."""
564         if self._websocket_server:
565             self._websocket_server.stop()
566
567     def release_http_lock(self):
568         if self._http_lock:
569             self._http_lock.cleanup_http_lock()
570
571     def test_expectations(self):
572         """Returns the test expectations for this port.
573
574         Basically this string should contain the equivalent of a
575         test_expectations file. See test_expectations.py for more details."""
576         raise NotImplementedError('Port.test_expectations')
577
578     def test_expectations_overrides(self):
579         """Returns an optional set of overrides for the test_expectations.
580
581         This is used by ports that have code in two repositories, and where
582         it is possible that you might need "downstream" expectations that
583         temporarily override the "upstream" expectations until the port can
584         sync up the two repos."""
585         return None
586
587     def test_base_platform_names(self):
588         """Return a list of the 'base' platforms on your port. The base
589         platforms represent different architectures, operating systems,
590         or implementations (as opposed to different versions of a single
591         platform). For example, 'mac' and 'win' might be different base
592         platforms, wherease 'mac-tiger' and 'mac-leopard' might be
593         different platforms. This routine is used by the rebaselining tool
594         and the dashboards, and the strings correspond to the identifiers
595         in your test expectations (*not* necessarily the platform names
596         themselves)."""
597         raise NotImplementedError('Port.base_test_platforms')
598
599     def test_platform_name(self):
600         """Returns the string that corresponds to the given platform name
601         in the test expectations. This may be the same as name(), or it
602         may be different. For example, chromium returns 'mac' for
603         'chromium-mac'."""
604         raise NotImplementedError('Port.test_platform_name')
605
606     def test_platforms(self):
607         """Returns the list of test platform identifiers as used in the
608         test_expectations and on dashboards, the rebaselining tool, etc.
609
610         Note that this is not necessarily the same as the list of ports,
611         which must be globally unique (e.g., both 'chromium-mac' and 'mac'
612         might return 'mac' as a test_platform name'."""
613         raise NotImplementedError('Port.platforms')
614
615     def test_platform_name_to_name(self, test_platform_name):
616         """Returns the Port platform name that corresponds to the name as
617         referenced in the expectations file. E.g., "mac" returns
618         "chromium-mac" on the Chromium ports."""
619         raise NotImplementedError('Port.test_platform_name_to_name')
620
621     def version(self):
622         """Returns a string indicating the version of a given platform, e.g.
623         '-leopard' or '-xp'.
624
625         This is used to help identify the exact port when parsing test
626         expectations, determining search paths, and logging information."""
627         raise NotImplementedError('Port.version')
628
629     def test_repository_paths(self):
630         """Returns a list of (repository_name, repository_path) tuples
631         of its depending code base.  By default it returns a list that only
632         contains a ('webkit', <webkitRepossitoryPath>) tuple.
633         """
634         return [('webkit', self.layout_tests_dir())]
635
636
637     _WDIFF_DEL = '##WDIFF_DEL##'
638     _WDIFF_ADD = '##WDIFF_ADD##'
639     _WDIFF_END = '##WDIFF_END##'
640
641     def _format_wdiff_output_as_html(self, wdiff):
642         wdiff = cgi.escape(wdiff)
643         wdiff = wdiff.replace(self._WDIFF_DEL, "<span class=del>")
644         wdiff = wdiff.replace(self._WDIFF_ADD, "<span class=add>")
645         wdiff = wdiff.replace(self._WDIFF_END, "</span>")
646         html = "<head><style>.del { background: #faa; } "
647         html += ".add { background: #afa; }</style></head>"
648         html += "<pre>%s</pre>" % wdiff
649         return html
650
651     def _wdiff_command(self, actual_filename, expected_filename):
652         executable = self._path_to_wdiff()
653         return [executable,
654                 "--start-delete=%s" % self._WDIFF_DEL,
655                 "--end-delete=%s" % self._WDIFF_END,
656                 "--start-insert=%s" % self._WDIFF_ADD,
657                 "--end-insert=%s" % self._WDIFF_END,
658                 actual_filename,
659                 expected_filename]
660
661     @staticmethod
662     def _handle_wdiff_error(script_error):
663         # Exit 1 means the files differed, any other exit code is an error.
664         if script_error.exit_code != 1:
665             raise script_error
666
667     def _run_wdiff(self, actual_filename, expected_filename):
668         """Runs wdiff and may throw exceptions.
669         This is mostly a hook for unit testing."""
670         # Diffs are treated as binary as they may include multiple files
671         # with conflicting encodings.  Thus we do not decode the output.
672         command = self._wdiff_command(actual_filename, expected_filename)
673         wdiff = self._executive.run_command(command, decode_output=False,
674             error_handler=self._handle_wdiff_error)
675         return self._format_wdiff_output_as_html(wdiff)
676
677     def wdiff_text(self, actual_filename, expected_filename):
678         """Returns a string of HTML indicating the word-level diff of the
679         contents of the two filenames. Returns an empty string if word-level
680         diffing isn't available."""
681         if not self._wdiff_available:
682             return ""
683         try:
684             # It's possible to raise a ScriptError we pass wdiff invalid paths.
685             return self._run_wdiff(actual_filename, expected_filename)
686         except OSError, e:
687             if e.errno in [errno.ENOENT, errno.EACCES, errno.ECHILD]:
688                 # Silently ignore cases where wdiff is missing.
689                 self._wdiff_available = False
690                 return ""
691             raise
692
693     # This is a class variable so we can test error output easily.
694     _pretty_patch_error_html = "Failed to run PrettyPatch, see error log."
695
696     def pretty_patch_text(self, diff_path):
697         if not self._pretty_patch_available:
698             return self._pretty_patch_error_html
699         command = ("ruby", "-I", os.path.dirname(self._pretty_patch_path),
700                    self._pretty_patch_path, diff_path)
701         try:
702             # Diffs are treated as binary (we pass decode_output=False) as they
703             # may contain multiple files of conflicting encodings.
704             return self._executive.run_command(command, decode_output=False)
705         except OSError, e:
706             # If the system is missing ruby log the error and stop trying.
707             self._pretty_patch_available = False
708             _log.error("Failed to run PrettyPatch (%s): %s" % (command, e))
709             return self._pretty_patch_error_html
710         except ScriptError, e:
711             # If ruby failed to run for some reason, log the command
712             # output and stop trying.
713             self._pretty_patch_available = False
714             _log.error("Failed to run PrettyPatch (%s):\n%s" % (command,
715                        e.message_with_output()))
716             return self._pretty_patch_error_html
717
718     def default_configuration(self):
719         return self._config.default_configuration()
720
721     #
722     # PROTECTED ROUTINES
723     #
724     # The routines below should only be called by routines in this class
725     # or any of its subclasses.
726     #
727     def _webkit_build_directory(self, args):
728         return self._config.build_directory(args[0])
729
730     def _path_to_apache(self):
731         """Returns the full path to the apache binary.
732
733         This is needed only by ports that use the apache_http_server module."""
734         raise NotImplementedError('Port.path_to_apache')
735
736     def _path_to_apache_config_file(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_config_file')
741
742     def _path_to_driver(self, configuration=None):
743         """Returns the full path to the test driver (DumpRenderTree)."""
744         raise NotImplementedError('Port.path_to_driver')
745
746     def _path_to_webcore_library(self):
747         """Returns the full path to a built copy of WebCore."""
748         raise NotImplementedError('Port.path_to_webcore_library')
749
750     def _path_to_helper(self):
751         """Returns the full path to the layout_test_helper binary, which
752         is used to help configure the system for the test run, or None
753         if no helper is needed.
754
755         This is likely only used by start/stop_helper()."""
756         raise NotImplementedError('Port._path_to_helper')
757
758     def _path_to_image_diff(self):
759         """Returns the full path to the image_diff binary, or None if it
760         is not available.
761
762         This is likely used only by diff_image()"""
763         raise NotImplementedError('Port.path_to_image_diff')
764
765     def _path_to_lighttpd(self):
766         """Returns the path to the LigHTTPd binary.
767
768         This is needed only by ports that use the http_server.py module."""
769         raise NotImplementedError('Port._path_to_lighttpd')
770
771     def _path_to_lighttpd_modules(self):
772         """Returns the path to the LigHTTPd modules directory.
773
774         This is needed only by ports that use the http_server.py module."""
775         raise NotImplementedError('Port._path_to_lighttpd_modules')
776
777     def _path_to_lighttpd_php(self):
778         """Returns the path to the LigHTTPd PHP executable.
779
780         This is needed only by ports that use the http_server.py module."""
781         raise NotImplementedError('Port._path_to_lighttpd_php')
782
783     def _path_to_wdiff(self):
784         """Returns the full path to the wdiff binary, or None if it is
785         not available.
786
787         This is likely used only by wdiff_text()"""
788         raise NotImplementedError('Port._path_to_wdiff')
789
790     def _shut_down_http_server(self, pid):
791         """Forcefully and synchronously kills the web server.
792
793         This routine should only be called from http_server.py or its
794         subclasses."""
795         raise NotImplementedError('Port._shut_down_http_server')
796
797     def _webkit_baseline_path(self, platform):
798         """Return the  full path to the top of the baseline tree for a
799         given platform."""
800         return self._filesystem.join(self.layout_tests_dir(), 'platform',
801                                      platform)
802
803
804 class Driver:
805     """Abstract interface for the DumpRenderTree interface."""
806
807     def __init__(self, port, png_path, options, executive):
808         """Initialize a Driver to subsequently run tests.
809
810         Typically this routine will spawn DumpRenderTree in a config
811         ready for subsequent input.
812
813         port - reference back to the port object.
814         png_path - an absolute path for the driver to write any image
815             data for a test (as a PNG). If no path is provided, that
816             indicates that pixel test results will not be checked.
817         options - command line options argument from optparse
818         executive - reference to the process-wide Executive object
819
820         """
821         raise NotImplementedError('Driver.__init__')
822
823     def run_test(self, uri, timeout, checksum):
824         """Run a single test and return the results.
825
826         Note that it is okay if a test times out or crashes and leaves
827         the driver in an indeterminate state. The upper layers of the program
828         are responsible for cleaning up and ensuring things are okay.
829
830         uri - a full URI for the given test
831         timeout - number of milliseconds to wait before aborting this test.
832         checksum - if present, the expected checksum for the image for this
833             test
834
835         Returns a TestOutput object.
836         """
837         raise NotImplementedError('Driver.run_test')
838
839     # FIXME: This is static so we can test it w/o creating a Base instance.
840     @classmethod
841     def _command_wrapper(cls, wrapper_option):
842         # Hook for injecting valgrind or other runtime instrumentation,
843         # used by e.g. tools/valgrind/valgrind_tests.py.
844         wrapper = []
845         browser_wrapper = os.environ.get("BROWSER_WRAPPER", None)
846         if browser_wrapper:
847             # FIXME: There seems to be no reason to use BROWSER_WRAPPER over --wrapper.
848             # Remove this code any time after the date listed below.
849             _log.error("BROWSER_WRAPPER is deprecated, please use --wrapper instead.")
850             _log.error("BROWSER_WRAPPER will be removed any time after June 1st 2010 and your scripts will break.")
851             wrapper += [browser_wrapper]
852
853         if wrapper_option:
854             wrapper += shlex.split(wrapper_option)
855         return wrapper
856
857     def poll(self):
858         """Returns None if the Driver is still running. Returns the returncode
859         if it has exited."""
860         raise NotImplementedError('Driver.poll')
861
862     def stop(self):
863         raise NotImplementedError('Driver.stop')