| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| |
| |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" /> |
| <!-- |
| <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css"> |
| --> |
| <link rel="stylesheet" type="text/css" media="screen" href="https://www.apache.org/css/code.css"> |
| <link href="/css/profile.css" rel="stylesheet" type="text/css" /> |
| <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css" /> |
| <link href="/css/print.css" rel="stylesheet" type="text/css" media="print" /> |
| |
| <script src="https://code.jquery.com/jquery.min.js"></script> |
| <script type="text/javascript" src="/js/jquery.stoc.js"></script> |
| <script> |
| $(document).ready(function(){ |
| $('ul#navigation a').each(function() { |
| if (this.href === window.location.href) |
| { $(this). attr('id', 'forefront');} |
| }); |
| $('ul#navigation a#forefront').each(function() { |
| |
| }); |
| }) |
| $(function(){ |
| $("#items").stoc({ search: "#content", stocTitle: "<h3>Page Contents</h3>" }); |
| }); |
| </script> |
| |
| |
| |
| <style> |
| .highlight {color: red;} |
| </style> |
| |
| </head> |
| |
| <body> |
| |
| <div id="banner"> |
| </div> |
| |
| <div id="navigation"> |
| <style type="text/css"> |
| /* The following code is added by mdx_elementid.py |
| It was originally lifted from http://subversion.apache.org/style/site.css */ |
| /* |
| * Hide class="elementid-permalink", except when an enclosing heading |
| * has the :hover property. |
| */ |
| .headerlink, .elementid-permalink { |
| visibility: hidden; |
| } |
| h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> |
| <p><a href="/"><img alt="Apache XML Graphics Project Logo" src="/images/apache-xml-graphics.gif" title="Apache XML Graphics Project" /></a></p> |
| <h1 id="apache-batik">Apache Batik<a class="headerlink" href="#apache-batik" title="Permanent link">¶</a></h1> |
| <ul> |
| <li><a href="/batik/">Overview</a></li> |
| <li><a href="/batik/license.html">License</a></li> |
| <li><a href="/batik/download.html">Download</a></li> |
| <li><a href="/batik/install.html">Notes</a></li> |
| <li><a href="/batik/status.html">Status</a></li> |
| <li><a href="/batik/demo-static.html">Demo</a></li> |
| <li><a href="/batik/faq.html">FAQs</a></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/XMLGRAPHICSBATIK">Batik Wiki</a></li> |
| <li><a href="/batik/mailing-lists.html">Mailing lists</a></li> |
| <li><a href="/batik/contributors.html">Contributors</a></li> |
| <li><a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20BATIK%20AND%20resolution%20%3D%20Unresolved%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20ORDER%20BY%20priority%20DESC">Bug database</a></li> |
| <li><a href="/batik/uses.html">Projects using Batik</a></li> |
| <li> |
| <h2 id="batik-tools">Batik Tools<a class="headerlink" href="#batik-tools" title="Permanent link">¶</a></h2> |
| <ul> |
| <li><a href="/batik/tools/">Overview</a></li> |
| <li><a href="/batik/tools/browser.html">Browser</a></li> |
| <li><a href="/batik/tools/rasterizer.html">Rasterizer</a></li> |
| <li><a href="/batik/tools/font-converter.html">Font converter</a></li> |
| <li><a href="/batik/tools/pretty-printer.html">Pretty printer</a></li> |
| </ul> |
| </li> |
| <li> |
| <h2 id="using-batik">Using Batik<a class="headerlink" href="#using-batik" title="Permanent link">¶</a></h2> |
| <ul> |
| <li><a href="/batik/using/">Overview</a></li> |
| <li><a href="/batik/using/architecture.html">Architecture</a></li> |
| <li><a href="/batik/javadoc/">Javadoc APIs</a></li> |
| <li><a href="/batik/using/dom-api.html">DOM API</a></li> |
| <li><a href="/batik/using/parsers.html">Parsers</a></li> |
| <li> |
| <h3 id="scripting">Scripting<a class="headerlink" href="#scripting" title="Permanent link">¶</a></h3> |
| </li> |
| <li><a href="/batik/using/scripting/ecmascript.html">Scripting with ECMAScript</a></li> |
| <li><a href="/batik/using/scripting/java.html">Scripting with Java</a></li> |
| <li><a href="/batik/using/scripting/security.html">Scripting with Security</a></li> |
| <li><a href="/batik/using/svg-generator.html">SVG generator</a></li> |
| <li><a href="/batik/using/swing.html">Swing components</a></li> |
| <li><a href="/batik/using/transcoder.html">Transcoder API</a></li> |
| <li><a href="/batik/using/extending.html">Extending Batik</a></li> |
| </ul> |
| </li> |
| <li> |
| <h2 id="development">Development<a class="headerlink" href="#development" title="Permanent link">¶</a></h2> |
| <ul> |
| <li><a href="/batik/dev/">Overview</a></li> |
| <li><a href="/batik/dev/branches.html">Branches</a></li> |
| <li><a href="/batik/dev/svg12.html">SVG 1.2 support</a></li> |
| <li><a href="/batik/dev/test.html">Test infrastructure</a></li> |
| </ul> |
| </li> |
| </ul> |
| <h1 id="apache-xml-graphics">Apache™ XML Graphics<a class="headerlink" href="#apache-xml-graphics" title="Permanent link">¶</a></h1> |
| <ul> |
| <li> |
| <h3 id="project-overview">Project Overview<a class="headerlink" href="#project-overview" title="Permanent link">¶</a></h3> |
| <ul> |
| <li><a href="/team.html">Who We Are</a></li> |
| <li><a href="/legal.html">Legal Stuff</a></li> |
| <li><a href="/charter.html">Project Charter</a></li> |
| <li><a href="/mail.html">Mailing Lists</a></li> |
| <li><a href="/repo.html">Code Repositories</a></li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li> |
| <li><a href="https://www.apache.org/foundation/thanks.html">ASF Thanks</a></li> |
| <li><a href="https://www.apache.org/licenses/">Licenses</a></li> |
| <li><a href="/security.html">Apache XML Graphics Security</a></li> |
| <li><a href="https://www.apache.org/security/">ASF Security</a></li> |
| </ul> |
| </li> |
| </ul> |
| <h1 id="sub-projects">Sub Projects<a class="headerlink" href="#sub-projects" title="Permanent link">¶</a></h1> |
| <ul> |
| <li><a href="/fop/">Apache FOP</a></li> |
| <li><a href="/commons/">Apache XML Graphics Commons</a></li> |
| </ul> |
| <h2 id="search-apache-xml-graphics">Search Apache XML Graphics<a class="headerlink" href="#search-apache-xml-graphics" title="Permanent link">¶</a></h2> |
| <form name="search" id="search" action="https://www.google.com/search" method="get"> |
| <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/> |
| <input type="text" name="q" id="query" /> |
| <input type="submit" id="submit" value="Search" /> |
| </form> |
| |
| <h3 id="apachecon-n-america">ApacheCon N. America<a class="headerlink" href="#apachecon-n-america" title="Permanent link">¶</a></h3> |
| <p><a title="ApacheCon North America" href="https://www.apachecon.com"><img class="apachecon_logo" alt="ApacheCon North America" src="https://www.apachecon.com/images/landingpage/apachecon-logo.png" width="200" /></a><br /><br /></p> |
| <ul> |
| <li><strong><a href="https://www.apachecon.com/">ApacheCon NA</a></strong></li> |
| </ul> |
| <p>Hope to see you there!</p> |
| <h3 id="apachecon-europe">ApacheCon Europe<a class="headerlink" href="#apachecon-europe" title="Permanent link">¶</a></h3> |
| <p><a title="ApacheCon Europe" href="https://www.apachecon.com"><img class="apachecon_logo" alt="ApacheCon Europe" src="https://www.apachecon.com/images/landingpage/apachecon-logo.png" width="200" /></a><br /><br /></p> |
| <ul> |
| <li><strong><a href="https://www.apachecon.com/">ApacheCon Europe</a></strong></li> |
| </ul> |
| <p>Hope to see you there!</p> |
| <p><a title="Apache Software Foundation" href="https://www.apache.org"><img id="asf_logo_url" alt="Apache Software Foundation " src="/images/asf_logo_url.png" width="200" /></a><br /><br /></p> |
| <p><a title="Support the Apache Software Foundation" href="https://donate.apache.org/"><img id="asf_support_url" alt="Support the Apache Software Foundation " src="https://blogs.apache.org/foundation/mediaresource/d67ca611-a57c-462d-ac23-95063f81d175" width="200" /></a></p> |
| <script> |
| $(document).ready(function () { |
| $('#navigation :header').click(function () { |
| var text = $(this).siblings('ul'); |
| if (text.is(':hidden')) { |
| text.slideDown('200'); |
| } else { |
| text.slideUp('200'); |
| } |
| }); |
| if ($('#navigation :header').siblings('ul')) { |
| $('#navigation :header').append(' »'); |
| } |
| $('#navigation > ul > li ul').hide(); |
| var str=location.href.toLowerCase(); |
| $("#navigation li a").each(function() { |
| if (str.indexOf(this.href.toLowerCase()) > -1) { |
| $(this).parents().slideDown('200'); |
| $("li.highlight").removeClass("highlight"); |
| $(this).parent().addClass("highlight"); |
| } |
| }); |
| }) |
| </script> </div> |
| |
| <div id="bannertext" style="border-bottom: 2px dashed #666666; height: 100px;"> |
| <a href="/batik/"><img src="/images/apache-batik-logo.png" alt="The Apache FOP Project" width="256" height="96" style="float:left; margin-right: 15px;" /></a> |
| <h2>The Apache™ Batik Project</h2> |
| </div> |
| |
| <h1>Test infrastructure</h1> |
| |
| |
| <h1>Test infrastructure</h1> |
| <p>This document describes the Batik test infrastructure whose goals are to:</p> |
| <ul> |
| <li> |
| <p>make it easy to detect regressions,</p> |
| </li> |
| <li> |
| <p>make it easy to run test suites, and</p> |
| </li> |
| <li> |
| <p>make it easy to write new tests and add them to an existing test suite.</p> |
| </li> |
| </ul> |
| <p>The intent for the test infrastructure is that it grows along with Batik and keeps monitoring the health of the code base.</p> |
| <p>While the test suites in the infrastructure will be run every day by build/test machines, they are also intended to help the committers and developers get confident that their code modifications did not introduce regressions.</p> |
| <h2 id="infrastructure">The test infrastructure</h2> |
| <h3 id="High-level-interfaces">High-level interfaces</h3> |
| <p>The following are the high level interfaces in the infrastructure.</p> |
| <p><a href="../javadoc/org/apache/batik/test/Test.html">Test</a> |
| : |
| A <code>Test</code> is performing whatever check is needed in its <code>run</code> method, and each run produces a <code>TestReport</code>.</p> |
| <p><a href="../javadoc/org/apache/batik/test/TestReport.html">TestReport</a> |
| : |
| A <code>TestReport</code> describes whether a <code>Test</code> run passed or failed and provides a description of the failure in terms of an error code (unique in the context of a given <code>Test</code>) and a set of key/value pairs.</p> |
| <p><a href="../javadoc/org/apache/batik/test/TestSuite.html">TestSuite</a> |
| : |
| A <code>TestSuite</code> is a test aggregation which can run a set of <code>Test</code> instances.</p> |
| <p><a href="../javadoc/org/apache/batik/test/TestReportProcessor.html">TestReportProcessor</a> |
| : |
| A <code>TestReportProcessor</code> is used to analyze a <code>TestReport</code>. A specific implementation can choose to create graphs, send an email or write an HTML file.</p> |
| <h3 id="Default-implementations">Default implementations</h3> |
| <p>The test infrastructure comes with a number of default implementations for the interfaces described above. Specifically:</p> |
| <p><a href="../javadoc/org/apache/batik/test/AbstractTest.html">AbstractTest</a> |
| : |
| This implementation of the <code>Test</code> interface is intended to make it easier to write a “safe” <code>Test</code> implementation. See the <a href="#writingNewTests">Writing new tests</a> section for a description of how to use that class.</p> |
| <p><a href="../javadoc/org/apache/batik/test/DefaultTestReport.html">DefaultTestReport</a> |
| : |
| This class provides a simple implementation of the <code>TestReport</code> interface that most <code>Test</code> implementations will be able to use. See the <a href="#writingNewTests">Writing new tests</a> section for more details.</p> |
| <p><a href="../javadoc/org/apache/batik/test/DefaultTestSuite.html">DefaultTestSuite</a> |
| : |
| This class provides an implementation of the <code>TestSuite</code> interface and makes it easy to aggregate <code>Test</code> instances.</p> |
| <p><a href="../javadoc/org/apache/batik/test/SimpleTestReportProcessor.html">SimpleTestReportProcessor</a> |
| : |
| This class is a sample <code>TestReportProcessor</code> implementation that simply traces the content of a <code>TestReport</code> to an output stream.</p> |
| <p><a href="../javadoc/org/apache/batik/test/TestReportMailer.html">TestReportMailer</a> |
| : |
| This is another implementation of the <code>TestReportProcessor</code> interface that emails a test report to a list of destination e-mail addresses.</p> |
| <h3 id="XML-implementations">XML implementations</h3> |
| <p>The test infrastructure is using XML-out (and XML-in too, see the <a href="#runningATestSuite">Running a test suite</a> section) as a favorite way to generate test reports. The <a href="../javadoc/org/apache/batik/test/XMLTestReportProcessor.html">XMLTestReportProcessor</a> implementation of the <code>TestReportProcessor</code> interface. It outputs reports in XML in a configurable directory.</p> |
| <p>The <code>XMLTestReportProcessor</code> can notify an <a href="../javadoc/org/apache/batik/test/XMLReportConsumer.html">XMLReportConsumer</a> when it has created a new report. There is one implementation of that interface that can run an XSL stylesheet on the XML report (e.g., to generate an HTML report), called <a href="../javadoc/org/apache/batik/test/XSLXMLReportConsumer.html">XSLXMLReportConsumer</a>. This is used by the <code>regard</code> rule in the Batik build to produce an HTML report for the default regression test suite.</p> |
| <h2 id="managingATestSuite">Managing test suites</h2> |
| <p>The infrastructure is designed to make it easy to create, update and modify test suites. This section describes how to describe a set of tests to be run and how to actually run that test suite.</p> |
| <h3 id="Describing-a-test-suite">Describing a test suite</h3> |
| <p>Test suites can be described in XML (XML-in refered to earlier in this document). The general format for describing a test suite is:</p> |
| <div class="highlight"><pre><span></span><span class="nt"><testSuite</span> <span class="na">id=</span><span class="s">"testSuiteA"</span> <span class="na">name=</span><span class="s">"MyFavoriteTestSuite"</span><span class="nt">></span> |
| <span class="c"><!-- Set of tests to be run --></span> |
| <span class="nt"><test</span> <span class="na">id=</span><span class="s">"t1"</span> <span class="na">class=</span><span class="s">"myFavoriteTestClassA"</span><span class="nt">/></span> |
| <span class="nt"><test</span> <span class="na">id=</span><span class="s">"t2"</span> <span class="na">class=</span><span class="s">"myFavoriteTestClassB"</span><span class="nt">/></span> |
| <span class="nt"><test</span> <span class="na">id=</span><span class="s">"t3"</span> <span class="na">class=</span><span class="s">"myFavoriteTestClassC"</span><span class="nt">/></span> |
| <span class="nt"></testSuite></span> |
| </pre></div> |
| |
| |
| <p>Note that tests can be grouped in <code>testGroup</code> elements, which can have their own <code>id</code> and <code>class</code> attributes. This is useful because it allows developers to run specific tests or test groups by specifying their IDs. In addition, because the class attribute is inherited by a <code>test</code> element from its parent, <code>testGroup</code> s allow the developers to group tests which use the same class and specify that class on the group.</p> |
| <p><code>Test</code> instances listed in a test suite can have arguments passed to them, as defined by the test class. These arguments are passed in using <code>arg</code> child elements.</p> |
| <p>The following example shows a test suite with two tests:</p> |
| <div class="highlight"><pre><span></span><span class="nt"><testSuite</span> <span class="na">id=</span><span class="s">"sampleTestSuite"</span> <span class="na">name=</span><span class="s">"SAMPLE TEST SUITE"</span><span class="nt">></span> |
| |
| <span class="c"><!-- ========================================================================== --></span> |
| <span class="c"><!-- Validates that the SVGRenderingAccuracyTest class is operating as expected --></span> |
| <span class="c"><!-- ========================================================================== --></span> |
| <span class="nt"><test</span> <span class="na">id=</span><span class="s">"renderingAccuracyTest"</span> <span class="na">class=</span><span class="s">"org.apache.batik.test.svg.SVGRenderingAccuracyTestValidator"</span><span class="nt">/></span> |
| |
| <span class="c"><!-- ========================================================================== --></span> |
| <span class="c"><!-- Rendering regression tests --></span> |
| <span class="c"><!-- ========================================================================== --></span> |
| <span class="nt"><test</span> <span class="na">id=</span><span class="s">"anne.svg"</span> <span class="na">class=</span><span class="s">"org.apache.batik.test.svg.SVGRenderingAccuracyTest"</span><span class="nt">></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.net.URL"</span> |
| <span class="na">value=</span><span class="s">"file:samples/anne.svg"</span><span class="nt">/></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.net.URL"</span> |
| <span class="na">value=</span><span class="s">"file:test-references/samples/solaris/anne.png"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"VariationURL"</span> |
| <span class="na">class=</span><span class="s">"java.net.URL"</span> |
| <span class="na">value=</span><span class="s">"file:test-references/samples/variation/anne.png"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"SaveVariation"</span> |
| <span class="na">class=</span><span class="s">"java.io.File"</span> |
| <span class="na">value=</span><span class="s">"test-references/samples/variation-candidate/anne.png"</span><span class="nt">/></span> |
| <span class="nt"></test></span> |
| |
| <span class="nt"></testSuite></span> |
| </pre></div> |
| |
| |
| <h2 id="runningATestSuite">Running a test suite</h2> |
| <p>Yet another XML file describes which test to run and how to process the generated test reports. The general syntax is something like:</p> |
| <div class="highlight"><pre><span></span><span class="nt"><testRun</span> <span class="na">id=</span><span class="s">"regard"</span> <span class="na">name=</span><span class="s">"Test Run Name Here"</span><span class="nt">></span> |
| |
| <span class="c"><!-- =================================== --></span> |
| <span class="c"><!-- Descriptions of processors that --></span> |
| <span class="c"><!-- will process the results of the --></span> |
| <span class="c"><!-- test suite --></span> |
| <span class="c"><!-- =================================== --></span> |
| <span class="nt"><testReportProcessor</span> <span class="na">class=</span><span class="s">"myFavoriteReportProcessorA"</span><span class="nt">/></span> |
| <span class="nt"><testReportProcessor</span> <span class="na">class=</span><span class="s">"myFavoriteReportProcessorB"</span><span class="nt">/></span> |
| |
| <span class="c"><!-- =================================== --></span> |
| <span class="c"><!-- Set of test suite to run. They will --></span> |
| <span class="c"><!-- produce TestReports. --></span> |
| <span class="c"><!-- =================================== --></span> |
| <span class="nt"><testSuite</span> <span class="na">href=</span><span class="s">"http://url.to.my.first.test.suite"</span><span class="nt">/></span> |
| <span class="nt"><testSuite</span> <span class="na">href=</span><span class="s">"http://url.to.my.second.test.suite"</span><span class="nt">/></span> |
| |
| <span class="nt"></testRun></span> |
| </pre></div> |
| |
| |
| <p><code>testRun</code> elements can be nested. In a nutshell, you can specify a set of <code>TestReportProcessor</code> s which should process the <code>TestReport</code> generated by the <code>TestSuite</code> built from the list of <code>Test</code> instances described in the files referenced by the <code>testSuite</code> elements.</p> |
| <p>For example:</p> |
| <div class="highlight"><pre><span></span><span class="nt"><testRun</span> <span class="na">name=</span><span class="s">"Batik Standard Regression Test Run"</span><span class="nt">></span> |
| |
| <span class="nt"><testRun</span> <span class="na">name=</span><span class="s">"REGARD"</span><span class="nt">></span> |
| <span class="nt"><testReportProcessor</span> <span class="na">class=</span><span class="s">"org.apache.batik.test.xml.XMLTestReportProcessor"</span><span class="nt">></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"org.apache.batik.test.xml.XSLXMLReportConsumer"</span><span class="nt">></span> |
| <span class="c"><!-- Stylesheet --></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.lang.String"</span> <span class="na">value=</span><span class="s">"file:test-resources/org/apache/batik/test/svg/HTMLReport.xsl"</span><span class="nt">/></span> |
| <span class="c"><!-- Ouput Directory --></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.lang.String"</span> <span class="na">value=</span><span class="s">"test-reports/html"</span><span class="nt">/></span> |
| <span class="c"><!-- Output file prefix --></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.lang.String"</span> <span class="na">value=</span><span class="s">"RegardResult"</span><span class="nt">/></span> |
| <span class="c"><!-- Output file suffix --></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.lang.String"</span> <span class="na">value=</span><span class="s">".html"</span><span class="nt">/></span> |
| <span class="nt"></arg></span> |
| <span class="nt"></testReportProcessor></span> |
| |
| <span class="nt"><testSuite</span> <span class="na">href=</span><span class="s">"file:test-resources/org/apache/batik/test/samplesRendering.xml"</span><span class="nt">/></span> |
| <span class="nt"><testSuite</span> <span class="na">href=</span><span class="s">"file:test-resources/org/apache/batik/svggen/regsvggen.xml"</span><span class="nt">/></span> |
| <span class="nt"><testSuite</span> <span class="na">href=</span><span class="s">"file:test-resources/org/apache/batik/test/unitTesting.xml"</span><span class="nt">/></span> |
| <span class="nt"></testRun></span> |
| |
| <span class="nt"></testRun></span> |
| </pre></div> |
| |
| |
| <p>There is a rule in Batik's <code>build.xml</code> file to run a test suite defined in an XML file as the one above. At the command line, type the following, for Windows:</p> |
| <div class="highlight"><pre><span></span>build runtestsuite path/to/my/newly/created/testSuite.xml |
| </pre></div> |
| |
| |
| <p>and for Unix:</p> |
| <div class="highlight"><pre><span></span>build.sh runtestsuite path/to/my/newly/created/testSuite.xml |
| </pre></div> |
| |
| |
| <p>In addition, the <code>regard</code> rule runs a specific set of tests by default, so that you do not need to pass any <em>testRun</em> file argument.</p> |
| <p><strong> <code>regard</code> is the project’s safeguard against regressions</strong>.</p> |
| <h2 id="regard">regard: the Batik regression test suite</h2> |
| <p>The regard test suite contains all the regression tests for the Batik project. The <code>regard</code> tool is a specific test suite description, <code>regard.xml</code> (which you can find in the <code>test-resources/org/apache/batik/test</code> directory). That file contains a set of test suite files which sould be run.</p> |
| <p>The following describes how to use the regard tool and some of the most important tests in the regard test suite.</p> |
| <h3 id="Running-regard">Running regard</h3> |
| <p>The regard tool lets you run either all the tests or any specific test you want in the test suite. To run all the tests in the regard test suite, type the following at the command line, for Windows:</p> |
| <div class="highlight"><pre><span></span>build regard |
| </pre></div> |
| |
| |
| <p>and for Unix:</p> |
| <div class="highlight"><pre><span></span>build.sh regard |
| </pre></div> |
| |
| |
| <p>To run a specific test in the test suite, type the qualified test ID or any substring of that ID:</p> |
| <div class="highlight"><pre><span></span>build.sh regard id-list |
| </pre></div> |
| |
| |
| <p>For example:</p> |
| <div class="highlight"><pre><span></span>build.sh regard unitTesting.ts batikFX.svg |
| </pre></div> |
| |
| |
| <p>will run all the tests with an ID containing <code>unitTesting.ts</code> (i.e., all the test selection unit testing, see <code>test-resources/org/apache/batik/gvt/unitTesting.xml</code>) and the accuracy rendering test on <code>batikFX.svg</code> (because it is the only test with <code>batikFX.svg</code> in its ID).</p> |
| <h3 id="Rendering-accuracy-tests">Rendering accuracy tests</h3> |
| <p>There is a <code>Test</code> implementation, <a href="../javadoc/org/apache/batik/test/SVGRenderingAccuracyTest.html">SVGRenderingAccuracyTest</a>, which checks that Batik’s rendering of an SVG document stays accurate. It compares reference images with the rendering Batik produces and reports any discrepancy.</p> |
| <p>An <code>SVGRenderingAccuracyTest</code> ’s constructor configuration is made of:</p> |
| <ul> |
| <li> |
| <p>the URL to the SVG it should render, and</p> |
| </li> |
| <li> |
| <p>the URL to a reference PNG file.</p> |
| </li> |
| </ul> |
| <p>The default behavior for the test is to render the SVG into a PNG file and compare with the reference image. If there is no difference, the test passes. Otherwise, it fails.</p> |
| <p>In addition to this default behavior, the <code>SVGRenderingAccuracyTest</code> can take an optional configuration parameter, an image URL defined as an “accepted” variation around the reference image. If such a variation image is specified, then the test will pass if:</p> |
| <ul> |
| <li> |
| <p>the rasterized SVG is equal to the reference image, or</p> |
| </li> |
| <li> |
| <p>the difference between the rasterized SVG and the reference image is exactly the same as the accepted variation image.</p> |
| </li> |
| </ul> |
| <p>Finally, to ease the process of creating “accepted” variation images, <code>SVGRenderingAccuracyTest</code> can take an optional file name (called <code>saveVariation</code>) describing where the variation between the rasterized SVG and the reference image will be stored in case the rasterized SVG is different from the reference image and the difference is not equal to the variation image, if any was defined. That way, it becomes possible to run a test, and if that test fails, the developer can review the <code>saveVariation</code> image and decide whether it is an acceptable variation or not and use it in subsequent test run as the “accepted” variation image, which will allow the test to pass if that exact same variation remains constant.</p> |
| <h3 id="Day-to-day-use-of-regard">Day to day use of regard</h3> |
| <h4 id="Initial-set-up">Initial set up</h4> |
| <p>To set up the test environment the first time, you need to:</p> |
| <ul> |
| <li> |
| <p>check out the latest version of the code, including the <code>test-*</code> directories (sources, resources and references) and the <code>build.xml</code> file, and</p> |
| </li> |
| <li> |
| <p>run the regard test suite once:build regard</p> |
| </li> |
| </ul> |
| <p>This will generate an HTML test report (<code>report.html</code>) in the <code>test-reports/</code><em><code>yyyy</code></em><code>.</code><em><code>mm</code></em><code>.</code><em><code>dd</code></em><code>-</code><em><code>HHhMMmSSs</code></em><code>/html</code> directory. Depending on how much different text rendering is between your work environment and the environment used to create the reference images, you will get more or less test that will fail, because of differences in the way text is rendered on various platforms and because of fonts not being available on some platforms. For example, a running the test on a Windows 2000 laptop against images generated on the Solaris platform caused 16 tests out of 71 to fail.</p> |
| <p>Review the HTML report to make sure that the differences are really due to text variations. This will usually be the case and you can make sure by clicking on the diff images contained in the report to see them at full scale. You can you can then turn the “candidate” variations generated by the test into “accepted” variations by moving files from one directory to another:</p> |
| <div class="highlight"><pre><span></span>mv test-references/samples/candidate-variations/*.png test-references/samples/accepted-variations/*.png |
| mv test-references/samples/tests/candidate-variations/*.png test-references/samples/tests/accepted-variations/*.png |
| </pre></div> |
| |
| |
| <p>You can now run the test again:</p> |
| <p>build regard</p> |
| <p>Check the newly generated HTML report in the <code>test-reports/html</code> directory: there should no longer be any test failure.</p> |
| <h4 id="Daily-usage">Daily usage</h4> |
| <p>Once the intial set up has been done, you can use regard by simply updating your SVN copy, including the test-references. If no change occurs, your test will keep passing with your reference images. If a test fails (e.g., if someone checks in a new reference image from a platform different than the one you are using, you will have to check if it is because of system specific reasons or if there is a bigger problem.</p> |
| <h3 id="SVG-generator-tests">SVG generator tests</h3> |
| <p>Regard contains over 100 tests for checking regressions on the SVG generator. If you use <code>svggen</code> as an argument to regard, all the SVG generator tests will be run (because <code>regard.xml</code> points to <code>test-resources/org/apache/batik/svggen/regsvggen.xml</code>, which is a test suite description for the SVG generator and that file’s root <code>testSuite</code> element has the “svggen” ID).</p> |
| <h2 id="writingNewTests">Writing new tests</h2> |
| <p>Writing a new test involves either configuring a new test or writing a new <code>Test</code> class. In both cases, you will need to add an entry to a test suite’s XML description. This section uses two test suites as an example: the “regard” test suite to show how to configure a new test and the “unitTests” test suite to show how to add a new <code>Test</code> implementation.</p> |
| <h3 id="Adding-a-new-test-configuration">Adding a new test configuration</h3> |
| <p>Imagine that you add a cool new test case to the <code>samples</code> directory, such as <code>linking-viewBox.svg</code>. In order to check for regressions on that file you can add the following entry:</p> |
| <div class="highlight"><pre><span></span><span class="nt"><test</span> <span class="na">id=</span><span class="s">"anne.svg"</span> <span class="na">class=</span><span class="s">"org.apache.batik.test.svg.SVGRenderingAccuracyTest"</span><span class="nt">></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.net.URL"</span> |
| <span class="na">value=</span><span class="s">"file:samples/tests/linkingViewBox.svg"</span><span class="nt">/></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.net.URL"</span> |
| <span class="na">value=</span><span class="s">"file:test-references/samples/tests/solaris/linkingViewBox.png"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"VariationURL"</span> |
| <span class="na">class=</span><span class="s">"java.net.URL"</span> |
| <span class="na">value=</span><span class="s">"file:test-references/samples/tests/variation/linkingViewBox.png"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"SaveVariation"</span> |
| <span class="na">class=</span><span class="s">"java.io.File"</span> |
| <span class="na">value=</span><span class="s">"test-references/samples/tests/variation-candidate/linkingViewBox.png"</span><span class="nt">/></span> |
| <span class="nt"></test></span> |
| </pre></div> |
| |
| |
| <p>to the <code>test-resources/org/apache/batik/test/samplesRendering.xml</code> test suite description, the description of the regard test suite. If you have access to the build machine where the reference images are typically generated, you can check on the reference image in <code>test-references/samples/tests</code>. Otherwise (and this is OK), you can let the test fail the first time it is run on the build/test machine and that will be a reminder for whoever is responsible for that machine that a valid reference image should be checked in.</p> |
| <h3 id="Writing-a-new-test">Writing a new test</h3> |
| <p>Imagine you want to validate some aspect of your code, and let's take the bridge error handling as an example. You could create a new class in the <code>test-sources</code> directory, in <code>test-sources/org/apache/batik/bridge</code> in our example, and let's call it <code>ErrorHandlingTest</code>. To simplify the implementation of the <code>Test</code> interface, you can choose to derive from the <code>AbstractTest</code> class and generate a <code>DefaultTestReport</code>.</p> |
| <p>While writing the <code>Test</code> you may want to use your own XML file with just your test, for example:</p> |
| <div class="highlight"><pre><span></span><span class="nt"><testReportProcessor</span> <span class="na">class=</span><span class="s">"org.apache.batik.test.SimpleTestReportProcessor"</span><span class="nt">/></span> |
| |
| <span class="nt"><test</span> <span class="na">class=</span><span class="s">"org.apache.batik.bridge.ErrorHandlingTest"</span><span class="nt">></span> |
| <span class="c"><!-- Expected error code --></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.lang.String"</span> <span class="na">value=</span><span class="s">"expected.error.code"</span><span class="nt">/></span> |
| <span class="c"><!-- Input SVG that this test manipulates to generate error conditions --></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.net.URL"</span> <span class="na">value=</span><span class="s">"file:test-resources/org/apache/batik/bridge/ErrorHandlingBase.svg"</span><span class="nt">/></span> |
| <span class="c"><!-- Id of the element to test --></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.lang.String"</span> <span class="na">value=</span><span class="s">"rectangle6"</span><span class="nt">/></span> |
| <span class="c"><!-- Attribute to test --></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.lang.String"</span> <span class="na">value=</span><span class="s">"x"</span><span class="nt">/></span> |
| <span class="c"><!-- Value to test on the attribute --></span> |
| <span class="nt"><arg</span> <span class="na">class=</span><span class="s">"java.lang.String"</span> <span class="na">value=</span><span class="s">"abcd"</span><span class="nt">/></span> |
| <span class="nt"></test></span> |
| </pre></div> |
| |
| |
| <p>This is just an example and does not pretend to be the right way to go about implementing or specifying this specific type of test. Once done with tuning the test, one or multiple configurations for the test can be added to the relevant test suite’s XML description. In some cases, it will be interesting to create a separate test suite.</p> |
| |
| <div class="clear"></div> |
| |
| <div id="footer"> |
| <div class="copyright"> |
| <div style="float:left; padding: 7px;"> |
| <a title="Apache Software Foundation" href="http://www.apache.org"><img id="asf-feather-logo" alt="Apache Software Foundation" src="/images/asf_logo_url.png" width="200" /></a> |
| </div> |
| <p> |
| Copyright © 2016 The Apache Software Foundation, Licensed under |
| the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. |
| <br /> |
| Apache, Apache XML Graphics, Apache FOP, Apache Batik, the Apache feather logo, and the |
| Apache XML Graphics logos are trademarks of <a href="http://www.apache.org">The Apache |
| Software Foundation</a>. All other marks mentioned may be trademarks or registered |
| trademarks of their respective owners. |
| <br /> |
| </p> |
| </div> |
| </div> |
| |
| </body> |
| </html> |
