@syncmatters/script-api 1.0.19 → 1.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/script-api",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "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": "3dcf1af8c79b37f9fe75992f52dbbdc70d0f22515d9f65b1123ceb7e4f31de20",
   "dependencies": {
     "@types/node": "*"
   }

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

@@ -54,7 +54,8 @@ export interface TestFeatureProvider {
     /**
      * Prepare data that can be used to test a queries with 'rowFilters'; you may either create new test data, or search/find
      * data that can be used to test the various row filters. Include one test of of test data for each row filter. Returning
-     * undefined indicates that row filters cannot be tested.
+     * undefined indicates that row filters cannot be tested (the rowFilter feature then reads Not tested, which does not
+     * make the object Partial: row filters have no ObjectFeatures flag to opt in with).
      */
     rowFiltersPrepare?(options: RowFiltersOptions): Promise<Array<RowFilterData> | undefined>;
     /** Delete test data created for use by a test. */
@@ -68,10 +69,52 @@ export interface TestFeatureProvider {
     upsertPrepare?(options: UpsertOptions): Promise<UpsertData | undefined>;
     /** Delete test data created for use by a test. */
     upsertCleanup?(options: UpsertCleanupOptions): Promise<void>;
+    /**
+     * Named checks that are not shaped like an object feature (a free statement, connection churn, a connection-level
+     * timeout). They run after the feature tests, in declaration order, each with its own status, duration and details.
+     * An escape hatch: a check that recurs across connectors belongs in the harness as a feature.
+     */
+    customChecks?(): Promise<CustomCheck[]>;
     /** Optional teardown function to run after all tests have completed. Can perform any required teardown, such as deleting test
      * data. */
     after?(): Promise<void>;
 }
+/** One named check run by the harness after the feature tests (TestFeatureProvider.customChecks()). */
+export interface CustomCheck {
+    /** stable id: keys the check's result and details (details["check:<id>"]) and is what --check names */
+    id: string;
+    /** display name for results */
+    name: string;
+    /**
+     * The object the check exercises. Gated like a feature: when the object is not on the connection (not selected on a
+     * two-phase connection, or not returned by meta()) the check reads Not tested with the reason, and its result is
+     * reported under that object. A check without one is connection-level and always runs.
+     */
+    objectId?: string;
+    /** default 60 000; capped at the run's remaining budget when the run has one */
+    timeoutMs?: number;
+    /** throw to fail; ctx.record(message, data) adds details. A check past its timeout fails and the suite carries on. */
+    run(ctx: CustomCheckContext): Promise<void>;
+}
+/** What a custom check runs with. */
+export interface CustomCheckContext {
+    /** the connection under test, as before() receives it */
+    connection: unknown;
+    /** metadata of the check's object, when it has one */
+    meta?: API.ObjectMeta;
+    log: API.Logger;
+    /** record a detail on the check's result (logged too), under the same size caps as every feature's details */
+    record(message: string, data?: unknown): void;
+}
+/** Result of one custom check. Its details are in the owning result's details under "check:<id>". */
+export interface CustomCheckResult {
+    id: string;
+    name: string;
+    status: "Passed" | "Not tested" | `Failed: ${string}`;
+    notTestedReason?: string;
+    durationMs: number;
+    fatalError?: CaughtError;
+}
 /** Specification of features that are supported by an object; much of this is auto generated however particular
  * features may be further refined/specified by the test harness.
  */
@@ -130,6 +173,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 */
@@ -208,10 +262,12 @@ export interface ConnectorTestResult {
     testConnection?: "Passed" | "Not tested" | "Failed: Fatal error during testing" | "Failed: Test connection response did not report success";
     objectsStatus?: "Passed" | "Partial: Only selected objects tested" | "Partial: Only selected objects tested, not all features can be tested" | "Partial: Only selected object tests run" | "Partial: Only selected objects tested, only selected object tests run" | "Partial: Not all features/objects can be tested" | "Not tested" | "Failed: Fatal error during testing" | "Failed: One or more objects failed tests";
     objects: ObjectTestResult[];
-    /** Diagnostic details for connection-level stages, keyed by stage (testConnection, metaRefresh). */
+    /** Diagnostic details for connection-level stages, keyed by stage (testConnection, metaRefresh) and check:<id>. */
     details?: {
         [stage: string]: TestDetail[];
     };
+    /** Connection-level custom checks (no objectId), in declaration order. */
+    customChecks?: CustomCheckResult[];
 }
 export interface ObjectTestResult {
     objectId: string;
@@ -219,15 +275,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 +296,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;
@@ -255,7 +311,15 @@ export interface ObjectTestResult {
     deleteFatalError?: CaughtError;
     fieldMetadata?: "Passed" | "Not tested" | "Failed: One or more fields have metadata issues";
     fieldMetadataIssues: FieldMetadataIssue[];
-    /** Diagnostic details keyed by feature (list, idsFilter, checkpointFilter, upsert, upsertClean, delete, fieldMetadata). */
+    rowFilter?: "Passed" | "Not tested" | "Not supported" | "Failed: Fatal error during testing" | "Failed: Test data invalid, no expected row ids" | "Failed: Row not returned" | "Failed: Returned unexpected row" | "Failed: Expected values did not match" | "Failed: Expected error did not occur";
+    rowFilterNotTestedReason?: string;
+    rowFilterFatalError?: CaughtError;
+    /** Custom checks with this objectId, in declaration order. */
+    customChecks?: CustomCheckResult[];
+    /**
+     * Diagnostic details keyed by feature (list, idsFilter, checkpointFilter, rowFilter, upsert, upsertClean, delete,
+     * fieldMetadata) and check:<id>.
+     */
     details?: {
         [feature: string]: TestDetail[];
     };
@@ -263,11 +327,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 +341,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 +392,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 +429,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 +455,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 +484,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 +512,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 +533,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 +556,67 @@ export interface RowFilterData {
     expectedRowIds: string[];
     /** optionally specify the fields to include in the rowFilter query */
     fields?: Array<API.JsonValuePath>;
+    /**
+     * The row-filter query must fail (error; e.g. a timeout forced with requestTimeoutOverride), or the rows it returns
+     * must hold these values (rows). With error set, expectedRowIds may be empty.
+     */
+    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