militia

Local orchestrator for ephemeral test services and integration test harnesses.

Features

• Define and run ephemeral service units (processes or Docker containers) with dependency ordering.
• Automatic port allocation, health checks, environment injection, and lifecycle hooks.
• Programmatic API and CLI to start, inspect, and stop groups of services for tests and local development.
• Support for YAML and JavaScript configuration for reproducible test harnesses.

Install

npm install militia

Quick Start

This example shows how to programmatically start a simple integration harness, run tests, and tear it down.

const Militia = require('militia');

async function run() {
  const muster = new Militia({
    units: {
      db: {
        type: 'docker',
        image: 'postgres:14',
        ports: { '5432/tcp': 0 },
        env: { POSTGRES_PASSWORD: 'pass' },
        health: { type: 'tcp', port: 5432 }
      },
      api: {
        cmd: 'node',
        args: ['server.js'],
        env: { DATABASE_URL: 'postgres://postgres:pass@{{db.host}}:{{db.port}}/postgres' },
        dependsOn: ['db'],
        health: { type: 'http', url: 'http://localhost:3000/health' }
      }
    }
  });

  await muster.start();

  // Inspect runtime info (ports, host, logs)
  const dbInfo = muster.get('db');
  console.log('Postgres running on:', dbInfo.address);

  // Run your integration tests here
  // await runTestsAgainst(muster);

  await muster.stop();
}

run().catch(err => {
  console.error(err);
  process.exit(1);
});

For CLI usage and YAML configuration examples, see the package docs.

License

MIT