77 lines
3.1 KiB
Markdown
77 lines
3.1 KiB
Markdown
`SDL2_image` automated test
|
|
===========================
|
|
|
|
Build-time tests
|
|
----------------
|
|
|
|
Configure with `--enable-tests` (Autotools) or `-DSDL2IMAGE_TESTS` (CMake).
|
|
|
|
Run build-time tests in the usual way, for example `make check`
|
|
(Autotools), or `ctest` or `make test` (CMake).
|
|
|
|
"As-installed" tests
|
|
--------------------
|
|
|
|
The tests can be installed alongside the library, allowing them to be
|
|
run on a target platform as a somewhat realistic equivalent of how a
|
|
game would behave.
|
|
|
|
Configure with `--enable-tests --enable-installed-tests` (Autotools) or
|
|
`-DSDL2IMAGE_TESTS -DSDL2IMAGE_TESTS_INSTALL` (CMake).
|
|
|
|
The tests and their required resource files are installed into
|
|
`${libexecdir}/installed-tests/SDL2_image`. When run, they will write
|
|
to the current working directory: create a temporary directory and run
|
|
them from there if necessary.
|
|
|
|
On platforms where `SDL_GetBasePath()` returns the directory containing
|
|
the executable, the whole `installed-tests/SDL2_image` directory can be
|
|
copied to any location and `testimage` can be run from there.
|
|
|
|
Metadata describing the tests is installed in
|
|
`${datadir}/installed-tests/SDL2_image`. This can be used to run the
|
|
tests with `ginsttest-runner` from
|
|
[gnome-desktop-testing](https://gitlab.gnome.org/GNOME/gnome-desktop-testing),
|
|
or any implementation of the same
|
|
[specification](https://wiki.gnome.org/Initiatives/GnomeGoals/InstalledTests).
|
|
|
|
Asserting format support
|
|
------------------------
|
|
|
|
By default, for each format that was configured at build-time, the test
|
|
asserts that the format can be loaded or saved as appropriate. Formats
|
|
that were not enabled at build-time are not tested.
|
|
|
|
This automatic behaviour is not always desirable: for example, if there
|
|
was a build-system regression that accidentally disabled WEBP support,
|
|
or if the required WEBP library was missing or not detected at build
|
|
time, then the test would would report WEBP as unsupported but would
|
|
not fail.
|
|
|
|
To check that the intended formats are actually supported, distributors
|
|
can set some environment variables before running the tests:
|
|
|
|
* For each *format* where loading can be supported, if
|
|
`SDL_IMAGE_TEST_REQUIRE_LOAD_` + *format* is set to 1,
|
|
the test will fail unless `SDL2_image` can load *format*.
|
|
(For example, `export SDL_IMAGE_TEST_REQUIRE_LOAD_WEBP=1`.)
|
|
|
|
* For each *format* where saving can be supported (`JPG` or `PNG`), if
|
|
`SDL_IMAGE_TEST_REQUIRE_SAVE_` + *format* is set to 1,
|
|
the test will fail unless `SDL2_image` can load *format*.
|
|
(For example, `export SDL_IMAGE_TEST_REQUIRE_SAVE_JPG=1`.)
|
|
|
|
Setting these variables to 0 causes them to be ignored, returning to the
|
|
automatic behaviour where the formats that were enabled at build-time
|
|
will be tested.
|
|
|
|
These variables are not set automatically for supported formats by the
|
|
Autotools or CMake build system, because that would defeat their purpose
|
|
of detecting build-system bugs.
|
|
|
|
The abbreviation used for *format* is the same as in the `supported[]`
|
|
table in `IMG.c`, for example `JPG` or `TIF`. `JPEG` and `TIFF` are
|
|
ignored.
|
|
|
|
On operating systems where environment variables are case-sensitive,
|
|
*format* must be in upper-case.
|