wiki:Writing DumpAsMarkup Tests

Version 2 (modified by rniwa@webkit.org, 9 years ago) (diff)

Updated "How to Use" to match the recent changes

Benefits of dumpAsMarkup Tests

  • Platform independent - dumpAsMarkup outputs plain text as the expected results and can be shared among all platforms.
  • Easier to read expected results - dumpAsMarkup's output is HTML with extra annotation.

Limitation

  • Can't test rendering - Since dumpAsMarkup test does not produce .png files or render tree outputs, we can't use dumpAsMarkup to test the correctness of rendering.

How to Use

Including the following line makes your layout test a dumpAsMarkup test:

<script src="<path to LayoutTests>/resources/dump-as-markup.js"></script>

dump-as-markup.js then outputs the DOM tree on the page load on DRT. If your test requires the test to be continued after the page load (e.g. uses setTimeout), then call Markup.waitUntilDone() before the page loads and Markup.notifyDone() to output the results and finish the test. Markup's waitUntilDone and notifyDone automatically calls layoutTestController's counterparts.

For example, if I have:

<script src="../../resources/dump-as-markup.js"></script>
<div id=foo>This is a dumpAsMarkup test.</div>
<script> window.getSelection().selectAllChildren(foo); </script>

I get:

| <html>
|   <head>
|     <script>
|       src="../../resources/dump-as-markup.js"
|     "
"
|   <body>
|     <div>
|       id="foo"
|       "<#selection-anchor>This is a dumpAsMarkup test.<#selection-focus>"
|     "
"
|     <script>
|       " window.getSelection().selectAllChildren(foo); "
|     "
"

Notice <selection-*> shows where the selection / caret is and double quotation wraps each text node on the page.

Output Subtree

If you want to output a subtree of the DOM, call Markup.setNodeToDump(<node>) where <node> is a HTMLElement object for which you want to print the subtree. You can also specify the id of an element.

For example, if I have:

<script src="../../resources/dump-as-markup.js"></script>
<div id="test"><a href="http://webkit.org/">WebKit</a> is <strong>awesome</strong></div>
<p>But cluttered expected result sucks :(</p>
<script>
Markup.description('This is a dumpAsMarkup test.')
Markup.setNodeToDump('test')
</script>

I get:

This is a dumpAsMarkup test.

<DIV id="test">
<A href="http://webkit.org/">
<#text>WebKit</#text>
</A>
<#text> is </#text>
<STRONG>
<#text>awesome</#text>
</STRONG>
</DIV>

Note "This is a dumpAsMarkup test." is added by Markup.description. The sentence will not be printed in DRT if we had it in a div like the earlier example because the entire document body is replaced by the output.

Dump Multiple Times

To dump the entire DOM or a subtree multiple times, call Markup.dump(<node>, <description>).

For example, if I have:

<script src="../../resources/dump-as-markup.js"></script>
<div id="test"><a href="http://webkit.org/">WebKit</a> is <strong>awesome</strong></div>
<p>But cluttered expected result sucks :(</p>
<script>
Markup.description('This test calls dump twice.')
Markup.setNodeToDump('test')
Markup.dump('test', 'before change')
document.getElementById('test').lastChild.innerText += ' because of you!'
Markup.dump(null, 'after change')
</script>

I get:

This test calls dump twice.

before change:
<DIV id="test">
<A href="http://webkit.org/">
<#text>WebKit</#text>
</A>
<#text> is </#text>
<STRONG>
<#text>awesome</#text>
</STRONG>
</DIV>

after change:
<DIV id="test">
<A href="http://webkit.org/">
<#text>WebKit</#text>
</A>
<#text> is </#text>
<STRONG>
<#text>awesome because of you!</#text>
</STRONG>
</DIV>

Notice that I call dump twice and the DOM is dumped exactly twice (onload didn't dump). You may still use Markup.waitUntilDone() and Markup.notifyDone() to avoid DRT finishing the test prematurely.

Note: as is implemented, the script adds pre element at the end of the document temporarily when you call dump and your script should not interfere with those pre tags.