ev-charging-simulator

OCPP 1.6 charging station simulator. Use it as a library in tests, or run it as a standalone server.

Installation

npm install ev-charging-simulator

Requires Node.js 20 or later.

Quick start

import { Charger } from 'ev-charging-simulator';

const charger = new Charger({
  evseId: 'EVSE-001',
  csmsUrl: 'ws://localhost:9000/ocpp1.6',
});

await charger.connect();
console.log(charger.isConnected()); // true

await charger.shutdown();

API

new Charger(properties, options?)

type ChargerProperties = {
  evseId: string;           // required, unique identifier sent in BootNotification
  csmsUrl?: string;         // OCPP WebSocket endpoint (falls back to options.csmsUrl, then CSMS_URL env, then ws://localhost:9000/ocpp1.6)
  connectors?: number;      // number of connectors (default: 1)
  power?: { amps: number; volts: number };
  boot?: Partial<BootOptions>;
  brand?: string;           // brand profile name for vendor-specific behaviour
};

type ChargerOptions = {
  csmsUrl?: string;
  connectors?: number;
  bootOverrides?: Partial<BootOptions>;
  brandProfile?: BrandProfile | null;
  chargerPassword?: string;
};

type BootOptions = {
  chargeBoxSerialNumber: string;
  chargePointModel: string;
  chargePointSerialNumber: string;
  chargePointVendor: string;
  firmwareVersion: string;
};

Properties on the constructor take precedence over options for fields that appear in both.

Instance methods

connect(): Promise<void>

Opens the WebSocket, sends BootNotification, and waits for the CSMS to accept it. Resolves once the charger is ready. Rejects if the WebSocket cannot connect or if the boot is rejected.

await charger.connect();

The charger will automatically reconnect on disconnect (exponential backoff, 2 s to 30 s). Call shutdown() to stop reconnection.

disconnect(): Promise<void>

Closes the WebSocket without preventing reconnection. The charger will reconnect on the next attempt. Use shutdown() if you want to stop it permanently.

reconnect(): Promise<void>

Forces a reconnection attempt immediately.

shutdown(): Promise<void>

Stops all timers, cancels all pending OCPP requests, and closes the WebSocket. Does not reconnect. Call this in afterEach / afterAll to avoid open handles in tests.

isConnected(): boolean

Returns true if the WebSocket is open and the BootNotification was accepted.

getState(): ConnectorState

Returns the current station-level connector state.

enum ConnectorState {
  Unavailable = 'Unavailable',
  Available   = 'Available',
  Preparing   = 'Preparing',
  Charging    = 'Charging',
  Finishing   = 'Finishing',
  Faulted     = 'Faulted',
}

setStatus(status: ConnectorState, connectorId?: number): Promise<void>

Sends a StatusNotification to the CSMS and updates the internal state. connectorId defaults to 1. If the connector has an active transaction and the new state is not Charging, the transaction is stopped first.

await charger.setStatus(ConnectorState.Available);
await charger.setStatus(ConnectorState.Faulted, 2);

localStart(connectorId?: number, idTag?: string): Promise<LocalStartResult>

Simulates a local (RFID/button) start: sends Authorize, then StartTransaction.

• connectorId defaults to 1
• idTag defaults to 'LOCALTAG'

type LocalStartResult =
  | { ok: true; transactionId: number | null }
  | { ok: false; reason: 'not_connected' | 'connector_not_found' | 'already_charging' | 'reservation_conflict' | 'authorize_rejected' };

const result = await charger.localStart(1, 'RFID-ABC');
if (!result.ok) {
  console.error(result.reason);
}

stopConnector(connectorId?: number): Promise<LocalStopResult>

Sends StopTransaction and transitions the connector back to Available.

• connectorId defaults to 1

type LocalStopResult =
  | { ok: true }
  | { ok: false; reason: 'connector_not_found' | 'no_active_transaction' };

getPower(): { amps: number; volts: number; watts: number }

Returns the current power model. Watts is derived (amps * volts).

setPower(amps?: number, volts?: number): void

Updates the power model used for meter value calculations. Pass only the fields you want to change.

snapshot(): ChargerSnapshot

Returns a point-in-time copy of the charger state.

type ChargerSnapshot = {
  evseId: string;
  csmsUrl: string;
  connectors: number;
  connected: boolean;
  state: ConnectorState;
  firmwareVersion: string;
  power: { amps: number; volts: number; watts: number };
};

getClient(): OcppClient

Returns the underlying OcppClient. Useful for lower-level control in tests (e.g. authorize(), dataTransfer(), sendMeterValues()).

createChargers(propertiesList, options?): Charger[]

Creates multiple chargers from an array of properties objects. All chargers share the same options.

import { createChargers } from 'ev-charging-simulator';

const chargers = createChargers([
  { evseId: 'EVSE-001', power: { amps: 32, volts: 230 } },
  { evseId: 'EVSE-002', power: { amps: 16, volts: 230 } },
], { csmsUrl: 'ws://localhost:9000/ocpp1.6' });

await Promise.all(chargers.map(c => c.connect()));

loadChargersFromConfig(source?, options?): Promise<Charger[]>

Loads charger definitions from a JSON file path, an object, or an array, and returns connected-ready Charger instances.

import { loadChargersFromConfig } from 'ev-charging-simulator';

const chargers = await loadChargersFromConfig('./evse-config.json', {
  csmsUrl: 'ws://localhost:9000/ocpp1.6',
});

Config file format:

{
  "evses": [
    {
      "evseId": "EVSE-001",
      "connectors": 2,
      "power": { "amps": 32, "volts": 230 },
      "boot": {
        "chargePointVendor": "Acme",
        "chargePointModel": "FastCharger",
        "firmwareVersion": "2.1.0"
      }
    }
  ]
}

loadChargersFromConfig accepts the same ChargerFleetLoadOptions as the charger constructor options, plus bootTemplate (applied before per-charger boot) and bootOverrides (applied after).

Traffic observer

Every OCPP frame sent and received is emitted on trafficBus. This lets you inspect raw traffic without a proxy.

import { trafficBus } from 'ev-charging-simulator';
import type { TrafficEvent } from 'ev-charging-simulator';

trafficBus.on('message', (event: TrafficEvent) => {
  console.log(event.dir, event.action, event.evseId);
});

type TrafficEvent = {
  ts: string;          // ISO timestamp
  evseId: string;
  dir: 'send' | 'recv';
  msgType: 2 | 3 | 4; // CALL / CALLRESULT / CALLERROR
  action?: string;     // present on CALL frames
  msgId: string;
  payload: Record<string, unknown>;
};

Framework integration

Playwright

Use a fixture so each test gets a fresh charger that is automatically shut down.

// fixtures.ts
import { test as base } from '@playwright/test';
import { Charger } from 'ev-charging-simulator';

type Fixtures = {
  charger: Charger;
};

export const test = base.extend<Fixtures>({
  charger: async ({}, use) => {
    const charger = new Charger({
      evseId: `TEST-${Date.now()}`,
      csmsUrl: process.env.CSMS_URL ?? 'ws://localhost:9000/ocpp1.6',
    });
    await charger.connect();
    await use(charger);
    await charger.shutdown();
  },
});

export { expect } from '@playwright/test';

// charging.spec.ts
import { test, expect } from './fixtures';
import { ConnectorState } from 'ev-charging-simulator';

test('CSMS shows charger as available after boot', async ({ page, charger }) => {
  await page.goto('/dashboard');
  await expect(page.getByTestId(`charger-${charger.evseId}`)).toHaveText('Available');
});

test('CSMS shows active transaction', async ({ page, charger }) => {
  const result = await charger.localStart(1, 'RFID-001');
  expect(result.ok).toBe(true);

  await page.goto('/dashboard');
  await expect(page.getByTestId(`charger-${charger.evseId}`)).toHaveText('Charging');
});

If you need multiple chargers per test, parametrize the fixture or create a fleet fixture:

// fixtures.ts (fleet variant)
import { test as base } from '@playwright/test';
import { createChargers, type Charger } from 'ev-charging-simulator';

type Fixtures = {
  chargerFleet: Charger[];
};

export const test = base.extend<Fixtures>({
  chargerFleet: async ({}, use) => {
    const chargers = createChargers(
      [{ evseId: 'FLEET-001' }, { evseId: 'FLEET-002' }, { evseId: 'FLEET-003' }],
      { csmsUrl: process.env.CSMS_URL ?? 'ws://localhost:9000/ocpp1.6' },
    );
    await Promise.all(chargers.map(c => c.connect()));
    await use(chargers);
    await Promise.all(chargers.map(c => c.shutdown()));
  },
});

Vitest

// charger.test.ts
import { beforeEach, afterEach, describe, it, expect } from 'vitest';
import { Charger, ConnectorState } from 'ev-charging-simulator';

describe('charging flow', () => {
  let charger: Charger;

  beforeEach(async () => {
    charger = new Charger({
      evseId: 'TEST-001',
      csmsUrl: 'ws://localhost:9000/ocpp1.6',
    });
    await charger.connect();
  });

  afterEach(async () => {
    await charger.shutdown();
  });

  it('starts in Available state', () => {
    expect(charger.getState()).toBe(ConnectorState.Available);
  });

  it('transitions to Charging after localStart', async () => {
    const result = await charger.localStart(1, 'RFID-001');
    expect(result.ok).toBe(true);
    expect(charger.getState()).toBe(ConnectorState.Charging);
  });

  it('returns to Available after stopConnector', async () => {
    await charger.localStart(1, 'RFID-001');
    const result = await charger.stopConnector(1);
    expect(result.ok).toBe(true);
    expect(charger.getState()).toBe(ConnectorState.Available);
  });
});

For shared setup across a suite, use beforeAll / afterAll — but note that state from one test will carry over to the next.

import { beforeAll, afterAll, describe, it, expect } from 'vitest';
import { Charger } from 'ev-charging-simulator';

describe('long-running suite', () => {
  let charger: Charger;

  beforeAll(async () => {
    charger = new Charger({ evseId: 'SHARED-001' });
    await charger.connect();
  });

  afterAll(async () => {
    await charger.shutdown();
  });

  it('...', () => { /* ... */ });
});

Jest

// charger.test.ts
import { Charger, ConnectorState } from 'ev-charging-simulator';

let charger: Charger;

beforeEach(async () => {
  charger = new Charger({
    evseId: 'TEST-001',
    csmsUrl: 'ws://localhost:9000/ocpp1.6',
  });
  await charger.connect();
});

afterEach(async () => {
  await charger.shutdown();
});

test('transitions to Charging after localStart', async () => {
  const result = await charger.localStart(1, 'RFID-001');
  expect(result.ok).toBe(true);
  expect(charger.getState()).toBe(ConnectorState.Charging);
});

If you use Jest with ESM, add the following to jest.config.js:

export default {
  extensionsToTreatAsEsm: ['.ts'],
  transform: {
    '^.+\\.tsx?$': ['ts-jest', { useESM: true }],
  },
};

Node.js built-in test runner

import { describe, it, before, after } from 'node:test';
import assert from 'node:assert/strict';
import { Charger, ConnectorState } from 'ev-charging-simulator';

describe('charger', () => {
  let charger: Charger;

  before(async () => {
    charger = new Charger({ evseId: 'TEST-001' });
    await charger.connect();
  });

  after(async () => {
    await charger.shutdown();
  });

  it('starts in Available state', () => {
    assert.equal(charger.getState(), ConnectorState.Available);
  });
});

Inspecting OCPP traffic in tests

Subscribe to trafficBus before calling connect, then assert on the frames you care about.

import { Charger, trafficBus, type TrafficEvent } from 'ev-charging-simulator';

const frames: TrafficEvent[] = [];
trafficBus.on('message', e => frames.push(e));

const charger = new Charger({ evseId: 'TRAFFIC-001' });
await charger.connect();
await charger.localStart();

const startTx = frames.find(f => f.action === 'StartTransaction' && f.dir === 'send');
console.log(startTx?.payload);
// { connectorId: 1, idTag: 'LOCALTAG', meterStart: ..., timestamp: '...' }

Environment variables

| Variable | Default | Description | |---|---|---| | CSMS_URL | ws://localhost:9000/ocpp1.6 | Default CSMS endpoint when not set in constructor | | ACE_LOGIN_PASSWORD | (empty) | Password for the ACE compatibility HTTP API | | LOG_OCPP_TRAFFIC | false | Set to true to log every OCPP frame to stdout | | FIRMWARE_ALLOWED_HOSTS | (any) | Comma-separated list of allowed firmware update hostnames | | FIRMWARE_REQUIRE_CHECKSUM | true | Set to false to skip firmware update checksum validation |

License

MIT