| // Copyright 2023 The Khronos Group Inc. |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| = Spec Build Tests |
| |
| This directory contains test source and expectation files for the `testBuild` |
| script. The test specification files are: |
| |
| * `testspec.adoc` |
| * `chapters/*.adoc` |
| * `chapters/commonvalidity/*.adoc` |
| * `appendices/*.adoc` |
| * `images/*.svg` |
| |
| The expectation files are: |
| |
| * `expectations/*.html` |
| * `expectations/validusage.json` |
| |
| The `testBuild` script builds the test specficiation (`testspec.adoc`) in an |
| array of configurations, such as Core (latest), Core 1.0, with all extensions, |
| with a specific extension etc. Additionally, it extracts the VUs into |
| validusage.json. |
| |
| Each build by `testBuild` is done in a separate directory under `gen-<build>`. |
| In all cases except `gen-validusage`, the output is |
| `gen-<build>/out/html/vkspec.html`. In the case of `gen-validusage`, the output |
| is `gen-validusage/out/validition/validusage.json`. |
| |
| The primary reason for these tests is ensuring correctness of asciidoc |
| extensions implemented in this repository. The `testBuild` script first builds |
| all configurations, then verifies the results against the expectations. |
| |
| If a build itself regresses (and fails), the script will stop so the issue can |
| be addressed after looking at the logs of the failing build. If the builds |
| succeed but the output does not match the expectations, the diff is output for |
| investigation. |
| |
| In some cases, the diff is small enough to be verified. Otherwise, each output |
| in `gen-<build>/` needs to be manually reviewed to ensure the results are still |
| correct; for example because the html is styled differently and the differences |
| are as expected. |
| |
| If the mismatch between the output and expectations is expected, and the output |
| is verified to be correct, update the expectations with: |
| |
| ---- |
| $ ./update-expectations |
| ---- |
