<?php
    $title = "Writing New Tests";
    include("../header.inc");
?>

<h2>Writing New Tests</h2>

<p>A layout test is simply a web page. The layout test machinery renders the web page, and then dumps the
internal representation, the render tree, with details of the layout. This lets engineers working on the project know 
if they do anything that changes the layout. Once we get a test rendering properly, we check it in as part of the layout test suite.
</p>

<p>The following are some guidelines to follow when writing new layout tests:</p>

<ol>
<li>The test should be the smallest possible code fragment that tests the feature.
<li>The test should fit on one page (unless of course it&rsquo;s testing scrolling).
<li>The test should clearly describe what feature it is testing.
<li>The test should clearly describe the expected result.  It should be possible through visual inspection alone to determine that the test has
failed.
</ol>

<p>An example of a layout test that follows these guidelines is <tt>fast/events/event-creation.html</tt>.</p>


<p>A layout test should work both in the browser itself, and in the layout test tool. The layout test tool provides an 
additional object on the window object called the layout test controller with some methods that control test output. 
One you should know about is the <tt>layoutTestController.dumpAsText</tt> method. Calling this from JavaScript within a test arranges 
for the output to be written out as plain text rather than as a render tree dump. 
This is useful for tests that are testing something other than layout. The event creation test mentioned above is a good example of 
how to do this and when it makes sense.</p>

<p>Some tests require pixel-level comparisons.  For these tests, you must generate expected output for a specific
machine type, operating system, and color profile.  When you add such a test, you can generate new expected output
automatically using the <tt>run-webkit-tests --pixel</tt> command.  This will automatically
configure the color profile, and place the resulting rendered image (and checksum) in the appropriate platform
directory for checkin.</p>

<p><a href="http://www.hixie.ch/resources/fonts/">The Ahem font</a> is useful in testing text layout, since its
glyphs&rsquo; metrics are well known, and it is always available to tests running
in the layout test tool. However, if you want to view tests that use Ahem in Safari,
you should <a href="Ahem.ttf">download Ahem</a>, open it in the Font Book
application, and click on the Install Font button to install it.</p>

<p>The CSS working group has an excellent document on <a href="http://www.w3.org/Style/CSS/Test/guidelines.html">test writing guidelines</a> for CSS tests.  <a href="http://trac.webkit.org/wiki/Writing%20Layout%20Tests%20for%20DumpRenderTree">This wiki article</a> has more information on writing good tests and the DumpRenderTree tool.</p>

<?php
    include("../footer.inc");
?>