// 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
----