Continuous Integration Tool

[admin]

One of the files included in the 0.37 release is a class named SampleSitesIT (located in the ci directory under the css4j-java2d module, although it does not require Java2D). It is a small tool for 'continuous integration' purposes: fetches a list of URLs with their style sheets, and performs a few tests with the computed styles, reporting any anomaly. The tool not only verifies whether a web page has style errors or warnings that the library detects (with the configured SAC parser), but also whether the native DOM and the DOM4J backend see the same document nodes and style sheets. The comparison is possible because the same HTML5 parser is used for both backends.

For each URL in the samplesites.txt file (that has to be put under the same package io.sf.carte.doc.style.css in the classpath), it fetches the document and its style sheets, computing styles for each element both with the native implementation and the DOM4J backend. It looks for errors in the style sheets and also compares the results of both backends. If there are errors or differences in the styles computed by the two implementations, they are reported (be sure to configure logging correctly) and the test fails.

If you try the test with a random high-volume website, beware that each site is retrieved twice (one by each backend), and some sites do send slightly different documents in these circumstances. Also remember that the DOM4J backend is likely to report different styles if there are selectors like :blank involved.

You can put as many websites as you want in samplesites.txt, and they can be commented out with the '#' character at the beginning of the line. There is a samplesites.properties that can be used for configuration, although currently only supports the 'parser' and 'fail-on-warning' options:

parser=<fully-qualified-class-name-of-SAC-parser>
fail-on-warning=<true|false>

parser: the qualified class name of the SAC/NSAC parser to be used in the test.

fail-on-warning: if set to true, a test shall fail even if only style sheet warnings were logged.

If your project uses css4j, you can use this tool to monitor a list of URLs that are important for you. The tool can be run with the Maven Failsafe plugin (mvn verify), provided that the CI environment is set up correctly. Unless you prefer to build the test source yourself, you possibly want to build a css4j-java2d test-jar by adding this to the build plugins in the 0.37 POM file for the css4j-java2d artifact:

 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-jar-plugin</artifactId>
   <version>3.0.2</version>
   <executions>
     <execution>
        <goals>
          <goal>test-jar</goal>
        </goals>
     </execution>
   </executions>
 </plugin>

This will probably be included in the next release's POM. You also need to set up a classpath directory in the failsafe configuration to put the configuration files so they can be read (and edited!), like:

 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-failsafe-plugin</artifactId>
   <version>2.20.1</version>
   <configuration>
     <additionalClasspathElements>
       <additionalClasspathElement>/my/path/to/ci</additionalClasspathElement>
     </additionalClasspathElements>
   </configuration>
   <executions>
     <execution>
       <goals>
         <goal>integration-test</goal>
         <goal>verify</goal>
       </goals>
     </execution>
   </executions>
 </plugin>

And then you can run your own integration tests with your chosen sites.

[admin]

If you try the test with a random high-volume website, beware that each site is retrieved twice (one by each backend), and some sites do send slightly different documents in these circumstances.

This caveat can be avoided with the new version of the CI tool that was just committed. Now all the URLs are stored on a simple cache, and the tests apply to the stored files.

The samplesites.properties has a new cachedir parameter that has to be set to the directory where the files can be stored. For example:

 

cachedir=/var/tmp/sitecache

If no directory is set, the cache is not used and the files are retrieved twice.