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 “vtkWasm-HTTPServerFixture” is used to coordinate the startup and shutdown of the HTTP server. The special unit test vtkWasm-HTTPServerSetup is run before all the unit tests that have “vtkWasm-HTTPServerFixture” in their FIXTURES_REQUIRED property and finally the vtkWasm-HTTPServerCleanup 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.