# [`gltest`][]
A [C++11][]/[OpenGL][] \>=[1.0][] [testing][] library.
[`gltest`]: https://git.rcrnstn.net/rcrnstn/gltest
[C++11]: https://en.wikipedia.org/wiki/C++11
[OpenGL]: https://en.wikipedia.org/wiki/OpenGL
[1.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history
## Usage
```cpp
#include <cerrno>
#include <cstring>
#include <fstream>
#include <stdexcept>
#include <string>
#include <GL/glew.h>
#include <glbackend.hpp>
#include <gltest.hpp>
// Function that throws with a system-supplied message.
void file_open(std::string const & filename)
{
auto file = std::ifstream{"nonexistent"};
if (!file)
throw std::runtime_error(std::string{} +
"Could not open file '" + filename + "':\n" +
std::strerror(errno) + "." // NOLINT
);
}
GLTEST(gltest, 640, 480, 2, 0)
{
backend.prefix("assets/tests");
GLTEST_EXPECT_VALUE(
GL_FALSE,
glIsEnabled(GL_DEPTH_TEST)
)
GLTEST_EXPECT_EXCEPTION(false,
"Expected exception",
throw std::runtime_error("Expected exception")
)
GLTEST_EXPECT_EXCEPTION(true,
"Could not open file 'nonexistent':\n",
// "No such file or directory"
file_open("nonexistent")
)
constexpr auto size = 0.5;
glBegin(GL_TRIANGLE_STRIP);
glVertex3f(-size, -size, 0);
glVertex3f(-size, +size, 0);
glVertex3f(+size, -size, 0);
glVertex3f(+size, +size, 0);
glEnd();
backend.tga_compare("GLTest.tga");
}
```
A `main()` entry point is provided which calls each test declared with the
macro `GLTEST(VERSION_MAJOR, VERSION_MINOR, WIDTH, HEIGHT, NAME)`. A double
buffered OpenGL debug context compatible with the specified version and with a
window of the specified width and height is set up prior to each test run and
teared down afterwards.
If OpenGL \>=4.3 or the extension [`KHR_debug`][] is available,
non-notification debug messages throw errors unless disabled by calling `bool
gltest_debug(false)` (which returns the old value). The root directory for
reading and writing files is set with `void gltest_root(std::string)`. Timing
can be manipulated with `void gltest_set_time(float)` and `float
gltest_get_time()`. Swapping buffers is performed with `void
gltest_swap_buffers()`.
The macro `GLTEST_EXPECT_VALUE(EXPR, VALUE)` runs `EXPR`, compares the result
to `VALUE` and throws an error if they do not match.
The macro `GLTEST_EXPECT_EXCEPTION(PREFIX, EXPR, WHAT)` catches any
[`std::exception`][]-derived exception thrown by `EXPR`, compares its
[`what()`][] to `WHAT` and throws an error if they do not match. If `PREFIX` is
true it is only required that `WHAT` is a prefix of `what()`, to allow trailing
external messages of unknown format. An error is also thrown if `EXPR` throws
no exception at all. `gltest_debug(false)` is automatically called before
`EXPR` is run, the previous value is restored afterwards.
The macro `GLTEST_EXPECT_FRAME(PATH)` reads `PATH` from disk, compares it to
the current (back) framebuffer and throws an error if they do not match. If
`PATH` does not exist, the current framebuffer is instead written to it and a
warning is printed.
If a `GLTEST_EXPECT_*` fails, the values of `GL_VENDOR`, `GL_RENDERER`,
`GL_VERSION` and `GL_SHADING_LANGUAGE_VERSION` is printed to standard error. In
addition, `GLTEST_EXPECT_VALUE` or `GLTEST_EXPECT_EXCEPTION` print something in
the style of:
```
>>> Expression:
glIsEnabled(GL_DEPTH_TEST)
>>> Expected value:
GL_TRUE = 1
>>> Got:
0
```
[`std::exception`]: https://en.cppreference.com/w/cpp/error/exception
[`what()`]: https://en.cppreference.com/w/cpp/error/exception/what
[`KHR_debug`]: https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_debug.txt
## Build system
This project supports [CMake][] and uses [`cmake-common`][]. There are several
ways to use it in other CMake-based projects:
- With [`find_package`][]: ([Package][] and) [install][] it on the system.
- With [`add_subdirectory`][]: Bundle it.
- With [`FetchContent`][]: Download it as part of the CMake configure step.
- With [`cmake-common`][]: Use any of the above methods through a simplified
interface.
As usual, use [`add_dependencies`][] or [`target_link_libraries`][] (or
`cmake-common`'s `DEPENDENCIES_*`) to declare the dependency.
[CMake]: https://cmake.org
[`cmake-common`]: https://git.rcrnstn.net/rcrnstn/cmake-common
[`FetchContent`]: https://cmake.org/cmake/help/v3.14/module/FetchContent.html
[`add_subdirectory`]: https://cmake.org/cmake/help/v3.14/command/add_subdirectory.html
[`find_package`]: https://cmake.org/cmake/help/v3.14/command/find_package.html
[Package]: #Package
[Install]: #Install
[`add_dependencies`]: https://cmake.org/cmake/help/v3.14/command/add_dependencies.html
[`target_link_libraries`]: https://cmake.org/cmake/help/v3.14/command/target_link_libraries.html
### Configure and generate
To configure and generate a build tree, use `cmake`:
```sh
cmake -B _build
```
To set the build type, pass e.g. `-D`[`CMAKE_BUILD_TYPE`][]`=Release`.
[`cmake`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#generate-a-project-buildsystem
[`CMAKE_BUILD_TYPE`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_BUILD_TYPE.html
### Build
To build, use [`cmake --build`][]:
```sh
cmake --build _build
```
To disable building tests, pass `-D`[`BUILD_TESTING`][]`=OFF`.
[`cmake --build`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#build-a-project
[`BUILD_TESTING`]: https://cmake.org/cmake/help/v3.14/module/CTest.html
### Test
To run tests, use [`ctest`][]:
```sh
(cd _build && ctest)
```
To show output from failing tests, pass `--output-on-failure`. To show output
from all tests, pass `--verbose`.
[`ctest`]: https://cmake.org/cmake/help/v3.14/manual/ctest.1.html
### Package
To package, use [`cpack`][]:
```sh
(cd _build && cpack)
```
[`cpack`]: https://cmake.org/cmake/help/v3.14/manual/cpack.1.html
### Install
To install onto the current system, use [`cmake --install`][]:
```sh
cmake --install _build
```
To set the prefix, pass e.g. `-D`[`CMAKE_INSTALL_PREFIX`][]`="$HOME/.local"`.
[`cmake --install`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#install-a-project
[`CMAKE_INSTALL_PREFIX`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_INSTALL_PREFIX.html
## License
Licensed under the [ISC License][] unless otherwise noted, see the
[`LICENSE`][] file.
[ISC License]: https://choosealicense.com/licenses/isc
[`LICENSE`]: LICENSE
git.rcrnstn.net