建档

Library/SDL2_image-2.5.2/test/README.md

@@ -0,0 +1,77 @@
+`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.