@aloma.io/integration-sdk 3.8.67 → 3.8.68

package/src/testing/harness.mts

@@ -0,0 +1,172 @@
+import {Config} from '../internal/websocket/config.mjs';
+import {WebsocketConnector} from '../internal/websocket/index.mjs';
+import {onConnect} from '../internal/connector/server/on-connect/index.mjs';
+import {onMessage} from '../internal/connector/server/on-message.mjs';
+import type {Connector} from '../internal/connector/index.mjs';
+import {FakeAloma} from './fake-aloma.mjs';
+import {testKeyPair} from './keys.mjs';
+import {VendorMock} from './vendor-mock.mjs';
+
+export type HarnessOptions = {
+  /**
+   * The connector under test, already configured:
+   * `const c = new Connector({id, version, name}); c.configure().types(...).resolvers(...).main(...)`
+   */
+  connector: Connector;
+  /** vendor mock; a fresh one is created when omitted */
+  vendor?: VendorMock;
+  /**
+   * configuration values ALOMA sends after the handshake (encrypted unless the field is `plain`).
+   * `null` skips sending any configuration (the connector then never starts its main()).
+   */
+  config?: Record<string, any> | null;
+  /** how long to wait for each step, ms */
+  timeoutMs?: number;
+};
+
+/**
+ * Runs a real connector against a fake ALOMA, in-process.
+ *
+ * It wires the same SDK parts as Connector.run() and makeServer(): Config, WebsocketConnector (connection,
+ * registration, transport), onConnect (config decryption, main()), onMessage (dispatch and reply).
+ * Left out on purpose: the Prometheus metrics server (fixed port 4050), process signal handlers and
+ * env-var configuration, which are global side effects that cannot run once per test.
+ */
+export class ConnectorHarness {
+
+  private constructor(
+    readonly aloma: FakeAloma,
+    readonly vendor: VendorMock,
+    private readonly server: WebsocketConnector,
+    private readonly started: Promise<void> | null
+  ) {}
+
+  static async start(options: HarnessOptions): Promise<ConnectorHarness> {
+    const {connector, timeoutMs = 5000} = options;
+    const dispatcher: any = connector.dispatcher;
+    if (!dispatcher) throw new Error('call connector.configure() before starting the harness');
+
+    const vendor = options.vendor || new VendorMock();
+    const aloma = await FakeAloma.start();
+    vendor.allowPassthrough((url) => url.origin === new URL(aloma.url).origin);
+    vendor.install();
+
+    // main() is what a connector runs once ALOMA has sent its configuration; observe it
+    let mainDone!: () => void;
+    let mainFailed!: (e: unknown) => void;
+    const started = new Promise<void>((resolve, reject) => {
+      mainDone = resolve;
+      mainFailed = reject;
+    });
+    started.catch(() => {});
+
+    const originalMain = dispatcher._main;
+    dispatcher.main(async (arg) => {
+      try {
+        await originalMain?.(arg);
+        mainDone();
+      } catch (e) {
+        mainFailed(e);
+        throw e;
+      }
+    });
+
+    let server: WebsocketConnector | undefined;
+
+    try {
+      const {processPacket, start, introspect, configSchema} = dispatcher.build();
+      const keys = await testKeyPair();
+
+      const config = new Config({
+        id: connector.id,
+        version: connector.version,
+        name: connector.name,
+        registrationToken: aloma.registrationToken,
+        endpoint: aloma.url,
+        wsEndpoint: aloma.wsUrl,
+        privateKey: keys.privateKey,
+        publicKey: keys.publicKey,
+        introspect,
+        configSchema,
+        icon: connector.icon,
+      });
+
+      server = new WebsocketConnector({
+        config,
+        onConnect: onConnect({config, configSchema, dispatcher, start}),
+        onMessage: onMessage(processPacket),
+      });
+
+      const harness = new ConnectorHarness(aloma, vendor, server, options.config === null ? null : started);
+
+      await server.start();
+      await aloma.waitForConnection(timeoutMs);
+
+      if (options.config !== null) {
+        await aloma.setConfig(options.config || {});
+        await withTimeout(started, timeoutMs, 'connector main() did not finish after the configuration was sent');
+      }
+
+      return harness;
+    } catch (e) {
+      await ConnectorHarness.shutdown(server, vendor, aloma);
+      throw e;
+    }
+  }
+
+  private static async shutdown(server: WebsocketConnector | undefined, vendor: VendorMock, aloma: FakeAloma) {
+    try {
+      if (server) {
+        const anyServer: any = server;
+
+        await anyServer.leaving();
+        await anyServer.close();
+
+        // the SDK leaves a 45s ping watchdog timer behind; clear it so a test run can exit
+        clearTimeout(anyServer.transport?.ws?.pingTimeout);
+      }
+    } finally {
+      vendor.uninstall();
+      await aloma.close();
+    }
+  }
+
+  /** call a connector method and return the raw answer (`{error}` when it failed) */
+  call(method: string | string[], variables?: any, ctx?: {taskId?: string; namespace?: string; sticky?: boolean}) {
+    return this.aloma.call(method, variables, ctx);
+  }
+
+  /** call a connector method; throws when the connector answered with an error */
+  async callOk(method: string | string[], variables?: any) {
+    const answer = await this.call(method, variables);
+    if (answer?.error) throw new Error(`${method} failed: ${answer.error}`);
+
+    return answer;
+  }
+
+  /**
+   * Shut down the connector and the fake endpoint, restore fetch and the network guard.
+   * Then fails if the connector made any request that was not mocked or the fake endpoint saw a protocol error.
+   */
+  async stop({verify = true}: {verify?: boolean} = {}) {
+    await ConnectorHarness.shutdown(this.server, this.vendor, this.aloma);
+
+    if (verify) {
+      this.vendor.verify();
+      if (this.aloma.protocolErrors.length) {
+        throw new Error(`protocol errors seen by the fake ALOMA: ${JSON.stringify(this.aloma.protocolErrors)}`);
+      }
+    }
+  }
+}
+
+const withTimeout = <T,>(promise: Promise<T>, ms: number, message: string): Promise<T> => {
+  let timer: NodeJS.Timeout;
+
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error(message)), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+};

package/src/testing/index.mts

@@ -0,0 +1,15 @@
+/**
+ * Test harness for connectors built on the ALOMA integration SDK.
+ *
+ *   import {ConnectorHarness, VendorMock} from '@aloma.io/integration-sdk/build/testing/index.mjs';
+ *
+ * Test tooling only: nothing in the SDK runtime imports this folder.
+ */
+export {ConnectorHarness} from './harness.mjs';
+export type {HarnessOptions} from './harness.mjs';
+export {FakeAloma} from './fake-aloma.mjs';
+export {VendorMock} from './vendor-mock.mjs';
+export type {VendorRequest, VendorResponse, VendorResponder, UrlMatcher} from './vendor-mock.mjs';
+export {installNetworkGuard, uninstallNetworkGuard} from './network-guard.mjs';
+export {testKeyPair} from './keys.mjs';
+export {connectorFromRuntimeContext} from './runtime-connector.mjs';

package/src/testing/keys.mts

@@ -0,0 +1,19 @@
+import JWE from '../internal/util/jwe/index.mjs';
+
+let pair: Promise<{privateKey: string; publicKey: string}> | undefined;
+
+/**
+ * One throwaway RSA key pair per process, generated at test time.
+ * Never committed, never a real key. Same encoding the connector expects in
+ * env.PRIVATE_KEY / env.PUBLIC_KEY (base64 of the PEM).
+ */
+export const testKeyPair = () => {
+  pair ||= (async () => {
+    const jwe = new JWE({algorithm: 'RSA-OAEP-256'});
+    await jwe.newPair();
+
+    return {privateKey: await jwe.exportPrivateAsBase64(), publicKey: await jwe.exportPublicAsBase64()};
+  })();
+
+  return pair;
+};

package/src/testing/network-guard.mts

@@ -0,0 +1,57 @@
+import net from 'node:net';
+
+/**
+ * Test-only network guard.
+ *
+ * While installed, any TCP connection to a host that is not loopback throws
+ * immediately. fetch (undici), http, https, ws and axios all end up in
+ * net.Socket.prototype.connect, so this is the safety net behind the vendor mock:
+ * even code that bypasses global fetch cannot reach the network from a test.
+ */
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
+let original: typeof net.Socket.prototype.connect | undefined;
+let installs = 0;
+export const blocked: string[] = [];
+
+const targetOf = (args: any[]): {host: string; local: boolean} => {
+  // net.connect hands over a normalized [options, callback] array
+  const first = Array.isArray(args[0]) ? args[0][0] : args[0];
+
+  if (first && typeof first === 'object' && !Array.isArray(first)) {
+    if (first.path) return {host: String(first.path), local: true};
+    return {host: String(first.host ?? 'localhost'), local: false};
+  }
+  if (typeof first === 'number' || (typeof first === 'string' && !Number.isNaN(Number(first)))) {
+    return {host: typeof args[1] === 'string' ? args[1] : 'localhost', local: false};
+  }
+
+  // unix socket path
+  return {host: String(first), local: true};
+};
+
+export const installNetworkGuard = () => {
+  if (installs++ > 0) return;
+
+  original = net.Socket.prototype.connect;
+
+  (net.Socket.prototype as any).connect = function (this: net.Socket, ...args: any[]) {
+    const {host, local} = targetOf(args);
+
+    if (!local && !LOOPBACK.has(host)) {
+      const message = `NETWORK BLOCKED by connector test harness: connection to ${host} is not allowed in tests`;
+      blocked.push(host);
+      throw new Error(message);
+    }
+
+    return (original as any).apply(this, args);
+  };
+};
+
+export const uninstallNetworkGuard = () => {
+  if (installs === 0) return;
+  if (--installs > 0) return;
+
+  (net.Socket.prototype as any).connect = original;
+  original = undefined;
+};

package/src/testing/runtime-connector.mts

@@ -0,0 +1,50 @@
+import {AbstractController} from '../controller/index.mjs';
+import {buildResolvers} from '../builder/runtime-context.mjs';
+import type RuntimeContext from '../builder/runtime-context.mjs';
+import {Connector} from '../internal/connector/index.mjs';
+
+/**
+ * Turn what a connector repo builds (`await new Builder()...build()` gives a RuntimeContext) into a configured
+ * `Connector` that the ConnectorHarness can run, without calling `connector.run()` (which starts a metrics
+ * server on a fixed port and installs process signal handlers).
+ *
+ * This repeats the wiring of RuntimeContext.start(): methods become resolvers, config/oauth/endpoint are applied,
+ * main() starts the controller and sends a health check. If RuntimeContext.start() changes, change this too.
+ */
+export const connectorFromRuntimeContext = (context: RuntimeContext): Connector => {
+  const {controller, data} = context as any as {controller: AbstractController; data: any};
+
+  if (!(controller instanceof AbstractController)) {
+    throw new Error('the controller needs to extend AbstractController');
+  }
+
+  const connector = new Connector({
+    id: data.id,
+    version: data.version,
+    name: `${data.id}/${data.version}`,
+    icon: undefined,
+  });
+
+  const configuration = connector.configure().config(data.config || {});
+  const methods: string[] = [...data.methods, '__autocomplete', '__endpoint', '__default'];
+
+  configuration.types(data.types).resolvers(buildResolvers(methods, controller));
+
+  if (data.options?.endpoint?.enabled) {
+    configuration.endpoint((arg) => (controller as any).__endpoint(arg), data.options?.endpoint?.required);
+  }
+
+  if (data.auth?.oauth) {
+    configuration.oauth(data.auth?.oauth);
+  }
+
+  configuration.main(
+    async ({newTask, updateTask, config, oauth, getClient, getBlob, getBlobContent, createBlob, healthCheck}) => {
+      await (controller as any)._doStop();
+      await (controller as any)._doStart(config, oauth, newTask, updateTask, getClient, getBlob, getBlobContent, createBlob);
+      await healthCheck(controller);
+    }
+  );
+
+  return connector;
+};

package/src/testing/vendor-mock.mts

@@ -0,0 +1,166 @@
+import {installNetworkGuard, uninstallNetworkGuard} from './network-guard.mjs';
+
+export type VendorRequest = {
+  method: string;
+  url: string;
+  /** the url exactly as the connector passed it to fetch */
+  rawUrl: string;
+  headers: Record<string, string>;
+  body?: string;
+};
+
+export type VendorResponse = {
+  status?: number;
+  headers?: Record<string, string>;
+  /** sent as JSON with a json content-type */
+  json?: unknown;
+  /** sent as is */
+  text?: string;
+};
+
+export type VendorResponder = VendorResponse | ((request: VendorRequest) => VendorResponse | Promise<VendorResponse>);
+export type UrlMatcher = string | RegExp | ((url: string) => boolean);
+
+type Route = {
+  method: string;
+  matcher: UrlMatcher;
+  respond: VendorResponder;
+  times: number;
+  used: number;
+};
+
+// "https:/host/x" (one slash, which the SDK Fetcher produces) and "https://host/x" are the same URL to fetch
+const canonical = (url: string): string => {
+  try {
+    return new URL(url).href;
+  } catch (e) {
+    return url;
+  }
+};
+
+const matches = (matcher: UrlMatcher, url: string): boolean => {
+  if (typeof matcher === 'string') return canonical(matcher) === url;
+  if (matcher instanceof RegExp) return matcher.test(url);
+  return matcher(url);
+};
+
+/**
+ * Mock for the HTTP calls a connector makes to its vendor API.
+ *
+ * - intercepts global fetch (what the SDK Fetcher and OAuth code use)
+ * - answers from routes you register with on()/get()/post()...
+ * - any request without a route is recorded in `unmocked` and rejected,
+ *   verify() then fails the test even if the connector swallowed the error
+ * - also installs the network guard, so nothing can reach a non-loopback host
+ */
+export class VendorMock {
+  readonly requests: VendorRequest[] = [];
+  readonly unmocked: VendorRequest[] = [];
+  private routes: Route[] = [];
+  private originalFetch?: typeof fetch;
+  private passthrough: (url: URL) => boolean = () => false;
+
+  /** urls for which the real fetch is used (the fake ALOMA endpoint); everything else is mocked */
+  allowPassthrough(fn: (url: URL) => boolean) {
+    this.passthrough = fn;
+    return this;
+  }
+
+  on(method: string, matcher: UrlMatcher, respond: VendorResponder, options: {times?: number} = {}) {
+    this.routes.push({method: method.toUpperCase(), matcher, respond, times: options.times ?? Infinity, used: 0});
+    return this;
+  }
+
+  get(matcher: UrlMatcher, respond: VendorResponder, options?: {times?: number}) {
+    return this.on('GET', matcher, respond, options);
+  }
+  post(matcher: UrlMatcher, respond: VendorResponder, options?: {times?: number}) {
+    return this.on('POST', matcher, respond, options);
+  }
+  put(matcher: UrlMatcher, respond: VendorResponder, options?: {times?: number}) {
+    return this.on('PUT', matcher, respond, options);
+  }
+  delete(matcher: UrlMatcher, respond: VendorResponder, options?: {times?: number}) {
+    return this.on('DELETE', matcher, respond, options);
+  }
+
+  install() {
+    if (this.originalFetch) return this;
+
+    installNetworkGuard();
+    this.originalFetch = globalThis.fetch;
+    globalThis.fetch = ((input: any, init?: any) => this.handle(input, init)) as typeof fetch;
+
+    return this;
+  }
+
+  uninstall() {
+    if (!this.originalFetch) return;
+
+    globalThis.fetch = this.originalFetch;
+    this.originalFetch = undefined;
+    uninstallNetworkGuard();
+  }
+
+  /** throws if the connector made a request that had no mock, even if it caught the error */
+  verify() {
+    if (this.unmocked.length) {
+      const list = this.unmocked.map((r) => `${r.method} ${r.url}`).join('\n  ');
+      throw new Error(`UNMOCKED vendor requests were made (no network is allowed in tests):\n  ${list}`);
+    }
+  }
+
+  /** throws if a registered route was never used */
+  verifyAllRoutesUsed() {
+    const unused = this.routes.filter((r) => r.used === 0);
+    if (unused.length) {
+      throw new Error(`mocked routes never called: ${unused.map((r) => `${r.method} ${String(r.matcher)}`).join(', ')}`);
+    }
+  }
+
+  private async handle(input: any, init: any = {}): Promise<Response> {
+    const rawUrl: string = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    const url = canonical(rawUrl);
+    const method = String(init.method || (typeof input === 'object' && input.method) || 'GET').toUpperCase();
+
+    const headers: Record<string, string> = {};
+    new Headers(init.headers || (typeof input === 'object' && (input as any).headers) || {}).forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    const request: VendorRequest = {method, url, rawUrl, headers};
+    if (init.body != null) request.body = typeof init.body === 'string' ? init.body : String(init.body);
+
+    const route = this.routes.find((r) => r.method === method && r.used < r.times && matches(r.matcher, url));
+
+    if (route) {
+      route.used++;
+      this.requests.push(request);
+      const spec = typeof route.respond === 'function' ? await route.respond(request) : route.respond;
+
+      const responseHeaders = {...spec.headers};
+      let body: string | null = null;
+      if (spec.json !== undefined) {
+        body = JSON.stringify(spec.json);
+        responseHeaders['content-type'] ||= 'application/json';
+      } else if (spec.text !== undefined) {
+        body = spec.text;
+      }
+
+      const status = spec.status ?? 200;
+      return new Response([204, 205, 304].includes(status) ? null : body, {status, headers: responseHeaders});
+    }
+
+    if (this.originalFetch && this.passthrough(new URL(url))) {
+      return this.originalFetch(input, init);
+    }
+
+    this.unmocked.push(request);
+
+    // status 400 makes the SDK Fetcher give up at once instead of retrying for seconds
+    const error: any = new Error(`UNMOCKED vendor request: ${method} ${url} (add a route with vendor.on(...))`);
+    error.status = 400;
+    error.alomaHarnessUnmocked = true;
+    throw error;
+  }
+}

package/test/MUTATION-entry.md

@@ -0,0 +1,21 @@
+# Mutation check for the SDK tests that `yarn test` now runs
+
+Result: **8/8 mutants killed** (24 Oct). Run with `yarn build && node tools/mutation-run-entry.mjs`.
+
+Each row is one deliberate single-point bug in `src/openapi-to-connector.mts` (the OpenAPI to connector generator). The
+script applies it alone, rebuilds, runs the full `yarn test`, expects a failure, and restores the file.
+
+| # | Bug | Result |
+|---|-----|--------|
+| E01 | the HTTP verb is taken in lower case | killed |
+| E02 | path parameter substitution is guarded by the wrong condition | killed |
+| E03 | fallback method name drops the separator | killed |
+| E04 | body properties are documented with the wrong required flag | killed |
+| E05 | headers are dropped from the generated options type | killed |
+| E06 | options is not defaulted in generated methods | killed |
+| E07 | invalid specs are no longer rejected | killed |
+| E08 | a property is required only if both the schema and the body say so | killed |
+
+A first run left two survivors: E02 (nothing asserted the path parameter substitution) and a draft E03 aimed at
+`disambiguateMethodName` (no test reaches it, so a different mutant on the fallback name was used). A test for E02 was
+added to `test/openapi-to-connector.test.mts`; `disambiguateMethodName` remains without direct coverage.

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/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/);
+  });
+});