spec-tests

Cross-language golden fixture suite for the BitChat SDKs.

The BitChat protocol has implementations in Swift, Kotlin (Android), TypeScript (Node), and Python. Each one ships its own encoder/decoder for the same wire format. This repo holds canonical encoded fixtures so every implementation can be verified byte-for-byte against the same set of vectors.

Layout

fixtures/
  broadcast_message_v1.json   # v1 binary packets, no recipient
  directed_message_v1.json    # v1 binary packets with HasRecipient flag
  malformed_packets.json      # malformed bytes; should_decode=false
  announcement_packet.json    # AnnouncementPacket TLV vectors
  private_message_tlv.json    # PrivateMessagePacket TLV vectors
scripts/
  generate.py                 # regenerator (uses bitchat-protocol from PyPI)

Schema

Each fixture file is a JSON array of entries:

{
  "id": "bcast-v1-message-ascii",
  "description": "v1 broadcast Message, short ASCII payload, no flags",
  "type": "broadcast_message_v1",       // or directed_message_v1 / malformed / announcement / private_message_tlv
  "should_decode": true,                 // true → decode succeeds; false → decoder returns null/None
  "no_roundtrip": false,                 // optional; true skips the re-encode equality check
  "encoded_hex": "01020700000001...",    // hex-encoded wire bytes (canonical)
  "tlv_input": { ... }                   // present for TLV-only fixtures; signals TLV decoder dispatch
}

encoded_hex is the wire bytes the decoder should accept (or reject, if should_decode=false). For should_decode=true entries, the test harnesses also re-encode the decoded value and assert the bytes match encoded_hex, unless no_roundtrip is set. Empty encoded_hex is treated as illustrative-only and skipped.

For TLV-only fixture types (announcement, private_message_tlv), the harness inspects tlv_input presence to dispatch to decodeAnnouncement / decodePrivateMessage (rather than the binary-packet decoder).

How implementations consume these

Each SDK's test harness expects this repo cloned as a sibling of the SDK repo:

your-workspace/
  spec-tests/                 # this repo
  protocol-core-js/           # bitchat-sdk/protocol-core-js
  protocol-core-py/           # bitchat-sdk/protocol-core-py
  ...

Test harnesses then load fixtures from ../spec-tests/fixtures/*.json (relative to each SDK).

• JS: bitchat-js-protocol-core/src/tests/fixtures.test.ts — runs as part of npm test
• Python: bitchat-python-protocol/tests/test_fixtures.py — runs as part of pytest

If spec-tests/ is not present, both harnesses silently skip all fixture tests.

Regenerating

The Python SDK (bitchat-protocol on PyPI) is currently the canonical encoder. Re-run the generator after any wire-format change:

pip install bitchat-protocol
python3 scripts/generate.py

The generator is deterministic — same inputs produce byte-identical fixtures. Timestamps and peer IDs are pinned to fixed values for reproducibility.

After regenerating, run all four SDKs' fixture tests to catch implementations that drift from the canonical bytes.

License

Unlicense — public domain.