+ The ocpp-debugkit anonymize command strips sensitive fields from a trace file,
+ making it safe to share for debugging or support purposes.
+
+ {`# Output to stdout
+ocpp-debugkit anonymize trace.json
+
+# Write to file
+ocpp-debugkit anonymize trace.json -o trace-anon.json`}
+
+
+ idTag — replaced with "anonymized"
+ chargePointSerialNumber / chargeBoxSerialNumber — replaced with{' '}
+ "station-anon"
+ stationId — replaced with "station-anon"
+ transactionId — replaced with sequential integers (1, 2, 3...)
+ identifier — replaced with "anonymized"
+ [redacted-email]
+ [redacted-phone]
+ [redacted-ip]
+ + Anonymization is performed locally — no data is uploaded. The anonymized trace is safe to + share in issue reports, support tickets, or public forums. +
++ Note: Anonymization is a best-effort process. Always review the output + before sharing to ensure no sensitive data remains. +
+ +
+ The ocpp-debugkit ci command runs all built-in scenarios (and optional external
+ scenario files) and exits with code 0 if all pass, 1 if any fail. This is designed for
+ integration into CI/CD pipelines.
+
+ {`# Run all built-in scenarios
+ocpp-debugkit ci
+
+# Also run external scenarios from a directory
+ocpp-debugkit ci ./scenarios
+
+# JSON output for CI tooling
+ocpp-debugkit ci --format json`}
+
+
+ Add the following step to your workflow:
+
+ {`- name: Run OCPP scenario tests
+ run: ocpp-debugkit ci --format json`}
+
+ + The command exits 0 (pass) or 1 (fail). The JSON output can be parsed for dashboards or + notifications. +
+ +
+ Create JSON scenario files in a directory and pass the directory path to the ci{' '}
+ command:
+
+ {`ocpp-debugkit ci ./scenarios`}
+
+ Scenario file format:
+
+ {`{
+ "name": "my-scenario",
+ "description": "Custom scenario for CI testing",
+ "trace": { ... },
+ "expectedFailures": ["FAILED_AUTHORIZATION"],
+ "assertions": [
+ { "type": "event_order", "params": { "actions": ["BootNotification", "Authorize"] } }
+ ]
+}`}
+
+
+
+ {`{
+ "results": [
+ {
+ "name": "normal-session",
+ "passed": true,
+ "detectedFailures": [],
+ "expectedFailures": [],
+ "assertionResults": []
+ },
+ ...
+ ],
+ "allPassed": true
+}`}
+
+
+
+ See the examples/ci-example/ directory for a complete GitHub Actions workflow
+ with scenario files.
+
Load and run an external scenario file (JSON format) instead of a built-in scenario:
+
+ {`ocpp-debugkit scenario run --file ./my-scenario.json`}
+
+
+ + Run all built-in scenarios (and optional external scenario files from a directory), exit 0 + if all pass, 1 if any fail. Designed for CI/CD pipelines. +
+
+ {`ocpp-debugkit ci [dir] [options]`}
+
+ --format <format> — Output format: text (default) or json
+ Examples:
+
+ {`# Run all built-in scenarios
+ocpp-debugkit ci
+
+# Also run external scenarios from a directory
+ocpp-debugkit ci ./scenarios
+
+# JSON output for CI tooling
+ocpp-debugkit ci --format json`}
+
+
+ + Strip sensitive fields from a trace file. Anonymizes idTag, chargePointSerialNumber, + stationId, transactionId, and email/phone/IP patterns. +
+
+ {`ocpp-debugkit anonymize [options]`}
+
+ -o, --output <file> — Write anonymized trace to file (default: stdout)
+ Example:
+
+ {`ocpp-debugkit anonymize trace.json -o trace-anon.json`}
+
+
+ Compare two trace files and show differences in events, failures, and summaries.
+
+ {`ocpp-debugkit diff [options]`}
+
+ --format <format> — Output format: text (default) or json
+ Example:
+
+ {`ocpp-debugkit diff trace-a.json trace-b.json`}
+
+ Integration examples showing how to use @ocpp-debugkit/toolkit in your
+ projects. Each example is a standalone project in the examples/ directory of
+ the repository.
+
ocpp-debugkit ci in GitHub Actions
+ workflows. Demonstrates CI integration with scenario files.
+ Each example is standalone. Clone the repo and run:
+
+ {`cd examples/simple-trace
+npm install
+npm start`}
+
+
+ + 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. +
+ +The following assertion types are available:
+ +Verify that events appear in a specific order (not necessarily consecutive).
+
+ {`{ type: 'event_order', params: { actions: ['BootNotification', 'Authorize', 'StartTransaction'] } }`}
+
+
+ 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' } }`}
+
+
+
+ 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 } }`}
+
+
+
+ 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 } }`}
+
+
+ Verify the session status (active, completed, or aborted).
+
+ {`{ type: 'session_state', params: { expected: 'completed' } }`}
+
+
+ Verify that a specific failure has the expected severity.
+
+ {`{ type: 'failure_severity', params: { code: 'UNRESPONSIVE_CSMS', severity: 'critical' } }`}
+
+
+ Verify that no failures are detected.
+
+ {`{ type: 'no_failures', params: {} }`}
+
+
+ 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 } }`}
+
+
+
+ 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 } }
+ ]
+}`}
+
+
+
+ {`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`}
+
+
+
+ Existing scenarios with only expectedFailures (no assertions{' '}
+ field) continue to work unchanged. The assertions field is optional.
+
+ OCPP DebugKit can compare two parsed traces and surface differences at multiple levels: + events, failures, and session summaries. This is useful for debugging regression issues, + comparing good vs bad sessions, and tracking changes after fixes. +
+ +
+ {`import { parseTrace, diffTraces } from '@ocpp-debugkit/toolkit/core';
+
+const resultA = parseTrace(traceAJson);
+const resultB = parseTrace(traceBJson);
+const diff = diffTraces(resultA, resultB);
+
+console.log('Events only in A:', diff.onlyInA.length);
+console.log('Events only in B:', diff.onlyInB.length);
+console.log('Modified events:', diff.modified.length);
+console.log('Failures only in A:', diff.failuresOnlyInA.map(f => f.code));
+console.log('Failures only in B:', diff.failuresOnlyInB.map(f => f.code));
+`}
+
+
+ onlyInA / onlyInB — Events present in only one trace (by
+ messageId)
+ modified — Field-level differences for events in both (timestamp, direction,
+ action, payload, errorCode)
+ failuresOnlyInA / failuresOnlyInB — Failures detected in one but
+ not the other
+ summaryDiff — Session summary differences (event count, failure count,
+ duration, status)
+
+ {`ocpp-debugkit diff trace-a.json trace-b.json
+ocpp-debugkit diff trace-a.json trace-b.json --format json`}
+
+
+
+ Events are matched by their OCPP messageId (UniqueId). A Call and its
+ CallResult share the same messageId — they are compared positionally within the same
+ messageId group.
+
+ Payloads are compared using deep equality. Any difference in nested fields is surfaced as a
+ single payload modification.
+