[Xmlgraphics-fop Wiki] Update of "HowToCreateLayoutEngineTests" by JeremiasMaerki

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Xmlgraphics-fop Wiki" for change notification.

The following page has been changed by JeremiasMaerki:
http://wiki.apache.org/xmlgraphics-fop/HowToCreateLayoutEngineTests

The comment on the change is:
Documentation for the layout engine tests

New page:
This page describes how to create "Layout Engine Test Cases".

== Where are they? ==

You can find the test cases in the following directory:

{{{test/layoutengine}}}

http://cvs.apache.org/viewcvs.cgi/xml-fop/test/layoutengine/

== How do I run them? ==

The easiest way is to simply run the FOP build process. There's an Ant target called "junit" that runs all of FOP's enabled tests.

Or you can setup FOP in your favourite Java IDE and run the JUnit tests from there.

Please note that there is a file "disabled-testcases.txt" which contains a list of file names. These are the tests which are by default excluded from the JUnit tests. Tests listed here currently fail and are kept as a reminder for those who fix bugs or implement missing features.

== How does it work? ==

The tests are basically XML files with a predefined structure. Here's the raw structure:

{{{
<testcase>
  <info>
    <p>
      This test checks <something>.....
    </p>
  </info>
  <fo>
    <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format" xmlns:svg="http://www.w3.org/2000/svg">
      <fo:layout-master-set>

        <!-- etc. etc. -->

    </fo:root>
  </fo>
  <checks>
    <eval expected="0 0 360000 360000" xpath="/areaTree/pageSequence/pageViewport/@bounds" desc="page size"/>
    <true xpath="/areaTree/pageSequence/pageViewport/page[1]"/>
    <true xpath="not(/areaTree/pageSequence/pageViewport/page[2])"/>
    <eval expected="0 0 360000 360000" xpath="/areaTree/pageSequence/pageViewport/page[1]/regionViewport/@rect" desc="region body area"/>
  </checks>
</testcase>
}}}

 * The first part ("info") simply contains some information what the test case does.

 * The second part ("fo") contains a full XSL-FO document.

 * The third part ("checks") contains all the checks for this test. See below for details.

Now, when you are creating a test case you can use the XSLT stylesheet called "testcase2fo.xsl" if you want to manually run it through FOP (or any other XSL-FO implementation). The stylesheet basically extracts the XSL-FO document from the XML file.

When the JUnit checks for the layout engine are run, the following happens. The checks are extracted from the XML file and each of them is checked against the result from a FOP processing run. Most tests will check against the "Area Tree XML" that is generated by FOP's XMLRenderer. From the command-line you can access it if you use "-at" instead of "-pdf", for example.

== What checks do I have available? ==

=== true ===

Format: 
{{{
<true xpath="[XPath expression which results in a boolean value (true or false)]"/>
}}}

If the XPath expression results to anything else than "true" the test fails.

=== eval ===

Format:
{{{
<eval expected="[expected value]" xpath="[XPath expression]"/>
}}}

This is similar to the first check, but here you can specify an expected value the XPath expression has to result into. Generally you get a more descriptive error message if such a test fails than with "true".

=== element-list ===

Format:
{{{
<element-list category="[category]" id="[id]" index="[index]">
  (box|penalty|glue|skip)*
</element-list>
}}}

This kind of check is mostly for those who know how the Knuth element list approach works. So this is mostly for developers only. With this check you can intercept an element list that is generated during layout.

 * "category" must be one of: "breaker" or "table-cell" (more may be added later)

 * "id" is optional and can be used to identify a specific element list coming from an FO node with the given ID. This works great for table-cells, for example.

 * "index" is also optional and can be used if you don't have an "id" but still more than one element lists of the same category. The index is zero-based.

{{{
<box w="[length]"/>

<penalty w="[length]" p="[p]" flagged="[boolean]" aux="[boolean]"/> <!-- p can also be "INF" or "-INF" -->

<glue w="[length]"/> <!-- stretch and shrink are NYI -->

<skip>[integer]</skip> <!-- can be used to skip n elements in the list -->
}}}

== How to create additional kinds of checks? ==

You can easily implement new checks by subclassing {{{org.apache.fop.layoutengine.LayoutEngineCheck}}}. When you do that be sure to register the new class in the static initialization block in {{{org.apache.fop.layoutengine.LayoutEngineTester}}}.

---------------------------------------------------------------------
To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org