JavaScript Unit Testing

Relevant source files

Purpose and Scope

This document describes the JavaScript unit testing infrastructure for the algovivo library. It covers the Jest-based test framework, custom test utilities, and detailed testing patterns for validating core components including the System, Vertices, Muscles, Triangles, and the underlying mmgrten tensor engine.

For browser-based visual regression testing, see Browser-Based Testing For Python testing infrastructure, see Python Testing

Test Framework and Configuration

The algovivo codebase uses Jest as its JavaScript testing framework. Jest provides test execution, assertion utilities, and test discovery capabilities.

Test Execution Configuration

The test environment is configured via jest.config.js. Tests are typically executed in a Node.js environment but interact with WebAssembly modules.

Test Utilities

The test infrastructure provides common utilities in test/utils.js that simplify test setup and assertions.

Custom Matchers

The toBeCloseToArray matcher provides tolerance-based comparison for numeric arrays, including nested arrays. It is extensively used to validate physical simulation results where floating-point precision might vary slightly.

Recursive comparison: Applies the matcher recursively to nested arrays test/utils.js36-39
Integration: Tests like test/triangles.test.js extend Jest's expect with this utility test/triangles.test.js4

Sources: test/utils.js9-44 test/triangles.test.js4

WebAssembly Loading Helpers

The utilities provide helper functions for loading the simulation engine in a test environment:

loadWasm(): Reads the compiled WASM binary from build/algovivo.wasm and instantiates it test/utils.js46-50
loadTen(): Creates a new algovivo.mmgrten.Engine instance and initializes it with the WASM instance, providing the tensor abstraction layer used by all components test/utils.js52-57

Sources: test/utils.js46-57

Core Component Testing

The testing suite validates the interaction between JavaScript classes and the WebAssembly-backed memory managed by mmgrten.

Vertices and System Testing

The Vertices component manages vertex positions and velocities. Tests ensure that JavaScript state correctly maps to WASM memory slots.

Title: Vertices Data Flow in Tests

Sources: algovivo/Vertices.js1-40 test/vertices.test.js6-82

Key behaviors tested:

Initial State: numVertices starts at 0 when a System or Vertices object is instantiated test/system.test.js9-11 test/vertices.test.js9
Batch Setting: Setting multiple vertices via system.set() or vertices.set() updates the underlying pos0 tensor test/system.test.js13-22 test/vertices.test.js11-23
Dynamic Addition: Using addVertex() to expand the simulation at runtime. This involves reallocating tensors and copying existing data algovivo/Vertices.js140-181 test/vertices.test.js53-79
Constraints: Validating fixVertex(id) behavior where the vertex position remains constant during a step() while other vertices move (e.g., under gravity) test/system.test.js36-52 algovivo/Vertices.js61-66

Sources: algovivo/Vertices.js61-181 test/vertices.test.js6-82 test/system.test.js36-52

Muscles and Triangles Testing

Tests for Muscles and Triangles focus on the calculation of rest lengths (l0) and reference shape inverses (rsi) derived from vertex positions.

Title: Simulation Component Associations

Sources: test/system.test.js1-71 test/ten/intTuple.test.js15-22 algovivo/Muscles.js63-69

Muscle Rest Lengths: When muscles are defined, the system computes l0 based on the current vertex positions via the WASM export l0_of_pos algovivo/Muscles.js63-69 test/muscles.test.js24-25 Setting keepA: true allows updating muscle structure while preserving current activations test/muscles.test.js92-101
Triangle Reference Shapes: Setting triangles calculates the rsi (Reference Shape Inverse) test/triangles.test.js22-32 The system supports manual rsi overrides via setTriangles({ rsi: [...] }) test/triangles.test.js76-89
Neural Network Layers: Linear layers are tested for correct forward pass calculations and memory allocation test/ten/nn/linear.test.js3-36

Sources: test/muscles.test.js6-111 test/triangles.test.js6-169 test/ten/nn/linear.test.js3-36

Memory Management Validation

A critical part of the unit testing is ensuring that WebAssembly memory is not leaked during simulation reconfigurations. The MemoryManager class handles raw allocation, supporting heapBase values from WebAssembly globals test/mmgr/memoryManager.test.js3-12

The test/memory.test.js suite performs the following validation:

Baseline: Verify numReservedBytes() is 0 before allocation test/memory.test.js29
Allocation: Set a mesh (vertices, triangles, muscles) and record the reserved bytes test/memory.test.js30-32
Idempotency: Re-set the same mesh data and verify numReservedBytes() has not increased, confirming that old tensors were correctly disposed of before new allocations test/memory.test.js39-40
Cleanup: Call system.dispose() and verify numReservedBytes() returns to 0 test/memory.test.js46-47

Sources: test/memory.test.js4-58 algovivo/Vertices.js183-212 test/mmgr/memoryManager.test.js3-12

Rendering and UI Component Testing

Unit tests also cover the rendering abstraction layers and math utilities:

mm2d Grid: Validates the geometry generation for the background grid, ensuring the correct number of lines and vertices are created based on row/column configuration test/render/mm2d/grid.test.js3-30
Geometry Utilities: Tests for AABB (Axis-Aligned Bounding Box) and SortedElements ensure correct spatial partitioning and draw-order management for the 2D renderer.
Tensor Ops: Basic tensor operations like fill_ and zero_ are validated to ensure memory contents are correctly modified test/ten/fill.test.js4-20

Sources: test/render/mm2d/grid.test.js3-30 test/ten/fill.test.js4-20