/epub-structural-tests

Primary LanguageHTMLOtherNOASSERTION

Harvest epubcheck for the EPUB 3.3. CR report

Tool to combine the information extracted from the test feature files of epubcheck with the EPUB 3.3 specification, and to produce a test report that lists the available tests and their relationships to the specification. The tool itself is a script written in TypeScript, based on a standard node.js environment.

Workflow

The tool does two things for each HTML files of the EPUB 3.3 specifications (i.e., the core index.html file as well as the vocabulary specification files):

  • It produces a separate file in the docs/fragments directory. The final report itself (in docs/index.html) combines these fragment files to produce a comprehensive set of tables on the tests. [T.B.D.: whether this file should be moved to another repository, or whether it can be directly picked up by the final reports.]

  • It modifies the specification file by adding the references to the tests in the relevant sections. This is done by adding the data-tests attributes (or expanding an existing one, if applicable) with the references to the test suite (see the respec documentation for the details).

    The modified HTML files are stored in the epub33/core, resp. epub33/core/vocab, directory. These files must be manually moved back into the specification repository by, e.g., copying them in a local clone and the defining a Pull Request. The tool does not do that automatically.

The input data for the tool is epubcheck_data/tests.json, which contains the test descriptions as extracted from the epubcheck test suite.

Installing and running the tool

The repository must be cloned to a local machine and the standard npm install should be run. To execute the script run

ts-node src/main.ts

from the top directory or, alternatively, run

npm run generate

anywhere in the repository.

By default, the tool reads the content of the specifications' HTML files by accessing them directly on github. The tool can also be run with two more options:

  • -d or --download: the original (i.e., unchanged) specification files are also stored locally in the epub33-orig directory.
  • -l or --local: instead of accessing github, the tool uses the specification files in the epub33-orig directory.

Directory content

  • epub33/core: the generated specification files, with all the modifications done/updated.
  • epub33-orig/core: a copy of the original specification files.
  • epub-33/common: is a copy of the original files in the EPUB repository (necessary to visualize the files). In particular, it also contains (a modified version of) epub33/common/js/data-test-displays.js that makes some necessary modifications on the files generated by respec to show the test references correctly.
  • epubcheck-data: files, and necessary scripts, containing the descriptions of the epubcheck tests suite entries.
  • docs: the final report
  • src: the TypeScript code itself

The rest of the files (package.json, LICENSE, etc, are self-evident).

@iherman