@aloma.io/integration-sdk 3.8.67 → 3.8.69

package/test/MUTATION.md

@@ -0,0 +1,43 @@
+# Mutation check for the connector test harness
+
+Result: **32/32 mutants killed**.
+
+Each row is one deliberate single-point bug in the SDK code paths the harness exercises (handshake, transport,
+dispatch, result return, config) or in the harness itself. `tools/mutation-run.mjs` applies it to `src/`, rebuilds,
+runs `test/harness.test.mjs` with `--bail`, expects a failure, and restores the file. Re-run with
+`yarn build && yarn test:mutation` after changing the harness or those SDK paths.
+
+| # | Area | File | Bug | Result |
+|---|------|------|-----|--------|
+| M01 | sdk handshake | `src/internal/websocket/connection/index.mjs` | a 401 from /connect no longer triggers registration | killed |
+| M02 | sdk handshake | `src/internal/websocket/connection/index.mjs` | the token from registration is not stored | killed |
+| M03 | sdk handshake | `src/internal/websocket/connection/registration.mjs` | registration reads the wrong field of the answer | killed |
+| M04 | sdk handshake | `src/internal/websocket/connection/registration.mjs` | registration sends the name as the connector id | killed |
+| M05 | sdk handshake | `src/internal/websocket/connection/registration.mjs` | registration omits the public key | killed |
+| M06 | sdk handshake | `src/internal/websocket/connection/constants.mjs` | authenticated requests drop the version from the User-Agent | killed |
+| M07 | sdk handshake | `src/internal/websocket/connection/constants.mjs` | wrong authorization scheme for the session token | killed |
+| M08 | sdk handshake | `src/internal/websocket/transport/index.mjs` | websocket opened without the "connector" subprotocol | killed |
+| M09 | sdk transport | `src/internal/websocket/transport/index.mjs` | the first packet of every incoming frame is dropped | killed |
+| M10 | sdk transport | `src/internal/websocket/transport/index.mjs` | outgoing frames use the wrong envelope | killed |
+| M11 | sdk transport | `src/internal/websocket/transport/index.mjs` | answers to connector-initiated requests are never routed to their callback | killed |
+| M12 | sdk dispatch | `src/internal/dispatcher/index.mts` | configuration secrets are dropped before onConfig | killed |
+| M13 | sdk dispatch | `src/internal/dispatcher/index.mts` | sticky is not forwarded to the method | killed |
+| M14 | sdk dispatch | `src/internal/dispatcher/index.mts` | unknown methods are no longer reported as "not found" | killed |
+| M15 | sdk result return | `src/internal/dispatcher/index.mts` | scalar results are wrapped under the wrong key | killed |
+| M16 | sdk result return | `src/internal/util/index.mts` | successful results are replied empty | killed |
+| M17 | sdk result return | `src/internal/util/index.mts` | errors lose their message | killed |
+| M18 | sdk result return | `src/internal/connector/server/on-message.mts` | results are never sent back | killed |
+| M19 | sdk config | `src/internal/connector/server/on-connect/decrypt-config.mts` | config is decrypted for the wrong audience | killed |
+| M20 | sdk config | `src/internal/connector/server/on-connect/decrypt-config.mts` | plain fields are decrypted like secrets | killed |
+| M21 | sdk config | `src/internal/connector/server/on-connect/index.mts` | main() receives an empty config | killed |
+| M22 | harness vendor mock | `src/testing/vendor-mock.mts` | an unmocked request is answered instead of rejected | killed |
+| M23 | harness vendor mock | `src/testing/vendor-mock.mts` | verify() never fails | killed |
+| M24 | harness vendor mock | `src/testing/vendor-mock.mts` | mocked status codes are ignored | killed |
+| M25 | harness vendor mock | `src/testing/vendor-mock.mts` | the times limit on a route is ignored | killed |
+| M26 | harness network guard | `src/testing/network-guard.mts` | the network guard lets everything through (the mutant may try one TCP connect to the TEST-NET-3 documentation address 203.0.113.9) | killed |
+| M27 | harness fake ALOMA | `src/testing/fake-aloma.mts` | the fake accepts a connect without registration | killed |
+| M28 | harness fake ALOMA | `src/testing/fake-aloma.mts` | the fake encrypts config for the wrong audience | killed |
+| M29 | harness fake ALOMA | `src/testing/fake-aloma.mts` | the fake drops the connector's answer | killed |
+| M30 | harness fake ALOMA | `src/testing/fake-aloma.mts` | call() drops the ctx fields | killed |
+| M31 | harness | `src/testing/harness.mts` | stop() no longer fails on unmocked requests | killed |
+| M32 | harness | `src/testing/harness.mts` | the harness never sends configuration | killed |

package/test/fixtures/transform/basic/expected.json

@@ -0,0 +1,9 @@
+{
+ "text": "\n/**\n * greet somebody\n *\n * @namespace demo\n * @example usage\n```javascript\ngreet({name: 'Ann'})\n```\n **/    \ndeclare function greet({name; times = 2; loud = false; label = 'x'; neg = -1; nothing}: {\n/**\nwho to greet, e.g. Ann\n */\n name: any; \n/**\nhow often\n */\n times: any; \n/**\n\n */\n loud: any; \n/**\n\n */\n label: any; \n/**\n\n */\n neg: any; \n/**\n\n */\n nothing: any}): { ok: boolean; greeting: any; };\n      \n/**\n * no params\n *\n * \n * \n **/    \ndeclare function ping(): { ok: boolean; };\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function list(): string[];\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function nothing(): void;\n      ",
+ "methods": [
+  "greet",
+  "ping",
+  "list",
+  "nothing"
+ ]
+}

package/test/fixtures/transform/basic/src/controller/abstract.mts

@@ -0,0 +1,5 @@
+// stands in for AbstractController from @aloma.io/integration-sdk
+export class AbstractController {
+  protected config: any = {};
+  async inheritedPublic(): Promise<void> {}
+}

package/test/fixtures/transform/basic/src/controller/index.mts

@@ -0,0 +1,30 @@
+import {AbstractController} from './abstract.mjs';
+
+export default class Controller extends AbstractController {
+  /**
+   * greet somebody
+   * @param name - who to greet, e.g. Ann
+   * @param times - how often
+   * @param opts - extra \@options
+   * @namespace demo
+   *
+   * @example
+   * ```javascript
+   * greet({name: 'Ann'})
+   * ```
+   */
+  async greet({name, times = 2, loud = false, label = 'x', neg = -1, nothing = null}, other = 1) {
+    return {ok: true, greeting: name + times};
+  }
+
+  /** no params */
+  async ping() {
+    return {ok: true};
+  }
+
+  async list(): Promise<string[]> {
+    return [];
+  }
+
+  async nothing(): Promise<void> {}
+}

package/test/fixtures/transform/basic/tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"target":"es2022","module":"node16","moduleResolution":"node16","skipLibCheck":true,"strict":true,"noImplicitAny":false,"experimentalDecorators":true,"esModuleInterop":true},"include":["src/**/*"]}

package/test/fixtures/transform/interface-param/src/controller/abstract.mts

@@ -0,0 +1,5 @@
+// stands in for AbstractController from @aloma.io/integration-sdk
+export class AbstractController {
+  protected config: any = {};
+  async inheritedPublic(): Promise<void> {}
+}

package/test/fixtures/transform/interface-param/src/controller/index.mts

@@ -0,0 +1,12 @@
+import {AbstractController} from './abstract.mjs';
+
+interface Opts {
+  id: string;
+  n?: number;
+}
+
+export default class Controller extends AbstractController {
+  async viaInterface({id, n}: Opts): Promise<{id: string; n: number | undefined}> {
+    return {id, n};
+  }
+}

package/test/fixtures/transform/interface-param/tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"target":"es2022","module":"node16","moduleResolution":"node16","skipLibCheck":true,"strict":true,"noImplicitAny":false,"experimentalDecorators":true,"esModuleInterop":true},"include":["src/**/*"]}

package/test/fixtures/transform/overloads/expected.json

@@ -0,0 +1,6 @@
+{
+ "text": "\n/**\n * first form\n *\n * \n * \n **/    \ndeclare function over({a}: {\n/**\n\n */\n a: string}): string;\n      \n\n/**\n * second form\n *\n * \n * \n **/    \ndeclare function over({b}: {\n/**\n\n */\n b: number}): number;\n      ",
+ "methods": [
+  "over"
+ ]
+}

package/test/fixtures/transform/overloads/src/controller/abstract.mts

@@ -0,0 +1,5 @@
+// stands in for AbstractController from @aloma.io/integration-sdk
+export class AbstractController {
+  protected config: any = {};
+  async inheritedPublic(): Promise<void> {}
+}

package/test/fixtures/transform/overloads/src/controller/index.mts

@@ -0,0 +1,11 @@
+import {AbstractController} from './abstract.mjs';
+
+export default class Controller extends AbstractController {
+  /** first form */
+  async over({a}: {a: string}): Promise<string>;
+  /** second form */
+  async over({b}: {b: number}): Promise<number>;
+  async over(args: any): Promise<any> {
+    return args;
+  }
+}

package/test/fixtures/transform/overloads/tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"target":"es2022","module":"node16","moduleResolution":"node16","skipLibCheck":true,"strict":true,"noImplicitAny":false,"experimentalDecorators":true,"esModuleInterop":true},"include":["src/**/*"]}

package/test/fixtures/transform/tdd-stub/expected.json

@@ -0,0 +1,8 @@
+{
+ "text": "\n/**\n * Returns recorded calls scoped to the current task.\n *\n * \n * @example usage\n```javascript\nconst log = await connectors.testing.getCallLog({})\n// log.calls = [{method, args, timestamp}, ...] for THIS task only\n```\n **/    \ndeclare function getCallLog(): { calls: CallRecord[]; count: number; };\n      \n/**\n * Resets the call log for the current task only.\n *\n * \n * @example usage\n```javascript\nawait connectors.testing.clearCallLog({})\n```\n **/    \ndeclare function clearCallLog(): { cleared: boolean; };\n      \n/**\n * Updates the response map for the current task at runtime.\n *\n * \n * @example usage\n```javascript\nawait connectors.testing.setResponses({\n  responses: { \"someConnector.create\": { id: \"456\" } }\n})\n```\n **/    \ndeclare function setResponses(): { updated: boolean; responseCount: number; };\n      ",
+ "methods": [
+  "getCallLog",
+  "clearCallLog",
+  "setResponses"
+ ]
+}

package/test/fixtures/transform/tdd-stub/src/controller/abstract.mts

@@ -0,0 +1,6 @@
+// stands in for AbstractController from @aloma.io/integration-sdk
+export class AbstractController {
+  protected config: any = {};
+  async inheritedPublic(): Promise<void> {}
+}
+export {};

package/test/fixtures/transform/tdd-stub/src/controller/index.mts

@@ -0,0 +1,204 @@
+import { AbstractController } from "./abstract.mjs";
+
+interface CallRecord {
+  method: string;
+  args: any;
+  timestamp: string;
+}
+
+/**
+ * Per-task scoped mock connector for ALOMA test workflows.
+ *
+ * State (responseMap, callLog) is keyed by ctx.taskId so concurrent
+ * test tasks against the same Testing pod do not contaminate each
+ * other's stubbed responses or recorded calls.
+ *
+ * Requires @aloma.io/integration-sdk ^3.8.67, which forwards
+ * { taskId, namespace, sticky } as the second arg to controller
+ * method handlers and to the __default fallback.
+ *
+ * Backward compatibility: when ctx is missing (legacy invocation or
+ * non-task call from admin UI), state falls into the "__no_ctx__"
+ * bucket so the connector does not crash. Isolation is NOT guaranteed
+ * in that mode — it is degraded compatibility only.
+ */
+export default class Controller extends AbstractController {
+  // Per-task scoped state — Maps keyed by taskId (insertion order = LRU order)
+  private responseMapByTask: Map<string, Record<string, any>> = new Map();
+  private callLogByTask: Map<string, CallRecord[]> = new Map();
+  private recording: boolean = true;
+  private defaultResponses: Record<string, any> = {};
+  // Memory cap (LRU). Configurable via config.maxTasks; default 1000.
+  private maxTasks: number = 1000;
+
+  protected async start() {
+    this.loadConfig();
+  }
+
+  private loadConfig() {
+    const config = this.config;
+
+    // Parse default responses from connector config — these seed each
+    // task's bucket when first touched.
+    if (config.responses) {
+      try {
+        this.defaultResponses =
+          typeof config.responses === "string"
+            ? JSON.parse(config.responses)
+            : config.responses;
+      } catch (e) {
+        this.defaultResponses = {};
+      }
+    } else {
+      this.defaultResponses = {};
+    }
+
+    this.recording = config.recordCalls !== "false";
+
+    // Allow config-driven override of LRU cap. Default 1000 if not set
+    // or not a positive number.
+    const configured = Number(config.maxTasks);
+    if (Number.isFinite(configured) && configured > 0) {
+      this.maxTasks = Math.floor(configured);
+    }
+  }
+
+  /**
+   * Resolve the bucket key for the current invocation. When ctx is
+   * absent or lacks taskId, falls back to a single shared bucket so
+   * legacy / hand-rolled callers do not crash. Isolation is not
+   * guaranteed in that mode.
+   */
+  private bucketKey(ctx?: { taskId?: string }): string {
+    return ctx && ctx.taskId ? ctx.taskId : "__no_ctx__";
+  }
+
+  /**
+   * LRU touch — ensures the bucket exists for the given key, evicting
+   * the least-recently-used entry if the cap would be exceeded. Map
+   * iteration order is insertion order; reinserting promotes a key to
+   * "most recently used" position.
+   */
+  private touchTask(key: string) {
+    // If not present and at cap, evict the oldest (insertion order)
+    if (!this.responseMapByTask.has(key)) {
+      if (this.responseMapByTask.size >= this.maxTasks) {
+        const firstKey = this.responseMapByTask.keys().next().value as
+          | string
+          | undefined;
+        if (firstKey !== undefined) {
+          this.responseMapByTask.delete(firstKey);
+          this.callLogByTask.delete(firstKey);
+        }
+      }
+      this.responseMapByTask.set(key, { ...this.defaultResponses });
+      this.callLogByTask.set(key, []);
+    }
+  }
+
+  /**
+   * Catch-all handler — registered as __default by the SDK via the
+   * fallback override below. Looks up the response in the task-scoped
+   * map, records the call in the task-scoped log, and returns the
+   * configured response or a default stub acknowledgement.
+   */
+  private async handleStubCall(
+    arg: any,
+    ctx?: { taskId?: string },
+  ): Promise<any> {
+    const key = this.bucketKey(ctx);
+    this.touchTask(key);
+
+    const method = Array.isArray(arg?.__method)
+      ? arg.__method.join(".")
+      : arg?.__method || "unknown";
+
+    if (this.recording) {
+      const log = this.callLogByTask.get(key)!;
+      log.push({
+        method,
+        args: { ...arg, __method: undefined },
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    const responseMap = this.responseMapByTask.get(key)!;
+    if (responseMap[method] !== undefined) {
+      return responseMap[method];
+    }
+    if (responseMap["default"] !== undefined) {
+      return responseMap["default"];
+    }
+
+    return { stubbed: true, method };
+  }
+
+  /**
+   * SDK override hook — invoked by AbstractController.__default with
+   * the per-invocation ctx (taskId, namespace, sticky) as second arg.
+   */
+  protected fallback(arg: any, ctx?: { taskId?: string }): Promise<any> {
+    return this.handleStubCall(arg, ctx);
+  }
+
+  /**
+   * Returns recorded calls scoped to the current task.
+   * @example
+   * ```javascript
+   * const log = await connectors.testing.getCallLog({})
+   * // log.calls = [{method, args, timestamp}, ...] for THIS task only
+   * ```
+   */
+  async getCallLog(_args: any, ctx?: { taskId?: string }) {
+    const key = this.bucketKey(ctx);
+    const calls = this.callLogByTask.get(key) || [];
+    return { calls: [...calls], count: calls.length };
+  }
+
+  /**
+   * Resets the call log for the current task only.
+   * @example
+   * ```javascript
+   * await connectors.testing.clearCallLog({})
+   * ```
+   */
+  async clearCallLog(_args: any, ctx?: { taskId?: string }) {
+    const key = this.bucketKey(ctx);
+    if (this.callLogByTask.has(key)) {
+      this.callLogByTask.set(key, []);
+    }
+    return { cleared: true };
+  }
+
+  /**
+   * Updates the response map for the current task at runtime.
+   * @example
+   * ```javascript
+   * await connectors.testing.setResponses({
+   *   responses: { "someConnector.create": { id: "456" } }
+   * })
+   * ```
+   */
+  async setResponses(args: any, ctx?: { taskId?: string }) {
+    const key = this.bucketKey(ctx);
+    this.touchTask(key);
+
+    if (args?.responses) {
+      try {
+        const newResponses =
+          typeof args.responses === "string"
+            ? JSON.parse(args.responses)
+            : args.responses;
+        const existing = this.responseMapByTask.get(key)!;
+        this.responseMapByTask.set(key, { ...existing, ...newResponses });
+      } catch (e) {
+        // ignore parse errors — leave existing map untouched
+      }
+    }
+
+    return {
+      updated: true,
+      responseCount: Object.keys(this.responseMapByTask.get(key)!).length,
+    };
+  }
+}

package/test/fixtures/transform/tdd-stub/tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"target":"es2022","module":"node16","moduleResolution":"node16","skipLibCheck":true,"strict":true,"noImplicitAny":false,"experimentalDecorators":true,"esModuleInterop":true},"include":["src/**/*"]}

package/test/fixtures/transform/two-exports/src/controller/abstract.mts

@@ -0,0 +1,5 @@
+// stands in for AbstractController from @aloma.io/integration-sdk
+export class AbstractController {
+  protected config: any = {};
+  async inheritedPublic(): Promise<void> {}
+}

package/test/fixtures/transform/two-exports/src/controller/index.mts

@@ -0,0 +1,9 @@
+import {AbstractController} from './abstract.mjs';
+
+export interface Extra {
+  a: string;
+}
+
+export default class Controller extends AbstractController {
+  async one() {}
+}

package/test/fixtures/transform/two-exports/tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"target":"es2022","module":"node16","moduleResolution":"node16","skipLibCheck":true,"strict":true,"noImplicitAny":false,"experimentalDecorators":true,"esModuleInterop":true},"include":["src/**/*"]}

package/test/fixtures/transform/type-error/src/controller/abstract.mts

@@ -0,0 +1,5 @@
+// stands in for AbstractController from @aloma.io/integration-sdk
+export class AbstractController {
+  protected config: any = {};
+  async inheritedPublic(): Promise<void> {}
+}

package/test/fixtures/transform/type-error/src/controller/index.mts

@@ -0,0 +1,7 @@
+import {AbstractController} from './abstract.mjs';
+
+export default class Controller extends AbstractController {
+  async one(): Promise<number> {
+    return 'not a number';
+  }
+}

package/test/fixtures/transform/type-error/tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"target":"es2022","module":"node16","moduleResolution":"node16","skipLibCheck":true,"strict":true,"noImplicitAny":false,"experimentalDecorators":true,"esModuleInterop":true},"include":["src/**/*"]}

package/test/fixtures/transform/typed/expected.json

@@ -0,0 +1,8 @@
+{
+ "text": "\n/**\n * \n *\n * \n * \n **/    \ndeclare function typed({email; count; tags; mode; either; nested}: {\n/**\n\n */\n email: string; \n/**\n\n */\n count: any; \n/**\n\n */\n tags: string[]; \n/**\n\n */\n mode: any; \n/**\n\n */\n either: any; \n/**\n\n */\n nested: any}): { ok: boolean; tags: number[]; };\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function tuple(): [string, number];\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function maybe(): string | undefined;\n      ",
+ "methods": [
+  "typed",
+  "tuple",
+  "maybe"
+ ]
+}

package/test/fixtures/transform/typed/src/controller/abstract.mts

@@ -0,0 +1,5 @@
+// stands in for AbstractController from @aloma.io/integration-sdk
+export class AbstractController {
+  protected config: any = {};
+  async inheritedPublic(): Promise<void> {}
+}

package/test/fixtures/transform/typed/src/controller/index.mts

@@ -0,0 +1,13 @@
+import {AbstractController} from './abstract.mjs';
+
+export default class Controller extends AbstractController {
+  async typed({email, count, tags, mode, either, nested}: {email: string; count?: number; tags: string[]; mode: 'a' | 'b'; either: string | number; nested: {x: number}}) {
+    return {ok: true, tags: [1, 2]};
+  }
+  async tuple(): Promise<[string, number]> {
+    return ['a', 1];
+  }
+  async maybe(): Promise<string | undefined> {
+    return undefined;
+  }
+}

package/test/fixtures/transform/typed/tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"target":"es2022","module":"node16","moduleResolution":"node16","skipLibCheck":true,"strict":true,"noImplicitAny":false,"experimentalDecorators":true,"esModuleInterop":true},"include":["src/**/*"]}

package/test/fixtures/transform/visibility/expected.json

@@ -0,0 +1,9 @@
+{
+ "text": "\n/**\n * \n *\n * \n * \n **/    \ndeclare function visible({a}: {\n/**\n\n */\n a: string}): string;\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function quoted-name({a}: {\n/**\n\n */\n a: string}): void;\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function arrow({a}: {\n/**\n\n */\n a: string}): string;\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function inheritedPublic(): void;\n      ",
+ "methods": [
+  "visible",
+  "quoted-name",
+  "arrow",
+  "inheritedPublic"
+ ]
+}

package/test/fixtures/transform/visibility/src/controller/abstract.mts

@@ -0,0 +1,5 @@
+// stands in for AbstractController from @aloma.io/integration-sdk
+export class AbstractController {
+  protected config: any = {};
+  async inheritedPublic(): Promise<void> {}
+}

package/test/fixtures/transform/visibility/src/controller/index.mts

@@ -0,0 +1,19 @@
+import {AbstractController} from './abstract.mjs';
+
+export default class Controller extends AbstractController {
+  async visible({a}: {a: string}) {
+    return a;
+  }
+  private async hidden({a}: {a: string}) {}
+  protected async guarded({a}: {a: string}) {}
+  static async stat({a}: {a: string}) {}
+  async _underscore({a}: {a: string}) {}
+  async 'quoted-name'({a}: {a: string}) {}
+  async '_quoted_private'({a}: {a: string}) {}
+  arrow = async ({a}: {a: string}) => a;
+  notAMethod = 5;
+  get getter() {
+    return 1;
+  }
+  override async inheritedPublic() {}
+}

package/test/fixtures/transform/visibility/tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"target":"es2022","module":"node16","moduleResolution":"node16","skipLibCheck":true,"strict":true,"noImplicitAny":false,"experimentalDecorators":true,"esModuleInterop":true},"include":["src/**/*"]}

package/test/harness-connector-smoke.test.mjs

@@ -0,0 +1,72 @@
+// Handshake smoke test: the one file a connector repo adds (see "Testing a connector" in the SDK README).
+//
+// In a connector repo the RuntimeContext comes from the repo's own builder after `yarn build`:
+//     const context = await new Builder().config({...}).build();
+// Here the controller is defined inline so this file also tests the harness path used by connector repos.
+import {describe, it, afterEach} from 'mocha';
+import {expect} from 'chai';
+import {AbstractController} from '../build/index.mjs';
+import RuntimeContext from '../build/builder/runtime-context.mjs';
+import {ConnectorHarness, connectorFromRuntimeContext} from '../build/testing/index.mjs';
+
+const VENDOR = 'https://api.crm.example.test';
+
+class Controller extends AbstractController {
+  async getContact({id}) {
+    return this.getClient({baseUrl: VENDOR, retry: 1, customize: (r) => {
+      r.headers = {...r.headers, Authorization: `Bearer ${this.config.apiKey}`};
+    }}).fetch(`/contacts/${id}`, {method: 'GET'});
+  }
+}
+
+const context = () =>
+  new RuntimeContext(new Controller(), {
+    id: 'crm-connector',
+    version: '0.0.1',
+    methods: ['getContact'],
+    types: 'type Query { getContact(id: String): String }',
+    config: {fields: {apiKey: {name: 'API Key', type: 'line'}}},
+  });
+
+describe('crm-connector handshake smoke test', function () {
+  this.timeout(15000);
+  let harness;
+
+  afterEach(async () => {
+    // stop() also fails the test when the connector made a request that was not mocked
+    if (harness) await harness.stop();
+    harness = undefined;
+  });
+
+  it('registers, connects, starts and reports healthy', async () => {
+    harness = await ConnectorHarness.start({
+      connector: connectorFromRuntimeContext(context()),
+      config: {apiKey: 'fake-api-key-not-real'},
+    });
+
+    expect(harness.aloma.registration.id).to.equal('crm-connector');
+    expect(harness.aloma.registration.schema.configSchema.fields).to.have.property('apiKey');
+
+    const health = await harness.aloma.waitForPacket('connector.health.check');
+    expect(health.a).to.deep.equal({ok: true, error: null});
+  });
+
+  it('answers a method call from a recorded vendor response', async () => {
+    harness = await ConnectorHarness.start({
+      connector: connectorFromRuntimeContext(context()),
+      config: {apiKey: 'fake-api-key-not-real'},
+    });
+    harness.vendor.get(`${VENDOR}/contacts/42`, {json: {id: 42, email: 'jane@example.test'}});
+
+    expect(await harness.callOk('getContact', {id: 42})).to.deep.equal({id: 42, email: 'jane@example.test'});
+    expect(harness.vendor.requests[0].headers.authorization).to.equal('Bearer fake-api-key-not-real');
+  });
+
+  it('reports a missing configuration value as unhealthy', async () => {
+    harness = await ConnectorHarness.start({connector: connectorFromRuntimeContext(context()), config: {}});
+
+    const health = await harness.aloma.waitForPacket('connector.health.check');
+    expect(health.a.ok).to.equal(false);
+    expect(health.a.error).to.match(/API Key is required/);
+  });
+});