Improve testing and documentation #266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

palemieux wants to merge 10 commits into main from feature/improve-reference-rendering-generation

.github/workflows/ci.pr.yml

-Original file line number
+Diff line change
@@ Expand Up / @@ -13,6 +13,8 @@ jobs: @@
         steps:
           - uses: actions/checkout@v4
+            with:
+              submodules: true
           - uses: actions/setup-node@v4
             with:
@@ Expand All / @@ -22,6 +24,9 @@ jobs: @@
           - name: Install
             run: npm ci
+          - name: Install Firefox
+            run: npm run install:firefox
           - name: Lint
             run: npm run lint
@@ Expand Down @@

CONTRIBUTING

-Original file line number
+Diff line change
@@ -0,0 +1,22 @@
+    By making a contribution to this project, I certify that:
+    (a) The contribution was created in whole or in part by me and I have the right
+    to submit it under the open source license indicated in the file; or
+    (b) The contribution is based upon previous work that, to the best of my
+    knowledge, is covered under an appropriate open source license and I have the
+    right under that license to submit that work with modifications, whether created
+    in whole or in part by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated in the file; or
+    (c) The contribution was provided directly to me by some other person who
+    certified (a), (b) or (c) and I have not modified it.
+    (d) I understand and agree that this project and the contribution are public and
+    that a record of the contribution (including all personal information I submit
+    with it, including my sign-off) is maintained indefinitely and may be
+    redistributed consistent with this project or the open source license(s)
+    involved.
+    Only contributions with a license compatible with the license at LICENSE.txt can
+    be accepted.

Pipfile

-Original file line number
+Diff line change
@@ -0,0 +1,10 @@
+    [[source]]
+    url = "https://pypi.org/simple"
+    verify_ssl = true
+    name = "pypi"
+    [packages]
+    pillow = "*"
+    [requires]
+    python_version = "3"

Pipfile.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

README.md

-Original file line number
+Diff line change
@@ -1,54 +1,41 @@
+    # imscJS
          _                                 _    _____
         (_)                               | |  / ____|
          _   _ __ ___    ___    ___       | | | (___
         | | | '_ ` _ \  / __|  / __|  _   | |  \___ \
         | | | | | | | | \__ \ | (__  | |__| |  ____) |
         |_| |_| |_| |_| |___/  \___|  \____/  |_____/
-    INTRODUCTION
-    ============
+    ## Introduction
     imscJS is a JavaScript library for rendering [IMSC 1.0.1](https://www.w3.org/TR/ttml-imsc1.0.1/) and [IMSC 1.1](https://www.w3.org/TR/ttml-imsc1.1/) documents to HTML5. IMSC is a profile of [TTML 2](https://www.w3.org/TR/ttml2/) designed for subtitle and caption delivery worldwide.
     A sample web app that uses imscJS is available at https://www.sandflow.com/imsc1_1/index.html.
     Documentation is available on [MDN](https://developer.mozilla.org/en-US/docs/Related/IMSC).
-    KNOWN ISSUES AND LIMITATIONS
-    ============================
+    ## Known issues and limitations
     imscJS is primarily developed on Firefox. Latest versions of Chrome, Safari, and Microsoft Edge are intended to be supported nevertheless, albeit with potentially reduced capabilities. In particular, advanced ruby layout is currently only supported by Firefox.
     imscJS is intended to reflect the most recent published versions of [IMSC 1.0.1](https://www.w3.org/TR/ttml-imsc1.0.1/) and [IMSC 1.1](https://www.w3.org/TR/ttml-imsc1.1/). These publications are routinely clarified by proposed resolutions to issues captured in their respective bug trackers.
     imscJS bugs are tracked at https://github.com/sandflow/imscJS/issues.
-    RUNTIME DEPENDENCIES
-    ====================
+    ## Runtime dependencies
     imscJS requires an XML parser. By default it uses the browser's native [`DOMParser`](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser), so no additional library is needed in a browser environment. In environments where `DOMParser` is not available, e.g. Node.js, the caller must provide `fromXML()` with a parser that implements the contract defined in [src/main/js/parser.js](src/main/js/parser.js), e.g. [sax-js](https://www.npmjs.com/package/sax).
     Rendering to HTML5 requires a browser environment, but parsing an IMSC document and transforming it into ISDs does not.
-    DEVELOPMENT DEPENDENCIES
-    ========================
+    ## Development dependencies
     (required) node.js (see [package.json](package.json) for a complete list of dependencies)
     (recommended) git
-    QUICK START
-    ===========
+    ## Quick start
     * run the `build` target defined in [Gruntfile.cjs](./Gruntfile.cjs) using [grunt](http://gruntjs.com/).
@@ Expand All / @@ -60,13 +47,9 @@ QUICK START @@
     See BUILD ARTIFACTS for a full list of build artifacts, and TESTS AND SAMPLES for a list of samples and tests available.
+    ## Architecture
-    ARCHITECTURE
-    ============
-    API
-    ---
+    ### API
     imscJS renders an IMSC document in three distinct steps:
@@ Expand All @@
     Inline documentation provides additional information.
+    ### Modules
-    MODULES
-    -------
-    imscJS consists of the following modules, which can be used in a node
-    environment using the `require` functionality, or standalone, in which case each module hosts its
-    definitions under a global name (the token between parantheses):
-    * `doc.js` (`imscDoc`): parses an IMSC document into an in-memory TT object
-    * `isd.js` (`imscISD`): generates an ISD object from a TT object
-    * `html.js` (`imscHTML`): generates an HTML fragment from an ISD object
-    * `names.js` (`imscNames`): common constants
-    * `styles.js` (`imscStyles`): defines TTML styling attributes processing
-    * `utils.js` (`imscUtils`): common utility functions
+    imscJS consists of the following ES modules at [src/main/js](src/main/js), which can be imported individually, or used together as the `imsc` global when loaded as a UMD bundle (see [Build](#build)):
+    * `main.js`: public entry point; exposes `fromXML()`, `renderHTML()`, `generateISD()` and `createSAXParserFromDOMParser()`
+    * `doc.js`: parses an IMSC document into an in-memory TT object
+    * `parser.js`: defines the XML parser contract expected by `doc.js`
+    * `dom_to_parser.js`: implements the XML parser contract using the browser's `DOMParser`
+    * `isd.js`: generates an ISD object from a TT object
+    * `html.js`: generates an HTML fragment from an ISD object
+    * `names.js`: common constants
+    * `styles.js`: defines TTML styling attributes processing
+    * `utils.js`: common utility functions
+    * `error.js`: defines error handling utilities used across modules
-    BUILD
-    =====
+    ## Build
     imscJS is built using the `build:release` or `build:debug` Grunt tasks -- the `build` task is an alias of `build:debug`.
     The `dist` directory contains the following build artifacts:
     * `imsc.debug.js`: Non-minified UMD build.
     * `imsc.min.js`: Minified UMD build.
     * `main/`: ES modules and TypeScript type declarations, used when the library is imported as an NPM package.
     The `build/public_html/libs/imsc.js` file is identical to:
     * `imsc.debug.js`, if the `build:debug` task is executed.
     * `imsc.min.js`, if the `build:release` task is executed.
-    RELEASES
-    ========
+    ## Releases
     imscJS is released as an NPM package under [imsc](https://www.npmjs.com/package/imsc). The `dev` distribution tag indicates pre-releases.
     Builds/dist are available on the [unpkg](https://unpkg.com/) CDN under the [`dist`](https://unpkg.com/browse/imsc/dist/) directory.
     To access the latest builds, please consult the [release page](https://github.com/sandflow/imscJS/releases).
+    ## Tests and samples
+    ### W3C Test Suite
-    TESTS AND SAMPLES
-    =================
+    The `gen-renders.html` web app or the headless script [src/test/script/gen-render-package.mjs](src/test/script/gen-render-package.mjs) can be used to generate PNG renderings as well as intermediary files (JSON document, ISD documents and HTML documents) from the [W3C IMSC test suite](https://github.com/w3c/imsc-tests).
+    ```sh
+    npm run gen-imsc1
+    npm run gen-imsc1_1
+    ```
-    W3C Test Suite
-    --------------
+    [src/test/script/compare_renders.py](src/test/script/compare_renders.py) compares two such render outputs (unzipped), performing byte-level, JSON/HTML and pixel-level PNG diffs, and optionally generating an HTML comparison report.
-    imscJS imports the [IMSC test suite](https://github.com/w3c/imsc-tests) as a submodule at `src/test/resources/imsc-tests`. The gen-renders.html web app can be used to generate PNG renderings as as well intermediary files from these tests.
+    ```sh
+    pipenv install
+    pipenv run python3 src/test/script/compare_renders.py <unzipped renders-imsc1> <unzipped renders-imsc1_1>
+    ```
+    ### Unit tests
-    Unit tests
-    ----------
+    Unit tests run using Node's built-in [test runner](https://nodejs.org/api/test.html) and are located at [src/test/js](src/test/js). They can be run with:
-    Unit tests run using [QUnit](https://qunitjs.com/) are split between:
+    ```sh
+    npm test
+    ```
-    * [src/test/webapp/js/unit-tests.js](src/test/webapp/js/unit-tests.js)
-    * [src/test/js](src/test/js)
+    Some unit tests validate rendering output against the reference files at [src/test/resources/reference-files](src/test/resources/reference-files). These reference files are generated from the [W3C IMSC test suite](https://github.com/w3c/imsc-tests) by running:
+    ```sh
+    npm run gen-reference-files
+    ```
-    NOTABLE DIRECTORIES AND FILES
-    =============================
+    ## Notable directories and files
     * [package.json](package.json): NPM package definition
     * [Gruntfile.cjs](Gruntfile.cjs): Grunt build script
     * [properties.json](properties.json): General project properties
+    * [eslint.config.js](eslint.config.js): ESLint configuration
+    * [tsconfig.json](tsconfig.json): TypeScript configuration used to generate the type declarations in `dist/main`
+    * [rollup.config.js](rollup.config.js): Rollup configuration used to bundle `dist/main` into the UMD builds at `dist/imsc.debug.js` and `dist/imsc.min.js`
+    * [src/test/script/Pipfile](src/test/script/Pipfile): [pipenv](https://pipenv.pypa.io/) dependency declaration for `compare_renders.py`
     * [LICENSE](LICENSE): License under which imscJS is made available
+    * [CONTRIBUTING](CONTRIBUTING): Certification required of contributions to imscJS
     * [src/main/js](src/main/js): JavaScript modules
     * [src/test](src/test): Test files
+    * [src/test/webapp](src/test/webapp): Web app, used to generate PNG renderings and intermediary files from the W3C IMSC test suite
     * [dist](dist): Built libraries
     * [build/public_html](build/public_html): Test web applications

eslint.config.js

-Original file line number
+Diff line change
@@ Expand Up / @@ -28,4 +28,12 @@ export default [ @@
           "eol-last": ["error", "always"],
         },
       },
+      {
+        files: ["src/test/script/**/*"],
+        languageOptions: {
+          globals: {
+            ...globals.node,
+          },
+        },
+      },
     ];

Navigation Menu

Uh oh!

Improve testing and documentation #266

Uh oh!

Diff view

Diff view

Uh oh!

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Improve testing and documentation #266

Are you sure you want to change the base?

Uh oh!

Improve testing and documentation #266

Uh oh!

Diff view

Diff view

Uh oh!

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!