From 2836fd0f2fa0a1626c99701273f65fc98ea2f9e2 Mon Sep 17 00:00:00 2001 From: sepehr-safari Date: Thu, 9 Jul 2026 10:33:34 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20v0.3=20content=20=E2=80=94=205=20new=20?= =?UTF-8?q?+=203=20updated=20docs=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #91 --- CURRENT_STATE.md | 1 + apps/web/src/app/docs/anonymize/page.tsx | 67 +++++++++++ apps/web/src/app/docs/ci-mode/page.tsx | 79 +++++++++++++ apps/web/src/app/docs/cli/page.tsx | 66 +++++++++++ apps/web/src/app/docs/examples/page.tsx | 57 +++++++++ apps/web/src/app/docs/page.tsx | 15 +++ .../src/app/docs/scenario-assertions/page.tsx | 108 ++++++++++++++++++ apps/web/src/app/docs/trace-diffing/page.tsx | 65 +++++++++++ 8 files changed, 458 insertions(+) create mode 100644 apps/web/src/app/docs/anonymize/page.tsx create mode 100644 apps/web/src/app/docs/ci-mode/page.tsx create mode 100644 apps/web/src/app/docs/examples/page.tsx create mode 100644 apps/web/src/app/docs/scenario-assertions/page.tsx create mode 100644 apps/web/src/app/docs/trace-diffing/page.tsx diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md index 2682551..2d353a5 100644 --- a/CURRENT_STATE.md +++ b/CURRENT_STATE.md @@ -206,6 +206,7 @@ integration examples, and contributor onboarding. - ✅ CLI: ci + anonymize + diff commands (Issue #88) - ✅ Integration examples — 4 example projects (Issue #89) - ✅ Contribution guide + 5 good-first-issues (Issue #90) +- ✅ v0.3 docs content — 5 new + 3 updated docs pages (Issue #91) ## What's Next diff --git a/apps/web/src/app/docs/anonymize/page.tsx b/apps/web/src/app/docs/anonymize/page.tsx new file mode 100644 index 0000000..3c62e20 --- /dev/null +++ b/apps/web/src/app/docs/anonymize/page.tsx @@ -0,0 +1,67 @@ +export default function AnonymizePage() { + return ( +
+

Anonymize

+

+ The ocpp-debugkit anonymize command strips sensitive fields from a trace file, + making it safe to share for debugging or support purposes. +

+ +

Usage

+ 
+        {`# Output to stdout
+ocpp-debugkit anonymize trace.json
+
+# Write to file
+ocpp-debugkit anonymize trace.json -o trace-anon.json`}
+
+ +

What Gets Anonymized

+ + +

Privacy Considerations

+

+ 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. +

+ +

What Is NOT Anonymized

+ +
+ ); +} diff --git a/apps/web/src/app/docs/ci-mode/page.tsx b/apps/web/src/app/docs/ci-mode/page.tsx new file mode 100644 index 0000000..5e5e179 --- /dev/null +++ b/apps/web/src/app/docs/ci-mode/page.tsx @@ -0,0 +1,79 @@ +export default function CiModePage() { + return ( +
+

CI Mode

+

+ 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. +

+ +

Basic Usage

+ 
+        {`# 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`}
+
+ +

GitHub Actions Integration

+

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. +

+ +

External Scenario Files

+

+ 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"] } }
+  ]
+}`}
+
+ +

JSON Output Format

+ 
+        {`{
+  "results": [
+    {
+      "name": "normal-session",
+      "passed": true,
+      "detectedFailures": [],
+      "expectedFailures": [],
+      "assertionResults": []
+    },
+    ...
+  ],
+  "allPassed": true
+}`}
+
+ +

Example Workflow

+

+ See the examples/ci-example/ directory for a complete GitHub Actions workflow + with scenario files. +

+
+ ); +} diff --git a/apps/web/src/app/docs/cli/page.tsx b/apps/web/src/app/docs/cli/page.tsx index e630869..35d7afd 100644 --- a/apps/web/src/app/docs/cli/page.tsx +++ b/apps/web/src/app/docs/cli/page.tsx @@ -67,6 +67,72 @@ export default function CliReferencePage() { analysis engine only. It is not active endpoint testing, WebSocket simulation, or live station/CSMS testing.

+

External 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`}
+
+ +

ci

+

+ 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]`}
+
+

Options

+ +

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`}
+
+ +

anonymize

+

+ Strip sensitive fields from a trace file. Anonymizes idTag, chargePointSerialNumber, + stationId, transactionId, and email/phone/IP patterns. +

+ 
+        {`ocpp-debugkit anonymize  [options]`}
+
+

Options

+ +

Example:

+ 
+        {`ocpp-debugkit anonymize trace.json -o trace-anon.json`}
+
+ +

diff

+

Compare two trace files and show differences in events, failures, and summaries.

+ 
+        {`ocpp-debugkit diff   [options]`}
+
+

Options

+
    +
  • + --format <format> — Output format: text (default) or json +
    • +
+

Example:

+ 
+        {`ocpp-debugkit diff trace-a.json trace-b.json`}
+

Global Options

 ); diff --git a/apps/web/src/app/docs/scenario-assertions/page.tsx b/apps/web/src/app/docs/scenario-assertions/page.tsx new file mode 100644 index 0000000..6c250f7 --- /dev/null +++ b/apps/web/src/app/docs/scenario-assertions/page.tsx @@ -0,0 +1,108 @@ +export default function ScenarioAssertionsPage() { + return ( +
+

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. +

+
+ ); +} diff --git a/apps/web/src/app/docs/trace-diffing/page.tsx b/apps/web/src/app/docs/trace-diffing/page.tsx new file mode 100644 index 0000000..df0c7fd --- /dev/null +++ b/apps/web/src/app/docs/trace-diffing/page.tsx @@ -0,0 +1,65 @@ +export default function TraceDiffingPage() { + return ( +
+

Trace Diffing

+

+ 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. +

+ +

Programmatic API

+ 
+        {`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));
+`}
+
+ +

TraceDiff Output

+
    +
  • + 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) +
    • +
+ +

CLI Usage

+ 
+        {`ocpp-debugkit diff trace-a.json trace-b.json
+ocpp-debugkit diff trace-a.json trace-b.json --format json`}
+
+ +

How Matching Works

+

+ 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. +

+
+ ); +}