Scenario Assertions

Scenario assertions provide a declarative way to verify analysis results beyond simple failure-code matching. They allow you to assert event ordering, counts, payload fields, timing constraints, session state, and more.

Assertion Types

The following assertion types are available:

event_order

Verify that events appear in a specific order (not necessarily consecutive).

{ type: 'event_order', params: { actions: ['BootNotification', 'Authorize', 'StartTransaction'] } }

event_count

Verify the count of events, optionally filtered by action.

{ type: 'event_count', params: { min: 5, max: 20 } }
{ type: 'event_count', params: { min: 1, action: 'StartTransaction' } }

payload_field

Verify a payload field value on a specific action. Supports equals (deep equality) and contains (array/string contains).

{ type: 'payload_field', params: { action: 'Authorize', field: 'idTag', equals: 'TAG-001' } }
{ type: 'payload_field', params: { action: 'StartTransaction', field: 'connectorId', equals: 1 } }

timing

Verify timing gaps between two actions. Uses minGapMs and/or maxGapMs.

{ type: 'timing', params: { actionA: 'BootNotification', actionB: 'StartTransaction', maxGapMs: 5000 } }
{ type: 'timing', params: { actionA: 'BootNotification', actionB: 'Heartbeat', minGapMs: 5000 } }

session_state

Verify the session status (active, completed, or aborted).

{ type: 'session_state', params: { expected: 'completed' } }

failure_severity

Verify that a specific failure has the expected severity.

{ type: 'failure_severity', params: { code: 'UNRESPONSIVE_CSMS', severity: 'critical' } }

no_failures

Verify that no failures are detected.

{ type: 'no_failures', params: {} }

failure_count

Verify the count of detected failures, optionally filtered by code.

{ type: 'failure_count', params: { min: 1, max: 3 } }
{ type: 'failure_count', params: { code: 'FAILED_AUTHORIZATION', min: 1 } }

Using Assertions in Scenarios

Assertions are an optional field on the Scenario type. They are evaluated alongside expectedFailures:

{
  name: 'my-scenario',
  description: 'Test scenario with assertions',
  trace: { /* ... */ },
  expectedFailures: ['FAILED_AUTHORIZATION'],
  assertions: [
    { type: 'event_order', params: { actions: ['BootNotification', 'Authorize'] } },
    { type: 'failure_count', params: { code: 'FAILED_AUTHORIZATION', min: 1, max: 1 } }
  ]
}

Programmatic API

import { evaluateScenario } from '@ocpp-debugkit/toolkit/core';

const result = evaluateScenario(scenario);
console.log(result.allPassed);           // true if all assertions + expectedFailures pass
console.log(result.assertions);          // AssertionResult[] with pass/fail per assertion
console.log(result.expectedFailuresPassed); // true if detected matches expected
console.log(result.detectedFailureCodes);   // detected failure codes

Backward Compatibility

Existing scenarios with only expectedFailures (no assertions field) continue to work unchanged. The assertions field is optional.