VTK WASM regression test suite architecture#

The VTK Emscripten test utilities utilize a custom protocol designed to address the file I/O requirements of WebAssembly (WASM) unit tests. This protocol allows C++ unit tests to dump files from the sandbox to the server hosting the WASM module.

Fixtures#

The test suite requires a HTTP server to run in the background. Additionally, the tests expect to find a “vtkhttp.lock” file in the ${CMAKE_BINARY_DIR}/Testing/Temporary directory.

This lock file must contain the URL of a HTTP server that the tests may connect to using web browser APIs. Right now, the connection is only made when a unit test needs to dump a file (like difference images) to server filesystem.

A new fixture called “HTTP” is used to coordinate the startup and shutdown of the HTTP server. The special unit test HTTPServerStart is run before all the unit tests that have “HTTP” in their FIXTURES_REQUIRED property and finally the HTTPServerStop is run at the end to shutdown the HTTP server.

Arguments#

The command line for a unit test is set by the CMake functions in vtkModuleTesting.cmake file. It looks like “cmake” -D… “CMake/vtkWasmTestRunner.cmake” “/path/to/vtkModuleNameCxxTests.js_file” “TestName” “arg1” “arg2” … “argn”

Routes:#

  1. /dump?file=/path/to/file.ext:

    Request description: wasm unit test initiates a POST with the full path of a file in its query parameters and sends the entire contents of the output file in the POST content.

    Expected response: No response needed if parameters are valid. ‘Invalid query for /dump’ if query parameters are invalid.

  2. /preload?file=[Drive:]/path/to/host_file.ext:

    Request description: wasm unit test initiates a GET with the full path of a file on the host filesystem in its query parameters.

    Expected response: The entire contents of the requested file if it exists. ‘File not found’ if the file does not exist.

  3. /favicon.ico:

    Request description: Browser requests the favicon for the server.

    Expected response: An empty response with 200 OK status is fine.

  4. /VTK<ModuleName>/test.html:

    Request description: Browser requests the test HTML page for a given VTK module.

    Expected response: The HTML page that loads the corresponding wasm module and runs the tests.

  5. /VTK<ModuleName>/vtk<ModuleName>CxxTests.js:

    Request description: Browser requests the wasm JS file for a given VTK module.

    Expected response: The wasm JS file that contains the compiled WebAssembly module and its JavaScript glue code. This file is located in the CMake build directory under ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}.

Reference Client-side implementation in VTK:#

  1. vtkEmscriptenTestUtilities.h

  2. vtkEmscriptenTestUtilities.cxx

  3. vtkEmscriptenTestUtilities.js

Reference Server-side implementation in VTK:#

The server.js implements the /dump request.