2011-02-11 Dirk Pranke <dpranke@chromium.org>
[WebKit-https.git] / 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         # If we're running on a mocked-out filesystem, this file almost
121         # certainly won't be available, so it's a good test to keep us
122         # from erroring out later.
123         self._pretty_patch_available = self._filesystem.exists(self._pretty_patch_path)
124         if not hasattr(self._options, 'configuration') or self._options.configuration is None:
125             self._options.configuration = self.default_configuration()
126         self._test_configuration = None
127
128     def default_child_processes(self):
129         """Return the number of DumpRenderTree instances to use for this
130         port."""
131         return self._executive.cpu_count()
132
133     def default_worker_model(self):
134         return 'old-threads'
135
136     def baseline_path(self):
137         """Return the absolute path to the directory to store new baselines
138         in for this port."""
139         raise NotImplementedError('Port.baseline_path')
140
141     def baseline_search_path(self):
142         """Return a list of absolute paths to directories to search under for
143         baselines. The directories are searched in order."""
144         raise NotImplementedError('Port.baseline_search_path')
145
146     def check_build(self, needs_http):
147         """This routine is used to ensure that the build is up to date
148         and all the needed binaries are present."""
149         raise NotImplementedError('Port.check_build')
150
151     def check_sys_deps(self, needs_http):
152         """If the port needs to do some runtime checks to ensure that the
153         tests can be run successfully, it should override this routine.
154         This step can be skipped with --nocheck-sys-deps.
155
156         Returns whether the system is properly configured."""
157         return True
158
159     def check_image_diff(self, override_step=None, logging=True):
160         """This routine is used to check whether image_diff binary exists."""
161         raise NotImplementedError('Port.check_image_diff')
162
163     def check_pretty_patch(self):
164         """Checks whether we can use the PrettyPatch ruby script."""
165
166         # check if Ruby is installed
167         try:
168             result = self._executive.run_command(['ruby', '--version'])
169         except OSError, e:
170             if e.errno in [errno.ENOENT, errno.EACCES, errno.ECHILD]:
171                 _log.error("Ruby is not installed; "
172                            "can't generate pretty patches.")
173                 _log.error('')
174                 return False
175
176         if not self.path_exists(self._pretty_patch_path):
177             _log.error('Unable to find %s .' % self._pretty_patch_path)
178             _log.error("Can't generate pretty patches.")
179             _log.error('')
180             return False
181
182         return True
183
184     def compare_text(self, expected_text, actual_text):
185         """Return whether or not the two strings are *not* equal. This
186         routine is used to diff text output.
187
188         While this is a generic routine, we include it in the Port
189         interface so that it can be overriden for testing purposes."""
190         return expected_text != actual_text
191
192     def diff_image(self, expected_contents, actual_contents,
193                    diff_filename=None, tolerance=0):
194         """Compare two images and produce a delta image file.
195
196         Return True if the two images are different, False if they are the same.
197         Also produce a delta image of the two images and write that into
198         |diff_filename| if it is not None.
199
200         |tolerance| should be a percentage value (0.0 - 100.0).
201         If it is omitted, the port default tolerance value is used.
202
203         """
204         raise NotImplementedError('Port.diff_image')
205
206
207     def diff_text(self, expected_text, actual_text,
208                   expected_filename, actual_filename):
209         """Returns a string containing the diff of the two text strings
210         in 'unified diff' format.
211
212         While this is a generic routine, we include it in the Port
213         interface so that it can be overriden for testing purposes."""
214
215         # The filenames show up in the diff output, make sure they're
216         # raw bytes and not unicode, so that they don't trigger join()
217         # trying to decode the input.
218         def to_raw_bytes(str):
219             if isinstance(str, unicode):
220                 return str.encode('utf-8')
221             return str
222         expected_filename = to_raw_bytes(expected_filename)
223         actual_filename = to_raw_bytes(actual_filename)
224         diff = difflib.unified_diff(expected_text.splitlines(True),
225                                     actual_text.splitlines(True),
226                                     expected_filename,
227                                     actual_filename)
228         return ''.join(diff)
229
230     def driver_name(self):
231         """Returns the name of the actual binary that is performing the test,
232         so that it can be referred to in log messages. In most cases this
233         will be DumpRenderTree, but if a port uses a binary with a different
234         name, it can be overridden here."""
235         return "DumpRenderTree"
236
237     def expected_baselines(self, filename, suffix, all_baselines=False):
238         """Given a test name, finds where the baseline results are located.
239
240         Args:
241         filename: absolute filename to test file
242         suffix: file suffix of the expected results, including dot; e.g.
243             '.txt' or '.png'.  This should not be None, but may be an empty
244             string.
245         all_baselines: If True, return an ordered list of all baseline paths
246             for the given platform. If False, return only the first one.
247         Returns
248         a list of ( platform_dir, results_filename ), where
249             platform_dir - abs path to the top of the results tree (or test
250                 tree)
251             results_filename - relative path from top of tree to the results
252                 file
253             (port.join() of the two gives you the full path to the file,
254                 unless None was returned.)
255         Return values will be in the format appropriate for the current
256         platform (e.g., "\\" for path separators on Windows). If the results
257         file is not found, then None will be returned for the directory,
258         but the expected relative pathname will still be returned.
259
260         This routine is generic but lives here since it is used in
261         conjunction with the other baseline and filename routines that are
262         platform specific.
263         """
264         testname = self._filesystem.splitext(self.relative_test_filename(filename))[0]
265
266         baseline_filename = testname + '-expected' + suffix
267
268         baseline_search_path = self.baseline_search_path()
269
270         baselines = []
271         for platform_dir in baseline_search_path:
272             if self.path_exists(self._filesystem.join(platform_dir,
273                                                       baseline_filename)):
274                 baselines.append((platform_dir, baseline_filename))
275
276             if not all_baselines and baselines:
277                 return baselines
278
279         # If it wasn't found in a platform directory, return the expected
280         # result in the test directory, even if no such file actually exists.
281         platform_dir = self.layout_tests_dir()
282         if self.path_exists(self._filesystem.join(platform_dir,
283                                                   baseline_filename)):
284             baselines.append((platform_dir, baseline_filename))
285
286         if baselines:
287             return baselines
288
289         return [(None, baseline_filename)]
290
291     def expected_filename(self, filename, suffix):
292         """Given a test name, returns an absolute path to its expected results.
293
294         If no expected results are found in any of the searched directories,
295         the directory in which the test itself is located will be returned.
296         The return value is in the format appropriate for the platform
297         (e.g., "\\" for path separators on windows).
298
299         Args:
300         filename: absolute filename to test file
301         suffix: file suffix of the expected results, including dot; e.g. '.txt'
302             or '.png'.  This should not be None, but may be an empty string.
303         platform: the most-specific directory name to use to build the
304             search list of directories, e.g., 'chromium-win', or
305             'chromium-mac-leopard' (we follow the WebKit format)
306
307         This routine is generic but is implemented here to live alongside
308         the other baseline and filename manipulation routines.
309         """
310         platform_dir, baseline_filename = self.expected_baselines(
311             filename, suffix)[0]
312         if platform_dir:
313             return self._filesystem.join(platform_dir, baseline_filename)
314         return self._filesystem.join(self.layout_tests_dir(), baseline_filename)
315
316     def expected_checksum(self, test):
317         """Returns the checksum of the image we expect the test to produce, or None if it is a text-only test."""
318         path = self.expected_filename(test, '.checksum')
319         if not self.path_exists(path):
320             return None
321         return self._filesystem.read_binary_file(path)
322
323     def expected_image(self, test):
324         """Returns the image we expect the test to produce."""
325         path = self.expected_filename(test, '.png')
326         if not self.path_exists(path):
327             return None
328         return self._filesystem.read_binary_file(path)
329
330     def expected_text(self, test):
331         """Returns the text output we expect the test to produce.
332         End-of-line characters are normalized to '\n'."""
333         # FIXME: DRT output is actually utf-8, but since we don't decode the
334         # output from DRT (instead treating it as a binary string), we read the
335         # baselines as a binary string, too.
336         path = self.expected_filename(test, '.txt')
337         if not self.path_exists(path):
338             return ''
339         text = self._filesystem.read_binary_file(path)
340         return text.replace("\r\n", "\n")
341
342     def filename_to_uri(self, filename):
343         """Convert a test file (which is an absolute path) to a URI."""
344         LAYOUTTEST_HTTP_DIR = "http/tests/"
345         LAYOUTTEST_WEBSOCKET_DIR = "http/tests/websocket/tests/"
346
347         relative_path = self.relative_test_filename(filename)
348         port = None
349         use_ssl = False
350
351         if (relative_path.startswith(LAYOUTTEST_WEBSOCKET_DIR)
352             or relative_path.startswith(LAYOUTTEST_HTTP_DIR)):
353             relative_path = relative_path[len(LAYOUTTEST_HTTP_DIR):]
354             port = 8000
355
356         # Make http/tests/local run as local files. This is to mimic the
357         # logic in run-webkit-tests.
358         #
359         # TODO(dpranke): remove the media reference and the SSL reference?
360         if (port and not relative_path.startswith("local/") and
361             not relative_path.startswith("media/")):
362             if relative_path.startswith("ssl/"):
363                 port += 443
364                 protocol = "https"
365             else:
366                 protocol = "http"
367             return "%s://127.0.0.1:%u/%s" % (protocol, port, relative_path)
368
369         return path.abspath_to_uri(self._filesystem.abspath(filename))
370
371     def tests(self, paths):
372         """Return the list of tests found (relative to layout_tests_dir()."""
373         return test_files.find(self, paths)
374
375     def test_dirs(self):
376         """Returns the list of top-level test directories.
377
378         Used by --clobber-old-results."""
379         layout_tests_dir = self.layout_tests_dir()
380         return filter(lambda x: self._filesystem.isdir(self._filesystem.join(layout_tests_dir, x)),
381                       self._filesystem.listdir(layout_tests_dir))
382
383     def path_isdir(self, path):
384         """Return True if the path refers to a directory of tests."""
385         # Used by test_expectations.py to apply rules to whole directories.
386         return self._filesystem.isdir(path)
387
388     def path_exists(self, path):
389         """Return True if the path refers to an existing test or baseline."""
390         # Used by test_expectations.py to determine if an entry refers to a
391         # valid test and by printing.py to determine if baselines exist.
392         return self._filesystem.exists(path)
393
394     def driver_cmd_line(self):
395         """Prints the DRT command line that will be used."""
396         driver = self.create_driver(0)
397         return driver.cmd_line()
398
399     def update_baseline(self, path, data):
400         """Updates the baseline for a test.
401
402         Args:
403             path: the actual path to use for baseline, not the path to
404               the test. This function is used to update either generic or
405               platform-specific baselines, but we can't infer which here.
406             data: contents of the baseline.
407         """
408         self._filesystem.write_binary_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 graphics_type(self):
466         """Returns whether the port uses accelerated graphics ('gpu') or not
467         ('cpu')."""
468         return 'cpu'
469
470     def real_name(self):
471         """Returns the actual name of the port, not the delegate's."""
472         return self.name()
473
474     def get_option(self, name, default_value=None):
475         # FIXME: Eventually we should not have to do a test for
476         # hasattr(), and we should be able to just do
477         # self.options.value. See additional FIXME in the constructor.
478         if hasattr(self._options, name):
479             return getattr(self._options, name)
480         return default_value
481
482     def set_option_default(self, name, default_value):
483         if not hasattr(self._options, name):
484             return setattr(self._options, name, default_value)
485
486     def path_from_webkit_base(self, *comps):
487         """Returns the full path to path made by joining the top of the
488         WebKit source tree and the list of path components in |*comps|."""
489         return self._config.path_from_webkit_base(*comps)
490
491     def script_path(self, script_name):
492         return self._config.script_path(script_name)
493
494     def path_to_test_expectations_file(self):
495         """Update the test expectations to the passed-in string.
496
497         This is used by the rebaselining tool. Raises NotImplementedError
498         if the port does not use expectations files."""
499         raise NotImplementedError('Port.path_to_test_expectations_file')
500
501     def relative_test_filename(self, filename):
502         """Relative unix-style path for a filename under the LayoutTests
503         directory. Filenames outside the LayoutTests directory should raise
504         an error."""
505         # FIXME: On Windows, does this return test_names with forward slashes,
506         # or windows-style relative paths?
507         assert filename.startswith(self.layout_tests_dir()), "%s did not start with %s" % (filename, self.layout_tests_dir())
508         return filename[len(self.layout_tests_dir()) + 1:]
509
510     def abspath_for_test(self, test_name):
511         """Returns the full path to the file for a given test name. This is the
512         inverse of relative_test_filename()."""
513         return self._filesystem.normpath(self._filesystem.join(self.layout_tests_dir(), test_name))
514
515     def results_directory(self):
516         """Absolute path to the place to store the test results."""
517         raise NotImplementedError('Port.results_directory')
518
519     def setup_test_run(self):
520         """Perform port-specific work at the beginning of a test run."""
521         pass
522
523     def setup_environ_for_server(self):
524         """Perform port-specific work at the beginning of a server launch.
525
526         Returns:
527            Operating-system's environment.
528         """
529         return os.environ.copy()
530
531     def show_results_html_file(self, results_filename):
532         """This routine should display the HTML file pointed at by
533         results_filename in a users' browser."""
534         return self._user.open_url(results_filename)
535
536     def create_driver(self, worker_number):
537         """Return a newly created base.Driver subclass for starting/stopping
538         the test driver."""
539         raise NotImplementedError('Port.create_driver')
540
541     def start_helper(self):
542         """If a port needs to reconfigure graphics settings or do other
543         things to ensure a known test configuration, it should override this
544         method."""
545         pass
546
547     def start_http_server(self):
548         """Start a web server if it is available. Do nothing if
549         it isn't. This routine is allowed to (and may) fail if a server
550         is already running."""
551         if self.get_option('use_apache'):
552             self._http_server = apache_http_server.LayoutTestApacheHttpd(self,
553                 self.get_option('results_directory'))
554         else:
555             self._http_server = http_server.Lighttpd(self,
556                 self.get_option('results_directory'))
557         self._http_server.start()
558
559     def start_websocket_server(self):
560         """Start a websocket server if it is available. Do nothing if
561         it isn't. This routine is allowed to (and may) fail if a server
562         is already running."""
563         self._websocket_server = websocket_server.PyWebSocket(self,
564             self.get_option('results_directory'))
565         self._websocket_server.start()
566
567     def acquire_http_lock(self):
568         self._http_lock = http_lock.HttpLock(None)
569         self._http_lock.wait_for_httpd_lock()
570
571     def stop_helper(self):
572         """Shut down the test helper if it is running. Do nothing if
573         it isn't, or it isn't available. If a port overrides start_helper()
574         it must override this routine as well."""
575         pass
576
577     def stop_http_server(self):
578         """Shut down the http server if it is running. Do nothing if
579         it isn't, or it isn't available."""
580         if self._http_server:
581             self._http_server.stop()
582
583     def stop_websocket_server(self):
584         """Shut down the websocket server if it is running. Do nothing if
585         it isn't, or it isn't available."""
586         if self._websocket_server:
587             self._websocket_server.stop()
588
589     def release_http_lock(self):
590         if self._http_lock:
591             self._http_lock.cleanup_http_lock()
592
593     #
594     # TEST EXPECTATION-RELATED METHODS
595     #
596
597     def test_configuration(self):
598         """Returns the current TestConfiguration for the port."""
599         if not self._test_configuration:
600             self._test_configuration = TestConfiguration(self)
601         return self._test_configuration
602
603     def all_test_configurations(self):
604         return self.test_configuration().all_test_configurations()
605
606     def test_expectations(self):
607         """Returns the test expectations for this port.
608
609         Basically this string should contain the equivalent of a
610         test_expectations file. See test_expectations.py for more details."""
611         return self._filesystem.read_text_file(self.path_to_test_expectations_file())
612
613     def test_expectations_overrides(self):
614         """Returns an optional set of overrides for the test_expectations.
615
616         This is used by ports that have code in two repositories, and where
617         it is possible that you might need "downstream" expectations that
618         temporarily override the "upstream" expectations until the port can
619         sync up the two repos."""
620         return None
621
622     def test_platform_name(self):
623         """Returns the string that corresponds to the given platform name
624         in the test expectations. This may be the same as name(), or it
625         may be different. For example, chromium returns 'mac' for
626         'chromium-mac'."""
627         raise NotImplementedError('Port.test_platform_name')
628
629     def test_platforms(self):
630         """Returns the list of test platform identifiers as used in the
631         test_expectations and on dashboards, the rebaselining tool, etc.
632
633         Note that this is not necessarily the same as the list of ports,
634         which must be globally unique (e.g., both 'chromium-mac' and 'mac'
635         might return 'mac' as a test_platform name'."""
636         raise NotImplementedError('Port.platforms')
637
638     def test_platform_name_to_name(self, test_platform_name):
639         """Returns the Port platform name that corresponds to the name as
640         referenced in the expectations file. E.g., "mac" returns
641         "chromium-mac" on the Chromium ports."""
642         raise NotImplementedError('Port.test_platform_name_to_name')
643
644     def version(self):
645         """Returns a string indicating the version of a given platform, e.g.
646         '-leopard' or '-xp'.
647
648         This is used to help identify the exact port when parsing test
649         expectations, determining search paths, and logging information."""
650         raise NotImplementedError('Port.version')
651
652     def test_repository_paths(self):
653         """Returns a list of (repository_name, repository_path) tuples
654         of its depending code base.  By default it returns a list that only
655         contains a ('webkit', <webkitRepossitoryPath>) tuple.
656         """
657         return [('webkit', self.layout_tests_dir())]
658
659
660     _WDIFF_DEL = '##WDIFF_DEL##'
661     _WDIFF_ADD = '##WDIFF_ADD##'
662     _WDIFF_END = '##WDIFF_END##'
663
664     def _format_wdiff_output_as_html(self, wdiff):
665         wdiff = cgi.escape(wdiff)
666         wdiff = wdiff.replace(self._WDIFF_DEL, "<span class=del>")
667         wdiff = wdiff.replace(self._WDIFF_ADD, "<span class=add>")
668         wdiff = wdiff.replace(self._WDIFF_END, "</span>")
669         html = "<head><style>.del { background: #faa; } "
670         html += ".add { background: #afa; }</style></head>"
671         html += "<pre>%s</pre>" % wdiff
672         return html
673
674     def _wdiff_command(self, actual_filename, expected_filename):
675         executable = self._path_to_wdiff()
676         return [executable,
677                 "--start-delete=%s" % self._WDIFF_DEL,
678                 "--end-delete=%s" % self._WDIFF_END,
679                 "--start-insert=%s" % self._WDIFF_ADD,
680                 "--end-insert=%s" % self._WDIFF_END,
681                 actual_filename,
682                 expected_filename]
683
684     @staticmethod
685     def _handle_wdiff_error(script_error):
686         # Exit 1 means the files differed, any other exit code is an error.
687         if script_error.exit_code != 1:
688             raise script_error
689
690     def _run_wdiff(self, actual_filename, expected_filename):
691         """Runs wdiff and may throw exceptions.
692         This is mostly a hook for unit testing."""
693         # Diffs are treated as binary as they may include multiple files
694         # with conflicting encodings.  Thus we do not decode the output.
695         command = self._wdiff_command(actual_filename, expected_filename)
696         wdiff = self._executive.run_command(command, decode_output=False,
697             error_handler=self._handle_wdiff_error)
698         return self._format_wdiff_output_as_html(wdiff)
699
700     def wdiff_text(self, actual_filename, expected_filename):
701         """Returns a string of HTML indicating the word-level diff of the
702         contents of the two filenames. Returns an empty string if word-level
703         diffing isn't available."""
704         if not self._wdiff_available:
705             return ""
706         try:
707             # It's possible to raise a ScriptError we pass wdiff invalid paths.
708             return self._run_wdiff(actual_filename, expected_filename)
709         except OSError, e:
710             if e.errno in [errno.ENOENT, errno.EACCES, errno.ECHILD]:
711                 # Silently ignore cases where wdiff is missing.
712                 self._wdiff_available = False
713                 return ""
714             raise
715
716     # This is a class variable so we can test error output easily.
717     _pretty_patch_error_html = "Failed to run PrettyPatch, see error log."
718
719     def pretty_patch_text(self, diff_path):
720         if not self._pretty_patch_available:
721             return self._pretty_patch_error_html
722         command = ("ruby", "-I", self._filesystem.dirname(self._pretty_patch_path),
723                    self._pretty_patch_path, diff_path)
724         try:
725             # Diffs are treated as binary (we pass decode_output=False) as they
726             # may contain multiple files of conflicting encodings.
727             return self._executive.run_command(command, decode_output=False)
728         except OSError, e:
729             # If the system is missing ruby log the error and stop trying.
730             self._pretty_patch_available = False
731             _log.error("Failed to run PrettyPatch (%s): %s" % (command, e))
732             return self._pretty_patch_error_html
733         except ScriptError, e:
734             # If ruby failed to run for some reason, log the command
735             # output and stop trying.
736             self._pretty_patch_available = False
737             _log.error("Failed to run PrettyPatch (%s):\n%s" % (command,
738                        e.message_with_output()))
739             return self._pretty_patch_error_html
740
741     def default_configuration(self):
742         return self._config.default_configuration()
743
744     #
745     # PROTECTED ROUTINES
746     #
747     # The routines below should only be called by routines in this class
748     # or any of its subclasses.
749     #
750     def _webkit_build_directory(self, args):
751         return self._config.build_directory(args[0])
752
753     def _path_to_apache(self):
754         """Returns the full path to the apache binary.
755
756         This is needed only by ports that use the apache_http_server module."""
757         raise NotImplementedError('Port.path_to_apache')
758
759     def _path_to_apache_config_file(self):
760         """Returns the full path to the apache binary.
761
762         This is needed only by ports that use the apache_http_server module."""
763         raise NotImplementedError('Port.path_to_apache_config_file')
764
765     def _path_to_driver(self, configuration=None):
766         """Returns the full path to the test driver (DumpRenderTree)."""
767         raise NotImplementedError('Port._path_to_driver')
768
769     def _path_to_webcore_library(self):
770         """Returns the full path to a built copy of WebCore."""
771         raise NotImplementedError('Port.path_to_webcore_library')
772
773     def _path_to_helper(self):
774         """Returns the full path to the layout_test_helper binary, which
775         is used to help configure the system for the test run, or None
776         if no helper is needed.
777
778         This is likely only used by start/stop_helper()."""
779         raise NotImplementedError('Port._path_to_helper')
780
781     def _path_to_image_diff(self):
782         """Returns the full path to the image_diff binary, or None if it
783         is not available.
784
785         This is likely used only by diff_image()"""
786         raise NotImplementedError('Port.path_to_image_diff')
787
788     def _path_to_lighttpd(self):
789         """Returns the path to the LigHTTPd binary.
790
791         This is needed only by ports that use the http_server.py module."""
792         raise NotImplementedError('Port._path_to_lighttpd')
793
794     def _path_to_lighttpd_modules(self):
795         """Returns the path to the LigHTTPd modules directory.
796
797         This is needed only by ports that use the http_server.py module."""
798         raise NotImplementedError('Port._path_to_lighttpd_modules')
799
800     def _path_to_lighttpd_php(self):
801         """Returns the path to the LigHTTPd PHP executable.
802
803         This is needed only by ports that use the http_server.py module."""
804         raise NotImplementedError('Port._path_to_lighttpd_php')
805
806     def _path_to_wdiff(self):
807         """Returns the full path to the wdiff binary, or None if it is
808         not available.
809
810         This is likely used only by wdiff_text()"""
811         raise NotImplementedError('Port._path_to_wdiff')
812
813     def _shut_down_http_server(self, pid):
814         """Forcefully and synchronously kills the web server.
815
816         This routine should only be called from http_server.py or its
817         subclasses."""
818         raise NotImplementedError('Port._shut_down_http_server')
819
820     def _webkit_baseline_path(self, platform):
821         """Return the  full path to the top of the baseline tree for a
822         given platform."""
823         return self._filesystem.join(self.layout_tests_dir(), 'platform',
824                                      platform)
825
826
827 class DriverInput(object):
828     """Holds the input parameters for a driver."""
829
830     def __init__(self, filename, timeout, image_hash):
831         """Initializes a DriverInput object.
832
833         Args:
834           filename: Full path to the test.
835           timeout: Timeout in msecs the driver should use while running the test
836           image_hash: A image checksum which is used to avoid doing an image dump if
837                      the checksums match.
838         """
839         self.filename = filename
840         self.timeout = timeout
841         self.image_hash = image_hash
842
843
844 class DriverOutput(object):
845     """Groups information about a output from driver for easy passing of data."""
846
847     def __init__(self, text, image, image_hash,
848                  crash=False, test_time=None, timeout=False, error=''):
849         """Initializes a TestOutput object.
850
851         Args:
852           text: a text output
853           image: an image output
854           image_hash: a string containing the checksum of the image
855           crash: a boolean indicating whether the driver crashed on the test
856           test_time: a time which the test has taken
857           timeout: a boolean indicating whehter the test timed out
858           error: any unexpected or additional (or error) text output
859         """
860         self.text = text
861         self.image = image
862         self.image_hash = image_hash
863         self.crash = crash
864         self.test_time = test_time
865         self.timeout = timeout
866         self.error = error
867
868
869 class Driver:
870     """Abstract interface for the DumpRenderTree interface."""
871
872     def __init__(self, port, worker_number):
873         """Initialize a Driver to subsequently run tests.
874
875         Typically this routine will spawn DumpRenderTree in a config
876         ready for subsequent input.
877
878         port - reference back to the port object.
879         worker_number - identifier for a particular worker/driver instance
880         """
881         raise NotImplementedError('Driver.__init__')
882
883     def run_test(self, driver_input):
884         """Run a single test and return the results.
885
886         Note that it is okay if a test times out or crashes and leaves
887         the driver in an indeterminate state. The upper layers of the program
888         are responsible for cleaning up and ensuring things are okay.
889
890         Args:
891           driver_input: a DriverInput object
892
893         Returns a DriverOutput object.
894         """
895         raise NotImplementedError('Driver.run_test')
896
897     # FIXME: This is static so we can test it w/o creating a Base instance.
898     @classmethod
899     def _command_wrapper(cls, wrapper_option):
900         # Hook for injecting valgrind or other runtime instrumentation,
901         # used by e.g. tools/valgrind/valgrind_tests.py.
902         wrapper = []
903         browser_wrapper = os.environ.get("BROWSER_WRAPPER", None)
904         if browser_wrapper:
905             # FIXME: There seems to be no reason to use BROWSER_WRAPPER over --wrapper.
906             # Remove this code any time after the date listed below.
907             _log.error("BROWSER_WRAPPER is deprecated, please use --wrapper instead.")
908             _log.error("BROWSER_WRAPPER will be removed any time after June 1st 2010 and your scripts will break.")
909             wrapper += [browser_wrapper]
910
911         if wrapper_option:
912             wrapper += shlex.split(wrapper_option)
913         return wrapper
914
915     def poll(self):
916         """Returns None if the Driver is still running. Returns the returncode
917         if it has exited."""
918         raise NotImplementedError('Driver.poll')
919
920     def stop(self):
921         raise NotImplementedError('Driver.stop')
922
923
924 class TestConfiguration(object):
925     def __init__(self, port=None, os=None, version=None, architecture=None,
926                  build_type=None, graphics_type=None):
927
928         # FIXME: We can get the O/S and version from test_platform_name()
929         # and version() for now, but those should go away and be cleaned up
930         # with more generic methods like operation_system() and os_version()
931         # or something. Note that we need to strip the leading '-' off the
932         # version string if it is present.
933         if port:
934             port_version = port.version()
935         self.os = os or port.test_platform_name().replace(port_version, '')
936         self.version = version or port_version[1:]
937         self.architecture = architecture or 'x86'
938         self.build_type = build_type or port._options.configuration.lower()
939         self.graphics_type = graphics_type or port.graphics_type()
940
941     def items(self):
942         return self.__dict__.items()
943
944     def keys(self):
945         return self.__dict__.keys()
946
947     def __str__(self):
948         return ("<%(os)s, %(version)s, %(build_type)s, %(graphics_type)s>" %
949                 self.__dict__)
950
951     def __repr__(self):
952         return "TestConfig(os='%(os)s', version='%(version)s', architecture='%(architecture)s', build_type='%(build_type)s', graphics_type='%(graphics_type)s')" % self.__dict__
953
954     def values(self):
955         """Returns the configuration values of this instance as a tuple."""
956         return self.__dict__.values()
957
958     def all_test_configurations(self):
959         """Returns a sequence of the TestConfigurations the port supports."""
960         # By default, we assume we want to test every graphics type in
961         # every configuration on every system.
962         test_configurations = []
963         for system in self.all_systems():
964             for build_type in self.all_build_types():
965                 for graphics_type in self.all_graphics_types():
966                     test_configurations.append(TestConfiguration(
967                         os=system[0],
968                         version=system[1],
969                         architecture=system[2],
970                         build_type=build_type,
971                         graphics_type=graphics_type))
972         return test_configurations
973
974     def all_systems(self):
975         return (('mac', 'leopard', 'x86'),
976                 ('mac', 'snowleopard', 'x86'),
977                 ('win', 'xp', 'x86'),
978                 ('win', 'vista', 'x86'),
979                 ('win', 'win7', 'x86'),
980                 ('linux', 'hardy', 'x86'))
981
982     def all_build_types(self):
983         return ('debug', 'release')
984
985     def all_graphics_types(self):
986         return ('cpu', 'gpu')