@syncmatters/script-api 1.0.20 → 1.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/script-api",
-  "version": "1.0.20",
+  "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": "6f0e7724c2cff15e666109cc05b76419887b64ffa0310e9ec23fe2b585a323e5",
+  "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.
  */
@@ -219,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;
@@ -266,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[];
     };
@@ -503,7 +556,10 @@ 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 */
+    /**
+     * 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;
 }
 /**