[Xmlgraphics-fop Wiki] Update of "VisualTestingFacility" 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/VisualTestingFacility

New page:
This page describes the visual testing facility found in the test/java/org/apache/fop/visual directory:

http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/test/java/org/apache/fop/visual/

= The idea =

There are several ways to test FOP's output. We have an approach which compares generated files against a set of reference files by checking the hash values of the files. These hashes may change simply due to a different timestamp in the metadata of the output file or after a tiny change in the sources which doesn't change the output. That makes the approach quite shaky and unattractive.

The layout engine tests are ideal to test the layout engine itself, but not the individual renderers. So even though the layout engine does the right thing, a renderer may still paint an element in the wrong place or not at all.

The middle way between the two approaches is to visually check and compare bitmaps generated from the output files created through FOP. Output from the Java2D renderer can be converted to bitmaps directly through our bitmap renderer. Output from PDF and PS can also be converted to bitmaps using external converters such as !GhostScript.

= What you (will) get =

 * You get bitmap versions of the output of each renderer (or at least for those output format we can create bitmaps from). You can put them aside from each other to do manual visual comparison.

 * You can automatically create a diff image of two bitmaps, so you can compare the output of two different renderers or against a reference bitmap stored elsewhere. (The code for that has been "borrowed" from the Apache Batik project.)

 * (TODO) You can let the facility create a simple website making all the processing results available on the web (potentially as part of a nightly build) through a simple navigation interface along with additional information such as warning and error messages. This can also be used as a demo case for FOP.

= The application =

Just run the {{org.apache.fop.visual.BatchDiffer}} class with a configuration file as sole parameter to the application.

= The configuration =

For simplicity, the configuration is done using an XML file and with the help of the Avalon Framework's configuration package. Here's a sample configuration file:

{{{
<?xml version="1.0" encoding="UTF-8"?>
<batch-diff>
  <!--source-directory>C:/Dev/FOP/main/trunk/examples/fo/basic</source-directory-->
  <!--source-directory>C:\Dev\FOP\main\trunk\test\layoutengine\testcases</source-directory-->
  <source-directory>C:\Dev\FOP\main\trunk\test\layoutengine\temp</source-directory>
  <filter-disabled>false</filter-disabled>
  <max-files>10</max-files>
  <target-directory>D:/Temp/diff-out</target-directory>
  <resolution>100</resolution>
  <stylesheet>C:\Dev\FOP\main\trunk\test\layoutengine\testcase2fo.xsl</stylesheet>
  <producers>
    <producer classname="org.apache.fop.visual.BitmapProducerPDF">
      <converter>C:\Dev\GhostScript\gs8.50\bin\gswin32c -sDEVICE=pngalpha -dNOPAUSE -dBATCH -dSAFER -r{2} -dFirstPage=1 -dLastPage=1 -sOutputFile="{1}" "{0}"</converter>
      <delete-temp-files>true</delete-temp-files>
    </producer>
    <producer classname="org.apache.fop.visual.BitmapProducerPS">
      <converter>C:\Dev\GhostScript\gs8.50\bin\gswin32c -sDEVICE=pngalpha -dNOPAUSE -dBATCH -dSAFER -r{2} -dFirstPage=1 -dLastPage=1 -sOutputFile="{1}" "{0}"</converter>
      <delete-temp-files>true</delete-temp-files>
    </producer>
    <producer classname="org.apache.fop.visual.BitmapProducerJava2D">
      <delete-temp-files>true</delete-temp-files>
    </producer>
    <!--producer classname="org.apache.fop.visual.ReferenceBitmapLoader">
      <directory>D:/Temp/diff-bitmaps</directory>
    </producer-->
  </producers>
</batch-diff>
}}}

The details on the configuration values can be found in the javadocs of !BatchDiffer and the !BitmapProducer implementations.

The above sample file shows how to use an external !GhostScript to convert PDF and PS to bitmaps. But you can also use any other external converter that does the job. For licensing reasons, the code is designed not to have any direct reference to !GhostScript or any other external converter. You simply have to provide the right command-line to call your own converter.

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