testparity

Documentation

Overview

Package main is the matter.js test-porting register: which of matter.js's test files at the schema pin this module has ported to Go tests, which it has in part, which are still to do, and which it leaves out on purpose.

Three artefacts, one of them generated from the other two:

• matterjs_tests.json — the SNAPSHOT. Every *Test.ts under packages/node/test and packages/protocol/test of matter.js at the commit parity/schema.json names in matter.sourceCommit, with its line count, the SHA-1 of its blob and its top-level describe names. Written by `go run ./script/testparity -snapshot` (make testparity-snapshot) from a matter.js clone (MATTERJS_DIR, default ../matter.js) through git ls-tree and git cat-file only — never the clone's working tree. A pin lift regenerates it; its diff shows the test files upstream added, removed and changed.
• register.json — the REGISTER, maintained by hand, one entry per snapshot path.
• notes/parity/matterjs_tests.md — the PAGE, rendered from both by `go run ./script/testparity -render` (make testparity). Never edited by hand.

register.json

{
  "entries": [
    {
      "path":        "packages/protocol/test/…/FooTest.ts", // a snapshot path
      "status":      "ported" | "partial" | "planned" | "excluded",
      "go":          ["<module-relative package dir>:<TestFunc>", …],
                     // ported and partial only, at least one
      "missing":     ["<it name>", …], // partial only, at least one
      "class":       "controller-stage" | "js-runtime-only" | "joint-fabric" |
                     "device-ble-thread" | "test-infrastructure",
                     // excluded only, required there
      "until":       "<roadmap stage or milestone>",
                     // controller-stage (required) and device-ble-thread (optional)
      "reason":      "<one sentence>", // every entry
      "snapshotSha": "<40 hex>"       // the blob the mapping was checked against
    }
  ]
}

Entries are sorted by path. ported means the Go tests cover the file's it cases semantically; partial names the it cases they do not cover. The classes: controller-stage — controller behaviour this module does not have yet; js-runtime-only — tests of JavaScript runtime concerns (observables, environment, plugins, storage caches, the Reactor); joint-fabric — Joint Fabric, deferred; device-ble-thread — device-side BLE or Thread, out of scope until milestone 7; test-infrastructure — tests of matter.js's own test helpers.

The guard is register_test.go (make testparity-check): every snapshot path has an entry and every entry a path, every go reference resolves to a Test function in the named package's _test.go files, a ported or partial entry whose snapshotSha differs from the snapshot fails ("re-check the mapping"), an excluded one too ("re-check the exclusion": its reason may no longer hold), the committed page is what rendering produces, and the number of planned entries sits exactly on testparityPlannedRatchet. It needs no matter.js clone: the snapshot is committed.