{"id":15600453,"url":"https://github.com/jason-fox/fox.jason.unit-test","last_synced_at":"2026-02-21T04:31:57.848Z","repository":{"id":54539662,"uuid":"129538519","full_name":"jason-fox/fox.jason.unit-test","owner":"jason-fox","description":"Unit Testing and Code Coverage Framework for DITA Open Toolkit Plugins","archived":false,"fork":false,"pushed_at":"2025-10-05T20:15:55.000Z","size":5134,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-10-22T01:44:45.501Z","etag":null,"topics":["code-coverage","coverage","dita-ot","dita-ot-plugin","testing","unit-testing"],"latest_commit_sha":null,"homepage":"https://jason-fox.github.io/dita-ot-plugins/unit-test","language":"XSLT","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jason-fox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-04-14T17:19:36.000Z","updated_at":"2025-10-05T20:15:58.000Z","dependencies_parsed_at":"2024-02-17T16:28:04.943Z","dependency_job_id":"5aa2986b-33b9-4bf6-9f83-fd524ebe161e","html_url":"https://github.com/jason-fox/fox.jason.unit-test","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/jason-fox/fox.jason.unit-test","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason-fox%2Ffox.jason.unit-test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason-fox%2Ffox.jason.unit-test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason-fox%2Ffox.jason.unit-test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason-fox%2Ffox.jason.unit-test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jason-fox","download_url":"https://codeload.github.com/jason-fox/fox.jason.unit-test/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason-fox%2Ffox.jason.unit-test/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29673785,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T03:11:15.450Z","status":"ssl_error","status_checked_at":"2026-02-21T03:10:34.920Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-coverage","coverage","dita-ot","dita-ot-plugin","testing","unit-testing"],"created_at":"2024-10-03T02:03:13.876Z","updated_at":"2026-02-21T04:31:57.810Z","avatar_url":"https://github.com/jason-fox.png","language":"XSLT","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unit Test Framework for DITA-OT [\u003cimg src=\"https://jason-fox.github.io/fox.jason.unit-test/unit.png\" align=\"right\" width=\"300\"\u003e](https://unit-test-framework-for-dita-ot.rtfd.io)\n\n[![license](https://img.shields.io/github/license/jason-fox/fox.jason.unit-test.svg)](http://www.apache.org/licenses/LICENSE-2.0)\n[![DITA-OT 4.2](https://img.shields.io/badge/DITA--OT-4.2-green.svg)](http://www.dita-ot.org/4.2)\n[![CI](https://github.com/jason-fox/fox.jason.unit-test/workflows/CI/badge.svg)](https://github.com/jason-fox/fox.jason.unit-test/actions?query=workflow%3ACI)\n[![Coverage Status](https://coveralls.io/repos/github/jason-fox/fox.jason.unit-test/badge.svg?branch=master)](https://coveralls.io/github/jason-fox/fox.jason.unit-test?branch=master)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=fox.jason.unit-test\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=fox.jason.unit-test)\n\nThis is a Unit Testing framework for the DITA Open Toolkit. This [DITA-OT Plug-in](https://www.dita-ot.org/plugins)\nconsists of seven DITA-OT transforms and an ANT library:\n\n-   Unit Testing\n    -   The `unit-test` transform allows a user to runs a sequence of `dita` commands and checks that the documents\n        created match the expected output. This is useful for regression testing, and confirming that any custom\n        plug-ins do not conflict when upgrading the base DITA-OT engine.\n    -   The `resource/antlib.xml` library offers a series of convenience methods for creating DITA-OT unit tests.\n-   Code Coverage\n    -   The `token-report` transform checks to see if a series of tokens representing all potential output values are\n        covered by unit tests\n    -   The `xsl-instrument` transform annotates an DITA-OT plug-in to enable code coverage reporting\n    -   The `xsl-deinstrument` transform removes the instrumentation annotation from a specified plug-in\n    -   The `xsl-report` transform displays which templates have been invoked whilst running unit tests\n-   ANT Profiling\n    -   The `antro` transform runs an ANT script profiler against a specified transform and outputs a profiler JSON file\n    -   The `antro.ui` transform starts up the UI for the ANT script profiler, allowing a user to load a JSON file and\n        interpret the results.\n\n:arrow_forward: [Video from DITA-OT Day 2018](https://youtu.be/MQRli3XICUo)\n\n[![](https://jason-fox.github.io/fox.jason.unit-test/unit-test-video.png)](https://youtu.be/MQRli3XICUo)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTable of Contents\u003c/strong\u003e\u003c/summary\u003e\n\n-   [Install](#install)\n    -   [Installing DITA-OT](#installing-dita-ot)\n    -   [Installing the Plug-in](#installing-the-plug-in)\n-   [Usage](#usage)\n    -   [Invocation from the Command line](#invocation-from-the-command-line)\n        -   [Obtaining a unit test report](#obtaining-a-unit-test-report)\n        -   [XSLT coverage report](#xslt-coverage-report)\n        -   [Token coverage report](#token-coverage-report)\n        -   [Obtaining ANT script profile information](#obtaining-ant-script-profile-information)\n        -   [Viewing profiler information](#viewing-profiler-information)\n        -   [Parameter Reference](#parameter-reference)\n    -   [Integration with Travis CI](#integration-with-travis-ci)\n    -   [Integration with Coveralls](#integration-with-coveralls)\n-   [Unit Test File Structure](#unit-test-file-structure)\n    -   [Test suite files](#test-suite-files)\n        -   [`bootstrap.xml` file](#bootstrapxml-file)\n        -   [`coverage.xml` file](#coveragexml-file)\n        -   [`template-coverage.xml` file](#template-coveragexml-file)\n        -   [`disabled.txt` file](#disabledtxt-file)\n        -   [Overrides for `attributes.xml` `colors.xml` and `fonts.xml`](#overrides-for-attributesxml--colorsxml--and-fontsxml)\n        -   [Overrides for `test.properties`](#overrides-for-testproperties)\n    -   [Individual test files](#individual-test-files)\n-   [API](#api)\n    -   [Compare-Output](#compare-output)\n    -   [Contains-Text](#contains-text)\n    -   [Exec-HTML5](#exec-html5)\n    -   [Exec-PDF](#exec-pdf)\n    -   [Exec-SVRL](#exec-svrl)\n    -   [Exec-Transtype](#exec-transtype)\n    -   [Get-HTML-Article](#get-html-article)\n    -   [Get-PDF-Article](#get-pdf-article)\n-   [Contribute](#contribute)\n-   [License](#license)\n\n\u003c/details\u003e\n\n## Install\n\nThe unit test framework plug-in has been tested against [DITA-OT 4.x](http://www.dita-ot.org/download). It is no longer\ncompatible with DITA-OT 2.x. and it is recommended that you upgrade to the latest version. The unit test framework\nplug-in relies on the use of [AntUnit](http://ant.apache.org/antlibs/antunit/) 1.4 to run tests and ANT jUnit to create\na test report. ANT 1.8 or higher is required, although a later ANT version (1.9 or 1.10) is recommended.\n\n### Installing DITA-OT\n\n\u003ca href=\"https://www.dita-ot.org\"\u003e\u003cimg src=\"https://www.dita-ot.org/images/dita-ot-logo.svg\" align=\"right\" height=\"55\"\u003e\u003c/a\u003e\n\nThe DITA-OT Unit Test Framework is a plug-in for the DITA Open Toolkit.\n\n-   Full installation instructions for downloading DITA-OT can be found\n    [here](https://www.dita-ot.org/4.0/topics/installing-client.html).\n\n    1.  Download the `dita-ot-4.2.zip` package from the project website at\n        [dita-ot.org/download](https://www.dita-ot.org/download)\n    2.  Extract the contents of the package to the directory where you want to install DITA-OT.\n    3.  **Optional**: Add the absolute path for the `bin` directory to the _PATH_ system variable.\n\n    This defines the necessary environment variable to run the `dita` command from the command line.\n\n```console\ncurl -LO https://github.com/dita-ot/dita-ot/releases/download/4.2/dita-ot-4.2.zip\nunzip -q dita-ot-4.2.zip\nrm dita-ot-4.2.zip\n```\n\n### Installing the Plug-in\n\n-   Run the plug-in installation command:\n\n```console\ndita -install https://github.com/jason-fox/fox.jason.unit-test/archive/master.zip\n```\n\nThe `dita` command line tool requires no additional configuration.\n\n---\n\n## Usage\n\n### Invocation from the Command line\n\nA series of test suites can be found within the plug-in at `PATH_TO_DITA_OT/plugins/fox.jason.unit-test/sample`\n\n#### Obtaining a unit test report\n\nTo run, use the `unit-test` transform.\n\n```console\nPATH_TO_DITA_OT/bin/dita -f unit-test  -o out -i PATH_TO_UNIT_TESTS\n```\n\nOnce the command has run, a test report file is created. Additionally, if any error occurs, the command will fail.\n\n**Sample Test Report** This is the test report from the example tests found within the plug-in `sample` directory. Nine\ntests are run over two test suites (PDF and HTML processing) - a third test suite has been disabled.\n\n![enter image description here](https://jason-fox.github.io/fox.jason.unit-test/results.png)\n\n-   If the `-i` input directory is a test suite, all tests within the suite will be run.\n-   If the `-i` input directory is not a test suite, all test suites directly beneath that directory will be run.\n\n#### XSLT Coverage Report\n\nTo run a XSLT Coverage Report, each DITA-OT Plug-In must be **instrumented** - this annotates the XSLT templates within\nthe plug-in to be able to generate coverage information. A copy of each `*.xsl` file is also saved with the `*.orig`\nsuffix.\n\n```console\nPATH_TO_DITA_OT/bin/dita -f xsl-instrument -i PATH_TO_PLUG_IN\n```\n\nTo revert back to the original files just run the de-instrument transform as shown:\n\n```console\nPATH_TO_DITA_OT/bin/dita -f xsl-instrument -i PATH_TO_PLUG_IN\n```\n\nOnce a Plug-In has been **instrumented** the test suite should contain a `template-coverage.xml` file which holds a list\nof all template decision points. To obtain coverage information, use the `unit-test` transform as stated previously:\n\n```console\nPATH_TO_DITA_OT/bin/dita -f unit-test -i PATH_TO_UNIT_TESTS\n```\n\n-   If the `-i` input directory is a test suite, XSL coverage for that test suite will be reported.\n-   If the `-i` input directory is not a test suite, XSL coverage for all test suites directly beneath that directory\n    will be reported.\n\nOnce the command has run, both a test report file and an XSL coverage report file are created. Additionally, if any\nerror occurs, the command will fail.\n\nIt is also possible to run XSL coverage over a single test. An individual test can be run directly from the command line\nby running the default target within that test. This can be followed by direct invocation of the coverage report\n\n```console\nant -f PATH_TO_PLUGIN/test/TEST_NAME/build.xml\nPATH_TO_DITA_OT/bin/dita -f xsl-report -i PATH_TO_PLUGIN\n```\n\n##### Sample XSL Report\n\nThe XSL coverage report will show a schematic of all template decision points, with covered lines displayed in green,\nand uncovered lines displayed in red.\n\n![](https://jason-fox.github.io/fox.jason.unit-test/xsl-coverage.png)\n\n#### Token Coverage Report\n\nThis is a quicker alternative report to XSLT instrumentation and code coverage, but it requires the developer to create\nthe token `coverage.xml` file manually. Each test suite should contain a `coverage.xml` file which holds a series of\ntokens representing all potential output values. To obtain coverage information, use the `test-coverage` transform.\n\n```console\nPATH_TO_DITA_OT/bin/dita -f token-report -i PATH_TO_UNIT_TESTS\n```\n\nOnce the command has run, a coverage report is created\n\n##### Sample Token Report\n\nThis is the token report from the example tests found within the plug-in `sample` directory.\n\n-   Coverage for the Spell-checker is looking to ensure that all rules have been run. Uncovered rules are highlighted in\n    RED.\n-   Coverage for HTML processing is looking for the presence of `\u003ccodeph\u003e`, `\u003ccodeblock\u003e` and `\u003cp\u003e` tags being rendered\n    in the tests.\n\n![enter image description here](https://jason-fox.github.io/fox.jason.unit-test/coverage.png)\n\n-   If the `-i` input directory is a test suite, coverage for that test suite will be reported.\n-   If the `-i` input directory is not a test suite, coverage for all test suites directly beneath that directory will\n    be reported.\n\n#### Obtaining ANT script profile information\n\n**Antro** is a hierarchical and line-level profiler for Ant build scripts. It can be run to check which ANT scripts have\nbeen invoked and how long they took.\n\nTo obtain profile information, use the `antro` transform and supply an additional test transtype\n\n```console\nPATH_TO_DITA_OT/bin/dita -f antro --test.transform=TRANSFORM_TO_PROFILE -i document.ditamap\n```\n\nA profiler JSON file will be generated.\n\n#### Viewing profiler information\n\nTo run the UI for the Antro profiler, use the `antro-ui` transform. The `-i` parameter is mandatory for all DITA-OT\nplug-ins, and should point to a real file, but is not used for this transform.\n\n```console\nPATH_TO_DITA_OT/bin/dita -f antro-ui -i document.ditamap\n```\n\nThe Antro UI is the displayed, load the profiler json file from to display a bar graph showing how long each ANT target\ntook:\n\n**Sample Antro Display** The Profiler was run against the `pdf` transform, FOP processing took 16s\n![](https://jason-fox.github.io/fox.jason.unit-test/profiler-bar.png)\n\nYou can drill down to an individual line to see if it has been invoked and how long it took:\n![](https://jason-fox.github.io/fox.jason.unit-test/profiler.png)\n\n### Parameter Reference\n\n-   `test.copy` - Specifies whether regenerated expectations should be copied. Default is `false`\n-   `test.transtype` - The real transtype to run the antro profiler against\n-   `test.propertyfile` - A properties file to use when running the unit tests or antro profiler\n\n### Integration with GitHub Actions.\n\n\u003ca href=\"https://docs.github.com/en/free-pro-team@latest/actions\"\u003e\u003cimg src=\"https://github.githubassets.com/images/modules/site/features/actions-icon-actions.svg\" align=\"right\" height=\"40\"\u003e\u003c/a\u003e\n\n**GitHub Actions** are a CI/CD environment integrated directly with GitHub. More information about how to set up GitHub Actions can be found on the\n[GitHub website](https://docs.github.com/en/free-pro-team@latest/actions)\n\n![](https://jason-fox.github.io/fox.jason.unit-test/github-actions.png)\n\nA GitHub Action has been created to automate your [DITA-OT Plugin testing](https://github.com/jason-fox/dita-unit-test-action). To add automated CI/CD testing of your DITA-OT plug-ins, place your tests under a `test` directory under the root of the repository\nalong with the `ci.yml` in the `.github/workflows` directory.\n\n```yaml\nname: CI\n'on':\n  push:\n    branches:\n      - master\n  pull_request:\n    branches:\n      - master\njobs:\n  unit-test:\n    name: Unit Tests\n    runs-on: ubuntu-latest\n    steps:\n      - name: Git checkout\n        uses: actions/checkout@v2\n      - name: Run DITA-OT Unit Test\n        uses: jason-fox/dita-unit-test-action@master\n        with:\n          plugin: 'com.oxygenxml.editlink'\n```\n\n-   `plugin` - **Required** The name of the DITA-OT plugin to install and test.\n-   `setup-script` - The name of an optional bash script to run to install any dependencies prior to run the test. Defaults to `test-setup.sh` if not supplied.\n-   `prerequisites` - Comma separated list of additional DITA-OT plugins to install prior to installing the plugin under test.\n\n### Integration with Travis CI\n\n\u003ca href=\"https://travis-ci.com/\"\u003e\u003cimg src=\"https://www.libtom.net/images/TravisCI-Full-Color-45e242791b7752b745a7ae53f265acd4.png\" align=\"right\" height=\"40\"\u003e\u003c/a\u003e\n\n**Travis CI** is a hosted, distributed continuous integration service used to build and test software projects hosted at\nGitHub. More information about how to set up Travis integration can be found on the\n[Travis website](https://docs.travis-ci.com/).\n\n![](https://jason-fox.github.io/fox.jason.unit-test/travis.png)\n\nFor automated testing of DITA-OT plug-ins, place your tests under a `test` directory under the root of the repository\nalong with the `.travis.yml` in the root itself.\n\nFor example to test against DITA-OT 3.4.1 use the following `.travis.yml`:\n\n```yml\nlanguage: java\njdk:\n    - oraclejdk8\nenv:\n    - DITA_OT=3.4.1\n\nbefore_install:\n    - zip -r PLUGIN-NAME.zip . -x *.zip* *.git/* *temp/* *out/*\n    - curl -LO https://github.com/dita-ot/dita-ot/releases/download/$DITA_OT/dita-ot-$DITA_OT.zip\n    - unzip -q dita-ot-$DITA_OT.zip\n    - mv dita-ot*/ dita-ot/\n    - chmod +x dita-ot/bin/dita\n\ninstall:\n    - dita-ot/bin/dita install https://github.com/jason-fox/fox.jason.unit-test/archive/master.zip\n    - dita-ot/bin/dita install PLUGIN-NAME.zip\n\nscript:\n    - dita-ot/bin/dita --input dita-ot/plugins/PLUGIN-NAME -f unit-test -v\n```\n\nThis will do the following:\n\n-   Zip up the files in the plug-in under test\n-   install the specified DITA-OT version\n-   install the unit-testing framework (repeat this for other dependencies)\n-   install the plug-in under test\n-   Run the tests\n\nUnit tests will be run whenever a commit occurs.\n\nThe output will appear within the log as follows:\n\n```text\n[UNIT002I][INFO] Running tests for 'PLUGIN-NAME'\n  [antunit] Build File: /tmp/temp20180420185923919/unit-test/fixtures/PLUGIN-NAME/fixture.xml\n  [antunit] Tests run: 3, Failures: 0, Errors: 0, Time elapsed: 31.063 sec\n  [antunit] Target: test:    Expect that ...  took 7.202 sec\n  [antunit] Target: test:    Expect that ...  took 17.596 sec\n...etc\n\n[SUCCESS] All tests have passed\ndita2unit-test:\nclean-temp:\nThe command \"dita-ot/bin/dita --input dita-ot/plugins/PLUGIN-NAME -f unit-test -v\" exited with 0.\n```\n\n### Integration with Coveralls\n\n\u003ca href=\"https://coveralls.io/\"\u003e\u003cimg src=\"https://www.libtom.net/images/coveralls-bd6b762f7cf724a89de199133db5868f.png\" align=\"right\" height=\"40\"\u003e\u003c/a\u003e\n\n**Coveralls** is a web service to help you track your code coverage over time, and ensure that all your new code is\nfully covered. More information about how to set up Coveralls-Travis integration can be found on the\n[Coveralls website](https://docs.coveralls.io/).\n\n![](https://jason-fox.github.io/fox.jason.unit-test/coveralls.png)\n\nIf a plug-in has been instrumented (using the `xsl-instrument` transform) and unit tests are run, a Cobertura style\n`coverage.xml` file will be created along with the test results and a coverage report. This can be forwarded to\nCoveralls using the standard maven plug-in as shown:\n\n```yml\nlanguage: java\njdk:\n    - oraclejdk8\nenv:\n    - DITA_OT=3.4.1\n\nbefore_install:\n    - zip -r PLUGIN-NAME.zip . -x *.zip* *.git/* *temp/* *out/*\n    - curl -LO https://github.com/dita-ot/dita-ot/releases/download/$DITA_OT/dita-ot-$DITA_OT.zip\n    - unzip -q dita-ot-$DITA_OT.zip\n    - chmod +x dita-ot-$DITA_OT/bin/dita\n\ninstall:\n    - dita-ot-$DITA_OT/bin/dita install https://github.com/jason-fox/fox.jason.unit-test/archive/master.zip\n    - dita-ot-$DITA_OT/bin/dita install PLUGIN-NAME.zip\n\nbefore_script:\n    - dita-ot-$DITA_OT/bin/dita --input dita-ot-$DITA_OT/plugins/PLUGIN-NAME -f xsl-instrument\n\nscript:\n    - dita-ot-$DITA_OT/bin/dita --input dita-ot-$DITA_OT/plugins/PLUGIN-NAME -f unit-test --output . -v\n\nafter_success:\n    - cp dita-ot-$DITA_OT/plugins/fox.jason.unit-test/resource/pom.xml pom.xml\n    - mvn clean org.eluder.coveralls:coveralls-maven-plugin:report\n```\n\n## Unit Test File Structure\n\nThe unit tests are organized in the following manner:\n\n```\n├── test-suite-A\n│   └── test\n│       ├── unit-test-1\n│       ├── unit-test-2\n│       ├── ... etc\n│       ├── bootstrap.xml\n│       └── coverage.xml\n│\n├── test-suite-B\n│   └── test\n│       ├── unit-test-1\n│       ├── unit-test-2\n│       ├── ... etc\n│       ├── bootstrap.xml\n│       └── coverage.xml\n```\n\nEach suite of tests (identified by a directory called `test`) can be found in a separate directory. Each test within the\nsuite can be found in a separate sub-directory. A `coverage.xml` file should be added to each test suite to enable the\nframework to calculate coverage.\n\nThis structure means that an integration test of multiple plug-ins can be run by adding a `test` directory to each\nplug-in and invoking the tests as shown:\n\n```console\nPATH_TO_DITA_OT/bin/dita --input ./plugins -f unit-test\n```\n\n### Test suite files\n\n#### `bootstrap.xml` file\n\nAt the root of the tests lies a `bootstrap.xml` file which references the `antlib.xml` library as shown:\n\n```xml\n\u003cproject name=\"bootstrap.unit-test\"\u003e\n  \u003cdirname property=\"test.root.dir\" file=\"${ant.file.bootstrap.unit-test}/..\" /\u003e\n  \u003cproperty name=\"dita.dir\" location=\"PATH_TO_DITA_OT\"/\u003e\n  \u003ctypedef file=\"${dita.dir}/plugins/fox.jason.unit-test/resource/antlib.xml\"/\u003e\n\u003c/project\u003e\n```\n\n-   The location of `test.root.dir` must be set - this allows the expectation of a single test to be updated directly\n    from the command line independently of the test harness.\n-   The location of `dita.dir` must be set - this allows a single test to be run directly from the command line\n    independently of the test harness.\n-   The functions from the unit-test `antlib.xml` must be loaded using the `\u003ctypedef\u003e` task.\n\n#### `coverage.xml` file\n\nA token coverage file consists of a list of XML elements or string literals which should be present in a test-suite's\noutputs. For example, PDF tests should cover all possible fop element and attributes.\n\n```xml\n\u003cpackage name=\"org.dita.pdf2\"\u003e\n  \u003clines\u003e\n    \u003cline id=\"plain-text\"\u003efont-family=\"STANDARD\"\u003c/line\u003e\n    \u003cline id=\"monospace-text\"\u003efont-family=\"MONOSPACE\"\u003c/line\u003e\n  \u003c/lines\u003e\n  \u003celements\u003e\n    \u003celement id=\"codeblock\"\u003efo:block font-family=\"MONOSPACE\"\u003c/element\u003e\n    \u003celement id=\"codeph-tt\"\u003efo:inline font-family=\"MONOSPACE\"\u003c/element\u003e\n    \u003celement id=\"colspec\"\u003efo:table-column\u003c/element\u003e\n    \u003celement id=\"colspec-width\"\u003efo:table-column column-width\u003c/element\u003e\n  \u003c/elements\u003e\n\u003c/package\u003e\n```\n\n#### `template-coverage.xml` file\n\nAn XSL coverage file consists of a list of XSL elements which are present within a plug-in. This file is generated by\nthe `xsl-instrument` transform\n\n```xml\n\u003cpackage name=\"fox.jason.unit-test\"\u003e\n   \u003cclasses\u003e\n      \u003cclass name=\"xsl/order\" filename=\"xsl/order.xsl\"\u003e\n         \u003clines\u003e\n            \u003cline id=\"d6e3:xsl/order.xsl\"\n                  element=\"xsl:template\"\n                  open=\"true\"\n                  indent=\"1\"\n                  branch=\"false\"\n                  attributes=\"match=\u0026#34;/\u0026#34;\"\n                  number=\"13\"\u003ed6e3:xsl/order.xsl\u003c/line\u003e\n            \u003cline id=\"d6e3:xsl/order.xsl\"\n                  element=\"xsl:apply-templates\"\n                  open=\"true\"\n                  indent=\"2\"\n                  branch=\"false\"\n                  attributes=\"select=\u0026#34;//failed-assert\u0026#34;\"\n                  number=\"19\"/\u003e\n```\n\n#### `disabled.txt` file\n\nIf a `disabled.txt` file is present within a test suite directory, none of the tests within the directory will be run.\n\n#### Overrides for `attributes.xml` `colors.xml` and `fonts.xml`\n\nThe `cfg` directory of the plug-in holds standard lists of fonts, colors and attributes to replace when running PDF\ntests - this can be overridden by individuals test or test suites if necessary by placing an equivalent override file in\nthe test directory or test-suite directory.\n\n#### Overrides for `test.properties`\n\nAdditional test properties can be passed to DITA-OT when each test is run if a `test.properties` file is present in the\ntest directory or test-suite directory. The name of the file to search for can also be altered. See\n[Setting build parameters with `.properties` files](http://www.dita-ot.org/3.0/topics/using-dita-properties-file.html)\nfor more details.\n\n### Individual test files\n\nEach unit test is organized in the following manner:\n\n```\n├── build.xml\n├── document.ditamap\n├── expected.html\n├── test.properties (optional)\n└── topics\n    └── *.dita files\n```\n\n-   An ANT `build.xml` file to invoke the test\n-   A `document.ditamap` referring to the individual `*.dita` files\n-   An optional `test.properties` file if passing any additional properties to DITA-OT\n-   A test expectation (usually called `expected.html` or `expected.fo`)\n-   Any further `*.dita` files or source files, graphics etc. required for the test.\n\nThe `build.xml` must consist of a single default target, and `import` the `bootstrap.xml` file as shown. The\n`description` is used within the test report.\n\n```xml\n\u003cproject basedir=\".\" default=\"unit-test\"\u003e\n  \u003cimport file=\"../../bootstrap.xml\"/\u003e\n  \u003cdescription\u003e\n    Body text should be displayed in the standard font\n  \u003c/description\u003e\n  \u003ctarget name=\"unit-test\"\u003e\n      \u003cexec-html5/\u003e\n      \u003cget-html-article from=\"topics/body-text.html\"/\u003e\n      \u003ccompare-output suffix=\".html\"/\u003e\n  \u003c/target\u003e\n\u003c/project\u003e\n```\n\n-   An individual test can be run directly from the command line by running the default target.\n-   Adding the comment `\u003c!-- @disabled --\u003e` within the `build.xml` file will disable a test\n\n## API\n\nThe following ANT tasks are available from the DITA-OT Unit Test Framework\n\n### Compare-Output\n\n#### Description\n\nFail the test if the test output file does not match the expectation file\n\n#### Parameters\n\n| Attribute   | Description                                                                 | Required                          |\n| ----------- | --------------------------------------------------------------------------- | --------------------------------- |\n| expectation | Location of the file that the output should match                           | No; defaults to `expected.fo`     |\n| os          | Only make the comparison if the current operating system is of a given type | No; defaults to `any`             |\n| result      | Location of the file output by the test                                     | No; defaults to `out/fragment.fo` |\n| suffix      | File suffix used by the test expectation                                    | No; defaults to `.fo`             |\n\n#### Examples\n\n```xml\n\u003ccompare-output/\u003e\n```\n\ncompares the file `out/fragment.fo` with `expected.fo` and fails if they do not match.\n\n```xml\n\u003ccompare-output suffix=\".html\"/\u003e\n```\n\ncompares the file `out/fragment.html` with `expected.html` and fails if they do not match.\n\n```xml\n\u003ccompare-output suffix=\".svrl\" expectation=\"expected.svrl.win\" os=\"windows\"/\u003e\n```\n\nif running on a Windows system, compares the file `out/fragment.svrl` with `expected.svrl.win` and fails if they do not\nmatch.\n\nif running on a UNIX system, no comparison is made.\n\n### Contains-Text\n\n#### Description\n\nFail the test if the log from the test does not contain the given string\n\n#### Parameters\n\n| Attribute | Description                                                                 | Required                            |\n| --------- | --------------------------------------------------------------------------- | ----------------------------------- |\n| actual    | The text actually output by the test                                        | No; defaults to output from DITA-OT |\n| expected  | The expected fragment of text                                               | Yes                                 |\n| os        | Only make the comparison if the current operating system is of a given type | No; defaults to `any`               |\n\n#### Examples\n\n```xml\n\u003ccontains-text expected=\"Lorem Ipsum\"/\u003e\n```\n\ncompares the output of DITA-OT and fails if the text \"Lorem Ipsum\" cannot be found\n\n```xml\n\u003ccontains-text expected=\"This is running on Windows\" os=\"windows\"/\u003e\n```\n\nif running on a Windows system, compares the output of DITA-OT and fails if the text \"This is running on Windows\" cannot\nbe found\n\nif running on a UNIX system, no comparison is made.\n\n### Exec-HTML5\n\n#### Description\n\nExecute the HTML5 DITA-OT transform in verbose mode The test will fail if the result was not as expected or took too\nlong\n\n#### Parameters\n\n| Attribute      | Description                                                                                  | Required                                                                                       |\n| -------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| ditamap        | The `*.ditamap` file specifying which topics and other resources to use to create a document | No; defaults to `document.ditamap`                                                             |\n| expectedresult | The expected result when invoking the transform                                              | No; defaults to `0` = success                                                                  |\n| maxwait        | The maximum time to create a document                                                        | No; defaults to 100 seconds                                                                    |\n| propertyfile   | The name of a file holding additional properties                                             | No; defaults to `test.properties`                                                              |\n| transtype      | The transtype to invoke when creating the document                                           | No; this can be `html5` or any DITA-OT transform that extends `base-html`; defaults to `html5` |\n\n#### Examples\n\n```xml\n\u003cexec-html5 transtype=\"custom-html\"/\u003e\n```\n\nruns DITA-OT using the `custom-html` HTML transtype. the output will be placed in the `/out/html` directory\n\n### Exec-PDF\n\n#### Description\n\nExecute the PDF DITA-OT transform in verbose mode\n\n#### Parameters\n\n| Attribute      | Description                                                                                  | Required                                                                                |\n| -------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| ditamap        | The `*.ditamap` file specifying which topics and other resources to use to create a document | No; defaults to `document.ditamap`                                                      |\n| expectedresult | The expected result when invoking the transform                                              | No; defaults to `0` = success                                                           |\n| maxwait        | The maximum time to create a document                                                        | No; defaults to 100 seconds                                                             |\n| propertyfile   | The name of a file holding additional properties                                             | No; defaults to `test.properties`                                                       |\n| transtype      | The transtype to invoke when creating the document                                           | No; this can be `pdf2` or any DITA-OT transform that extends `pdf2`; defaults to `pdf2` |\n\n#### Examples\n\n```xml\n\u003cexec-pdf transtype=\"custom-pdf\"/\u003e\n```\n\nruns DITA-OT using the `custom-pdf` PDF transtype. `topic.fo` and `document.pdf` will be placed in the `/out` directory\n\n### Exec-SVRL\n\n#### Description\n\nExecute the HERE Validator SVRL DITA-OT transform in verbose mode. The test will fail if the result was not as expected\nor took too long.\n\n#### Parameters\n\n| Attribute      | Description                                                                                  | Required                                                                                |\n| -------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| ditamap        | The `*.ditamap` file specifying which topics and other resources to use to create a document | No; defaults to `document.ditamap`                                                      |\n| expectedresult | The expected result when invoking the transform                                              | No; defaults to `0` = success                                                           |\n| maxwait        | The maximum time to create a document                                                        | No; defaults to 100 seconds                                                             |\n| propertyfile   | The name of a file holding additional properties                                             | No; defaults to `test.properties`                                                       |\n| transtype      | The transtype to invoke when creating the document                                           | No; this can be `svrl` or any DITA-OT transform that extends `svrl`; defaults to `svrl` |\n\n#### Examples\n\n```xml\n\u003cexec-svrl transtype=\"text-rules\"/\u003e\n```\n\nruns DITA-OT using the `text-rules` SVRL transtype\n\n```xml\n\u003cexec-svrl transtype=\"svrl-echo\" expectedresult=\"1\"/\u003e\n```\n\nruns DITA-OT using the `svrl-echo` SVRL transtype - the invocation is expected to fail with validation errors.\n\n### Exec-Transtype\n\n#### Description\n\nExecute an arbitrary DITA-OT transform in verbose mode. The test will fail if the result was not as expected or took too\nlong.\n\n#### Parameters\n\n| Attribute      | Description                                                                                  | Required                                                                                |\n| -------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| ditamap        | The `*.ditamap` file specifying which topics and other resources to use to create a document | No; defaults to `document.ditamap`                                                      |\n| expectedresult | The expected result when invoking the transform                                              | No; defaults to `0` = success                                                           |\n| maxwait        | The maximum time to create a document                                                        | No; defaults to 100 seconds                                                             |\n| propertyfile   | The name of a file holding additional properties                                             | No; defaults to `test.properties`                                                       |\n| transtype      | The transtype to invoke when creating the document                                           | No; this can be `svrl` or any DITA-OT transform that extends `svrl`; defaults to `svrl` |\n\n#### Examples\n\n```xml\n\u003cexec-svrl transtype=\"custom\"/\u003e\n```\n\nruns DITA-OT using the `custom` transtype\n\n```xml\n\u003cexec-svrl transtype=\"custom\" expectedresult=\"1\"/\u003e\n```\n\nruns DITA-OT using the `custom` SVRL transtype - the invocation is expected to fail.\n\n### Get-HTML-Article\n\n#### Description\n\nLoads a given HTML file and extracts the first `\u003carticle\u003e` element (which corresponds to a DITA topic) for further\nexamination.\n\n#### Parameters\n\n| Attribute | Description                                                      | Required                            |\n| --------- | ---------------------------------------------------------------- | ----------------------------------- |\n| dir       | Location of the files output by the test                         | No; defaults to `out/html`          |\n| from      | the name of the file to extract an HTML fragment from            | Yes                                 |\n| to        | Location of the output file holding the fragment of HTML to test | No; defaults to `out/fragment.html` |\n\n#### Examples\n\n```xml\n\u003cget-html-article from=\"topics/body-text.html\"/\u003e\n```\n\ncreates a file called `fragment.html` holding the `\u003carticle\u003e` element from the `topics/body-text.html` file.\n\n### Get-PDF-Article\n\n#### Description\n\nLoads a given `topic.fo` file and extracts the last `fo.flow` element (which corresponds to a DITA topic) for further\nexamination. Also remove colors, fonts and excess attributes\n\n#### Parameters\n\n| Attribute | Description                                                     | Required                          |\n| --------- | --------------------------------------------------------------- | --------------------------------- |\n| from      | Location of the file to extract an HTML fragment from           | No; defaults to `out/topic.fo`    |\n| to        | Location of the output file holding the fragment of FOP to test | No; defaults to `out/fragment.fo` |\n\n#### Examples\n\n```xml\n\u003cget-pdf-article/\u003e\n```\n\ncreates a file called `fragment.fo` holding the final `\u003cfo.flow\u003e` element from the `topics.fo` file.\n\n## Contribute\n\nPRs accepted.\n\n## License\n\n[Apache 2.0](LICENSE) © 2018 - 2024 Jason Fox\n\nThe Program includes the following additional software components which were obtained under license:\n\n-   ant-antunit.jar - https://ant.apache.org/antlibs/antunit/ - **Apache 2.0 license**\n-   ant-contrib.jar - http://ant-contrib.sourceforge.net/ - **Apache 2.0 license**\n-   ant-junit.jar - https://ant.apache.org/ - **Apache 2.0 license**\n-   Saxon-9.1.0.8.jar - http://saxon.sourceforge.net/ - **Mozilla Public license 1.0**\n-   Saxon-9.1.0.8-dom.jar - http://saxon.sourceforge.net/ - **Mozilla Public license 1.0**\n-   xmltask.jar - http://www.oopsconsultancy.com/software/xmltask/ - **Apache 1.1 license**\n-   antro.jar - https://github.com/jkff/antro/ - **Gnu General Public License 3**\n-   swingx-2008_03_09.jar - http://swingx.dev.java.net/ - **Gnu General Public License 3**\n-   json.jar- http://www.json.org/ - **Gnu General Public License 3**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjason-fox%2Ffox.jason.unit-test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjason-fox%2Ffox.jason.unit-test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjason-fox%2Ffox.jason.unit-test/lists"}