Testing Infrastructure

Relevant source files

Purpose and Scope

This document describes the multi-layered testing infrastructure used to validate the algovivo system across its JavaScript, WebAssembly, and Python targets. The suite ensures numerical accuracy of the energy-based simulation, API consistency, and visual fidelity.

For deep technical details on specific subsystems, refer to the following child pages:

JavaScript Unit Testing — Covers Jest-based testing for the core simulation logic and WASM integration.
Python Testing — Details the pytest suite for the native shared library interface.
Browser-Based Testing — Documents the Puppeteer-based framework for visual regression and demo validation.

Testing Architecture

The infrastructure validates the system at different levels of abstraction, from low-level memory management to high-level UI components.

Testing Layer	Technology	Primary Files	Target Artifacts
JS Unit	Jest	`test/*.test.js`	`build/algovivo.wasm`, `build/algovivo/index.js`
Python	pytest	`utils/py/test/*.py`	`build/algovivo.so`
Visual/UI	Puppeteer	`demo/test/*.test.js`	Demo App, `SystemViewport`

Sources: test/utils.js46-57 test/system.test.js1-5 jest.config.js6-8

System-to-Code Mapping: Test Execution Flow

The following diagram bridges high-level testing concepts to specific code entities and utility functions defined in the test suite.

Testing Workflow and Entity Mapping

Sources: test/utils.js46-57 test/system.test.js6-22 test/triangles.test.js6-21 test/ten/intTuple.test.js15-21 test/memory.test.js8-9 test/backwardEuler.test.js25-30

Core Test Utilities

The repository provides specialized utilities in test/utils.js to handle the unique requirements of a WASM-powered physics engine.

Numerical and Memory Validation

Because physics simulations involve floating-point accumulation, tests use a custom Jest matcher toBeCloseToArray to validate multi-dimensional arrays within a tolerance (default 1e-3) test/utils.js9-44 This is used extensively to verify system state such as vertex positions test/system.test.js20-21 and Reference Shape Inverses (RSI) for triangles test/triangles.test.js32

Memory management is validated by monitoring the mmgrten.Engine's internal state. Tests in test/memory.test.js verify that system.set() triggers memory reservation via memoryManager.numReservedBytes() and system.dispose() successfully returns the reserved count to zero test/memory.test.js29-50 Low-level memory allocation is also tested against simulated WebAssembly.Global objects to ensure compatibility with various heapBase formats test/mmgr/memoryManager.test.js3-12

WASM Lifecycle Management

Tests must manually load and instantiate the compiled WebAssembly binary.

loadWasm(): Reads build/algovivo.wasm from the filesystem and compiles it using the WebAssembly global test/utils.js46-50
loadTen(): Initializes the mmgrten.Engine (aliased as ten) and links it to the WASM instance test/utils.js52-57

Sources: test/utils.js9-57 test/memory.test.js29-58 test/triangles.test.js22-32 test/mmgr/memoryManager.test.js3-12

JavaScript Unit Testing

The core JavaScript suite uses Jest to validate the System class and its interaction with WASM exports.

Key focus areas:

System State: Verifying system.set() correctly populates vertices, muscles, and triangles test/system.test.js13-22
Physics Step: Validating that system.step() correctly updates positions, including constraints like fixed vertices via system.vertices.fixVertex() test/system.test.js36-52
Triangle Configuration: Testing the calculation of Reference Shape Inverses (RSI) when setting triangles and positions test/triangles.test.js6-44
Numerical Integration: Validating specific WASM exports like backward_euler_update_vel and optim_init to ensure the mathematical foundations of the Backward Euler solver are sound test/backwardEuler.test.js6-68
WASM Environment: Validating that the system can operate with custom WASM environments, such as passing custom malloc and free hooks to the wasmInstance test/systemWithCustomWasmEnv.test.js6-20
Tensor Utilities: Testing low-level data structures like intTuple and their interaction with WASM exports like flatten_idx test/ten/intTuple.test.js15-21

For details, see JavaScript Unit Testing.

Sources: test/system.test.js6-71 test/triangles.test.js6-169 test/systemWithCustomWasmEnv.test.js6-38 test/ten/intTuple.test.js3-21 test/backwardEuler.test.js6-68

Python Testing

The Python testing infrastructure validates the native shared library interface (algovivo.so). This ensures that the same C++ energy functions behave identically across platforms when accessed via ctypes.

For details, see Python Testing.

Browser-Based & Visual Testing

These tests use Puppeteer to launch a headless browser to validate the SystemViewport and interactive demo components.