@syncmatters/connector-sdk 1.0.18 → 1.0.19

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") } },
@@ -111,7 +112,8 @@ To disable those tests use `cannotTestReason` instead
 - `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.)
+  hook you already implement. `RowFilterData` accepts an `expect` clause like every other
+  feature's data, but it is not evaluated until the row-filter feature ships.)
 - `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 +134,168 @@ 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`) 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)               |
+
+`expectedRowIds` / `expectedMatchRowIds` / `expectedRelatedRowIds` may be empty when `error` is
+set.
+
+**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.
+
+## 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 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

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

@@ -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,
@@ -227,7 +236,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 +426,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": {
@@ -546,6 +573,23 @@ the connector's doing. Widen the test connection's selection rather than scoping
 `sm 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 +625,11 @@ 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.

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.19",
   "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": "acd8d8f87e1b337a1deddca006f59a875fd740b920d602ed59b3a3775a862332",
   "dependencies": {
     "@types/node": "*",
-    "@syncmatters/script-api": "^1.0.19"
+    "@syncmatters/script-api": "^1.0.20"
   }
 }