[prev in list] [next in list] [prev in thread] [next in thread] 

List:       fop-cvs
Subject:    [Xmlgraphics-fop Wiki] Update of "HowToCreateLayoutEngineTests" by
From:       Apache Wiki <wikidiffs () apache ! org>
Date:       2005-05-27 12:56:37
Message-ID: 20050527125637.21759.68293 () ajax ! apache ! org
[Download RAW message or body]

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


[prev in list] [next in list] [prev in thread] [next in thread]