npm package: @iron-stack/e2e
Description: 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.
Latest version: 1.0.0

# @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

```bash
npm install @iron-stack/e2e
```

## Quick Start

```ts
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