@syncmatters/script-api 1.0.19 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/script-api",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "description": "TypeScript type definitions for the SyncMatters script API (types only - scripts execute on the SyncMatters platform)",
   "types": "./index.d.ts",
   "exports": {
@@ -28,7 +28,7 @@
   "license": "MIT",
   "author": "SyncMatters",
   "homepage": "https://syncmatters.com",
-  "typesContentHash": "c99cda04200f9c6c8b5d28f7433f84607e3b6ddab34d4ca5ae6ce081effbf310",
+  "typesContentHash": "6f0e7724c2cff15e666109cc05b76419887b64ffa0310e9ec23fe2b585a323e5",
   "dependencies": {
     "@types/node": "*"
   }

package/sdk-test/sdk-test.d.ts

@@ -130,6 +130,17 @@ export interface ObjectFeatures {
         relationshipsToSameAsObjectId?: string;
         /** This option is as-per the object level cannotTestReason, however applied to all relationship operations */
         relationshipsToCannotTestReason?: string;
+        /**
+         * The query field whose value becomes row.meta.key (generated like upsert.key). When declared, the fieldMetadata
+         * feature checks that the field is tagged isKey (isUserKey when expectUserKey) and that no other query field is, and
+         * the list and idsFilter features check that every returned row's meta.key equals the string form of its value.
+         */
+        key?: {
+            /** Path to the key in query fields */
+            path?: API.JsonValuePath;
+            /** Is the key field tagged isUserKey (a user supplied key) rather than isKey? */
+            expectUserKey?: boolean;
+        };
     };
     upsert?: {
         /** This option is as-per the object level sameAsObjectId, however applied at the upsert operation */
@@ -219,15 +230,15 @@ export interface ObjectTestResult {
     fatalError?: CaughtError;
     notTestedSameAsObjectId?: string;
     notTestedReason?: string;
-    list?: "Passed" | "Passed: Limited test data, pagination not tested" | "Not tested" | "Not supported" | "Failed: 'Same as object' not tested" | "Failed: Object metadata supports list, test spec does not" | "Failed: Test spec supports list, object metadata does not" | "Failed: Fatal error during testing" | "Failed: No test data";
+    list?: "Passed" | "Passed: Limited test data, pagination not tested" | "Not tested" | "Not supported" | "Failed: 'Same as object' not tested" | "Failed: Object metadata supports list, test spec does not" | "Failed: Test spec supports list, object metadata does not" | "Failed: Fatal error during testing" | "Failed: No test data" | "Failed: Expected values did not match" | "Failed: Expected error did not occur";
     listNotTestedSameAsObjectId?: string;
     listNotTestedReason?: string;
     listFatalError?: CaughtError;
-    idsFilter?: "Passed" | "Not tested" | "Not supported" | "Failed: 'Same as object' not tested" | "Failed: Object metadata supports idsFilter, test spec does not" | "Failed: Test spec supports idsFilter, object metadata does not" | "Failed: Fatal error during testing" | "Failed: No test data" | "Failed: Returned unexpected row" | "Failed: Row not returned" | "Failed: More rows returned than expected";
+    idsFilter?: "Passed" | "Not tested" | "Not supported" | "Failed: 'Same as object' not tested" | "Failed: Object metadata supports idsFilter, test spec does not" | "Failed: Test spec supports idsFilter, object metadata does not" | "Failed: Fatal error during testing" | "Failed: No test data" | "Failed: Returned unexpected row" | "Failed: Row not returned" | "Failed: More rows returned than expected" | "Failed: Expected values did not match" | "Failed: Expected error did not occur";
     idsFilterNotTestedSameAsObjectId?: string;
     idsFilterNotTestedReason?: string;
     idsFilterFatalError?: CaughtError;
-    checkpointFilter?: "Passed" | "Not tested" | "Not supported" | "Failed: 'Same as object' not tested" | "Failed: Object metadata supports checkpointFilter, test spec does not" | "Failed: Test spec supports checkpointFilter, object metadata does not" | "Failed: Fatal error during testing" | "Failed: No test data for step 1" | "Failed: No test data for step 2" | "Failed: Returned unexpected row for step 1" | "Failed: Returned unexpected row for step 2" | "Failed: Row not returned for step 1" | "Failed: Row not returned for step 2" | "Failed: Next checkpoint not returned";
+    checkpointFilter?: "Passed" | "Not tested" | "Not supported" | "Failed: 'Same as object' not tested" | "Failed: Object metadata supports checkpointFilter, test spec does not" | "Failed: Test spec supports checkpointFilter, object metadata does not" | "Failed: Fatal error during testing" | "Failed: No test data for step 1" | "Failed: No test data for step 2" | "Failed: Returned unexpected row for step 1" | "Failed: Returned unexpected row for step 2" | "Failed: Row not returned for step 1" | "Failed: Row not returned for step 2" | "Failed: Next checkpoint not returned" | "Failed: Expected values did not match" | "Failed: Expected error did not occur";
     checkpointFilterNotTestedSameAsObjectId?: string;
     checkpointFilterNotTestedReason?: string;
     checkpointFilterFatalError?: CaughtError;
@@ -240,7 +251,7 @@ export interface ObjectTestResult {
     matchFilterNotTestedReason?: string;
     matchFieldCount?: number;
     matchFilterResults?: MatchRuleTestResult[];
-    upsert?: "Passed" | "Passed (insert only)" | "Not tested" | "Not supported" | "Failed: 'Same as object' not tested" | "Failed: Feature has no test spec" | "Failed: Fatal error during testing" | "Failed: Test spec does not define key field" | "Failed: No test data for insert" | "Failed: No test data for update" | "Failed: No verifyField included with test data" | "Failed: query after insert did not return expected rows" | "Failed: No key path to test update" | "Failed: update returned unexpected row" | "Failed: verifyField value on the upsert row was blank" | "Failed: verifyField value on the queried row does not match the upsert value";
+    upsert?: "Passed" | "Passed (insert only)" | "Not tested" | "Not supported" | "Failed: 'Same as object' not tested" | "Failed: Feature has no test spec" | "Failed: Fatal error during testing" | "Failed: Test spec does not define key field" | "Failed: No test data for insert" | "Failed: No test data for update" | "Failed: No verifyField included with test data" | "Failed: query after insert did not return expected rows" | "Failed: No key path to test update" | "Failed: update returned unexpected row" | "Failed: verifyField value on the upsert row was blank" | "Failed: verifyField value on the queried row does not match the upsert value" | "Failed: Expected values did not match";
     upsertNotTestedSameAsObjectId?: string;
     upsertNotTestedReason?: string;
     upsertFatalError?: CaughtError;
@@ -263,11 +274,11 @@ export interface ObjectTestResult {
 export interface FieldMetadataIssue {
     operation: "query" | "upsert" | "delete";
     path?: string;
-    issue: "Missing canMatch" | "No test spec for key field" | "Key field from test spec not found on object" | "Key field not tagged with isKey" | "Key field not tagged with isUserKey" | "Key field user key structure incorrect {value: string, operation: string}";
+    issue: "Missing canMatch" | "No test spec for key field" | "Key field from test spec not found on object" | "Key field not tagged with isKey" | "Key field not tagged with isUserKey" | "Key field user key structure incorrect {value: string, operation: string}" | "More than one query field tagged with isKey or isUserKey";
 }
 export interface MatchRuleTestResult {
     rule: API.RowMatchRuleType;
-    status?: "Passed" | "Not tested" | "Failed: Rule has no test spec" | "Failed: Rule not present on object" | "Failed: Fatal error during testing" | "Failed: No test data" | "Failed: Expected match not returned" | "Failed: Wrong match returned" | "Failed: Test data invalid, no expected row ids";
+    status?: "Passed" | "Not tested" | "Failed: Rule has no test spec" | "Failed: Rule not present on object" | "Failed: Fatal error during testing" | "Failed: No test data" | "Failed: Expected match not returned" | "Failed: Wrong match returned" | "Failed: Test data invalid, no expected row ids" | "Failed: Expected values did not match" | "Failed: Expected error did not occur";
     notTestedSameAsObjectId?: string;
     notTestedReason?: string;
     errorRowId?: string;
@@ -277,7 +288,7 @@ export interface MatchRuleTestResult {
 }
 export interface RelatedFilterTestResult {
     relationshipId: string;
-    status?: "Passed" | "Not tested" | "Failed: Relationship has no test spec" | "Failed: Relationship not present on object" | "Failed: Fatal error during testing" | "Failed: No test data" | "Failed: Did not find expected related row" | "Failed: Found unexpected row" | "Failed: Test data invalid, no expected row ids" | "Failed: Test data invalid, 'from' row not returned via idsFilter";
+    status?: "Passed" | "Not tested" | "Failed: Relationship has no test spec" | "Failed: Relationship not present on object" | "Failed: Fatal error during testing" | "Failed: No test data" | "Failed: Did not find expected related row" | "Failed: Found unexpected row" | "Failed: Test data invalid, no expected row ids" | "Failed: Test data invalid, 'from' row not returned via idsFilter" | "Failed: Expected values did not match" | "Failed: Expected error did not occur";
     notTestedSameAsObjectId?: string;
     notTestedReason?: string;
     errorRowId?: string;
@@ -328,6 +339,11 @@ export interface UpsertData {
     verifyFields?: Array<API.JsonValuePath>;
     /** optionally specify other fields to include when querying the data back for validation */
     fields?: Array<API.JsonValuePath>;
+    /**
+     * Assertions on the query-back of this data's row, for values the test did not write (identity and computed columns,
+     * defaults, server timestamps, rowversions). Not evaluated by the delete test, which reuses upsertPrepare.
+     */
+    expect?: UpsertExpect;
 }
 /** Expresses how to simulate an upsertClean issue, and defines the expected response. */
 export interface UpsertIssueSimulator {
@@ -360,6 +376,8 @@ export interface MatchData {
     expectedMatchRowIds: string[];
     /** optionally specify the fields to include in the match query */
     fields?: Array<API.JsonValuePath>;
+    /** the match query must fail (error), or its matched rows must hold these values (rows) */
+    expect?: Expect;
 }
 /** Options passed when requesting data that will be used for a relationship test. */
 export interface RelationshipOptions {
@@ -384,6 +402,8 @@ export interface RelationshipData {
     srcFields?: Array<API.JsonValuePath>;
     /** optionally specify the fields from the 'other' row that should be returned in the response */
     relatedFields?: Array<API.JsonValuePath>;
+    /** the related query must fail (error), or the related rows it returns must hold these values (rows) */
+    expect?: Expect;
 }
 /** Options passed when requesting data that will be used for a checkpoint test. */
 export interface CheckpointStep1Options {
@@ -411,12 +431,16 @@ export interface CheckpointStep1Data {
     expectedRowIds: string[];
     /** optionally specify the fields to include in the checkpoint query */
     fields?: Array<API.JsonValuePath>;
+    /** the step 1 query must fail (error; step 2 is then skipped), or its rows must hold these values (rows) */
+    expect?: Expect;
 }
 export interface CheckpointStep2Data {
     /** id of rows we should receive back in response to the second checkpoint query */
     expectedRowIds: string[];
     /** optionally specify the fields to include in the checkpoint query */
     fields?: Array<API.JsonValuePath>;
+    /** the step 2 query must fail (error), or its rows must hold these values (rows) */
+    expect?: Expect;
 }
 /** Options passed when requesting data that will be used for an list test. */
 export interface ListOptions {
@@ -435,6 +459,11 @@ export interface ListData {
     fields?: Array<API.JsonValuePath>;
     /** if the test harness created test data, place the ids of the rows created here */
     rowIds?: string[];
+    /**
+     * The list query must fail (error), or the rows it returns must hold these values (rows). The list reads one page plus
+     * one row (pageSize + 1), so a row named by its key must be within that read; use "*" for assertions on every row.
+     */
+    expect?: Expect;
 }
 /** Options passed when requesting data that will be used for an idsFilter test. */
 export interface IdsFilterOptions {
@@ -451,6 +480,11 @@ export interface IdsFilterData {
     id2: string;
     /** optionally specify the fields to include in the idsFilter query */
     fields?: Array<API.JsonValuePath>;
+    /**
+     * With error, the connector must reject the ids: the harness runs one query for [id1, id2] and passes only when it
+     * fails as described. With rows, the rows that query returns must hold these values.
+     */
+    expect?: Expect;
 }
 /** Options passed when requesting data that will be used for a rowFilters test. */
 export interface RowFiltersOptions {
@@ -469,7 +503,64 @@ export interface RowFilterData {
     expectedRowIds: string[];
     /** optionally specify the fields to include in the rowFilter query */
     fields?: Array<API.JsonValuePath>;
+    /** declared for uniformity with the other features; the harness does not run row filters yet, so it is not evaluated */
+    expect?: Expect;
+}
+/**
+ * Expected outcome of a feature's query, beyond which rows come back. The module computes these at prepare time from
+ * data it seeded; nothing here should be read from the connector under test.
+ */
+export interface Expect {
+    /** the operation must fail, and fail like this; a success is a failure of the test */
+    error?: ExpectedError;
+    /**
+     * Assertions on returned rows' values by path, keyed by row meta.key; "*" applies to every returned row, and an
+     * assertion under a row's own key overrides a "*" assertion on the same path.
+     */
+    rows?: Record<string, Assertion[]>;
+}
+/** How an expected failure must look. With neither member set, any error passes. */
+export interface ExpectedError {
+    /** must equal the thrown error's `code` (e.g. a ScriptError code) */
+    code?: string;
+    /** regex source that must match the thrown error's message */
+    messagePattern?: string;
+}
+/** Assertions on the query-back of an upsert test row, which cannot be keyed: the insert assigns its key. */
+export interface UpsertExpect {
+    /** assertions on the row queried back after the insert */
+    insert?: Assertion[];
+    /** assertions on the row queried back after the update (not run for insertOnly objects) */
+    update?: Assertion[];
 }
+/**
+ * One assertion on a value in row.data:
+ * - equals: compared per the field's declared type (strings exactly, numbers numerically, booleans, dates as instants at
+ *   the precision the field's date format implies, objects and arrays structurally; undeclared paths structurally)
+ * - matches: regex source the value (as a string) must match, for hex, GUIDs and formats
+ * - approx: numeric value within tolerance
+ * - present: the value is there and not null
+ * - absent: the path is not in the row at all (a column the connector must not echo)
+ */
+export type Assertion = {
+    path: API.JsonValuePath;
+    equals: unknown;
+} | {
+    path: API.JsonValuePath;
+    matches: string;
+} | {
+    path: API.JsonValuePath;
+    approx: {
+        value: number;
+        tolerance: number;
+    };
+} | {
+    path: API.JsonValuePath;
+    present: true;
+} | {
+    path: API.JsonValuePath;
+    absent: true;
+};
 /**
  * Find object field metadata by path.
  * @param {API.ObjectField[]} fields