Testing

QuickJS-ng has a comprehensive test suite to ensure correctness and ECMAScript compliance. This guide covers how to run tests and work with the test262 compliance suite.

Running Tests

Basic Test Suite

Run the basic QuickJS test suite:

make test

This executes the test suite defined in tests.conf using the run-test262 tool.

Manual Test Execution

You can also run the test runner directly:

build/run-test262 -c tests.conf

Test262 Compliance Suite

Test262 is the official ECMAScript conformance test suite. QuickJS-ng runs this suite to ensure spec compliance.

Running test262

To run the full test262 suite:

make test262

This command:

Initializes the test262 submodule if needed
Runs all applicable test262 tests
Reports pass/fail statistics

The test262 suite is extensive and may take several minutes to complete.

Fast test262 Subset

For quicker feedback during development, run a smaller subset:

make test262-fast

Updating test262 Results

After implementing a new feature that changes test262 results:

make test262-update

This updates the error/pass report files, which should be committed with your changes.

Checking test262 Results

Verify that test262 results match expected outcomes:

make test262-check

This runs test262 with the -E flag to check against expected results.

Specialized Tests

API Tests

Test the C API:

build/api-test

Standalone Compilation Test

Test JavaScript-to-executable compilation:

build/qjs -c examples/hello.js -o hello
./hello

Examples Tests

If built with examples enabled:

build/qjs examples/test_fib.js
build/qjs examples/test_point.js
build/qjs tests/test_bjson.js
build/function_source

Microbenchmarks

Run performance microbenchmarks:

make microbench

This executes tests/microbench.js to measure performance of common operations.

Platform-Specific Testing

Windows (MSVC)

cmake -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release
build\Release\run-test262.exe -c tests.conf

Windows (MinGW)

make
make test

Emscripten

emcmake cmake -B build -DQJS_BUILD_LIBC=ON
emmake make -C build qjs_wasm

WASI

cmake -B build -DCMAKE_TOOLCHAIN_FILE=/opt/wasi-sdk/share/cmake/wasi-sdk.cmake
make -C build qjs_exe
wasmtime run build/qjs -qd

CI Test Matrix

The continuous integration pipeline tests QuickJS-ng across:

Operating Systems

Ubuntu Linux (latest, 24.04)
macOS (latest)
Windows (latest, Server 2019)
FreeBSD
OpenBSD
Cygwin

Architectures

x86 (32-bit)
x64 (64-bit)
ARM64
RISC-V (riscv64)
s390x

Build Configurations

Debug builds
Release builds
Shared library builds
Example builds
Amalgamated builds

Compilers

GCC
Clang
MSVC (Visual Studio 2022)
MinGW (mingw32, mingw64, ucrt64, clang64)
TCC (Tiny C Compiler)
Clang-CL

Sanitizers

AddressSanitizer (ASan)
UndefinedBehaviorSanitizer (UBSan)
MemorySanitizer (MSan)
ThreadSanitizer (TSan, separate workflow)

Special Builds

Emscripten (WebAssembly)
WASI
Android (arm64-v8a)
iOS
Parserless builds
mimalloc integration

Test Runner Options

The run-test262 tool supports several options:

build/run-test262 [options]

Common Options

-c <file> - Use configuration file
-m - Run in multi-threaded mode
-a - Run all tests
-u - Update test results
-E - Check expected results
-t <threads> - Number of threads (default: auto)

Configuration Files

tests.conf - Basic QuickJS test suite
test262.conf - Full test262 suite
test262-fast.conf - Fast test262 subset

Writing Tests

Test File Format

QuickJS tests are JavaScript files that throw exceptions on failure:

// Test basic arithmetic
if (1 + 1 !== 2) {
    throw new Error("Math is broken!");
}

// Tests pass if no exception is thrown

Adding Tests

Create a new .js file in the tests/ directory
Add test cases that throw on failure
Add the test to the appropriate .conf file
Run the test suite to verify

Debugging Test Failures

Run a Single Test

build/qjs tests/test_file.js

Enable Debug Output

build/qjs -d tests/test_file.js

Use Sanitizers

Build with sanitizers to catch memory errors:

cmake -B build -DQJS_ENABLE_ASAN=ON -DQJS_ENABLE_UBSAN=ON
cmake --build build
export ASAN_OPTIONS=halt_on_error=1
export UBSAN_OPTIONS=halt_on_error=1
build/qjs tests/test_file.js

Valgrind

Run tests under Valgrind for memory debugging:

valgrind --leak-check=full build/qjs tests/test_file.js

QuickJS-ng has a dedicated Valgrind CI workflow for automated memory leak detection.

Performance Testing

View Engine Statistics

make stats

This shows memory usage and allocation statistics.

Benchmark Suite

Run the microbenchmark suite:

make microbench

The benchmarks test:

Arithmetic operations
Function calls
Object creation
Array operations
String manipulation
Regular expressions

Best Practices

Always run make test before submitting pull requests
Run test262 for changes affecting ECMAScript compliance
Test on multiple platforms when making platform-specific changes
Use sanitizers during development to catch memory errors early
Add tests for bug fixes to prevent regressions
Add tests for new features to ensure they work correctly
Update test262 results when implementing new ECMAScript features

​Testing

​Running Tests

​Basic Test Suite

​Manual Test Execution

​Test262 Compliance Suite

​Running test262

​Fast test262 Subset

​Updating test262 Results

​Checking test262 Results

​Specialized Tests

​API Tests

​Standalone Compilation Test

​Examples Tests

​Microbenchmarks

​Platform-Specific Testing

​Windows (MSVC)

​Windows (MinGW)

​Emscripten

​WASI

​CI Test Matrix

​Operating Systems

​Architectures

​Build Configurations

​Compilers

​Sanitizers

​Special Builds

​Test Runner Options

​Common Options

​Configuration Files

​Writing Tests

​Test File Format

​Adding Tests

​Debugging Test Failures

​Run a Single Test

​Enable Debug Output

​Use Sanitizers

​Valgrind

​Performance Testing

​View Engine Statistics

​Benchmark Suite

​Best Practices

Testing

Running Tests

Basic Test Suite

Manual Test Execution

Test262 Compliance Suite

Running test262

Fast test262 Subset

Updating test262 Results

Checking test262 Results

Specialized Tests

API Tests

Standalone Compilation Test

Examples Tests

Microbenchmarks

Platform-Specific Testing

Windows (MSVC)

Windows (MinGW)

Emscripten

WASI

CI Test Matrix

Operating Systems

Architectures

Build Configurations

Compilers

Sanitizers

Special Builds

Test Runner Options

Common Options

Configuration Files

Writing Tests

Test File Format

Adding Tests

Debugging Test Failures

Run a Single Test

Enable Debug Output

Use Sanitizers

Valgrind

Performance Testing

View Engine Statistics

Benchmark Suite

Best Practices