Test Spec: Expanded J1939 Workflows¶

Document Control¶

Field	Value
Status	Partial
Related design spec	`docs/design/j1939-expanded-workflows.md`
Primary test area	CLI, protocol

Test Objectives¶

Validate that the expanded J1939 workflows preserve protocol-first behavior and correctly parse supported SPN, TP, DM1, inventory, and multi-capture comparison scenarios.

Coverage Requirements¶

j1939 spn / j1939 pgn offline reference lookup without --file
j1939 spn structured value extraction from a supported SPN
j1939 tp sessions BAM session summary and reassembly
j1939 dm1 parsing for both direct and TP-reassembled messages
j1939 inventory source-address inventory assembly from identification and DM1 context
j1939 compare multi-capture PGN/source/dm1/identifier differences
text output for DM1 remains human-readable

Requirement Traceability¶

Requirement ID	Covered by test IDs
`REQ-J1939-01`	`TEST-J1939-01`, `TEST-J1939-02`, `TEST-J1939-03`, `TEST-J1939-04`, `TEST-J1939-05`, `TEST-J1939-08`, `TEST-J1939-09`, `TEST-J1939-10`, `TEST-J1939-11`
`REQ-J1939-02`	`TEST-J1939-02`
`REQ-J1939-03`	`TEST-J1939-03`
`REQ-J1939-04`	`TEST-J1939-04`
`REQ-J1939-05`	`TEST-J1939-02`, `TEST-J1939-03`, `TEST-J1939-04`, `TEST-J1939-05`, `TEST-J1939-06`, `TEST-J1939-07`
`REQ-J1939-06`	`TEST-J1939-01`, `TEST-J1939-15`
`REQ-J1939-07`	Deferred
`REQ-J1939-08`	`TEST-J1939-16`
`REQ-J1939-21`	`TEST-J1939-17`
`REQ-J1939-09`	`TEST-J1939-06`, `TEST-J1939-07`
`REQ-J1939-10`	`TEST-J1939-06`, `TEST-J1939-07`
`REQ-J1939-11`	`TEST-J1939-08`, `TEST-J1939-09`
`REQ-J1939-12`	`TEST-J1939-08`, `TEST-J1939-09`
`REQ-J1939-13`	`TEST-J1939-08`, `TEST-J1939-09`
`REQ-J1939-14`	`TEST-J1939-08`
`REQ-J1939-15`	`TEST-J1939-10`
`REQ-J1939-16`	`TEST-J1939-10`
`REQ-J1939-17`	`TEST-J1939-10`
`REQ-J1939-18`	`TEST-J1939-10`, `TEST-J1939-11`
`REQ-J1939-19`	`TEST-J1939-12`

Representative Test Cases¶

`TEST-J1939-01` — SPN reference lookup without a capture¶

Given  no capture file is provided
When   the operator runs `canarchy j1939 spn 110 --json`
Then   the command shall exit with code `0`
And    `data.mode` shall equal `"reference"` with `source` `"catalog"`
And    `data` shall report the SPN name, owning PGN, and units from the bundled catalog

Test: test_j1939_spn_without_file_returns_reference_definition. Fixture: none required.

`TEST-J1939-02` — SPN observation extraction¶

Given  a capture fixture containing PGN `65262` is available
When   the operator runs `canarchy j1939 spn 110 --file sample.candump --json`
Then   exactly one observation shall be returned
And    the observation shall include the expected SPN, PGN, source address, decoded value, and units

Fixture: tests/fixtures/sample.candump.

`TEST-J1939-03` — TP BAM session summary¶

Given  the fixture `j1939_dm1_tp.candump` contains TP.CM BAM and TP.DT frames for a DM1 payload
When   the operator runs `canarchy j1939 tp sessions --file j1939_dm1_tp.candump --json`
Then   exactly one complete BAM session shall be returned
And    the session shall include the expected transferred PGN, packet count, and reassembled payload bytes

Fixture: tests/fixtures/j1939_dm1_tp.candump.

`TEST-J1939-04` — DM1 direct and transported parsing¶

Given  the fixture `j1939_dm1_tp.candump` contains one direct DM1 and one TP-reassembled DM1
When   the operator runs `canarchy j1939 dm1 --file j1939_dm1_tp.candump --json`
Then   both DM1 messages shall be returned
And    the TP-reassembled message shall have two DTCs
And    the direct message shall preserve its source address and FMI

Fixture: tests/fixtures/j1939_dm1_tp.candump.

`TEST-J1939-05` — DM1 text output¶

Given  the fixture `j1939_dm1_tp.candump` is available
When   the operator runs `canarchy j1939 dm1 --file j1939_dm1_tp.candump --text`
Then   the output shall include the command header
And    the output shall include a message section with a transport label
And    the output shall include DTC summaries for each message

Fixture: tests/fixtures/j1939_dm1_tp.candump.

`TEST-J1939-06` — TP printable identification text¶

Given  the fixture `j1939_tp_printable_id.candump` contains a completed TP payload with obvious printable ASCII identification text
When   the operator runs `canarchy j1939 tp sessions --file j1939_tp_printable_id.candump --json`
Then   the returned TP session shall preserve `reassembled_data`
And    the session shall include `decoded_text` plus a heuristic flag
And    the session shall include a stable payload label when the transferred PGN is known to be identification-style data

Fixture: tests/fixtures/j1939_tp_printable_id.candump.

`TEST-J1939-07` — TP text output surfaces printable identification text¶

Given  the fixture `j1939_tp_printable_id.candump` contains a printable TP identification payload
When   the operator runs `canarchy j1939 tp sessions --file j1939_tp_printable_id.candump --text`
Then   the operator-facing output shall include the payload label when available
And    the operator-facing output shall include the decoded printable text without hiding the TP session summary context

Fixture: tests/fixtures/j1939_tp_printable_id.candump.

`TEST-J1939-08` — Inventory JSON output associates IDs with source addresses¶

Given  the fixture `j1939_inventory.candump` contains per-source operational PGNs, component-identification TP payloads, a vehicle-identification TP payload, and DM1 traffic
When   the operator runs `canarchy j1939 inventory --file j1939_inventory.candump --json`
Then   the result shall include one inventory node per observed source address
And    the source-address rows shall include top PGNs plus first and last timestamps
And    the reporting source address shall include the decoded component-identification and vehicle-identification strings when available
And    the reporting source address shall include DM1 presence metadata

Fixture: tests/fixtures/j1939_inventory.candump.

`TEST-J1939-09` — Inventory text output remains operator-friendly¶

Given  the fixture `j1939_inventory.candump` is available
When   the operator runs `canarchy j1939 inventory --file j1939_inventory.candump --text`
Then   the output shall include the command header
And    the output shall include the decoded vehicle identification text when available
And    the output shall include per-source rows with component-identification and DM1 presence summaries

Fixture: tests/fixtures/j1939_inventory.candump.

`TEST-J1939-10` — Compare JSON output highlights capture differences¶

Given  two J1939 capture fixtures with intentional differences in PGNs, source addresses, DM1 content, and printable identification payloads are available
When   the operator runs `canarchy j1939 compare compare_a.candump compare_b.candump --json`
Then   the result shall include common and capture-unique PGNs
And    the result shall include common and capture-unique source addresses
And    the result shall include DM1 differences for source addresses whose active fault content changed
And    the result shall include source-address identification differences when printable TP payloads differ

Fixture: tests/fixtures/j1939_inventory.candump, tests/fixtures/j1939_compare_shifted.candump.

`TEST-J1939-11` — Compare text output remains operator-friendly¶

Given  two J1939 capture fixtures with identification differences are available
When   the operator runs `canarchy j1939 compare compare_a.candump compare_b.candump --text`
Then   the output shall include the command header
And    the output shall include common-PGN and unique-source sections
And    the output shall include the differing printable identification values

Fixture: tests/fixtures/j1939_inventory.candump, tests/fixtures/j1939_compare_shifted.candump.

`TEST-J1939-12` — Compare requires multiple captures¶

Given  only one capture file is provided
When   the operator runs `canarchy j1939 compare compare_a.candump --json`
Then   the command shall exit with code `1`
And    `errors[0].code` shall equal `"J1939_COMPARE_REQUIRES_MULTIPLE_FILES"`

Fixture: tests/fixtures/j1939_inventory.candump.

Fixtures And Environment¶

existing sample.candump
j1939_dm1_tp.candump for TP and DM1 coverage
j1939_tp_printable_id.candump for printable TP identification coverage
j1939_inventory.candump for source-address inventory coverage
j1939_compare_shifted.candump for multi-capture comparison coverage

Explicit Non-Coverage¶

full RTS/CTS transport control flows
large multi-packet TP sessions beyond the BAM starter path
broad SPN database coverage beyond the curated starter decoder set

Traceability¶

This spec maps to the J1939 expansion acceptance criteria around protocol-relevant output fields, SPN/TP/DM1 behavior, and representative transport and DM coverage.

`TEST-J1939-13` — FMI catalog resolves fault-mode descriptions (`REQ-J1939-20`)¶

Given  the bundled SAE J1939-73 FMI catalog
When   `fmi_lookup` is called with 3, 5, and 31
Then   it shall return the standard descriptions ("Voltage Above Normal, Or Shorted To High Source", "Current Below Normal Or Open Circuit", "Condition Exists")
And    out-of-range values shall return `None`
When   DM1 messages are decoded from a capture with SPN 175 / FMI 5
Then   each DTC shall carry `name: "Engine Oil Temperature 1"` and `fmi_description: "Current Below Normal Or Open Circuit"`

Fixture: tests/fixtures/j1939_dm1_spn175.candump.

`TEST-J1939-14` — OEM SPN overrides merge over the bundled catalog (`REQ-J1939-20`)¶

Given  a JSON overrides file mapping SPN 520001 to a proprietary name
And    `CANARCHY_J1939_SPN_OVERRIDES` points at that file
When   `spn_lookup(520001)` is called
Then   it shall return the proprietary name
And    bundled entries (e.g. SPN 175) shall remain resolvable

Fixture: temporary overrides file.

`TEST-J1939-15` — SPN reference resolves an OEM SPN from a supplied DBC (`REQ-J1939-06`)¶

Given  SPN 9999 is absent from the bundled catalog but defined by a DBC
When   the operator runs `canarchy j1939 spn 9999 --dbc <dbc> --json` without `--file`
Then   the command shall exit with code `0`
And    `data.mode` shall equal `"reference"` with `source` `"dbc"`
And    `data` shall report the DBC signal name, units, resolution, and bit layout

Test: test_j1939_spn_reference_resolves_oem_spn_from_dbc. Fixture: tests/fixtures/j1939_oem_spn.dbc.

`TEST-J1939-16` — Unknown SPN without catalog or DBC entry errors (`REQ-J1939-08`)¶

Given  SPN 999999 is absent from the catalog and no DBC is supplied
When   the operator runs `canarchy j1939 spn 999999 --json` without `--file`
Then   the command shall exit with code `1`
And    `errors[0].code` shall equal `"J1939_SPN_UNSUPPORTED"`

Test: test_j1939_spn_unknown_without_file_returns_structured_error. Fixture: none.

`TEST-J1939-17` — PGN reference lookup without a capture (`REQ-J1939-21`)¶

Given  no capture file is provided
When   the operator runs `canarchy j1939 pgn 61444 --json`
Then   the command shall exit with code `0`
And    `data.mode` shall equal `"reference"` with label `"EEC1"`
And    `data.spns` shall list the catalogued SPNs the PGN carries (including SPN 190)

Test: test_j1939_pgn_without_file_returns_reference_definition. Fixture: none.

Test Spec: Expanded J1939 Workflows¶

Document Control¶

Test Objectives¶

Coverage Requirements¶

Requirement Traceability¶

Representative Test Cases¶

TEST-J1939-01 — SPN reference lookup without a capture¶

TEST-J1939-02 — SPN observation extraction¶

TEST-J1939-03 — TP BAM session summary¶

TEST-J1939-04 — DM1 direct and transported parsing¶

TEST-J1939-05 — DM1 text output¶

TEST-J1939-06 — TP printable identification text¶

TEST-J1939-07 — TP text output surfaces printable identification text¶

TEST-J1939-08 — Inventory JSON output associates IDs with source addresses¶

TEST-J1939-09 — Inventory text output remains operator-friendly¶

TEST-J1939-10 — Compare JSON output highlights capture differences¶

TEST-J1939-11 — Compare text output remains operator-friendly¶

TEST-J1939-12 — Compare requires multiple captures¶

Fixtures And Environment¶

Explicit Non-Coverage¶

Traceability¶

TEST-J1939-13 — FMI catalog resolves fault-mode descriptions (REQ-J1939-20)¶

TEST-J1939-14 — OEM SPN overrides merge over the bundled catalog (REQ-J1939-20)¶

TEST-J1939-15 — SPN reference resolves an OEM SPN from a supplied DBC (REQ-J1939-06)¶

TEST-J1939-16 — Unknown SPN without catalog or DBC entry errors (REQ-J1939-08)¶

TEST-J1939-17 — PGN reference lookup without a capture (REQ-J1939-21)¶

`TEST-J1939-01` — SPN reference lookup without a capture¶

`TEST-J1939-02` — SPN observation extraction¶

`TEST-J1939-03` — TP BAM session summary¶

`TEST-J1939-04` — DM1 direct and transported parsing¶

`TEST-J1939-05` — DM1 text output¶

`TEST-J1939-06` — TP printable identification text¶

`TEST-J1939-07` — TP text output surfaces printable identification text¶

`TEST-J1939-08` — Inventory JSON output associates IDs with source addresses¶

`TEST-J1939-09` — Inventory text output remains operator-friendly¶

`TEST-J1939-10` — Compare JSON output highlights capture differences¶

`TEST-J1939-11` — Compare text output remains operator-friendly¶

`TEST-J1939-12` — Compare requires multiple captures¶

`TEST-J1939-13` — FMI catalog resolves fault-mode descriptions (`REQ-J1939-20`)¶

`TEST-J1939-14` — OEM SPN overrides merge over the bundled catalog (`REQ-J1939-20`)¶

`TEST-J1939-15` — SPN reference resolves an OEM SPN from a supplied DBC (`REQ-J1939-06`)¶

`TEST-J1939-16` — Unknown SPN without catalog or DBC entry errors (`REQ-J1939-08`)¶

`TEST-J1939-17` — PGN reference lookup without a capture (`REQ-J1939-21`)¶