Skip to content

Add a new scenario: heartbeat-timeout #137

Description

@sepehr-safari

Good First Issue

Add a new scenario heartbeat-timeout. The TIMEOUT_NO_HEARTBEAT detection rule
has no scenario covering it, so nothing in the corpus would catch a regression in
it.

What to do

  1. Create packages/toolkit/src/scenarios/__scenarios__/heartbeat-timeout.ts
  2. Build a synthetic trace where the station boots and then never sends a
    Heartbeat:
    • BootNotification at 2026-01-15T06:00:00.000Z
    • Its CallResult with interval: 300
    • StatusNotification (connector 1, status Available) at
      2026-01-15T06:12:00.000Z, and its CallResult
    • No Heartbeat anywhere in the trace
  3. Set expectedFailures: ['TIMEOUT_NO_HEARTBEAT']
  4. Add an assertion, for example
    { type: 'failure_severity', params: { code: 'TIMEOUT_NO_HEARTBEAT', severity: 'warning' } }
  5. Import and register in packages/toolkit/src/scenarios/index.ts
  6. Update the scenario count and name list, see "Files to modify"
  7. Add a changeset with pnpm changeset, minor bump for @ocpp-debugkit/toolkit

Why those timestamps

The rule reads interval from the BootNotification response and sets a threshold
at twice that interval after the boot, so 300 gives a threshold at
06:10:00.000Z. It deliberately stays silent when the trace simply ends before a
heartbeat is due, so the trace needs at least one event after the threshold. The
StatusNotification at 06:12:00.000Z is what makes the rule fire.

Files to modify

  • packages/toolkit/src/scenarios/__scenarios__/heartbeat-timeout.ts (new)
  • packages/toolkit/src/scenarios/index.ts (register, and add to scenarioNames)
  • packages/toolkit/src/scenarios/index.test.ts (count, name order, getScenario)
  • tests/external-fixture/test.mjs (count)
  • README.md (count)
  • packages/toolkit/README.md (count)
  • .changeset/ (new changeset file)

Guidelines

  • All data must be synthetic. This scenario reserves station ID
    CS-SYNTHETIC-018, so please use that one.
  • Follow the pattern in an existing scenario file, unresponsive-csms.ts is a
    close match in shape.
  • Verify with ocpp-debugkit scenario run heartbeat-timeout that
    TIMEOUT_NO_HEARTBEAT is the only failure reported. If another rule fires,
    adjust the trace rather than adding the extra code to expectedFailures.
  • Then run the full local check from
    Verify Locally.
    ocpp-debugkit ci covers neither formatting nor lint nor types, and CI stops at
    the first failure.
  • The scenario count depends on what has merged ahead of you. Run the suite and
    use the number it reports rather than assuming.

How to claim

Comment "I'd like to work on this" and it will be assigned to you.

Please hold one open claim at a time. Once the pull request for it is merged,
say which issue you want next and it will be assigned. That keeps issues from
sitting claimed while another is still in review, so other newcomers can see
what is genuinely free.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions