JarCastingOGC KML 2.x Conformance Test Suite
Scope
This test suite verifies that a KML 2.x resource conforms to the following OGC specifications:
- OGC KML, Version 2.3 (OGC 12-007r2)
- OGC KML 2.3 - Abstract Test Suite (OGC 14-068r2)
- OGC KML, Version 2.2 (OGC 07-147r2)
The KML specification defines three conformance levels indicating the relative importance or priority of a particular set of constraints; each level successively increases the test coverage. The highest level (CL3) indicates full conformance, but a given application or user community may opt for a lower level of conformance. All three levels will be implemented by the test suite:
- CL1: includes tests covering requirements that must be satisfied by every (minimally) conforming KML document.
- CL2: as for CL1, plus tests that address recommended constraints that should be satisfied; non-conformance at this level may hinder the utility, portability, or interoperability of the resource.
- CL3: as for CL2, plus tests for optional constraints that are purely informative in nature.
Visit the project documentation website for more information, including the API documentation.
Special dependencies
The KML 2.3 specification adopted XML Schema 1.1 as the normative schema language. The Xerces2 Java parser aspires to provide support for the current W3C Recommendation, but it seems to be mired in an interminable beta development phase (the last release was November 2010!). The test suite currently uses a component built from the xml-schema-1.1-dev branch (revision: 1667115); this artifact is available from the central Maven repository:
<dependency>
<groupId>org.opengis.cite.xerces</groupId>
<artifactId>xercesImpl-xsd11-shaded</artifactId>
<version>2.12-beta-r1667115</version>
</dependency>
Note: The classes in this library have been relocated in order to avoid conflicts with other components that depend on the latest public release of the Xerces2 Java implementation (2.11.0).
In order to enable checking of assertions that may be defined in an XML Schema 1.1 grammar, the XPath 2.0 processor bundled with the Eclipse Web Tools Platform (WTP) is required. Unfortunately the Xerces schema processor does not use an official release of this component; rather, it uses a build based on the R3_2_maintenance branch. This special dependency has also been published to the central repository:
<dependency>
<groupId>org.opengis.cite.eclipse.webtools.sse</groupId>
<artifactId>org.eclipse.wst.xml.xpath2.processor</artifactId>
<version>1.1.5-738bb7b85d</version>
</dependency>
Note: The WTP 3.2 release included v1.1.4 of the XPath 2.0 processor, and WTP 3.3 included the v2.0.0 processor. Neither version will work with Xerces.
How to run the tests
Integrated development environment (IDE)
You can use a Java IDE such as Eclipse, NetBeans, or IntelliJ to run the test suite. Clone the repository and build the project. The runtime configuration is summarized below.
Main class: org.opengis.cite.kml2.TestNGController
Arguments: The first argument must refer to an XML properties file containing the required test run argument (a reference to a KML resource). If not specified, the default location at ${user.home}/test-run-props.xml will be used.
You can modify the default settings in the sample test-run-props.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties version="1.0">
<comment>Test run arguments (ets-kml2)</comment>
<entry key="kml">https://developers.google.com/kml/documentation/KML_Samples.kml</entry>
<entry key="lvl">1</entry>
</properties>
The TestNG results file (testng-results.xml) will be written to a subdirectory in ${user.home}/testng/ having a UUID value as its name.
Command shell (console)
One of the build artifacts is an "all-in-one" JAR file that includes the test suite with all of its dependencies. This makes it very easy to execute the test suite in a command shell like so:
java -jar ets-kml2-${version}-aio.jar [-o|--outputDir $TMPDIR] [-d|--deleteSubjectOnFinish] [test-run-props.xml]
OGC test harness
Use TEAMengine, the official OGC test harness. The latest test suite release should be available at the beta testing facility. You can also build and deploy the test harness yourself and use a local installation.
How to contribute
If you would like to get involved, you can:
- Report an issue such as a defect or an enhancement request
- Help to resolve an open issue
- Fix a bug: Fork the repository, apply the fix, and create a pull request
- Add new tests: Fork the repository, implement (and verify) the tests on a new topic branch, and create a pull request
