@iron-stack/e2e

Multi-device end-to-end testing framework with device synchronization, shared state, and database utilities -- designed for testing real-time apps across multiple simultaneous clients.

Installation

npm install @iron-stack/e2e

Quick Start

import { createSyncClient, createDbHelper, assert, sleep } from '@iron-stack/e2e';

// 1. Create a sync client for this device
const sync = createSyncClient('device-alice', 'http://localhost:9876');

// 2. Register with the coordination server
await sync.register();

// 3. Share data between devices
await sync.share('aliceUserId', 'user-123');

// 4. Wait for all devices to reach the same point
await sync.barrier('both-registered');

// 5. Read shared variables from other devices
const vars = await sync.getVars<{ bobUserId: string }>();

// 6. Assert expected state
assert(vars.bobUserId !== undefined, 'Bob should have registered');

// 7. Database assertions
const db = createDbHelper({
  user: 'postgres',
  password: 'postgres',
  database: 'myapp_test',
});

assert(db.count('messages', `sender_id = '${vars.bobUserId}'`) > 0, 'Bob should have sent a message');

API Reference

Device Synchronization

| Export | Description | |---|---| | createSyncClient(deviceName, coordUrl?) | Creates a sync client that communicates with the coordination server | | SyncClient.register() | Register this device with the coordinator. Returns { ok, devices } | | SyncClient.barrier(eventName) | Block until all registered devices reach this barrier | | SyncClient.share(key, value) | Share a key-value pair with all devices | | SyncClient.getVars<T>() | Retrieve all shared variables | | SyncClient | Type interface for the sync client |

Database Utilities

| Export | Description | |---|---| | createDbHelper(config) | Creates a PostgreSQL helper for test assertions and cleanup | | DbHelper.sql(query) | Execute raw SQL and return the result as a string | | DbHelper.count(table, where?) | Count rows in a table with optional WHERE clause | | DbHelper.clean(tables) | Delete all rows from the given tables | | DbHelper.assertEmpty(tables) | Throw if any of the given tables contain rows | | DbHelper | Type interface for the database helper | | DbConfig | Configuration interface for database connection |

Test Helpers

| Export | Description | |---|---| | assert(condition, message) | Throws with a descriptive error if condition is false | | sleep(ms) | Returns a promise that resolves after the given milliseconds |

Configuration

DbConfig

| Option | Type | Default | Description | |---|---|---|---| | host | string | "localhost" | PostgreSQL host | | port | number | 5432 | PostgreSQL port | | user | string | required | Database user | | password | string | required | Database password | | database | string | required | Database name |

createSyncClient Parameters

| Parameter | Type | Default | Description | |---|---|---|---| | deviceName | string | required | Unique name for this device (e.g., "device-alice") | | coordUrl | string | "http://localhost:9876" | URL of the coordination server |

How It Works

The E2E framework uses a coordination server pattern for multi-device testing:

1. Each device (simulator, emulator, or test process) creates a SyncClient and registers with a shared coordinator.
2. Barriers block execution until every registered device reaches the same named checkpoint -- ensuring deterministic ordering across devices.
3. Shared variables let devices exchange data (user IDs, tokens, conversation IDs) without hardcoding.
4. Database helpers let tests verify server-side state directly via SQL.

This enables tests like "Alice sends a message, Bob receives a push notification" with full synchronization guarantees.

License

MIT