Sketch of documentation for mobileOK Basic implementation

Here's the beginnings of a the documentation that we should produce
along with the reference implementation:


1. Overview
2. Design Overview
3. Usage
4. Implementation notes
5. Appendices


1. Overview

This document describes the design and usage of the mobileOK Basic
Tests reference implementation. These are intended to be useful to
developers who wish to integrate the reference implementation into an
existing application or infrastructure.

mobileOK Basic does leaves some decisions up to particular
implementations, and allows for implementations to provide additional
functionality. So, this document also discusses
implementation-specific decisions taken during development. These are
intended to be useful to developers who are porting this
implementation to another platform, or, developing a new
implementation from scratch.


2. Design Overview

The reference implementation provided here is written in Java and
requires J2SDK 5.0. It is a pure Java library, rather than an
application. It is intended to be embedded in another application,
possibly one that provides a GUI or web-based interface to its
functionality.

2.1 Architecture

(TODO: insert basic architecture diagram)

In essence, the library accepts as input a URI, and outputs two sets
of information. First is the set of test results of course. The second
output summarizes the results of accessing and  pre-processing the URI
under test. This second output is provided for information, but also
to aid extensibility.

2.2 Design of public API

(TODO: insert class diagram)

The key API classes are:

Tester
This is the top-level abstraction which runs the test. It can be
constructed to operate on a file, a URI, or can be given the HTTP
response body and headers directly. It exposes a runTests() method
that runs everything, or, runTest() which runs just one test.

TestType
Just an enum of all test types.

TestResults
TestResult
Returned by runTests() and runTest() respectively, and encapsulate the
results of many tests and one test, respectively. TestResults includes
many TestResult instances. These objects include test outcome,
warnings, and information.

TestOutcome
Just an enum of PASS and FAIL, the two test outcomes

TestException
Throw if something goes wrong in the tester -- that is, not just that
there was an error accessing the document but that something is wrong
with the tester.


3. Usage

3.1 Java

-------------------
Tester tester = new Tester("http://example.org");
TestResults results = tester.runTests();
TestOutcome outcome = results.getOverallOutcome();
TestResult = results.getResultForTest(TestType.AUTO_REFRESH);

...
TestResult oneResult = tester.runTest(TestType.AUTO_REFRESH);
-------------------

3.2 Command line

While provided as a library, it is also possible to get quick results
on the command line:

-------------------
java -cp mobileOKBasic-RI.jar org.w3c.mwi.mobileok.basic.Tester
http://example.org
-------------------


4. Implementation Notes

This section discusses implementation decisions taken in design and
development that were not dictated by the mobileOK Basic Tests
specification.

4.1 Preprocessing Results

The most noticeable feature of this implementation is that it exposes
a large amount of information about the results of accessing and
pre-processing the URI under test (see Appendices). This is provided
from method XXX of class XXX  in Java. It also provided as a DOM which
may be serialized and used by any external tool. Appendix XX describes
the format of this DOM in detail. This data structure contains the
following information:

TODO

4.2 Test Results

Test results are available from the method Tester.runTests(), which
returns a TestResults object. The same information is available as a
DOM from method XXX, in a format described in Appendix XX. The format
uses the EARL RDF vocabulary to describe the outcome. Test results are
provided in this form as well to ease integration with external tools.
The test results data structures include the following information:

- Overall outcome (PASS or FAIL)
- Global warning messages
- Global informational messages
- For each test:
  - Test outcome (PASS or FAIL)
  - Error message if any
  - Warning messages
  - Informational messages

4.3 Notes to extenders

This section contains notes that may be useful to developers who wish
to build on this implementation to construct additional tests of
mobile content beyond what is defined in mobileOK Basic.

TODO

4.4 Malformed markup and tidying

It is expected that the most common cause of test failures is
malformed markup. This will cause the VALID_MARKUP test to fail of
course, and thus the entire test suite.

However, many tests must have a valid DOM to run and produce any
useful information. It is of course desirable to provide as much
information as possible to the person running the tests rather than
completely fail on the common case of malformed markup.

So, in the event that the input document cannot be parsed into a DOM,
this implementation will attempt to "tidy" the document using
HtmlCleaner and then re-run all tests. This does not change the fact
that the overall test suite result is FAIL; however, this does
potentially allow some tests to run and provide some useful feedback
to the developer.

4.5 Third-party packages
  Jakarta Commons Codec 1.3
  Jakarta Commons HttpClient 3.1
  Jakarta Commons Logging 1.1
  HtmlCleaner 1.12


5. Appendices

5.1 Intermediate results
5.1.1 Schema
5.1.2 Example

TODO

5.2 Test results schema
5.2.1 Schema
5.2.2 Example

TODO

Received on Wednesday, 21 March 2007 01:37:16 UTC