@ephemeral-broker/wdio

WebDriverIO service plugin for @ephemeral-broker/core.

Share bootstrap data, tokens, and secrets across parallel WDIO workers without touching disk or opening ports.

Why?

When running WebDriverIO tests in parallel:

• Problem: Each worker regenerates tokens, fetches bootstrap data, makes duplicate API calls
• Solution: Generate once, share via ephemeral broker, workers read from in-memory store

Performance: 80x faster bootstrap (8s → 0.1s per worker)

Features

• ✅ Zero disk I/O - All data stored in-memory via named pipes/UNIX sockets
• ✅ Parallel-safe - No race conditions, each worker reads independently
• ✅ Automatic cleanup - Broker stops when tests complete
• ✅ TTL support - Data expires automatically
• ✅ Secure - No ports opened, filesystem permissions only

Installation

npm install --save-dev @ephemeral-broker/wdio @ephemeral-broker/core

Quick Start

1. Add Service to WDIO Config

// wdio.conf.js
import { EphemeralBrokerService } from '@ephemeral-broker/wdio'

export const config = {
  services: [
    [EphemeralBrokerService, {
      ttl: 600000, // 10 minutes
      seedData: {
        cache: {
          courseId: 'COURSE_123',
          modeIds: { test: 'mode_1' }
        },
        ephemeral: {
          pubToken: 'Bearer abc123...',
          adminToken: 'Bearer xyz789...'
        }
      }
    }]
  ]
}

2. Access Data in Tests

// test/example.spec.js
import { Client } from '@ephemeral-broker/core'

describe('My Tests', () => {
  let client

  before(async () => {
    // Connect to broker (pipe path set by service)
    client = new Client(process.env.EPHEMERAL_PIPE)
  })

  it('should use shared bootstrap data', async () => {
    const courseId = await client.get('courseId')
    const token = await client.get('pubToken')

    console.log(`Using course: ${courseId}`)
    // ... test logic
  })
})

Configuration Options

{
  // Time-to-live for cached data (milliseconds)
  ttl: 600000, // Default: 10 minutes

  // Enable debug logging
  debug: false,

  // Bootstrap data to seed
  seedData: {
    // Persistent cache (from .cache files)
    cache: {
      courseId: 'COURSE_123',
      districtId: 'DISTRICT_456',
      // ... other bootstrap data
    },

    // Ephemeral secrets (never persisted)
    ephemeral: {
      pubToken: 'Bearer ...',
      adminToken: 'Bearer ...',
      // ... tokens, run metadata
    }
  }
}

How It Works

┌─────────────────────────────────────────────┐
│ WDIO Test Run                               │
│                                             │
│ 1. onPrepare: Start broker + seed data     │
│ 2. Spawn 5 parallel workers                │
│ 3. Workers read from broker (fast!)        │
│ 4. onComplete: Stop broker + cleanup       │
└─────────────────────────────────────────────┘

Named Pipe: /tmp/broker-abc123.sock
├── Worker 1 (reads tokens)
├── Worker 2 (reads tokens)
├── Worker 3 (reads tokens)
├── Worker 4 (reads tokens)
└── Worker 5 (reads tokens)

Advanced Usage

Load Cache from Files

import fs from 'fs'

const cache = JSON.parse(
  fs.readFileSync('data/.cache/satellite.qa.bootstrap.json', 'utf8')
)

export const config = {
  services: [
    [EphemeralBrokerService, {
      seedData: {
        cache: cache,
        ephemeral: {
          pubToken: await generateToken(),
          runId: Date.now().toString(36)
        }
      }
    }]
  ]
}

Custom Seeding in onPrepare

export const config = {
  services: [
    [EphemeralBrokerService, { ttl: 600000 }]
  ],

  onPrepare: async function (config, capabilities) {
    // Get service instance
    const brokerService = config.services.find(
      s => s[0] === EphemeralBrokerService
    )?.[1]

    // Seed custom data
    await brokerService.seed({
      cache: { customData: 'value' },
      ephemeral: { token: 'abc123' }
    })
  }
}

Integration with Smart Runner

This plugin was extracted from the smart-runner pattern used in content2class. See INTEGRATION.md for migrating from smart-runner to the plugin.

API

EphemeralBrokerService

Constructor Options

• ttl (number): Time-to-live for cached data in milliseconds. Default: 600000 (10 minutes)
• debug (boolean): Enable debug logging. Default: false
• seedData (object): Bootstrap data to seed
  • cache (object): Persistent cache data
  • ephemeral (object): Ephemeral secrets (tokens, metadata)

Methods

• seed(data): Seed broker with additional data
• getWorkerEnv(): Get environment variables for workers

WDIO Hooks

• onPrepare(): Starts broker before tests
• onComplete(): Stops broker after tests

Environment Variables

Set automatically by the service:

• EPHEMERAL_PIPE: Path to broker pipe (e.g., /tmp/broker-abc123.sock)
• EPHEMERAL_BROKER_MODE: Set to 'true' when broker is active

Examples

See examples/ directory for complete working examples:

• wdio.conf.js - Basic configuration
• wdio.advanced.js - Advanced patterns

Related Projects

• @ephemeral-broker/core - Core broker package
• WebDriverIO - Test automation framework

License

MIT © Kathy Wegrzynowski