Replace visual tests CMake options with environment variables of the same name

Applies to the options:
- RMLUI_VISUAL_TESTS_RML_DIRECTORIES
- RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY
- RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY

Document the options better in the Tests readme and the CSS test conversion tool.

CMakeLists.txt

@@ -46,9 +46,6 @@ if(RMLUI_IS_ROOT_PROJECT)
 	if(BUILD_TESTING)
 		enable_testing()
 		set(RMLUI_TESTS ON)
-		set(RMLUI_VISUAL_TESTS_RML_DIRECTORIES "" CACHE PATH "Specify additional directories containing *.rml test documents for VisualTests. Separate multiple directories by comma.")
-		set(RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY "" CACHE PATH "Set the input directory for screenshot comparison performed by VisualTests.")
-		set(RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY "" CACHE PATH "Set the output directory for screenshots generated by VisualTests.")
 		if(WIN32 AND BUILD_SHARED_LIBS AND NOT CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS)
 			message(FATAL_ERROR "The RmlUi testing framework cannot be built when using shared libraries with default visibility on Windows. "
 				"Please disable either BUILD_SHARED_LIBS or BUILD_TESTING.")

Tests/Source/VisualTests/CMakeLists.txt

@@ -23,13 +23,3 @@ target_link_libraries(${TARGET_NAME} PRIVATE
 	rmlui_shell
 	lodepng::lodepng
 )
-
-if(RMLUI_VISUAL_TESTS_RML_DIRECTORIES)
-	target_compile_definitions(${TARGET_NAME} PRIVATE RMLUI_VISUAL_TESTS_RML_DIRECTORIES="${RMLUI_VISUAL_TESTS_RML_DIRECTORIES}")
-endif()
-if(RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY)
-	target_compile_definitions(${TARGET_NAME} PRIVATE RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY="${RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY}")
-endif()
-if(RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY)
-	target_compile_definitions(${TARGET_NAME} PRIVATE RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY="${RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY}")
-endif()

Tests/Source/VisualTests/TestConfig.cpp

@@ -31,24 +31,29 @@
 #include <RmlUi/Core/Types.h>
 #include <PlatformExtensions.h>
 #include <Shell.h>
+#include <cstdlib>
 
 Rml::String GetCompareInputDirectory()
 {
-#ifdef RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY
-	const Rml::String input_directory = Rml::String(RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY);
-#else
-	const Rml::String input_directory = PlatformExtensions::FindSamplesRoot() + "../Tests/Output";
-#endif
+	Rml::String input_directory;
+
+	if (const char* env_variable = std::getenv("RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY"))
+		input_directory = env_variable;
+	else
+		input_directory = PlatformExtensions::FindSamplesRoot() + "../Tests/Output";
+
 	return input_directory;
 }
 
 Rml::String GetCaptureOutputDirectory()
 {
-#ifdef RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY
-	const Rml::String output_directory = Rml::String(RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY);
-#else
-	const Rml::String output_directory = PlatformExtensions::FindSamplesRoot() + "../Tests/Output";
-#endif
+	Rml::String output_directory;
+
+	if (const char* env_variable = std::getenv("RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY"))
+		output_directory = env_variable;
+	else
+		output_directory = PlatformExtensions::FindSamplesRoot() + "../Tests/Output";
+
 	return output_directory;
 }
 
@@ -58,9 +63,8 @@ Rml::StringList GetTestInputDirectories()
 
 	Rml::StringList directories = {samples_root + "../Tests/Data/VisualTests"};
 
-#ifdef RMLUI_VISUAL_TESTS_RML_DIRECTORIES
-	Rml::StringUtilities::ExpandString(directories, RMLUI_VISUAL_TESTS_RML_DIRECTORIES, ',');
-#endif
+	if (const char* env_variable = std::getenv("RMLUI_VISUAL_TESTS_RML_DIRECTORIES"))
+		Rml::StringUtilities::ExpandString(directories, env_variable, ',');
 
 	return directories;
 }

Tests/Tools/convert_css_test_suite_to_rml.py

@@ -31,8 +31,19 @@ import argparse
 parser = argparse.ArgumentParser(description=\
 '''Convert the W3C CSS 2.1 test suite to RML documents for testing in RmlUi.
 
-Fetch the CSS tests archive from here: https://www.w3.org/Style/CSS/Test/CSS2.1/
-Extract the 'xhtml1' folder and point the 'in_dir' argument to this directory.''')
+Instructions:
+  1. Fetch the CSS tests archive from here: https://www.w3.org/Style/CSS/Test/CSS2.1/
+  2. Extract the 'xhtml1' folder, and point the 'in_dir' argument to this directory.
+  3. Call this script with the 'out_dir' argument pointing to a directory of your choosing.
+
+The resulting tests can be opened in the `Visual tests` application. Set the environment variable
+`RMLUI_VISUAL_TESTS_RML_DIRECTORIES` to the 'out_dir' used above. After opening the application, use
+the arrow keys Up/Down to change the test suite directory.
+
+This script can also be used with the CSS3 test suites, such as the one for flexbox:
+	https://test.csswg.org/suites/css-flexbox-1_dev/nightly-unstable/
+''',
+formatter_class=argparse.RawTextHelpFormatter)
 
 parser.add_argument('in_dir',
                     help="Input directory which contains the 'xhtml1' (.xht) files to be converted.")

Tests/readme.md

@@ -1,27 +1,35 @@
 ## RmlUi Test Suite
 
-This directory contains tests and benchmarks for RmlUi. They have been separated into three projects located under the `Source` directory. These projects can be enabled using the CMake options `BUILD_TESTING`.
+This directory contains tests and benchmarks for RmlUi. They have been separated into three projects located under the `Source` directory. These projects can be enabled using the CMake options `BUILD_TESTING`, and built using the CMake targets below.
 
+#### Visual tests: `rmlui_visual_tests`
 
-#### Visual tests
+For visually testing the layout engine in particular, with small test documents that can easily be added. Includes features for capturing and comparing tests for easily spotting differences during development. A conversion script for CSS tests is available, as described below.
 
-For visually testing the layout engine in particular, with small test documents that can be easily added. Includes features for capturing and comparing tests for easily spotting differences during development. A conversion script for the CSS 2.1 tests is available as described below.
+The following environment variables can be used to configure the directories used for the visual tests:
 
-#### Unit tests
+| Environment variable                   | Description                                                                                                                                                 |
+|----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `RMLUI_VISUAL_TESTS_RML_DIRECTORIES`   | Additional directories containing `*.rml` test documents. Separate multiple directories by comma. Change test suite directory using `Up`/`Down` arrow keys. |
+| `RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY` | Input directory for screenshot comparisons.                                                                                                                 |
+| `RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY` | Output directory for generated screenshots.                                                                                                                 |
 
-To ensure smaller units of the library are working properly.
 
-#### Benchmarks
+#### Unit tests: `rmlui_unit_tests`
+
+Ensures smaller units of the library are working properly.
 
-Benchmarking various components of the library to keep track of performance improvements or regressions for future development, and to find any performance hotspots that could need extra attention.
 
+#### Benchmarks: `rmlui_benchmarks`
+
+Benchmarking various components of the library to keep track of performance improvements or regressions for future development, and to find any performance hotspots that could need extra attention.
 
 
 ### Directory Overview
 
 #### `Data`
 
-This directory contains the shared style sheets and documents, as well as the source documents for the included visual tests. All documents located under `Data/VisualTests/` will automatically be loaded by the visual tests project. Additional source folders can be specified with the CMake option `RMLUI_VISUAL_TESTS_RML_DIRECTORIES`. 
+This directory contains the shared style sheets and documents, as well as the source documents for the included visual tests. All documents located under `Data/VisualTests/` will automatically be loaded by the visual tests project. Additional source folders can be specified with the environment variable `RMLUI_VISUAL_TESTS_RML_DIRECTORIES` as described above. 
 
 #### `Dependencies`
 
@@ -29,7 +37,7 @@ This directory contains additional libraries used by the test suite.
 
 #### `Output`
 
-By default, the visual tests will store screenshots and other outputs into this directory, and read previous screenshots from this directory. To specify other directories, use the CMake options `RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY` and `RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY`.
+By default, the visual tests will store screenshots and other outputs into this directory, and read previous screenshots from this directory. To specify other directories, use the environment variables options `RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY` and `RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY` as described above.
 
 #### `Source`
 
@@ -37,4 +45,4 @@ Source code for the test suite.
                
 #### `Tools`
 
-Includes a best-effort conversion script for the [CSS 2.1 tests](https://www.w3.org/Style/CSS/Test/CSS2.1/), which includes thousands of tests, to RML/RCSS for testing conformance with the CSS specifications.
+Includes a best-effort conversion script for the [CSS 2.1 tests](https://www.w3.org/Style/CSS/Test/CSS2.1/) in particular, which includes thousands of tests, to RML/RCSS for testing conformance with the CSS specifications. Also works with some CSS 3 tests, like for [flexbox](https://test.csswg.org/suites/css-flexbox-1_dev/) support.

changelog.md

@@ -294,32 +294,32 @@ We have a new set of CMake naming conventions for the library:
 
 The following table lists all the new option names.
 
-| Option                               | Default value | Old related option             | Comment                                                                                                                                 |
-|--------------------------------------|---------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
-| RMLUI_BACKEND                        | auto          | SAMPLES_BACKEND                |                                                                                                                                         |
-| RMLUI_COMPILER_OPTIONS               | ON            |                                | Automatically sets recommended compiler flags                                                                                           |
-| RMLUI_CUSTOM_CONFIGURATION           | OFF           | CUSTOM_CONFIGURATION           |                                                                                                                                         |
-| RMLUI_CUSTOM_CONFIGURATION_FILE      |               | CUSTOM_CONFIGURATION_FILE      |                                                                                                                                         |
-| RMLUI_CUSTOM_INCLUDE_DIRS            |               | CUSTOM_INCLUDE_DIRS            |                                                                                                                                         |
-| RMLUI_CUSTOM_LINK_LIBRARIES          |               | CUSTOM_LINK_LIBRARIES          |                                                                                                                                         |
-| RMLUI_CUSTOM_RTTI                    | OFF           | DISABLE_RTTI_AND_EXCEPTIONS    | No longer modifies compiler flags - only enables RmlUi's custom RTTI solution so that the user can disable language RTTI and exceptions |
-| RMLUI_FONT_ENGINE                    | freetype      | NO_FONT_INTERFACE_DEFAULT      | Now takes a string with one of the options: `none`, `freetype`                                                                          |
-| RMLUI_HARFBUZZ_SAMPLE                | OFF           |                                |                                                                                                                                         |
-| RMLUI_INSTALL_RUNTIME_DEPENDENCIES   | ON            |                                | Automatically install runtime dependencies on supported platforms (e.g. DLLs)                                                           |
-| RMLUI_LOTTIE_PLUGIN                  | OFF           | ENABLE_LOTTIE_PLUGIN           |                                                                                                                                         |
-| RMLUI_LUA_BINDINGS                   | OFF           | BUILD_LUA_BINDINGS             |                                                                                                                                         |
-| RMLUI_LUA_BINDINGS_LIBRARY           | lua           | BUILD_LUA_BINDINGS_FOR_LUAJIT  | Now takes a string with one of the options: `lua`, `lua_as_cxx`, `luajit`                                                               |
-| RMLUI_MATRIX_ROW_MAJOR               | OFF           | MATRIX_ROW_MAJOR               |                                                                                                                                         |
-| RMLUI_PRECOMPILED_HEADERS            | ON            | ENABLE_PRECOMPILED_HEADERS     |                                                                                                                                         |
-| RMLUI_SAMPLES                        | OFF           | BUILD_SAMPLES                  |                                                                                                                                         |
-| RMLUI_SVG_PLUGIN                     | OFF           | ENABLE_SVG_PLUGIN              |                                                                                                                                         |
-| RMLUI_THIRDPARTY_CONTAINERS          | ON            | NO_THIRDPARTY_CONTAINERS       |                                                                                                                                         |
-| RMLUI_TRACY_CONFIGURATION            | ON            |                                | New option for multi-config generators to add Tracy as a separate configuration.                                                        |
-| RMLUI_TRACY_MEMORY_PROFILING         | ON            |                                | New option to overload global operator new/delete for memory inspection with Tracy.                                                     |
-| RMLUI_TRACY_PROFILING                | OFF           | ENABLE_TRACY_PROFILING         |                                                                                                                                         |
-| RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY |               | VISUAL_TESTS_CAPTURE_DIRECTORY |                                                                                                                                         |
-| RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY |               | VISUAL_TESTS_COMPARE_DIRECTORY |                                                                                                                                         |
-| RMLUI_VISUAL_TESTS_RML_DIRECTORIES   |               | VISUAL_TESTS_RML_DIRECTORIES   |                                                                                                                                         |
+| Option                             | Default value | Old related option             | Comment                                                                                                                                 |
+|------------------------------------|---------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
+| RMLUI_BACKEND                      | auto          | SAMPLES_BACKEND                |                                                                                                                                         |
+| RMLUI_COMPILER_OPTIONS             | ON            |                                | Automatically sets recommended compiler flags                                                                                           |
+| RMLUI_CUSTOM_CONFIGURATION         | OFF           | CUSTOM_CONFIGURATION           |                                                                                                                                         |
+| RMLUI_CUSTOM_CONFIGURATION_FILE    |               | CUSTOM_CONFIGURATION_FILE      |                                                                                                                                         |
+| RMLUI_CUSTOM_INCLUDE_DIRS          |               | CUSTOM_INCLUDE_DIRS            |                                                                                                                                         |
+| RMLUI_CUSTOM_LINK_LIBRARIES        |               | CUSTOM_LINK_LIBRARIES          |                                                                                                                                         |
+| RMLUI_CUSTOM_RTTI                  | OFF           | DISABLE_RTTI_AND_EXCEPTIONS    | No longer modifies compiler flags - only enables RmlUi's custom RTTI solution so that the user can disable language RTTI and exceptions |
+| RMLUI_FONT_ENGINE                  | freetype      | NO_FONT_INTERFACE_DEFAULT      | Now takes a string with one of the options: `none`, `freetype`                                                                          |
+| RMLUI_HARFBUZZ_SAMPLE              | OFF           |                                |                                                                                                                                         |
+| RMLUI_INSTALL_RUNTIME_DEPENDENCIES | ON            |                                | Automatically install runtime dependencies on supported platforms (e.g. DLLs)                                                           |
+| RMLUI_LOTTIE_PLUGIN                | OFF           | ENABLE_LOTTIE_PLUGIN           |                                                                                                                                         |
+| RMLUI_LUA_BINDINGS                 | OFF           | BUILD_LUA_BINDINGS             |                                                                                                                                         |
+| RMLUI_LUA_BINDINGS_LIBRARY         | lua           | BUILD_LUA_BINDINGS_FOR_LUAJIT  | Now takes a string with one of the options: `lua`, `lua_as_cxx`, `luajit`                                                               |
+| RMLUI_MATRIX_ROW_MAJOR             | OFF           | MATRIX_ROW_MAJOR               |                                                                                                                                         |
+| RMLUI_PRECOMPILED_HEADERS          | ON            | ENABLE_PRECOMPILED_HEADERS     |                                                                                                                                         |
+| RMLUI_SAMPLES                      | OFF           | BUILD_SAMPLES                  |                                                                                                                                         |
+| RMLUI_SVG_PLUGIN                   | OFF           | ENABLE_SVG_PLUGIN              |                                                                                                                                         |
+| RMLUI_THIRDPARTY_CONTAINERS        | ON            | NO_THIRDPARTY_CONTAINERS       |                                                                                                                                         |
+| RMLUI_TRACY_CONFIGURATION          | ON            |                                | New option for multi-config generators to add Tracy as a separate configuration.                                                        |
+| RMLUI_TRACY_MEMORY_PROFILING       | ON            |                                | New option to overload global operator new/delete for memory inspection with Tracy.                                                     |
+| RMLUI_TRACY_PROFILING              | OFF           | ENABLE_TRACY_PROFILING         |                                                                                                                                         |
+| -                                  |               | VISUAL_TESTS_CAPTURE_DIRECTORY | Replaced with environment variable `RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY`                                                               |
+| -                                  |               | VISUAL_TESTS_COMPARE_DIRECTORY | Replaced with environment variable `RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY`                                                               |
+| -                                  |               | VISUAL_TESTS_RML_DIRECTORIES   | Replaced with environment variable `RMLUI_VISUAL_TESTS_RML_DIRECTORIES`                                                                 |
 
 For reference, the following options have not changed names, as these are standard options used by CMake.