Module unit testing by jsdt · Pull Request #5558 · clockworklabs/SpacetimeDB

jsdt · 2026-07-16T14:59:28Z

Description of Changes

Adds unit testing support for SpacetimeDB module code in Rust and TypeScript.

The main work here is adding a test datastore API for use in these unit tests. There are some new feature gates added for this, which are described below.

Module Unit Test APIs

Adds spacetimedb::test_utils for Rust module tests, including TestContext, TestAuth, reducer transactions, procedure/view contexts, typed queries, test clock/RNG helpers, and HTTP/sleep hooks.
Adds TypeScript server test utilities under spacetimedb/server/test-utils, with Vitest and WASM runtime helpers.
Refactors generated/runtime hooks so Rust and TypeScript module code can run against an in-memory test datastore instead of host syscalls.

Portable Datastore

Adds spacetimedb-test-datastore, a native in-memory datastore wrapper for Rust module tests.
Adds spacetimedb-portable-datastore, a WASM-compatible in-memory datastore initialized from a module definition.
Adds spacetimedb-portable-datastore-wasm, a thin wasm-bindgen adapter used by the TypeScript test runtime.
Splits spacetimedb-datastore behind feature gates so portable builds can avoid server-only dependencies:
- durability: commitlog, snapshot, durability, and path-dependent code.
- execution: execution-plan-aware transaction/query behavior.
- metrics: Prometheus/SpacetimeDB metrics plumbing.
- portable: minimal datastore surface needed by the portable test datastore.
Adds wasm32-unknown-unknown guards, including portable time handling where std::time::Instant::now() is unavailable.

Test Datastore ABI

For Rust module tests, look at:

crates/bindings/src/test_utils.rs
crates/test-datastore/src/lib.rs
crates/bindings/src/table.rs

For TypeScript module tests, look at:

crates/portable-datastore-wasm/src/lib.rs for the wasm-bindgen ABI.
crates/bindings-typescript/src/server/test-utils/wasm.ts for the TypeScript-side ABI interface.
crates/bindings-typescript/src/server/test-utils/backend.ts and crates/bindings-typescript/src/server/backend.ts for the DatastoreBackend bridge.

Example Usage

Examples are included in the updated chat templates (though I need to either remove these or replace them with tests that are actually meaningful for the templates):

Rust: templates/chat-console-rs/spacetimedb/src/lib.rs
- TestContext::new()
- with_reducer_tx
- TestAuth::from_jwt_payload
- procedure_context
- run_query
- mocked procedure HTTP
TypeScript: templates/chat-react-ts/spacetimedb/src/index.test.ts
- createModuleTestHarness(spacetime, moduleExports)
- test.withReducerTx
- test.procedureContext
- test.viewContext
- test.runQuery

For exhaustive coverage, see:

crates/bindings/tests/test_utils.rs
crates/bindings-typescript/tests/server_test_utils_wasm.test.ts

Testing

New test coverage added in this branch:

Rust module unit-test API coverage in crates/bindings/tests/test_utils.rs
Native test datastore coverage in crates/test-datastore/src/lib.rs
Portable datastore coverage in crates/portable-datastore/src/lib.rs
TypeScript/WASM module test harness coverage in crates/bindings-typescript/tests/server_test_utils_wasm.test.ts
TypeScript WASM adapter coverage in crates/bindings-typescript/tests/server_test_utils_wasm_adapter.test.ts
Template example tests in:
- templates/chat-console-rs/spacetimedb/src/lib.rs
- templates/chat-react-ts/spacetimedb/src/index.test.ts

Adds cargo ci portable-datastore, wired into GitHub Actions as the portable_datastore job. This checks that the portable datastore path stays buildable for wasm32-unknown-unknown without the normal server-only dependency stack, then runs native portable datastore tests.

…publishing

…tore # Conflicts: # Cargo.lock # Cargo.toml # crates/bindings-typescript/src/server/procedures.ts # crates/bindings-typescript/src/server/runtime.ts # crates/bindings-typescript/vitest.config.ts # crates/bindings/src/http.rs # crates/bindings/src/lib.rs # crates/bindings/src/rt.rs # crates/bindings/tests/ui/views.stderr # crates/datastore/src/locking_tx_datastore/committed_state.rs # crates/datastore/src/locking_tx_datastore/datastore.rs # crates/datastore/src/locking_tx_datastore/mut_tx.rs # tools/ci/src/main.rs

…dt/portable-datastore-2

Shubham8287 · 2026-09-17T05:26:32Z

@@ -1,3 +1,5 @@
+#![cfg_attr(not(feature = "metrics"), allow(dead_code, unused_imports, unused_variables))]


Ca we not avoid adding lint supressors at file level?

Shubham8287 · 2026-09-17T05:26:47Z

@@ -1,11 +1,18 @@
+#![cfg_attr(not(feature = "metrics"), allow(dead_code))]


same as above

Shubham8287 · 2026-09-21T12:34:25Z

            #vis struct #index_ident;
            impl spacetimedb::table::#index_kind_trait for #index_ident {}
            impl spacetimedb::table::Index for #index_ident {
+                const INDEX_NAME: &'static str = #index_name;


Not clear to me, why is this added. Maybe put a comment that it is required for Test setup and how Host doesn't use it.

Shubham8287 · 2026-09-21T12:34:53Z

        /// - `NOT_IN_TRANSACTION`, when called outside of a transaction.
        /// - `NO_SUCH_TABLE`, when `table_id` is not a known ID of a table.
        pub fn datastore_table_row_count(table_id: TableId, out: *mut u64) -> u16;
+        // pub fn datastore_table_row_count<T: InstanceId>(table_id: TableId, out: *mut u64, instance_id: T) -> u16;


Shubham8287 · 2026-09-21T12:39:06Z

    }
 }

+#[cfg(feature = "execution")]


What's the consequences of messing up with feature flags in future? I am worried, what happen if I make a new change in this file and forget to put the cfg.
Will it be caught by build/CI?

Shubham8287 · 2026-09-21T13:04:09Z

+
+function makeModule() {
+  const person = table(
+    { name: 'person', public: true },


I think we should have a test which exercise case conversion too, such that some names defined in other than snake case inside the module.

…tore-2 # Conflicts: # Cargo.toml # crates/bindings-typescript/case-conversion-test-client/src/module_bindings/index.ts # crates/datastore/src/locking_tx_datastore/datastore.rs

jsdt added 25 commits April 30, 2026 12:56

A version that uses a ctor approach. It passes a test, haven't tried …

9f9619a

…publishing

actually add the test_utils

484bf37

Flesh out the moduledef

972d3e6

Get a test datastore

e63a74a

Add more of reducercontext

78e6db8

Fix index methods

1e30e04

Add more procedure testing

3961992

Before changing callback context

c27a213

Give callbacks the full TestContext

c0cdd34

Add sleep callback

d9f4e9d

Implement for tests

fec9a08

Typescript tests

e437e63

Get sql working for ts

aba828d

Random fixes for ci test

ef63acb

Cleanup

a2a2161

Updates from proposal changes

4532fcc

Update http responder

a58ab30

Fix post-merge test failures

8db3dd8

merge

032bea8

Merge branch 'master' into jsdt/portable-datastore-2

9867744

Merge branch 'master' into jsdt/portable-datastore-2

e51eee0

Merge branch 'master' into jsdt/portable-datastore-2

d69ea44

Merge branch 'master' into jsdt/portable-datastore-2

e1dea85

Fix some warnings

015dc37

jsdt requested a review from gefjon July 20, 2026 15:11

jsdt added 3 commits July 22, 2026 10:36

Merge branch 'master' into jsdt/portable-datastore-2

7749f2e

Remove some extraneous changes

c3e8de0

Merge branch 'master' into jsdt/portable-datastore-2

72010c1

jsdt force-pushed the jsdt/portable-datastore-2 branch from 225987b to 72010c1 Compare September 14, 2026 06:21

Fix generated binding artifacts

64db870

jsdt requested review from Shubham8287 and removed request for gefjon September 14, 2026 21:56

jsdt added 5 commits September 14, 2026 15:53

Merge origin/master into jsdt/portable-datastore-2

d869afd

Fix testing crate lint warnings

90cbe64

Fix TypeScript lint warnings

f9af751

Fix chat template lint project

62a03bf

lint fix

5f20a47

jsdt marked this pull request as ready for review September 16, 2026 15:08

jsdt requested review from bfops, cloutiertyler and jdetter as code owners September 16, 2026 15:08

jsdt added 3 commits September 16, 2026 11:21

env_get fix

88ff36b

Merge branch 'master' of github.com:clockworklabs/SpacetimeDB into js…

d1511ec

…dt/portable-datastore-2

Fix chat template tests after master merge

5143096

Shubham8287 reviewed Sep 21, 2026

View reviewed changes

Shubham8287 reviewed Sep 22, 2026

View reviewed changes

captain-mirage mentioned this pull request Sep 22, 2026

Fix TS index uniqueness treating a prefix of a composite unique constraint as unique #5969

Open

7 tasks

jsdt added 8 commits September 24, 2026 13:56

Regenerate TypeScript module artifacts

47085ce

Merge remote-tracking branch 'origin/master' into jsdt/portable-datas…

b5765cd

…tore-2 # Conflicts: # Cargo.toml # crates/bindings-typescript/case-conversion-test-client/src/module_bindings/index.ts # crates/datastore/src/locking_tx_datastore/datastore.rs

Narrow lint suppression

7b0d237

Remove commented out code

e1a3c66

test case conversion with the wasm datastore

d4374cd

use existing index_id method

fd14627

update comments

059a57b

Add extra check to cargo ci portable-datastore

0e0fc6a

Navigation Menu

Module unit testing - #5558

Module unit testing#5558
jsdt wants to merge 45 commits into
masterfrom
jsdt/portable-datastore-2

jsdt commented Jul 16, 2026 •

edited

Loading

Uh oh!

Shubham8287 Sep 17, 2026

Uh oh!

Shubham8287 Sep 17, 2026

Uh oh!

Shubham8287 Sep 21, 2026

Uh oh!

Shubham8287 Sep 21, 2026

Uh oh!

Shubham8287 Sep 21, 2026

Uh oh!

Shubham8287 Sep 21, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -1,3 +1,5 @@
		#![cfg_attr(not(feature = "metrics"), allow(dead_code, unused_imports, unused_variables))]

		@@ -1,11 +1,18 @@
		#![cfg_attr(not(feature = "metrics"), allow(dead_code))]

Conversation

jsdt commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Changes

Module Unit Test APIs

Portable Datastore

Test Datastore ABI

Example Usage

Testing

Uh oh!

Shubham8287 Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

Shubham8287 Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

Shubham8287 Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

Shubham8287 Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

Shubham8287 Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

Shubham8287 Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jsdt commented Jul 16, 2026 •

edited

Loading