@deepexi/datasense-connector 3.0.1 → 3.1.0

package/src/testing/replay.ts

@@ -0,0 +1,437 @@
+/**
+ * 用例回放：guest 的宿主调用一律由用例应答，不联网（`runTests`、CLI `test` 与 runner 的 `fixture_test` 共用）。
+ *
+ * `createReplayHost(fixture)`：
+ * - `http`：匹配键是 `method + URL（query 并入并按键排序、遮蔽规则同录制）+ body`，取 seq 最小的未用往来；
+ *   找不到时该调用失败 `FIXTURE_EXCHANGE_MISMATCH`，绝不回落到真实请求；
+ * - `db.query`：按 SQL 与参数匹配，一页回全部行；录制时中途失败的查询先回已取到的行，下一次 `db.next` 再报错；
+ * - `crypto`：先查录制的往来；没有时 `hash` 本地计算，`hmac` / `sign` 报 `FIXTURE_EXCHANGE_MISMATCH`；
+ * - `secret.reveal` 从 `case.secrets` 取值（值是 `***` 也照给），`cache.*` 在单次回放内用内存表。
+ *
+ * `runFixture(executor, descriptor, fixture)`：每次执行新建一个回放宿主；表结构取连接器描述（静态）。
+ * - 拉取用例按描述里该数据流的表执行；全量模式再回放一遍，比较两遍的记录集合（`FULL_READ_NOT_REPEATABLE`）；
+ * - 推送用例重放 `requests.ndjson`；
+ * - 操作用例跑一次操作的 `run`，结果与 `expect.ok`（输出精确相等，不同时给出逐字段差异）或 `expect.error`（失败码）比较；
+ * - 建议列用例跑一次 `suggestColumns`，结果与 `expect.columns` 比较。
+ * 用例所属的能力不在描述里时失败（`CAPABILITY_UNKNOWN`）。
+ * 结果 `ok` 为 true 当且仅当运行没有失败、且除 `FIXTURE_EXCHANGE_UNUSED` 外没有任何 finding。
+ */
+import { createHash } from 'node:crypto';
+import type { ConnectorDescriptor, SuggestedColumn, TableDescriptor } from '../descriptor';
+import type { CacheEntry, CryptoRequest, DbQueryResponse, EgressHttpResponse, GuestJob, GuestOperationResult } from '../runtime/protocol';
+import { checkCompliance, type ComplianceFinding } from './compliance';
+import {
+  canonicalJson, canonicalRequestUrl, parseFixtures, type ConnectorFixtureFile, type FixtureCase, type FixtureExchange, type LoadedFixture,
+} from './fixtures';
+import { redactSecretValues, redactUrl } from './redaction';
+import type { GuestExecutor, HostMethod, LocalHost, LocalRunResult } from './types';
+
+/** 回放宿主自己的宿主调用失败（`code` 回给 guest）。 */
+export class FixtureReplayError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'FixtureReplayError';
+    this.code = code;
+  }
+}
+
+export interface FixtureMismatch { method: string; detail: string }
+
+export type ReplayHost = LocalHost & { unused(): FixtureExchange[]; mismatches(): FixtureMismatch[] };
+
+/** 一个用例的回放结果。 */
+export interface FixtureCaseResult {
+  /** 形如 `streams/orders`。 */
+  capability: string;
+  name: string;
+  kind: FixtureCase['kind'];
+  ok: boolean;
+  findings: ComplianceFinding[];
+  stats: { records: Record<string, number>; removals: Record<string, number>; checkpoints: number; rejected: number };
+  error: { code: string; message: string; stack: string | null } | null;
+}
+
+export interface RunFixtureOptions {
+  /** 每次执行（不是整个用例）的超时，交给 `executor.run`。 */
+  timeoutMs?: number;
+}
+
+const MISMATCH = 'FIXTURE_EXCHANGE_MISMATCH';
+const PLAIN_HANDLE = /ontos:secret:([A-Za-z_][A-Za-z0-9_]*)/g;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function preview(text: string, max = 200): string {
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+// ---------------------------------------------------------------------------
+// 回放宿主
+
+export function createReplayHost(fixture: LoadedFixture): ReplayHost {
+  const caseSecrets = fixture.case.secrets ?? {};
+  const secretValues = Object.values(caseSecrets);
+  const redact = (text: string): string => redactSecretValues(text, secretValues);
+  const used = new Set<number>();
+  const mismatched: FixtureMismatch[] = [];
+  const failingCursors = new Map<string, { code: string; message: string }>();
+  const cache = new Map<string, CacheEntry>();
+
+  const mismatch = (method: string, detail: string): never => {
+    mismatched.push({ method, detail });
+    throw new FixtureReplayError(MISMATCH, `no recorded exchange in fixture "${fixture.name}" matches ${method} ${detail}`);
+  };
+
+  const take = <K extends FixtureExchange['kind']>(kind: K, matches: (exchange: Extract<FixtureExchange, { kind: K }>) => boolean): Extract<FixtureExchange, { kind: K }> | null => {
+    for (const exchange of fixture.exchanges) {
+      if (exchange.kind !== kind || used.has(exchange.seq)) continue;
+      const typed = exchange as Extract<FixtureExchange, { kind: K }>;
+      if (!matches(typed)) continue;
+      used.add(exchange.seq);
+      return typed;
+    }
+    return null;
+  };
+
+  const lookupSecret = (field: string): string => {
+    const value = Object.hasOwn(caseSecrets, field) ? caseSecrets[field] : undefined;
+    if (typeof value !== 'string') throw new FixtureReplayError('EGRESS_SECRET_UNAVAILABLE', `Secret '${field}' is not in the fixture's case.json secrets`);
+    return value;
+  };
+
+  const http = (payload: unknown): EgressHttpResponse => {
+    if (!isRecord(payload) || typeof payload.method !== 'string' || typeof payload.url !== 'string') {
+      throw new FixtureReplayError('BAD_REQUEST', 'http request must have a method and a url');
+    }
+    const query = isRecord(payload.query) ? payload.query as Record<string, string | string[]> : undefined;
+    const scriptUrl = canonicalRequestUrl(payload.url, query);
+    const url = redactUrl(scriptUrl, secretValues);
+    const bodyEncoding = payload.bodyEncoding === 'base64' ? 'base64' : 'utf8';
+    const body = typeof payload.body === 'string' ? (bodyEncoding === 'utf8' ? redact(payload.body) : payload.body) : null;
+    const method = payload.method;
+    const exchange = take('http', (item) =>
+      item.request.method === method && item.request.url === url && item.request.body === body && (body === null || item.request.bodyEncoding === bodyEncoding));
+    if (!exchange) return mismatch('http', `${method} ${url}${body !== null ? ` with body ${preview(body)}` : ''}`);
+    if (exchange.error) throw new FixtureReplayError(exchange.error.code, exchange.error.message);
+    if (!exchange.response) throw new FixtureReplayError('HOST_CALL_FAILED', 'the recorded exchange has no response');
+    return { status: exchange.response.status, url: scriptUrl, headers: { ...exchange.response.headers }, body: exchange.response.body, bodyEncoding: exchange.response.bodyEncoding };
+  };
+
+  const dbQuery = (payload: unknown): DbQueryResponse => {
+    if (!isRecord(payload) || typeof payload.sql !== 'string') throw new FixtureReplayError('BAD_REQUEST', 'db.query needs sql');
+    const sql = redact(payload.sql);
+    const params = canonicalJson(JSON.parse(redact(JSON.stringify(Array.isArray(payload.params) ? payload.params : []))));
+    const exchange = take('db', (item) => item.sql === sql && canonicalJson(item.params) === params);
+    if (!exchange) return mismatch('db.query', `${preview(sql.replace(/\s+/g, ' ').trim())} with params ${preview(params)}`);
+    const rows = exchange.rows.map((row) => ({ ...row }));
+    const fields = exchange.fields.map((field) => ({ ...field }));
+    if (!exchange.error) return { cursorId: null, fields, rows, done: true };
+    // 查询本身就失败（没有列、没有行）：直接报错；取到一部分后失败：先回已取到的行，下一次 db.next 报错。
+    if (fields.length === 0 && rows.length === 0) throw new FixtureReplayError(exchange.error.code, exchange.error.message);
+    const cursorId = `replay-${exchange.seq}`;
+    failingCursors.set(cursorId, exchange.error);
+    return { cursorId, fields, rows, done: false };
+  };
+
+  const crypto = (payload: unknown): { value: string } => {
+    if (!isRecord(payload) || typeof payload.op !== 'string') throw new FixtureReplayError('BAD_REQUEST', 'crypto request must have an op');
+    const request = JSON.parse(redact(JSON.stringify(payload))) as CryptoRequest;
+    const key = canonicalJson(request);
+    const exchange = take('crypto', (item) => canonicalJson(item.request) === key);
+    if (exchange) return { value: exchange.value };
+    if (request.op === 'hash') {
+      const data = request.data.replace(PLAIN_HANDLE, (_match, field: string) => lookupSecret(field));
+      return { value: createHash(request.algorithm).update(data, 'utf8').digest(request.encoding) };
+    }
+    return mismatch('crypto', `${request.op} ${request.algorithm}`);
+  };
+
+  const call = async (method: HostMethod, payload: unknown): Promise<unknown> => {
+    switch (method) {
+      case 'http':
+        return http(payload);
+      case 'db.query':
+        return dbQuery(payload);
+      case 'db.next': {
+        const cursorId = isRecord(payload) && typeof payload.cursorId === 'string' ? payload.cursorId : '';
+        const error = failingCursors.get(cursorId);
+        if (!error) throw new FixtureReplayError('DB_CURSOR_NOT_FOUND', "The cursor doesn't exist or was closed");
+        failingCursors.delete(cursorId);
+        throw new FixtureReplayError(error.code, error.message);
+      }
+      case 'db.close': {
+        const cursorId = isRecord(payload) && typeof payload.cursorId === 'string' ? payload.cursorId : '';
+        failingCursors.delete(cursorId);
+        return null;
+      }
+      case 'crypto':
+        return crypto(payload);
+      case 'cache.get': {
+        const key = isRecord(payload) && typeof payload.key === 'string' ? payload.key : '';
+        const entry = cache.get(key);
+        if (!entry || Date.parse(entry.expiresAt) <= Date.now()) return null;
+        return entry;
+      }
+      case 'cache.set': {
+        if (!isRecord(payload) || typeof payload.key !== 'string' || typeof payload.value !== 'string' || typeof payload.ttlSeconds !== 'number') {
+          throw new FixtureReplayError('BAD_REQUEST', 'cache.set needs key, value and ttlSeconds');
+        }
+        cache.set(payload.key, { value: payload.value, expiresAt: new Date(Date.now() + payload.ttlSeconds * 1000).toISOString() });
+        return null;
+      }
+      case 'secret.reveal': {
+        const field = isRecord(payload) && typeof payload.field === 'string' ? payload.field : '';
+        return { value: lookupSecret(field) };
+      }
+      default:
+        throw new FixtureReplayError('HOST_METHOD_UNSUPPORTED', `fixture replay does not answer ${method}`);
+    }
+  };
+
+  return {
+    call,
+    redact,
+    async close() {
+      failingCursors.clear();
+    },
+    unused() {
+      return fixture.exchanges.filter((exchange) => !used.has(exchange.seq)).map((exchange) => JSON.parse(JSON.stringify(exchange)) as FixtureExchange);
+    },
+    mismatches() {
+      return mismatched.map((item) => ({ ...item }));
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 回放用例
+
+function countBy<T extends { table: string }>(items: readonly T[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const item of items) counts[item.table] = (counts[item.table] ?? 0) + 1;
+  return counts;
+}
+
+function exchangeSummary(exchange: FixtureExchange): string {
+  switch (exchange.kind) {
+    case 'http':
+      return `${exchange.request.method} ${exchange.request.url}`;
+    case 'db':
+      return preview(exchange.sql.replace(/\s+/g, ' ').trim());
+    case 'crypto':
+      return `${exchange.request.op} ${exchange.request.algorithm}`;
+  }
+}
+
+/** 用例范围内的表与消息里的范围说明；能力不在描述里时 tables 为 null。 */
+function scopeOf(descriptor: ConnectorDescriptor, fixtureCase: FixtureCase): { tables: Record<string, TableDescriptor> | null; scope: string } {
+  if (fixtureCase.kind === 'pull' || fixtureCase.kind === 'suggest') {
+    const stream = Object.hasOwn(descriptor.streams, fixtureCase.stream) ? descriptor.streams[fixtureCase.stream] : undefined;
+    return { tables: stream ? stream.tables : null, scope: `stream "${fixtureCase.stream}"` };
+  }
+  if (fixtureCase.kind === 'push') {
+    const push = Object.hasOwn(descriptor.pushes, fixtureCase.push) ? descriptor.pushes[fixtureCase.push] : undefined;
+    return { tables: push ? push.tables : null, scope: `push "${fixtureCase.push}"` };
+  }
+  return { tables: null, scope: `operation "${fixtureCase.operation}"` };
+}
+
+function capabilityKnown(descriptor: ConnectorDescriptor, fixtureCase: FixtureCase): boolean {
+  switch (fixtureCase.kind) {
+    case 'pull':
+    case 'suggest':
+      return Object.hasOwn(descriptor.streams, fixtureCase.stream);
+    case 'push':
+      return Object.hasOwn(descriptor.pushes, fixtureCase.push);
+    case 'operation':
+      return Object.hasOwn(descriptor.operations, fixtureCase.operation);
+  }
+}
+
+function sameCounts(expected: Record<string, number>, actual: Record<string, number>): string[] {
+  return Object.entries(expected)
+    .filter(([table, count]) => (actual[table] ?? 0) !== count)
+    .map(([table, count]) => `${table}: expected ${count}, got ${actual[table] ?? 0}`);
+}
+
+/** 两个 JSON 值的逐字段差异（路径形如 `output.items[0].qty`）；相同时为空。 */
+function jsonDiff(expected: unknown, actual: unknown, path: string, out: Array<{ path: string; expected: unknown; actual: unknown }>): void {
+  if (isRecord(expected) && isRecord(actual)) {
+    for (const key of new Set([...Object.keys(expected), ...Object.keys(actual)])) {
+      jsonDiff(expected[key], actual[key], `${path}.${key}`, out);
+    }
+    return;
+  }
+  if (Array.isArray(expected) && Array.isArray(actual)) {
+    for (let index = 0; index < Math.max(expected.length, actual.length); index += 1) {
+      jsonDiff(expected[index], actual[index], `${path}[${index}]`, out);
+    }
+    return;
+  }
+  if (canonicalJson(expected) !== canonicalJson(actual)) out.push({ path, expected: expected ?? null, actual: actual ?? null });
+}
+
+function checkOperationExpectation(fixtureCase: Extract<FixtureCase, { kind: 'operation' }>, operation: GuestOperationResult | undefined): ComplianceFinding[] {
+  const expect = fixtureCase.expect;
+  const failed = (message: string, detail: unknown): ComplianceFinding[] => [{ code: 'EXPECTATION_FAILED', message, detail }];
+  if (!operation) return failed('the operation returned no result', null);
+  if ('ok' in expect) {
+    if (!operation.ok) {
+      return failed(`expected the operation to succeed, got ${operation.code}: ${operation.message}`, { expected: 'ok', actual: { code: operation.code, message: operation.message } });
+    }
+    const actual = 'output' in operation ? operation.output : null;
+    const differences: Array<{ path: string; expected: unknown; actual: unknown }> = [];
+    jsonDiff(expect.ok, actual, 'output', differences);
+    if (differences.length === 0) return [];
+    return failed(`expect.ok does not match the output (${differences.map((item) => item.path).join(', ')})`, { expected: expect.ok, actual, differences });
+  }
+  if (operation.ok) return failed(`expected error ${expect.error}, but the operation succeeded`, { expected: expect.error, actual: 'ok' });
+  if (operation.code !== expect.error) {
+    return failed(`expected error ${expect.error}, got ${operation.code}: ${operation.message}`, { expected: expect.error, actual: { code: operation.code, message: operation.message } });
+  }
+  return [];
+}
+
+function sortedColumns(columns: readonly SuggestedColumn[]): string[] {
+  return columns.map((column) => canonicalJson(column)).sort();
+}
+
+function checkSuggestExpectation(fixtureCase: Extract<FixtureCase, { kind: 'suggest' }>, columns: SuggestedColumn[] | undefined): ComplianceFinding[] {
+  const actual = columns ?? [];
+  const expected = sortedColumns(fixtureCase.expect.columns);
+  const got = sortedColumns(actual);
+  if (expected.length === got.length && expected.every((item, index) => item === got[index])) return [];
+  const expectedNames = fixtureCase.expect.columns.map((column) => column.name).sort();
+  const actualNames = actual.map((column) => column.name).sort();
+  return [{
+    code: 'EXPECTATION_FAILED',
+    message: `expect.columns does not match the suggested columns (expected [${expectedNames.join(', ')}], got [${actualNames.join(', ')}])`,
+    detail: { expected: fixtureCase.expect.columns, actual },
+  }];
+}
+
+function checkExpectation(fixture: LoadedFixture, result: LocalRunResult): ComplianceFinding[] {
+  if (fixture.case.kind === 'operation') return checkOperationExpectation(fixture.case, result.operation);
+  if (fixture.case.kind === 'suggest') return checkSuggestExpectation(fixture.case, result.suggest);
+  const expect = fixture.case.expect;
+  if (!expect) return [];
+  const findings: ComplianceFinding[] = [];
+  const failed = (what: string, problems: string[], detail: unknown): void => {
+    findings.push({ code: 'EXPECTATION_FAILED', message: `expect.${what} does not match (${problems.join('; ')})`, detail });
+  };
+  if (expect.records) {
+    const actual = countBy(result.records);
+    const problems = sameCounts(expect.records, actual);
+    if (problems.length > 0) failed('records', problems, { expected: expect.records, actual });
+  }
+  if (expect.removals) {
+    const actual = countBy(result.removals);
+    const problems = sameCounts(expect.removals, actual);
+    if (problems.length > 0) failed('removals', problems, { expected: expect.removals, actual });
+  }
+  if (expect.rejected !== undefined && expect.rejected !== result.rejected.length) {
+    failed('rejected', [`expected ${expect.rejected}, got ${result.rejected.length}`], { expected: expect.rejected, actual: result.rejected.length });
+  }
+  if (expect.checkpoints !== undefined && expect.checkpoints !== result.checkpoints.length) {
+    failed('checkpoints', [`expected ${expect.checkpoints}, got ${result.checkpoints.length}`], { expected: expect.checkpoints, actual: result.checkpoints.length });
+  }
+  return findings;
+}
+
+/** 回放一个用例（见文件头）。 */
+export async function runFixture(executor: GuestExecutor, descriptor: ConnectorDescriptor, fixture: LoadedFixture, options: RunFixtureOptions = {}): Promise<FixtureCaseResult> {
+  const fixtureCase = fixture.case;
+  const config = fixtureCase.config;
+  const secretFields = Object.keys(fixtureCase.secrets ?? {});
+  const base = { capability: fixture.capability, name: fixture.name, kind: fixtureCase.kind };
+  const emptyStats = { records: {}, removals: {}, checkpoints: 0, rejected: 0 };
+  if (!capabilityKnown(descriptor, fixtureCase)) {
+    const message = `${fixture.capability} is not in the connector descriptor`;
+    return { ...base, ok: false, findings: [], stats: emptyStats, error: { code: 'CAPABILITY_UNKNOWN', message, stack: null } };
+  }
+  const { tables, scope } = scopeOf(descriptor, fixtureCase);
+
+  const execute = async (job: GuestJob, limit?: number): Promise<{ host: ReplayHost; result: LocalRunResult }> => {
+    const host = createReplayHost(fixture);
+    try {
+      const result = await executor.run(job, host, {
+        ...(limit !== undefined ? { limit } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+      });
+      return { host, result };
+    } finally {
+      await host.close();
+    }
+  };
+
+  let main: { host: ReplayHost; result: LocalRunResult };
+  let rerun: LocalRunResult | undefined;
+  switch (fixtureCase.kind) {
+    case 'pull': {
+      const job: GuestJob = {
+        kind: 'pull', config, secretFields, stream: fixtureCase.stream, mode: fixtureCase.mode, state: fixtureCase.state ?? null,
+        streamConfig: fixtureCase.streamConfig ?? {}, tables: Object.keys(tables ?? {}),
+      };
+      main = await execute(job, fixtureCase.limit);
+      if (fixtureCase.mode === 'full' && main.result.error === null) rerun = (await execute(job, fixtureCase.limit)).result;
+      break;
+    }
+    case 'push':
+      main = await execute({
+        kind: 'push', config, secretFields,
+        requests: fixture.requests.map((request) => ({ ...request, headers: { ...request.headers }, push: fixtureCase.push })),
+      });
+      break;
+    case 'operation':
+      main = await execute({
+        kind: 'operation', phase: 'run', config, secretFields,
+        operation: fixtureCase.operation, params: fixtureCase.params, idempotencyKey: fixtureCase.idempotencyKey,
+      });
+      break;
+    case 'suggest':
+      main = await execute({ kind: 'suggest', config, secretFields, stream: fixtureCase.stream, table: fixtureCase.table });
+      break;
+  }
+
+  const result = main.result;
+  const error = result.error;
+  const findings: ComplianceFinding[] = [];
+  for (const item of main.host.mismatches()) {
+    findings.push({ code: 'FIXTURE_EXCHANGE_MISMATCH', message: `no recorded exchange matches ${item.method} ${item.detail}`, detail: item });
+  }
+  if (error === null) {
+    // 记录合规只对产出记录的用例有意义；操作与建议列用例只比较期望。未声明字段排在最前（失败原因取第一条）。
+    if (fixtureCase.kind === 'pull' || fixtureCase.kind === 'push') {
+      findings.unshift(...checkCompliance({
+        tables, scope, ...(fixtureCase.kind === 'pull' ? { mode: fixtureCase.mode } : {}), result, ...(rerun ? { rerun } : {}),
+      }));
+    }
+    for (const exchange of main.host.unused()) {
+      findings.push({
+        code: 'FIXTURE_EXCHANGE_UNUSED',
+        message: `recorded exchange ${exchange.seq} (${exchange.kind} ${exchangeSummary(exchange)}) was not used`,
+        detail: { seq: exchange.seq, kind: exchange.kind },
+      });
+    }
+    findings.push(...checkExpectation(fixture, result));
+  }
+
+  return {
+    ...base,
+    ok: error === null && findings.every((finding) => finding.code === 'FIXTURE_EXCHANGE_UNUSED'),
+    findings,
+    stats: { records: countBy(result.records), removals: countBy(result.removals), checkpoints: result.checkpoints.length, rejected: result.rejected.length },
+    error,
+  };
+}
+
+/** 解析用例文件（格式错误抛 `FixtureFormatError`）后逐个回放，按能力与用例名排序。 */
+export async function runFixtures(executor: GuestExecutor, descriptor: ConnectorDescriptor, files: ConnectorFixtureFile[], options: RunFixtureOptions = {}): Promise<FixtureCaseResult[]> {
+  const results: FixtureCaseResult[] = [];
+  for (const fixture of parseFixtures(files)) results.push(await runFixture(executor, descriptor, fixture, options));
+  return results;
+}

package/src/testing/run-tests.ts

@@ -0,0 +1,115 @@
+/**
+ * 跑连接器的测试用例并统计覆盖（`runTests` 给作者与 CLI，`runConnectorTests` 给只有文件的调用方，如 runner 的 `fixture_test`）。
+ *
+ * 覆盖口径：描述里的每个数据流、推送、操作（能力，形如 `streams/orders`）在它的 `tests/` 下至少有一个用例才算覆盖；
+ * 数据流目录下的建议列用例（`"kind": "suggest"`）照常运行，但不计入覆盖。
+ * 发布门禁另要求每个连接器操作至少有一个成功用例（`expect.ok`）和一个被拒绝的用例（`expect.error = 'REJECTED'`），
+ * 缺的列在 `operationCases`。
+ * `ok` 为 true 当且仅当所有运行的用例都通过、没有未覆盖的能力、`operationCases` 为空。
+ */
+import type { ConnectorDescriptor } from '../descriptor';
+import { createVmExecutor, type VmExecutorOptions } from './engine';
+import { parseFixtures, type ConnectorFixtureFile, type LoadedFixture } from './fixtures';
+import { runFixture, type FixtureCaseResult } from './replay';
+import type { LocalConnector } from './source-loader';
+import type { GuestExecutor } from './types';
+
+export interface TestReport {
+  ok: boolean;
+  cases: Array<{ capability: string; name: string; ok: boolean; failure: { code: string; message: string } | null }>;
+  covered: string[];
+  uncovered: string[];
+  /** 缺成功用例（`ok`）或拒绝用例（`REJECTED`）的连接器操作；都齐时为 []。 */
+  operationCases: OperationCaseGap[];
+}
+
+export interface OperationCaseGap { operation: string; missing: Array<'ok' | 'REJECTED'> }
+
+export interface RunTestsOptions {
+  /**
+   * 只跑这些用例：每项是 `<能力>/<用例名>`（如 `streams/orders/first-page`）或能力（如 `streams/orders`，跑它的全部用例）。
+   * 覆盖统计不受影响（按全部用例算）。
+   */
+  cases?: string[];
+  /** 每次执行的超时（毫秒）。 */
+  timeoutMs?: number;
+}
+
+/** 描述里的全部能力，按数据流、推送、操作的顺序。 */
+export function descriptorCapabilities(descriptor: ConnectorDescriptor): string[] {
+  return [
+    ...Object.keys(descriptor.streams).map((name) => `streams/${name}`),
+    ...Object.keys(descriptor.pushes).map((name) => `pushes/${name}`),
+    ...Object.keys(descriptor.operations).map((name) => `operations/${name}`),
+  ];
+}
+
+/** 覆盖统计：有非建议列用例的能力为已覆盖。 */
+export function testCoverage(descriptor: ConnectorDescriptor, fixtures: ReadonlyArray<Pick<LoadedFixture, 'capability' | 'case'>>): { covered: string[]; uncovered: string[] } {
+  const tested = new Set(fixtures.filter((fixture) => fixture.case.kind !== 'suggest').map((fixture) => fixture.capability));
+  const capabilities = descriptorCapabilities(descriptor);
+  return { covered: capabilities.filter((item) => tested.has(item)), uncovered: capabilities.filter((item) => !tested.has(item)) };
+}
+
+/** 每个声明的连接器操作缺哪种用例：至少一个 `expect.ok` 和一个 `expect.error = 'REJECTED'`。 */
+export function operationCaseGaps(descriptor: ConnectorDescriptor, fixtures: ReadonlyArray<Pick<LoadedFixture, 'case'>>): OperationCaseGap[] {
+  const gaps: OperationCaseGap[] = [];
+  for (const operation of Object.keys(descriptor.operations)) {
+    const expects = fixtures.flatMap((fixture) => (fixture.case.kind === 'operation' && fixture.case.operation === operation ? [fixture.case.expect] : []));
+    const missing: OperationCaseGap['missing'] = [];
+    if (!expects.some((expect) => 'ok' in expect)) missing.push('ok');
+    if (!expects.some((expect) => 'error' in expect && expect.error === 'REJECTED')) missing.push('REJECTED');
+    if (missing.length > 0) gaps.push({ operation, missing });
+  }
+  return gaps;
+}
+
+/** 用例的失败原因：运行错误优先，其次是第一条不是 `FIXTURE_EXCHANGE_UNUSED` 的检查结果。 */
+function failureOf(result: FixtureCaseResult): { code: string; message: string } | null {
+  if (result.ok) return null;
+  if (result.error) return { code: result.error.code, message: result.error.message };
+  const finding = result.findings.find((item) => item.code !== 'FIXTURE_EXCHANGE_UNUSED');
+  return finding ? { code: finding.code, message: finding.message } : { code: 'TEST_FAILED', message: 'the test case failed' };
+}
+
+function selected(fixture: LoadedFixture, cases: readonly string[] | undefined): boolean {
+  if (!cases) return true;
+  const id = `${fixture.capability}/${fixture.name}`;
+  return cases.some((item) => item === id || item === fixture.capability);
+}
+
+/**
+ * 解析用例文件（格式错误抛 `FixtureFormatError`），逐个回放，返回报告与每个用例的完整结果。
+ * `files` 是能力目录下 `tests/` 里的文件（路径相对源码根目录）。
+ */
+export async function runConnectorTests(
+  executor: GuestExecutor,
+  descriptor: ConnectorDescriptor,
+  files: ConnectorFixtureFile[],
+  options: RunTestsOptions = {},
+): Promise<{ report: TestReport; results: FixtureCaseResult[] }> {
+  const fixtures = parseFixtures(files);
+  const results: FixtureCaseResult[] = [];
+  for (const fixture of fixtures) {
+    if (!selected(fixture, options.cases)) continue;
+    results.push(await runFixture(executor, descriptor, fixture, options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}));
+  }
+  const { covered, uncovered } = testCoverage(descriptor, fixtures);
+  const operationCases = operationCaseGaps(descriptor, fixtures);
+  const cases = results.map((result) => ({ capability: result.capability, name: result.name, ok: result.ok, failure: failureOf(result) }));
+  const ok = cases.every((item) => item.ok) && uncovered.length === 0 && operationCases.length === 0;
+  return { report: { ok, cases, covered, uncovered, operationCases }, results };
+}
+
+/**
+ * 跑本地连接器的全部测试用例（与平台 runner 同一个 guest 会话，在空环境变量的子进程里执行）。
+ * `options.executor` 可换成别的执行器（测试用）。
+ */
+export async function runTests(
+  connector: LocalConnector,
+  options: RunTestsOptions & { executor?: GuestExecutor; vm?: VmExecutorOptions } = {},
+): Promise<TestReport> {
+  const executor = options.executor ?? createVmExecutor(connector, options.vm);
+  const { report } = await runConnectorTests(executor, connector.descriptor, connector.testFiles, options);
+  return report;
+}

package/src/testing/schema.ts

@@ -0,0 +1,70 @@
+/**
+ * 由记录推断列类型（预览面板的「推断结构」、合规检查共用）。纯函数，不依赖 Node 模块（meta 与 UI 都可能用）。
+ */
+
+export type InferredColumnType = 'string' | 'number' | 'boolean' | 'timestamp' | 'json' | 'null';
+
+/** ISO-8601 日期时间（偏移可省略，省略时按 UTC 解释）。 */
+const ISO_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-]\d{2}(?::?\d{2})?)?$/i;
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+function validDate(year: number, month: number, day: number): boolean {
+  return month >= 1 && month <= 12 && day >= 1 && day <= new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+/** ISO-8601 日期时间字符串 → 毫秒时刻；不是时返回 null。只有日期的写法不算（推断为 `string`）。 */
+export function parseIsoDateTime(value: string): number | null {
+  const match = ISO_DATE_TIME.exec(value);
+  if (!match) return null;
+  const [, year, month, day, hour, minute, second, offset] = match;
+  if (!validDate(Number(year), Number(month), Number(day)) || Number(hour) > 23 || Number(minute) > 59 || Number(second ?? '0') > 59) return null;
+  const local = value.slice(0, value.length - (offset?.length ?? 0)).replace(' ', 'T').replace(/(\.\d{3})\d+$/, '$1');
+  let zone = 'Z';
+  if (offset !== undefined && offset.toUpperCase() !== 'Z') {
+    const digits = offset.slice(1).replace(':', '');
+    zone = `${offset[0]}${digits.slice(0, 2)}:${digits.length > 2 ? digits.slice(2) : '00'}`;
+  }
+  const parsed = Date.parse(`${local}${zone}`);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+/** ISO-8601 时间字符串（日期时间，或只有日期）→ 毫秒时刻；断点单调判定用。 */
+export function parseIsoInstant(value: string): number | null {
+  const dateTime = parseIsoDateTime(value);
+  if (dateTime !== null) return dateTime;
+  const match = ISO_DATE.exec(value);
+  if (!match || !validDate(Number(match[1]), Number(match[2]), Number(match[3]))) return null;
+  return Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+}
+
+function kindOf(value: unknown): Exclude<InferredColumnType, 'null'> | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'number' || typeof value === 'bigint') return 'number';
+  if (typeof value === 'boolean') return 'boolean';
+  if (typeof value === 'string') return parseIsoDateTime(value) !== null ? 'timestamp' : 'string';
+  return 'json';
+}
+
+/**
+ * 列 → 推断类型：空值不参与；全是空值为 `'null'`；字符串全是 ISO 日期时间为 `'timestamp'`，混有普通字符串为 `'string'`；
+ * 对象 / 数组或多种类型混用为 `'json'`。列按首次出现的顺序。
+ */
+export function inferRecordSchema(rows: Array<Record<string, unknown>>): Record<string, InferredColumnType> {
+  const seen = new Map<string, Set<Exclude<InferredColumnType, 'null'>>>();
+  for (const row of rows) {
+    for (const [column, value] of Object.entries(row)) {
+      const kinds = seen.get(column) ?? new Set();
+      const kind = kindOf(value);
+      if (kind) kinds.add(kind);
+      seen.set(column, kinds);
+    }
+  }
+  const schema: Record<string, InferredColumnType> = {};
+  for (const [column, kinds] of seen) {
+    if (kinds.size === 0) schema[column] = 'null';
+    else if (kinds.size === 1) schema[column] = [...kinds][0] ?? 'json';
+    else if (kinds.size === 2 && kinds.has('string') && kinds.has('timestamp')) schema[column] = 'string';
+    else schema[column] = 'json';
+  }
+  return schema;
+}