Re: [Xmlgraphics-fop Wiki] Update of "HowToCreateLayoutEngineTests" by VincentHennebert

[Vincent Hennebert <vh...@gmail.com>]

Hi,

Now that the inline-container branch has been merged back into trunk, it
is possible to checks for events triggered when processing layout tests.

I’d like to encourage anyone writing layout tests to use that feature
and add in their tests checks for the events they are expecting. Indeed,
such events won’t be passed on to the standard output like is the case
now. That will help to keep the output clean.

Eventually, we can add such checks to existing test cases and
progressively sanitize the output. That will make it easier to spot
those tests that issue unexpected warnings, that we want to fix.

Thanks,
Vincent


On 29/01/14 14:02, Apache Wiki wrote:
> Dear Wiki user,
>
> You have subscribed to a wiki page or wiki category on "Xmlgraphics-fop Wiki" for change notification.
>
> The "HowToCreateLayoutEngineTests" page has been changed by VincentHennebert:
> https://wiki.apache.org/xmlgraphics-fop/HowToCreateLayoutEngineTests?action=diff&rev1=13&rev2=14
>
> Comment:
> Added doc about new event check
>
>    When you run test cases the generated Area Tree XML is written to the {{{build/test-results/layoutengine}}} directory.
>
>    == What checks do I have available? ==
> + === Area Tree Checks ===
> - === true ===
> + ==== true ====
>    Format:
>
>    {{{
> @@ -112, +113 @@
>
>    }}}
>    If the XPath expression results to anything else than "true" the test fails. The fail-msg can be used to supply a custom error message when the check fails. The fail-msg attribute is optional.
>
> - === eval ===
> + ==== eval ====
>    Format:
>
>    {{{
> @@ -120, +121 @@
>
>    }}}
>    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". You can use the optional "tolerance" value to specify a tolerance for number comparisons.
>
> - === element-list ===
> + ==== element-list ====
>    Format:
>
>    {{{
> @@ -145, +146 @@
>
>
>    <skip>[integer]</skip> <!-- can be used to skip n elements in the list -->
>    }}}
> +
> + === Event Check ===
> + It is possible to check that certain [[http://xmlgraphics.apache.org/fop/trunk/events.html|events]] have occurred while processing the tests, and that (some of) its parameters match expected values. For example:
> + {{{
> + <event-checks>
> +   <event key="inlineContainerAutoIPDNotSupported" fallback="300.0"/>
> + </event-checks>
> + }}}
> +
> + The general format is:
> + {{{
> + <event key="[key as returned by Event.getEventKey()]" [param1="expected value1" param2="expected value2" ...]/>
> + }}}
> +
> + In theory we should check on the event ID rather than its key to avoid any ambiguity, but that would be impractical (the full ID of the event shown in the example is "org.apache.fop.layoutmgr.!BlockLevelEventProducer.inlineContainerAutoIPDNotSupported"...). In practice, the key alone will be enough to distinguish events.
> +
> + It is possible to specify only the subset of the event's parameters that is of interest. The expected value should be what the {{{toString}}} method called on the parameter would return.
> +
> + The event checker will process events sequentially. If several events with the same key are expected, then they will be checked in the order given against the sequence of actual events. The checker will not skip one event in an attempt to find a subsequent one that matches. This is to avoid a lack of precision in the event checking. That means that if we want to check one event, then we must also add checks for all the previous events with the same key.
> +
> + For example, if two "inlineContainerAutoIPDNotSupported" events are expected, one with a fallback value of 300 and one with a fallback value of 100, and we are interested in checking the second one, then the we must still add a check for the first one. Otherwise, the checker has no means to determine whether the test should fail because the first event has a fallback value of 300 while 100 was expected, or whether it should pass because the first event should be ignored and the second one does have a fallback value of 100.
> +
> + Events that are not checked will be passed on to a regular !EventListener that will typically display the corresponding message on the standard output.
> +
>    == 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}}}.