@syncmatters/connector-sdk 1.0.18 → 1.0.20

package/docs/09-testing.md

@@ -34,6 +34,7 @@ export const objectFeatures = {
       matchRules: [{ rule: "email[ci]" }],
       canMatchFields: toJsonPaths(["id", "email", "name"]),
       relationshipsTo: [{ id: "companies-companyId", relObjectId: "companies" }],
+      key: { path: toJsonPath("id") }, // the query field whose value becomes row.meta.key
     },
     upsert: { canUpsert: true, key: { path: toJsonPath("id") }, canUpsertClean: true },
     delete: { canDelete: true, key: { path: toJsonPath("id") } },
@@ -72,7 +73,8 @@ export default class Test {
 
   // prepare hooks - create/arrange the data a given test needs, return what it should expect:
   // listPrepare, idsFilterPrepare, checkpointFilterStep1Prepare / Step2Prepare,
-  // matchFilterPrepare, relatedFilterPrepare, upsertPrepare
+  // matchFilterPrepare, relatedFilterPrepare, rowFiltersPrepare, upsertPrepare
+  // and, for what is not shaped like a feature, customChecks() (below)
 }
 ```
 
@@ -109,9 +111,14 @@ To disable those tests use `cannotTestReason` instead
 ([15-example-test-file.md](./15-example-test-file.md) shows the worked semantics):
 
 - `listPrepare` / `idsFilterPrepare` — arrange rows and return what the suite should expect.
-  (`rowFiltersPrepare` exists in the contract but the suite does NOT run rowFilter tests yet —
-  when `meta()` exposes `queryFilter.rowFilter`, cover it yourself with a direct query in a
-  hook you already implement.)
+- `rowFiltersPrepare` — one `RowFilterData { rowFilter, expectedRowIds, fields?, expect? }` per
+  case, for the filters `meta()` declares in `queryFilter.rowFilter`. The harness queries each
+  with its `rowFilter` (and `fields`), in order, and the rows must be exactly `expectedRowIds`;
+  the first case that fails decides the object's `rowFilter` status (`Row not returned`,
+  `Returned unexpected row`, or the `expect` failures below), details under `rowFilter`. Row
+  filters have no `ObjectFeatures` flag, so a suite without the hook (or one that returns
+  `undefined`) reads `Not tested` with the reason and the object is NOT made Partial; with
+  neither the hook nor declared row filters the status is `Not supported`.
 - `checkpointFilterStep1Prepare` / `Step2Prepare` — the two-step round-trip test of your
   differential contract; see [Checkpoint testing](#checkpoint-testing-what-the-two-steps-prove)
   below, it is the most-misimplemented pair.
@@ -132,6 +139,235 @@ To disable those tests use `cannotTestReason` instead
   checks a flag field instead of row absence, and `afterDeleteMaxIndexWaitTimeMs` tolerates
   APIs whose deletions surface asynchronously.
 
+## Expected values and errors: the `expect` clause
+
+The data every prepare hook returns (`ListData`, `IdsFilterData`, `CheckpointStep1Data`,
+`CheckpointStep2Data`, `MatchData`, `RelationshipData`, `RowFilterData`) takes an optional `expect`, for what a
+row-id comparison cannot prove: that a value comes back in the right form, or that a call fails
+the way it must.
+
+```js
+/** @type {SDKTest.ListData} */
+const listData = {
+  pageSize: 2,
+  expect: {
+    rows: {
+      // "*" applies to every row the list returns
+      "*": [
+        { path: toJsonPath("RowVer"), matches: "^[0-9a-f]{16}$" }, // rowversion as 16 hex chars
+        { path: toJsonPath("Guid"), matches: "^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$" },
+        { path: toJsonPath("Never_Set"), absent: true }, // a column the connector must not echo
+      ],
+      // a row's own meta.key: these win over "*" on the same path
+      [alphaKey]: [{ path: toJsonPath("Amount"), equals: 10.5 }],
+    },
+  },
+};
+
+/** @type {SDKTest.IdsFilterData} */
+const idsFilterData = {
+  id1: "not-a-number",
+  id2: "also-not",
+  // the connector must reject these ids; success is a failure of the test
+  expect: { error: { code: "SCRIPT_INVALID_INDEX_FILTER_VALUE", messagePattern: "not an integer" } },
+};
+```
+
+**`rows`** maps a row's `meta.key` (or `"*"` for every row) to assertions on `row.data` by path.
+Each assertion is one of:
+
+| Matcher                                  | Passes when                                                                                    |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `equals: value`                          | the value equals, compared per the field's declared type (below)                               |
+| `matches: "regex"`                       | the value (as a string) matches the regex source; for hex, GUIDs and formats                   |
+| `approx: { value, tolerance }`           | the value is a number within `tolerance` of `value`                                            |
+| `present: true`                          | the path is in the row and its value is not `null`                                             |
+| `absent: true`                           | the path is not in the row at all; a `null` value is present and fails                         |
+
+`equals` compares by the declared type of the field at the path in the object's
+`queryFields`:
+
+- `string` exactly (`"12"` does not equal `12`), `number` numerically (`"20.250"` equals
+  `20.25`, so a decimal's scale does not matter), `boolean` strictly, `object` and `array`
+  structurally (key order ignored, element order kept).
+- A date: a field with `constraints.dt`, or a `format` naming a date (`date`, `date-time`,
+  `datetime`, `iso8601`, `unix`, `unix_ms`, a `yyyy-MM-dd`-style pattern), compares as an
+  instant at the precision its format implies: days for date-only formats, seconds for
+  `unix` and `yyyy-MM-dd HH:mm:ss`, milliseconds otherwise. So `"2026-09-27T10:00:00+02:00"`
+  equals `"2026-09-27T08:00:00Z"`.
+- A path with no declared field compares structurally.
+
+The details say which comparison each assertion used (`number`, `instant (seconds)`,
+`structural (no declared field)`...).
+
+A keyed row that the query did not return is a mismatch. The list reads one page plus one row
+(`pageSize + 1`), so key only rows inside that read, or use `"*"`. If you pass `fields`, include
+the paths you assert on — except `absent` ones. The query only returns what it asked for.
+
+**`error`** makes the feature pass only when the operation throws, and throws like this: `code`
+must equal the error's `code` (a `ConnectorError`/`ScriptError` code), and `messagePattern` is a
+regex over its message. With neither, any error passes. The actual error — or, when the call
+succeeded, the rows it returned — is recorded in the details either way. What must fail:
+
+| Data                  | The operation `expect.error` applies to                                                         |
+| --------------------- | ----------------------------------------------------------------------------------------------- |
+| `ListData`            | the list query                                                                                  |
+| `IdsFilterData`       | one query for `[id1, id2]`, which replaces the usual three. `id1`/`id2` must come from the hook; the harness does not look up ids from a list for an expected error |
+| `CheckpointStep1Data` | the step 1 query. Step 2 is then skipped, since there is no emitted checkpoint                  |
+| `CheckpointStep2Data` | the step 2 query, from the checkpoint step 1 emitted                                            |
+| `MatchData`           | that match query                                                                                |
+| `RelationshipData`    | the related query (the 'from' row is still fetched by `idsFilter` and must exist)               |
+| `RowFilterData`       | that row-filter query                                                                           |
+
+`expectedRowIds` / `expectedMatchRowIds` / `expectedRelatedRowIds` may be empty when `error` is
+set.
+
+A timeout is the typical row-filter case: SQL Server's statement filter with a `WAITFOR` and a
+`requestTimeoutOverride` shorter than the wait must fail with the driver's timeout, not hang or
+return rows:
+
+```js
+/** @type {SDKTest.RowFilterData} */
+const timeoutCase = {
+  rowFilter: { where: { clause: "1 = 1; WAITFOR DELAY '00:00:05'" }, requestTimeoutOverride: 1000 },
+  expectedRowIds: [],
+  expect: { error: { code: "ETIMEOUT" } },
+};
+```
+
+**Upsert**: `UpsertData.expect` is `{ insert?, update? }`, each an assertion list for this
+data's own row as queried back after that phase. `upsertPrepare` runs once per row, and the
+row's key is only assigned by the insert, so there is nothing to key by. The asserted paths are
+added to the query-back's fields for you. `verifyFields` stays the shorthand for "what I wrote
+comes back". Use `expect` for what the test did NOT write: identity and computed columns,
+defaults, server timestamps, rowversions. For example, `update:
+[{ path: toJsonPath("RowVer"), matches: ... }]` checks a value the update moved. There is no
+`error` on upsert: `issueSimulators` already express an upsert that must fail. `update` is not
+run for `insertOnly` objects, and the delete test (which reuses `upsertPrepare`) ignores
+`expect`.
+
+Failures land in the feature's existing status and details:
+
+- **`Failed: Expected values did not match`**, with one error detail per assertion that did not
+  hold: the row key, the path, the expected form, the actual value and how they were
+  compared. Oversized values are truncated under the usual caps, not dropped.
+- **`Failed: Expected error did not occur`**, when the call succeeded or failed differently.
+
+Match rules and relationships report these on the rule or relationship result, and roll up as
+`One or more rules/filters have issues`.
+
+Compute expectations at prepare time from data your suite seeded (`before()` or the hook
+itself), never by reading the connector under test. Asserting a returned value's shape is also
+the right test of a type mapping: it proves the connector's behaviour, where a metadata check
+would only prove its declaration.
+
+## `query.key`: the rows' key is the field tagged as the key
+
+[04](./04-meta-objects-fields.md) makes `isKey` a contract: the tagged query field's value
+becomes `row.meta.key`, and exactly one query field carries `isKey` (or `isUserKey`). The
+generator declares that field as `query.key { path, expectUserKey? }`, found the same way as
+`upsert.key`. Regenerate `mod ObjectTestFeatures.mjs` to pick it up. A hand-authored spec can
+declare it too. When it is declared:
+
+- the **fieldMetadata** feature checks that the field at `path` is tagged `isKey` (`isUserKey`
+  when `expectUserKey`) and that no other query field carries either tag (`More than one query
+  field tagged with isKey or isUserKey`);
+- the **list** and **idsFilter** features check that every returned row's `meta.key` equals
+  `String()` of that field's value (for a user key, of its `value`). The first mismatch fails
+  the feature as `Failed: Expected values did not match`, with a detail that says it is the key
+  check (`key check (query.key, not a value assertion)`). A query that names its `fields` also
+  gets the key path added.
+
+This catches a connector that keys its rows on one column and tags another, which otherwise
+only a sync finds. A spec without `query.key` (anything generated before it existed) skips
+these checks.
+
+## Custom checks: `customChecks()`
+
+Some tests are not shaped like an object feature: a free statement with typed parameters,
+500 sequential statements to prove connections are released, a connection-level timeout, an API
+quirk. They go in `customChecks()`, which returns named checks the harness runs **after the
+feature tests, in declaration order**, each with its own status, duration and details:
+
+```js
+/** @type {SDKTest.TestFeatureProvider["customChecks"]} */
+async customChecks() {
+  return [
+    {
+      id: "exec-typed-parameters", // stable: keys the result and details, and is what --check names
+      name: "$Exec binds typed parameters",
+      objectId: "$Exec", // gated like a feature; omit for a connection-level check
+      timeoutMs: 30000, // default 60 000
+      run: async ({ connection, meta, record }) => {
+        const rows = await collect(connection.query["$Exec"]({ rowFilter: { statement: "SELECT @p0 AS v", parameters: [{ name: "p0", sqlType: "int", value: 42 }] } }));
+        record("returned", { rows }); // a detail on the check, under the usual caps
+        if (rows[0]?.data.v !== 42) throw new Error(`expected 42, got ${rows[0]?.data.v}`);
+      },
+    },
+  ];
+}
+```
+
+- **Status**: `Passed`, `Failed: <message>` (the first line of what `run` threw; the full error
+  is kept as the check's `fatalError`), or `Not tested` with `notTestedReason`. Results are
+  `CustomCheckResult { id, name, status, notTestedReason?, durationMs, fatalError? }`, on the
+  object's result for a check with an `objectId` and on the run's for one without.
+- **Details**: `record(message, data)` adds a detail under `details["check:<id>"]`; the harness
+  adds one saying how the check ended. Same caps and ~48-hour retention as every feature's.
+- **Selection**: a check with an `objectId` whose object is not on the connection (not selected
+  on a two-phase connection, or not returned by `meta()`) reads `Not tested` with the reason —
+  it does not fail. The object need not be one of `objectIds()`; if it is, the harness's object
+  check fails the run first, as it does for any tested object. A check without an `objectId` is
+  connection-level and always runs. `ctx.meta` is the check object's metadata.
+- **Timeout**: `timeoutMs` (default 60 000) is capped at the run's remaining budget when the run
+  has one. A check still running at its timeout fails (`Failed: Timed out after <n>ms`), what it
+  records afterwards is dropped, and the next check runs.
+- **Roll-up**: a failed check fails its object and the run; a check not tested makes a Passed
+  object Partial and keeps a run that would pass at `Partial: Not all features/objects can be
+  tested`.
+- **Which checks a run reaches**: all of them on a full run; with `--object`, the
+  connection-level checks plus the selected objects'; none with `--only
+  connection|meta|discover|query`; exactly the named ones with `--check <id>` (repeatable),
+  whatever else the run tests. An id the suite does not declare fails as `No such check in the
+  test suite`.
+
+A check is the escape hatch, not the default. If the same check turns up in a second connector,
+it belongs in the harness as a feature; and a value assertion on rows a feature already fetches
+belongs in that feature's `expect`, where it reports on the feature.
+
+## Fixtures on two-phase connections: fixed names, seeded in `before()`
+
+A two-phase test connection collects only the objects it selected. So a fixture object — a
+sandbox table, a custom object — must exist before discovery and be selected before the run.
+**`before()` seeds rows, never objects.** Creating a table in `before()` cannot work: the run's
+refresh covers only the selection, and the harness checks every object to test against the
+connection right after it.
+
+The procedure:
+
+1. Create the fixtures once, with fixed names (the SQLServer suite's `dbo.sm_test_*` pattern).
+2. Run `sm connector test --only discover`.
+3. Select the fixtures on the test connection.
+4. Run the suite.
+
+A create-a-fresh-table-per-run pattern (`SMTST<random>`) cannot be ported to the harness.
+
+`before()` already has the connection and runs before the harness's own object check. A suite
+that wants a clearer message than "objects not on the connection" checks its own fixtures
+there:
+
+```js
+async before({ connection }) {
+  const missing = FIXTURES.filter((id) => !connection.objectIds.includes(id));
+  if (missing.length > 0) {
+    throw new Error(`fixtures not on the connection: ${missing.join(", ")} - create them, run --only discover, select them, run again`);
+  }
+}
+```
+
+A thrown `before()` is the run's fatal error, message included, so this fails the run before
+any feature runs.
+
 ## Checkpoint testing: what the two steps prove
 
 The checkpoint contract is a ROUND-TRIP ([05](./05-query.md)): the platform stores whatever
@@ -242,25 +478,31 @@ The harness always executes platform-side. What each entry point actually runs:
 
 | Command                      | What runs                                                                                      |
 | ---------------------------- | ----------------------------------------------------------------------------------------------- |
-| `sm test`                    | The FULL suite — `connection.test()` + `metaRefresh()` + every object feature above. Identical to the web UI's connector test. |
-| `sm test --only connection`  | `connection.test()` only — credentials check, nothing else. The harness has NOT run.            |
-| `sm test --only meta`        | `connection.metaRefresh()` only — for a connection with a selection, that is `meta()` over the selected objects. |
-| `sm test --only discover`    | `connection.discover()` only (two-phase connectors) — reports the catalogue size, which settings it returned overrides for, and how long it took, then refreshes the selection and checks every selected object is in the catalogue. |
-| `sm test --only query`       | Every object's plain list query only — no ids/checkpoint/match/related, no writes.              |
+| `sm connector test`                    | The FULL suite — `connection.test()` + `metaRefresh()` + every object feature above + every custom check. Identical to the web UI's connector test. |
+| `sm connector test --only connection`  | `connection.test()` only — credentials check, nothing else. The harness has NOT run.            |
+| `sm connector test --only meta`        | `connection.metaRefresh()` only — for a connection with a selection, that is `meta()` over the selected objects. |
+| `sm connector test --only discover`    | `connection.discover()` only (two-phase connectors) — reports the catalogue size, which settings it returned overrides for, and how long it took, then refreshes the selection and checks every selected object is in the catalogue. |
+| `sm connector test --only query`       | Every object's plain list query only — no ids/checkpoint/match/related, no writes, no custom checks. |
+| `sm connector test --object <id>`      | The full suite for the named object(s), plus the connection-level custom checks and those object(s)' checks. |
+| `sm connector test --check <id>`       | Only the named custom check(s) (repeat the flag); no object features unless `--object` is given too. The fast loop for one failing check. |
 | Web UI (connector → test results → run) | Same engine, feature selection via the run dialog.                                   |
 
+(The old short name `sm test` now prints the replacement and exits 2.)
+
 Each feature test records the inputs it ran with and what the connector returned — pass or
 fail — onto the saved result as diagnostic `details` (the ids an `idsFilter` ran with and the
-rows returned; expected vs actual rows per match rule / relationship; upserted rows and their
-query-back). Review them on the web UI's test results screen instead of re-running with extra
+rows returned; expected vs actual rows per match rule / relationship / row filter; upserted rows
+and their query-back; what each custom check recorded). The web UI shows custom checks in a
+"Custom checks" table under each object and under the connection, and `sm connector test`
+prints one line per check after the object lines. Review them on the web UI's test results screen instead of re-running with extra
 logging. Payloads over the size budget are dropped and flagged `truncated`; details hold real
 connection data and are scrubbed ~48 hours after the run (statuses are kept).
 
 Do not mistake a passing `--only connection` or `--only query` for suite coverage — only the
-full run exercises the prepare hooks and write features. `sm test` needs a developer token
+full run exercises the prepare hooks and write features. `sm connector test` needs a developer token
 with the `scripts:read`, `connections:read` and `scripts:execute` scopes; a 403 from the CLI
 names the missing one. The dev loop around it: `sm validate` (workspace structure), `checkJs`
-type checking against the SDK types, `sm push`, then `sm test`. Keep `test()` cheap and
+type checking against the SDK types, `sm push`, then `sm connector test`. Keep `test()` cheap and
 `meta()` deterministic so the suite stays fast.
 
 Three workspace facts that bite here:
@@ -278,8 +520,79 @@ Three workspace facts that bite here:
   `sm connector features` (or the web UI's feature-generate action) after `meta()` changes;
   new relationships/match rules will NOT be tested until you do, because the generated
   `relationshipsTo`/`matchRules` spec still reflects the old metadata. The loop is:
-  edit `meta()` → `sm push` → `sm connector features` → `sm test`.
+  edit `meta()` → `sm push` → `sm connector features` → `sm connector test`.
 - The typed test connection (the `API.connections.<connection_name>.Connection` `@typedef` in
   the `mod Test.mjs` example above) resolves from **generated** typings:
   `types/connections/*.d.ts` in a CLI workspace (`sm types` refreshes them; `sm pull` runs it
   automatically) — never hand-write these.
+
+## Migrating an old test module to `mod Test.mjs`
+
+Many connectors still carry a second suite in `files/Scripts/Tests/mod <Conn>.mjs`, run by the
+loop in `_tst Connector.mjs`: every `test*` method is called, logged as Success or Fail, and the
+run throws at the end. The harness replaces it. Port each method to the first of these that
+fits, and delete the old module and its `_tst` entry when the last method has moved:
+
+1. **An existing feature.** Most methods (list, by id, by ids, by last-modified, match rules,
+   related rows, insert/update, the `test_*_metadata` methods) are already what the harness
+   tests. Port them as prepare data (`listPrepare`, `idsFilterPrepare`, ...), not as checks;
+   metadata methods are covered by the generated spec and the `fieldMetadata` feature.
+2. **An `expect` clause.** A method that checks a returned value's form (a rowversion as hex, a
+   GUID, a decimal's value, a column that must not be echoed) or a call that must fail (a
+   timeout, a rejected id, a `*_not_exist` query) becomes `expect.rows` or `expect.error` on the
+   feature data that makes that call.
+3. **A custom check**, for what is left: a method that is not shaped like a feature.
+
+Porting a method to a custom check:
+
+```js
+// old: files/Scripts/Tests/mod SQLServer v2.mjs
+async testExec() {
+  const rows = await collect(this.conn.query["$Exec"]({ rowFilter: { statement: "SELECT 1 AS one" } }));
+  if (rows[0].data.one !== 1) throw new Error("exec did not return 1");
+  this.log.info("exec ok");
+}
+
+// new: in mod Test.mjs
+async customChecks() {
+  return [
+    {
+      id: "exec",
+      name: "$Exec returns a statement's rows",
+      objectId: "$Exec",
+      run: async ({ connection, record }) => {
+        const rows = await collect(connection.query["$Exec"]({ rowFilter: { statement: "SELECT 1 AS one" } }));
+        record("returned", { rows });
+        if (rows[0]?.data.one !== 1) throw new Error(`exec returned ${JSON.stringify(rows[0]?.data)}`);
+      },
+    },
+  ];
+}
+```
+
+- The method body moves into `run`; `this.conn` becomes `ctx.connection` (or the suite's own
+  typed connection from `before()`), `this.log.info` of what you want to review later becomes
+  `ctx.record`, and the `throw` stays: throwing is how a check fails.
+- Give it a stable `id` (the old method name without `test` is a good one) and, when it
+  exercises one object, that `objectId`, so an unselected object reads Not tested instead of
+  failing.
+- `onlyTest*` / `skipTest*` renames are gone: `--check <id>` runs one check, and a check that
+  must not run is deleted or given a reason in its own code, not renamed.
+- A method that loops or times (500 sequential statements, a large read) keeps its loop; put
+  the timing in `record`, not in a pass/fail threshold, and set `timeoutMs` above what it needs.
+- Setup the old module did in its constructor or `before()` moves to the suite's `before()`,
+  which runs once for features and checks alike. **Seed rows there, never objects**.
+
+What cannot be ported:
+
+- **Creating a table, custom object or other schema per test** (the `SMTST<random>` pattern).
+  A two-phase test connection only collects the objects it selected, so an object made during
+  the run is never on it. Use a fixed fixture instead ([above](#fixtures-on-two-phase-connections-fixed-names-seeded-in-before)):
+  create it once with a fixed name, discover, select it, and let the check or feature seed rows.
+  Tests that only prove "a table can be created" go.
+- **Anything whose pass/fail is a timing threshold.** A threshold needs a per-environment budget
+  the harness does not have; record the timing as a detail instead.
+- **Methods that depend on another method having run first.** Checks run in declaration order,
+  but each must stand alone (a `--check` run may run only one); share state through `before()`.
+- **Platform tests** (`mod ScriptAPI`, `Storage`, `Webhook`, `Drives`, ...) are not connector
+  tests and stay where they are, with `_tst Main.mjs`.

package/docs/15-example-test-file.md

@@ -2,7 +2,7 @@
 
 The test-file counterpart to [12-example-connector.md](./12-example-connector.md): the complete
 `mod Test.mjs` + `mod ObjectTestFeatures.mjs` pair for the Acme connector, on one page. The
-platform's connector test suite AND the CLI's `sm test` both require a file of sidecar
+platform's connector test suite AND the CLI's `sm connector test` both require a file of sidecar
 type `"connectortest"` in the connector's folder — **a connector without one cannot be
 run-tested at all**. Harness conventions and hook semantics live in
 [09-testing.md](./09-testing.md); this page shows them applied end to end against Acme's three
@@ -39,7 +39,7 @@ generated module via `module_script_file_paths`:
 }
 ```
 
-Keep exactly one `"connectortest"` file per connector folder — `sm test` resolves the test
+Keep exactly one `"connectortest"` file per connector folder — `sm connector test` resolves the test
 module from the folder beside the connector's entry file, and several candidates are ambiguous
 (`<Name>.test.mjs` wins when present).
 
@@ -71,7 +71,10 @@ export const objectFeatures = {
       idsFilter: true,
       checkpointFilter: true,
       matchRules: [{"rule":"id"},{"rule":"name[ci]"}],
-      canMatchFields: toJsonPaths(["id", "name", "domain"])
+      canMatchFields: toJsonPaths(["id", "name", "domain"]),
+      key: {
+        path: toJsonPath("id")
+      }
     },
     upsert: {
       canUpsert: true,
@@ -94,7 +97,10 @@ export const objectFeatures = {
       checkpointFilter: true,
       matchRules: [{"rule":"id"},{"rule":"email[ci]"},{"rule":"first_and_last_name[ci]"}],
       canMatchFields: toJsonPaths(["id", "email", "first_name", "last_name"]),
-      relationshipsTo: [{"id":"companies-company_id","relObjectId":"companies"}]
+      relationshipsTo: [{"id":"companies-company_id","relObjectId":"companies"}],
+      key: {
+        path: toJsonPath("id")
+      }
     },
     upsert: {
       canUpsert: true,
@@ -114,7 +120,10 @@ export const objectFeatures = {
   salesorders: {
     query: {
       list: true,
-      idsFilter: true
+      idsFilter: true,
+      key: {
+        path: toJsonPath("$compositeKey")
+      }
     },
     upsert: {
       canUpsert: true,
@@ -171,6 +180,8 @@ export default class TestFeatureProvider {
   #connection;
   /** @type string */
   #fixtureCompanyId = ""; // shared parent row for contact test data
+  /** @type string */
+  #fixtureVendorId = ""; // the sandbox's one vendor company, for the companyType row filter
 
   /** @type SDKTest.TestFeatureProvider["before"] */
   async before(ctx) {
@@ -204,6 +215,10 @@ export default class TestFeatureProvider {
     const company = await this.#connection.queryOne.companies();
     if (!company) throw new Error("Sandbox has no companies - seed at least one before testing");
     this.#fixtureCompanyId = company.meta.key;
+    for await (const row of this.#connection.query.companies()) {
+      if (row.data.name === "sm_fixture Vendor") this.#fixtureVendorId = row.meta.key;
+    }
+    if (!this.#fixtureVendorId) throw new Error("Sandbox fixture 'sm_fixture Vendor' is missing - create it once as a vendor");
   }
 
   /** @type SDKTest.TestFeatureProvider["after"] */
@@ -227,7 +242,17 @@ export default class TestFeatureProvider {
     // a small pageSize forces real pagination through Acme's cursor (05)
     switch (options.meta.id) {
       case "salesorders":
-        return { pageSize: 25, fields: [[{ path: "$compositeKey" }], [{ path: "status" }]] };
+        return {
+          pageSize: 25,
+          fields: [[{ path: "$compositeKey" }], [{ path: "status" }]],
+          // expected values (09): "*" asserts on every row the list returns - here the key
+          // encoding (11), sorted JSON with the parent part first. No row-id bookkeeping needed.
+          expect: {
+            rows: {
+              "*": [{ path: [{ path: "$compositeKey" }], matches: '^\\{"business_unit":".+","order_id":\\d+\\}$' }],
+            },
+          },
+        };
       default:
         return { pageSize: 25 };
     }
@@ -407,6 +432,14 @@ export default class TestFeatureProvider {
         // the payload it just sent - so every verify field must be present (non-null) in
         // BOTH insert and update, and the update should carry a CHANGED value (09)
         result.verifyFields.push([{ path: "domain" }]);
+        // ...and expect covers what the test did NOT write: Acme assigns id and created_at.
+        // The row's key is unknown until the insert, so these name the phase, not a key (09)
+        result.expect = {
+          insert: [
+            { path: [{ path: "id" }], matches: "^\\d+$" },
+            { path: [{ path: "created_at" }], present: true },
+          ],
+        };
         break;
       }
       case "contacts": {
@@ -467,6 +500,57 @@ export default class TestFeatureProvider {
     await this.#deleteRows(options.meta.id, options.inserted.map((r) => r.meta.key));
   }
 
+  /** @type SDKTest.TestFeatureProvider["rowFiltersPrepare"] */
+  async rowFiltersPrepare(options) {
+    // companies declares one row filter, companyType (12). Acme's API cannot set a company's
+    // type, so the sandbox holds a fixed fixture instead: exactly one vendor, named
+    // "sm_fixture Vendor", created once and never touched by the suite (the fixed-fixture rule, 09).
+    // before() looked its key up; every other sandbox company is a customer.
+    if (options.meta.id !== "companies") return undefined;
+    return [
+      {
+        rowFilter: { companyType: "vendor" },
+        expectedRowIds: [this.#fixtureVendorId],
+        expect: { rows: { "*": [{ path: [{ path: "name" }], equals: "sm_fixture Vendor" }] } },
+      },
+    ];
+  }
+
+  /** @type SDKTest.TestFeatureProvider["customChecks"] */
+  async customChecks() {
+    // what is not shaped like an object feature; each check reports its own status (09)
+    return [
+      {
+        // connection-level (no objectId): always runs
+        id: "sequential-tests",
+        name: "20 sequential test() calls all succeed",
+        run: async ({ record }) => {
+          const started = Date.now();
+          for (let i = 0; i < 20; i++) {
+            const result = await this.#connection.test();
+            if (!result.success) throw new Error(`test() call ${i + 1} failed: ${result.message}`);
+          }
+          record("20 test() calls", { durationMs: Date.now() - started }); // timing is a detail, not a threshold
+        },
+      },
+      {
+        // object-level: reads Not tested, not Failed, if contacts is not selected on the connection
+        id: "contacts-page-walk",
+        name: "Listing three pages of contacts returns no duplicate keys",
+        objectId: "contacts",
+        timeoutMs: 120000,
+        run: async ({ record }) => {
+          const seen = new Set();
+          for await (const row of this.#connection.query.contacts({ limit: 300 })) {
+            if (seen.has(row.meta.key)) throw new Error(`key ${row.meta.key} returned twice`);
+            seen.add(row.meta.key);
+          }
+          record(`${seen.size} distinct contacts`);
+        },
+      },
+    ];
+  }
+
   // === private helpers ======================================================
 
   /** Create one prefixed row; creating counts as a modification for checkpoint tests.
@@ -543,9 +627,26 @@ Nothing in this pair changes when a connector gains `discover()`
 regenerates `mod ObjectTestFeatures.mjs` without it — it warns about the catalogue entries the
 connection did not select, so read that output rather than assuming a shrunken generated file is
 the connector's doing. Widen the test connection's selection rather than scoping the object out;
-`sm test --only discover` ([09](./09-testing.md#running-the-suite)) checks the catalogue against
+`sm connector test --only discover` ([09](./09-testing.md#running-the-suite)) checks the catalogue against
 the selection and prints what is missing.
 
+The same rule applies to fixture objects a suite owns, such as a sandbox table or a custom
+object. Create them once with fixed names, discover, select them, and have `before()` seed rows
+only, never objects ([09](./09-testing.md#fixtures-on-two-phase-connections-fixed-names-seeded-in-before)).
+A suite that wants its own message checks the fixtures first:
+
+```js
+const FIXTURES = ["companies", "contacts", "salesorders"];
+
+async before({ connection }) {
+  const missing = FIXTURES.filter((id) => !connection.objectIds.includes(id));
+  if (missing.length > 0) {
+    throw new Error(`fixtures not on the connection: ${missing.join(", ")} - create them, run --only discover, select them, run again`);
+  }
+  // ...then seed rows as above
+}
+```
+
 ## What to notice (the parts assistants most often get wrong)
 
 1. **Every created record is prefixed** (`sm_test`) and `before()`/`after()` sweep the
@@ -581,3 +682,20 @@ the selection and prints what is missing.
    the differential window into `expectedRowIds` before seeding one guaranteed change, and
    step 2 expects step-1 rows to reappear because the connector's checkpoint deliberately
    overlaps (05, 12).
+9. **Row ids prove which rows came back; `expect` proves what is in them.** Value fidelity
+   (a key encoding, a server-assigned id or timestamp, a column that must not be echoed) goes
+   in the prepare data's `expect` clause, computed from data the suite seeded. A call that must
+   fail (ids the API rejects, an invalid checkpoint) is `expect.error` on that feature's data.
+   `equals` compares by the field's declared type, and a date compares as an instant (09).
+10. **`query.key` is generated, like `upsert.key`.** It names the field whose value IS
+   `row.meta.key`, and the list and idsFilter tests check every row against it. If the
+   generated file lacks it, it predates the check: regenerate.
+11. **Row filters are tested from a fixed fixture.** `rowFiltersPrepare` has to name the exact
+   rows a filter returns, so it needs a sandbox whose answer it knows: here one vendor company
+   created once and looked up in `before()`, never created by the run. Without the hook
+   companies' row filter reads `Not tested`, which does not make the object Partial.
+12. **Custom checks are for what no feature expresses**, and each reports on its own:
+   `sequential-tests` on the connection, `contacts-page-walk` under contacts (Not tested, not
+   Failed, if contacts is not selected). Throwing fails a check; `record` puts what you want to
+   review later on the result; timings are details, never thresholds. Rerun one with
+   `sm connector test Acme --check contacts-page-walk`.

package/docs/connector-authoring.md

@@ -28,13 +28,13 @@ queryable.
 | [06-upsert-delete.md](./06-upsert-delete.md)                     | implementing `upsert()`, `delete()`, `upsertClean()`, `upsertFieldOptions()`, batching                          |
 | [07-events-webhooks.md](./07-events-webhooks.md)                 | webhooks: `parseEvents()`, signature verification (and the usually-skipped `handleParsedEvent()`)               |
 | [08-errors.md](./08-errors.md)                                   | error handling — `ConnectorError`, `ErrorCode` selection, `HttpError`                                           |
-| [09-testing.md](./09-testing.md)                                 | the test harness: `mod Test.mjs` + `mod ObjectTestFeatures.mjs`                                                 |
+| [09-testing.md](./09-testing.md)                                 | the test harness: `mod Test.mjs` + `mod ObjectTestFeatures.mjs`, expected values/errors (`expect`), `query.key`, fixtures |
 | [10-style-and-pitfalls.md](./10-style-and-pitfalls.md)           | style rules, deprecated APIs to avoid, known traps — skim this once regardless                                  |
 | [11-composite-keys.md](./11-composite-keys.md)                   | objects with multi-part identity (child REST resources, junction rows) — key encoding across query/upsert/delete |
 | [12-example-connector.md](./12-example-connector.md)             | **the canonical worked connector** — a complete three-object connector (relationships, matching, composite keys, custom fields, upsertClean, query/upsert/delete) on one page; its test-file counterpart is 15 |
 | [13-file-fields.md](./13-file-fields.md)                         | objects carrying file content — fields of `type: "file"`, FileProvider, fields-driven inclusion (do NOT copy the fleet's legacy `row.file`) |
 | [14-vendor-sdks-and-non-http.md](./14-vendor-sdks-and-non-http.md) | vendor npm SDKs (googleapis, AWS, box), database/on-prem `agent_mode: "always"` connectors, SOAP/XML, self-managed rate limiting |
-| [15-example-test-file.md](./15-example-test-file.md)             | **the canonical worked test file** — the complete `mod Test.mjs` + `mod ObjectTestFeatures.mjs` pair for the Acme connector of 12 (TestFeatureProvider, prepare/cleanup hooks, issue simulators, feature scoping) |
+| [15-example-test-file.md](./15-example-test-file.md)             | **the canonical worked test file** — the complete `mod Test.mjs` + `mod ObjectTestFeatures.mjs` pair for the Acme connector of 12 (TestFeatureProvider, prepare/cleanup hooks, issue simulators, expected values, feature scoping) |
 | [16-the-end-game-syncs.md](./16-the-end-game-syncs.md)           | **why any of this exists** — how the sync pipeline consumes each connector capability, and what silently degrades when one is missing. Read once before designing `meta()` |
 | [17-user-help-pages.md](./17-user-help-pages.md)                 | writing the connector's customer help pages — they ship IN the connector (`Connectors/<Name>/help/*.md`, sidecar type `"markdown"`); the house structure, frontmatter, and example conventions |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/connector-sdk",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "TypeScript type definitions for the SyncMatters connector SDK (types only - connectors execute on the SyncMatters platform)",
   "types": "./index.d.ts",
   "exports": {
@@ -12,9 +12,9 @@
   "license": "MIT",
   "author": "SyncMatters",
   "homepage": "https://syncmatters.com",
-  "typesContentHash": "2d30d816e8bb71a9fe2d9390945f4aa62c8eff1f4f86e69ec8f965e8a42cd6c8",
+  "typesContentHash": "376c97b772af51a69f5155aff7c80362062a74710e0672b3dd0582679b5cfffb",
   "dependencies": {
     "@types/node": "*",
-    "@syncmatters/script-api": "^1.0.19"
+    "@syncmatters/script-api": "^1.0.21"
   }
 }