Test API Reference

@korajs/test provides a testing harness for multi-device sync scenarios. It creates virtual networks with real SQLite stores and in-memory transports.

import {
  createTestNetwork,
  expectConverged,
  checkConvergence,
} from '@korajs/test'

import type {
  TestNetwork,
  TestDevice,
  TestServer,
  TestNetworkOptions,
  ConvergenceResult,
  CollectionDifference,
  FieldDifference,
} from '@korajs/test'

---

createTestNetwork()

Creates a virtual network with a server and multiple devices for testing sync behavior.

Signature

function createTestNetwork(
  schema: SchemaDefinition,
  options?: TestNetworkOptions
): Promise<TestNetwork>

Parameters

Parameter	Type	Description
schema	SchemaDefinition	The schema for all devices and the server.
options	TestNetworkOptions	Optional configuration.

TestNetworkOptions

Field	Type	Default	Description
devices	number	2	Number of devices to create.
deviceNames	string[]	['device-0', 'device-1', ...]	Custom names for devices. Overrides devices count.

Returns

Promise<TestNetwork> -- A network object with server, devices, and cleanup.

TestNetwork

Property	Type	Description
server	TestServer	The virtual sync server.
devices	TestDevice[]	Array of virtual devices.
tmpDir	string	Temporary directory for SQLite databases.
close()	Promise<void>	Close all devices and the server, clean up temp files.

Example

const network = await createTestNetwork(schema, { devices: 3 })

try {
  // ... test logic
} finally {
  await network.close()
}

---

TestDevice

A virtual device with a real SQLite store, sync engine, and merge engine.

Properties

Property	Type	Description
name	string	Device name (for identification in logs).
store	Store	The device's local store.
emitter	KoraEventEmitter	Event emitter for instrumentation events.

Methods

.collection(name)

Returns a collection accessor for performing CRUD operations.

collection(name: string): CollectionAccessor

await device.collection('todos').insert({ title: 'Test' })

.sync()

Connects to the server and performs a full sync cycle.

sync(): Promise<void>

.disconnect()

Closes the current sync connection.

disconnect(): Promise<void>

.reconnect()

Re-establishes a sync connection to the server (disconnects first if connected).

reconnect(): Promise<void>

.getState(collectionName)

Returns all records in a collection as plain objects. Useful for assertions.

getState(collectionName: string): Promise<Record<string, unknown>[]>

.getNodeId()

Returns the device's unique node ID.

getNodeId(): string

.getVersionVector()

Returns the device's current version vector.

getVersionVector(): VersionVector

.isConnected()

Returns whether the device is currently connected to the server.

isConnected(): boolean

.close()

Releases all resources (closes store, disconnects sync).

close(): Promise<void>

---

TestServer

The virtual sync server that devices connect to.

Properties

Property	Type	Description
store	MemoryServerStore	The server's in-memory operation store.

Methods

.getAllOperations()

Returns all operations stored on the server.

getAllOperations(): Operation[]

.getConnectionCount()

Returns the number of currently connected devices.

getConnectionCount(): number

.close()

Closes the server and all connections.

close(): Promise<void>

---

expectConverged()

Asserts that all devices have identical state across all collections. Throws a descriptive error if devices have not converged.

Signature

function expectConverged(
  devices: TestDevice[],
  schema: SchemaDefinition
): Promise<void>

Parameters

Parameter	Type	Description
devices	TestDevice[]	Devices to compare.
schema	SchemaDefinition	Schema defining the collections to check.

Throws

Throws an error with message 'Devices have not converged' and detailed difference information if any device has different state.

---

checkConvergence()

Checks convergence without throwing. Returns a detailed result describing any differences.

Signature

function checkConvergence(
  devices: TestDevice[],
  schema: SchemaDefinition
): Promise<ConvergenceResult>

Returns

ConvergenceResult

Field	Type	Description
converged	boolean	true if all devices have identical state.
differences	CollectionDifference[]	Details of any differences found.

CollectionDifference

Field	Type	Description
collection	string	Collection name where difference was found.
deviceA	string	Name of the first device.
deviceB	string	Name of the second device.
missingInB	string[]	Record IDs present in A but missing in B.
missingInA	string[]	Record IDs present in B but missing in A.
fieldDifferences	FieldDifference[]	Field-level differences for records present in both.

FieldDifference

Field	Type	Description
recordId	string	The record with differing values.
field	string	The field name that differs.
valueInA	unknown	Value on device A.
valueInB	unknown	Value on device B.

---

ChaosTransport

Re-exported from @korajs/sync. A transport wrapper that simulates unreliable network conditions for stress testing.

import { ChaosTransport } from '@korajs/test'

See the Sync API reference for ChaosTransport configuration options.