SpacetimeDB/tests/client-comparison/README.md

SpacetimeDB SDK Client Comparison Tool

Compares client code generated from Rust and C++ bindings modules to validate type system equivalence and catch regressions.

Quick Start

./run_client_comparison.sh

This builds the C++ module, regenerates clients, and runs both client and module schema comparisons.

How It Works

3-Step Process:

1. Build & Regenerate: Compiles lib.cpp and generates fresh C++ client
2. Compare: Runs client code and module schema comparisons in parallel
3. Summarize: Shows statistics and generates detailed analysis files

Prerequisites:

• SpacetimeDB CLI: cargo build --release -p spacetimedb-cli

Output:

• client_diff_analysis.txt - Detailed client code differences
• module_diff_analysis.txt - Module schema comparison
• Console summaries with key metrics

Scripts

run_client_comparison.sh (Main)

Complete workflow: build → regenerate → compare → summarize

scripts/compare_clients.sh

Client code comparison with intelligent filtering:

• Ignores paths, version comments, whitespace
• Shows only meaningful code differences
• Provides accurate file statistics

scripts/compare_modules.sh

Module schema comparison:

• Publishes WASM to temporary databases
• Extracts schemas via spacetime describe --json
• Compares typespace, tables, reducers, named types

scripts/regenerate_cpp_client.sh

Rebuilds C++ client only (no comparison)

Understanding Results

Client Comparison:

• File counts: Total files generated by each SDK
• Identical files: Files with no meaningful differences (after filtering)
• Difference types: Type representations, imports, structure flattening

Module Schema:

• Typespace: Core type definitions and relationships
• Common differences: Registration order, duplicates, special type handling

Usage

Standard workflow:

cd crates/bindings-cpp/tests/client-comparison
./run_client_comparison.sh

Update baselines:

# Rust baseline
cd rust-sdk-test
spacetime generate --lang rust --out-dir . --project-path ../../../modules/sdk-test

# Rust baseline
./scripts/regenerate_rust_client.sh

# C++ baseline  
./scripts/regenerate_cpp_client.sh

Troubleshooting

• "CLI not found": Build CLI with cargo build --release -p spacetimedb-cli
• "Client generation failed": Check if lib.cpp publishes successfully
• "No differences": Normal if no changes were made

The tool validates C++ bindings functionality by comparing generated client code and module schemas against the Rust SDK baseline.