@deepexi/datasense-connector 3.0.1 → 3.1.0

package/test/testing/engine.test.ts

@@ -0,0 +1,283 @@
+/**
+ * 本地执行器：vm 子进程与进程内执行的结果一致、与 runner 的 guest 会话一致；limit 截断；超时杀子进程；子进程环境变量为空。
+ */
+import { afterAll, describe, expect, spyOn, test } from 'bun:test';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import ts from 'typescript';
+import { defineStream, type ConnectorDescriptor } from '../../src';
+import type { GuestJob, GuestPullBatch } from '../../src/runtime';
+import {
+  createInProcessExecutor, createLocalGateway, createVmExecutor, loadLocalConnector, runStream, type LocalRunResult,
+} from '../../src/testing';
+import { VM_CHILD_ENTRY } from '../../src/testing/engine';
+import { HTTP_PULL_DIR } from '../fixtures/acceptance';
+import { descriptor, push, stream, table } from '../fixtures/descriptor';
+import { runGuest } from '../runtime/helpers';
+
+const CONFIG = { baseUrl: 'https://api.example.com/v1' };
+const SECRETS = { token: 'tok-secret-1' };
+
+const PAGES: Record<string, { items: Array<{ id: string; name: string; updatedAt: string }>; nextCursor: string | null }> = {
+  first: {
+    items: [
+      { id: 'a', name: 'Alpha', updatedAt: '2026-10-01T00:00:00.000Z' },
+      { id: 'b', name: 'Beta', updatedAt: '2026-10-02T00:00:00.000Z' },
+    ],
+    nextCursor: 'p2',
+  },
+  p2: { items: [{ id: 'c', name: 'Gamma', updatedAt: '2026-10-03T00:00:00.000Z' }], nextCursor: null },
+};
+
+/** 假上游：没有 cursor 回第一页，`cursor=p2` 回第二页；记下收到的鉴权头。 */
+function twoPageFetch(seen: string[]): typeof fetch {
+  const impl = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const url = new URL(typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url);
+    seen.push(new Headers(init?.headers).get('authorization') ?? '');
+    return Response.json(PAGES[url.searchParams.get('cursor') ?? 'first']);
+  };
+  return impl as typeof fetch;
+}
+
+function gateway(seen: string[] = []) {
+  return createLocalGateway({ hosts: ['api.example.com'], secrets: SECRETS, fetch: twoPageFetch(seen) });
+}
+
+const EXPECTED_RECORDS = [
+  { table: 'items', row: { id: 'a', name: 'Alpha', updated_at: '2026-10-01T00:00:00.000Z' } },
+  { table: 'items', row: { id: 'b', name: 'Beta', updated_at: '2026-10-02T00:00:00.000Z' } },
+  { table: 'items', row: { id: 'c', name: 'Gamma', updated_at: '2026-10-03T00:00:00.000Z' } },
+];
+const EXPECTED_STATES = [{ updatedSince: '2026-10-02T00:00:00.000Z', cursor: 'p2' }, { updatedSince: '2026-10-03T00:00:00.000Z' }];
+
+const pullJob = (overrides: Partial<Extract<GuestJob, { kind: 'pull' }>> = {}): GuestJob => ({
+  kind: 'pull', config: CONFIG, secretFields: ['token'], stream: 'items', mode: 'full', state: null, streamConfig: {}, tables: ['items'], ...overrides,
+});
+
+const normalizeLogs = (result: LocalRunResult): LocalRunResult => ({ ...result, logs: result.logs.map((log) => ({ ...log, at: '<at>' })) });
+
+const temps: string[] = [];
+
+async function tempDir(prefix: string): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), prefix));
+  temps.push(dir);
+  return dir;
+}
+
+const PUSH_DESCRIPTOR = (name: string, tables: ConnectorDescriptor['pushes'][string]['tables']): ConnectorDescriptor =>
+  descriptor({ name, version: '0.0.1', pushes: { default: push(tables) } });
+
+/** 写一个只有默认推送的连接器项目（`pushes/default/index.ts` 为 `source`，描述手写进 `.ontos/descriptor.json`）。 */
+async function pushProject(name: string, tables: ConnectorDescriptor['pushes'][string]['tables'], source: string): Promise<string> {
+  const dir = await tempDir(`sdk-engine-${name}-`);
+  await mkdir(path.join(dir, '.ontos'));
+  await mkdir(path.join(dir, 'pushes', 'default'), { recursive: true });
+  await writeFile(path.join(dir, '.ontos', 'descriptor.json'), JSON.stringify(PUSH_DESCRIPTOR(name, tables)));
+  await writeFile(path.join(dir, 'pushes', 'default', 'index.ts'), source);
+  await writeFile(path.join(dir, 'package.json'), JSON.stringify({ dependencies: { '@deepexi/datasense-connector': '^3.0.0' } }));
+  return dir;
+}
+
+const SPIN_SOURCE = `import { definePush } from '@deepexi/datasense-connector';
+export default definePush('default', { map() { for (;;) { /* 死循环，等超时 */ } } });
+`;
+
+const ESCAPE_SOURCE = `import { definePush } from '@deepexi/datasense-connector';
+
+declare const process: { env: Record<string, string> } | undefined;
+declare const Bun: unknown;
+
+/** 每个请求体是一个探测名，map 记录探测结果，供测试断言沙箱里拿不到这些能力。 */
+export default definePush('default', {
+  map(ctx: { record(table: string, row: Record<string, unknown>): void }, req: { body: string }) {
+    const probes: Record<string, () => unknown> = {
+      process: () => typeof process === 'undefined' ? 'absent' : JSON.stringify(process.env),
+      require: () => typeof (globalThis as { require?: unknown }).require === 'undefined' ? 'absent' : 'present',
+      bun: () => typeof Bun === 'undefined' ? 'absent' : 'present',
+    };
+    ctx.record('probe', { name: req.body, result: String(probes[req.body]!()) });
+  },
+});
+`;
+
+const spinProject = (name: string) => pushProject(name, {}, SPIN_SOURCE);
+const escapeProject = () => pushProject('escape', { probe: table({ name: 'string', result: 'string' }, ['name']) }, ESCAPE_SOURCE);
+
+/** 替身子进程入口：先把自己的 pid 与环境变量名写进文件，再加载真正的子进程入口。 */
+async function probeChildEntry(): Promise<{ entry: string; report: () => Promise<{ pid: number; envKeys: string[] }> }> {
+  const dir = await tempDir('sdk-engine-probe-');
+  const reportFile = path.join(dir, 'report.json');
+  const entry = path.join(dir, 'probe-child.ts');
+  await writeFile(entry, [
+    "import { writeFileSync } from 'node:fs';",
+    `writeFileSync(${JSON.stringify(reportFile)}, JSON.stringify({ pid: process.pid, envKeys: Object.keys(process.env) }));`,
+    `await import(${JSON.stringify(VM_CHILD_ENTRY)});`,
+  ].join('\n'));
+  return { entry, report: async () => JSON.parse(await readFile(reportFile, 'utf8')) as { pid: number; envKeys: string[] } };
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+afterAll(async () => {
+  await Promise.all(temps.map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+describe('the HTTP acceptance connector', () => {
+  test('vm execution matches the runner guest session (records, checkpoints, substituted credentials)', async () => {
+    const connector = await loadLocalConnector(HTTP_PULL_DIR, { typescript: ts });
+    expect(connector.name).toBe('http_pull');
+    const seen: string[] = [];
+    const order: string[] = [];
+    const inner = gateway(seen);
+    const host = {
+      call(method: Parameters<typeof inner.call>[0], payload: unknown) {
+        order.push(method);
+        return inner.call(method, payload);
+      },
+      close: () => inner.close(),
+    };
+    const vm = await createVmExecutor(connector).run(pullJob(), host);
+    expect(vm.error).toBeNull();
+    expect(vm.records).toEqual(EXPECTED_RECORDS);
+    expect(vm.checkpoints.map((checkpoint) => checkpoint.state)).toEqual(EXPECTED_STATES);
+    expect(vm.checkpoints.map((checkpoint) => checkpoint.seq)).toEqual([1, 2]);
+    expect(vm.logs.map((log) => log.message)).toEqual(['page 1: 2 item(s), next cursor p2', 'page 2: 1 item(s), next cursor none']);
+    expect(seen).toEqual(['Bearer tok-secret-1', 'Bearer tok-secret-1']);
+    // 不再有 definition / declaration：宿主只收到出站调用
+    expect(order).toEqual(['http', 'http']);
+
+    // runner 路径：同一份打包串交给 runner 用的 guest 会话
+    const runnerHost = gateway();
+    const runner = await runGuest({
+      code: connector.code,
+      job: pullJob(),
+      expect: { name: connector.name, version: connector.version },
+      host: { http: (payload) => runnerHost.call('http', payload), emit: () => null },
+    });
+    expect(runner.outcome.type).toBe('result');
+    const batches = runner.calls.filter((call) => call.method === 'emit').map((call) => call.payload as GuestPullBatch);
+    expect(batches.flatMap((batch) => batch.records)).toEqual(vm.records);
+    expect(batches.flatMap((batch) => (batch.checkpoint ? [batch.checkpoint.state] : []))).toEqual(vm.checkpoints.map((checkpoint) => checkpoint.state));
+  });
+
+  test('runStream in process gives the same result as the vm, field by field', async () => {
+    const connector = await loadLocalConnector(HTTP_PULL_DIR, { typescript: ts });
+    const items = (await import(path.join(HTTP_PULL_DIR, 'streams/items/index.ts')) as { default: unknown }).default;
+    const local = await runStream({ descriptor: connector.descriptor, implementations: { streams: { items } } }, { stream: 'items', config: CONFIG, host: gateway() });
+    const vm = await createVmExecutor(connector).run(pullJob(), gateway());
+    expect(local.error).toBeNull();
+    expect(local.records).toEqual(EXPECTED_RECORDS);
+    expect(local.stopped).toBe(false);
+    expect(normalizeLogs(local)).toEqual(normalizeLogs(vm));
+  });
+
+  test('a pull rejects records for tables outside the stream with SCHEMA_ERROR', async () => {
+    const module = {
+      descriptor: descriptor({ name: 'stray', streams: { items: stream({ items: table({ id: 'string' }, ['id']) }) } }),
+      implementations: { streams: { items: defineStream('items', async function* (ctx) { yield ctx.record('other' as never, { id: 'x' } as never); }) } },
+    };
+    const result = await runStream(module, { stream: 'items', config: {}, host: createLocalGateway({ hosts: [], secrets: {} }) });
+    expect(result.records).toEqual([]);
+    expect(result.error?.code).toBe('SCHEMA_ERROR');
+  });
+});
+
+describe('limit', () => {
+  const TEN = {
+    descriptor: descriptor({ name: 'ten', streams: { items: stream({ item: table({ id: 'integer' }, ['id']) }, { syncModes: ['full'] }) } }),
+    implementations: {
+      streams: {
+        items: defineStream('items', async function* (ctx) {
+          for (let id = 0; id < 10; id += 1) {
+            yield ctx.record('item', { id });
+            if (id % 4 === 3) yield ctx.checkpoint({ after: id });
+          }
+          yield ctx.checkpoint({ after: 'end' });
+        }),
+      },
+    },
+  };
+
+  test('limit 3 of 10 records: 3 records and stopped', async () => {
+    const result = await runStream(TEN, { stream: 'items', config: {}, limit: 3, host: createLocalGateway({ hosts: [], secrets: {} }) });
+    expect(result.error).toBeNull();
+    expect(result.records.map((record) => record.row.id)).toEqual([0, 1, 2]);
+    expect(result.stopped).toBe(true);
+    // 断点跨过了被截掉的记录，不记
+    expect(result.checkpoints).toEqual([]);
+  });
+
+  test('without a limit every record and checkpoint is kept', async () => {
+    const result = await createInProcessExecutor(TEN).run(
+      { kind: 'pull', config: {}, secretFields: [], stream: 'items', mode: 'full', state: null, streamConfig: {}, tables: ['item'] },
+      createLocalGateway({ hosts: [], secrets: {} }),
+    );
+    expect(result.records).toHaveLength(10);
+    expect(result.stopped).toBe(false);
+    expect(result.checkpoints.map((checkpoint) => checkpoint.state)).toEqual([{ after: 3 }, { after: 7 }, { after: 'end' }]);
+  });
+});
+
+describe('vm child process', () => {
+  const pushJob = (bodies: string[]): GuestJob => ({
+    kind: 'push', config: {}, secretFields: [],
+    requests: bodies.map((body, index) => ({
+      requestId: `r${index}`, push: 'default', receivedAt: '2026-10-25T00:00:00.000Z', headers: { 'content-type': 'text/plain' }, body,
+    })),
+  });
+
+  test('an async infinite loop ends with TIMEOUT within 2-5 seconds and the child is gone; the child env is empty', async () => {
+    const source = await loadLocalConnector(await spinProject('spin'), { typescript: ts });
+    const probe = await probeChildEntry();
+    const startedAt = Date.now();
+    const result = await createVmExecutor(source, { childEntry: probe.entry }).run(pushJob(['x']), createLocalGateway({ hosts: [], secrets: {} }), { timeoutMs: 2000 });
+    const elapsed = Date.now() - startedAt;
+    expect(result.error?.code).toBe('TIMEOUT');
+    expect(elapsed).toBeGreaterThanOrEqual(2000);
+    expect(elapsed).toBeLessThan(5000);
+    const report = await probe.report();
+    expect(isAlive(report.pid)).toBe(false);
+    expect(report.envKeys).toEqual([]);
+  }, 10_000);
+
+  test('connector code in the vm cannot reach process, require or Bun', async () => {
+    const source = await loadLocalConnector(await escapeProject(), { typescript: ts });
+    const result = await createVmExecutor(source).run(pushJob(['process', 'require', 'bun']), createLocalGateway({ hosts: [], secrets: {} }));
+    expect(result.error).toBeNull();
+    expect(result.records.map((record) => record.row)).toEqual([
+      { name: 'process', result: 'absent' },
+      { name: 'require', result: 'absent' },
+      { name: 'bun', result: 'absent' },
+    ]);
+  });
+
+  test('whatever the child writes to stdout goes to the parent stderr, not stdout', async () => {
+    const source = await loadLocalConnector(await spinProject('stdout'), { typescript: ts });
+    const dir = await tempDir('sdk-engine-stdout-');
+    const entry = path.join(dir, 'noisy-child.ts');
+    await writeFile(entry, [
+      "process.stdout.write('noise-from-child\\n');",
+      `await import(${JSON.stringify(VM_CHILD_ENTRY)});`,
+    ].join('\n'));
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+    const outSpy = spyOn(process.stdout, 'write').mockImplementation(((chunk: string | Uint8Array) => { stdout.push(String(chunk)); return true; }) as typeof process.stdout.write);
+    const errSpy = spyOn(process.stderr, 'write').mockImplementation(((chunk: string | Uint8Array) => { stderr.push(String(chunk)); return true; }) as typeof process.stderr.write);
+    try {
+      await createVmExecutor(source, { childEntry: entry }).run(pushJob(['x']), createLocalGateway({ hosts: [], secrets: {} }), { timeoutMs: 1500 });
+    } finally {
+      outSpy.mockRestore();
+      errSpy.mockRestore();
+    }
+    expect(stderr.join('')).toContain('noise-from-child');
+    expect(stdout.join('')).not.toContain('noise-from-child');
+  }, 10_000);
+});

package/test/testing/fixtures.test.ts

@@ -0,0 +1,221 @@
+/**
+ * 用例格式：位置 `<能力目录>/tests/<用例名>/`、kind 由目录推出、用例名、必有文件、NDJSON 行号、往返无损、读目录。
+ */
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  COMPLIANCE_CODES, FixtureFormatError, parseFixtures, readFixtureDir, serializeFixture,
+  type FixtureCase, type FixtureExchange, type FixtureRequest,
+} from '../../src/testing';
+
+const PULL_CASE = JSON.stringify({ mode: 'full', config: {} });
+const T = 'streams/items/tests';
+
+function formatError(run: () => unknown): FixtureFormatError {
+  try {
+    run();
+  } catch (error) {
+    if (error instanceof FixtureFormatError) return error;
+    throw error;
+  }
+  throw new Error('expected a FixtureFormatError');
+}
+
+describe('parseFixtures', () => {
+  test('case names must be lower case: Basic fails, basic-1 passes; kind and the stream come from the directory', () => {
+    const error = formatError(() => parseFixtures([{ path: `${T}/Basic/case.json`, content: PULL_CASE }]));
+    expect(error.file).toBe(`${T}/Basic/case.json`);
+    expect(error.line).toBeNull();
+    const [fixture] = parseFixtures([{ path: `${T}/basic-1/case.json`, content: PULL_CASE }]);
+    expect(fixture?.name).toBe('basic-1');
+    expect(fixture?.capability).toBe('streams/items');
+    expect(fixture?.case).toEqual({ kind: 'pull', stream: 'items', mode: 'full', config: {} });
+    expect(fixture?.exchanges).toEqual([]);
+    expect(fixture?.requests).toEqual([]);
+  });
+
+  test('a push case without requests.ndjson fails, pointing at its case.json', () => {
+    const error = formatError(() => parseFixtures([{ path: 'pushes/default/tests/hook/case.json', content: JSON.stringify({ config: {} }) }]));
+    expect(error.file).toBe('pushes/default/tests/hook/case.json');
+    expect(error.message).toContain('requests.ndjson');
+  });
+
+  test('line 3 of exchanges.ndjson that is not JSON fails with line 3', () => {
+    const exchange = (seq: number) => JSON.stringify({ seq, kind: 'crypto', request: { op: 'hash', algorithm: 'sha256', data: 'x', encoding: 'hex' }, value: 'v' });
+    const error = formatError(() => parseFixtures([
+      { path: `${T}/basic/case.json`, content: PULL_CASE },
+      { path: `${T}/basic/exchanges.ndjson`, content: `${exchange(1)}\n${exchange(2)}\n{not json\n` },
+    ]));
+    expect(error.file).toBe(`${T}/basic/exchanges.ndjson`);
+    expect(error.line).toBe(3);
+  });
+
+  test('a missing case.json, an unknown file, a bad shape, and seq going backwards all fail', () => {
+    expect(formatError(() => parseFixtures([{ path: `${T}/basic/exchanges.ndjson`, content: '' }])).file).toBe(`${T}/basic/case.json`);
+    expect(formatError(() => parseFixtures([{ path: `${T}/basic/notes.txt`, content: '' }])).file).toBe(`${T}/basic/notes.txt`);
+    expect(formatError(() => parseFixtures([{ path: 'src/index.ts', content: '' }])).file).toBe('src/index.ts');
+    expect(formatError(() => parseFixtures([{ path: `${T}/basic/case.json`, content: JSON.stringify({ config: {} }) }])).message)
+      .toContain('mode');
+    expect(formatError(() => parseFixtures([{ path: `${T}/basic/case.json`, content: JSON.stringify({ mode: 'full', config: {}, extra: 1 }) }])).message)
+      .toContain('extra');
+    // 旧格式：kind / stream 写在 case.json 里、或放在根目录 fixtures/ 下
+    expect(formatError(() => parseFixtures([{ path: `${T}/basic/case.json`, content: JSON.stringify({ kind: 'pull', mode: 'full', config: {} }) }])).message)
+      .toContain('kind');
+    expect(formatError(() => parseFixtures([{ path: `${T}/basic/case.json`, content: JSON.stringify({ stream: 'items', mode: 'full', config: {} }) }])).message)
+      .toContain('stream');
+    expect(formatError(() => parseFixtures([{ path: 'fixtures/basic/case.json', content: PULL_CASE }])).file).toBe('fixtures/basic/case.json');
+    expect(formatError(() => parseFixtures([{ path: 'operations/create_followup/tests/ok/case.json', content: JSON.stringify({ kind: 'operation', params: {}, idempotencyKey: 'k', config: {}, expect: { ok: {} } }) }])).message)
+      .toContain('kind');
+    const hash = (seq: number) => JSON.stringify({ seq, kind: 'crypto', request: { op: 'hash', algorithm: 'sha256', data: 'x', encoding: 'hex' }, value: 'v' });
+    const backwards = formatError(() => parseFixtures([
+      { path: `${T}/basic/case.json`, content: PULL_CASE },
+      { path: `${T}/basic/exchanges.ndjson`, content: `${hash(2)}\n${hash(1)}\n` },
+    ]));
+    expect(backwards.line).toBe(2);
+    const requests = formatError(() => parseFixtures([
+      { path: `${T}/basic/case.json`, content: PULL_CASE },
+      { path: `${T}/basic/requests.ndjson`, content: '' },
+    ]));
+    expect(requests.file).toBe(`${T}/basic/requests.ndjson`);
+  });
+
+  test('a suggest case under a stream directory writes kind suggest and needs expect.columns', () => {
+    const [fixture] = parseFixtures([{
+      path: 'streams/customers/tests/s1/case.json',
+      content: JSON.stringify({ kind: 'suggest', table: 'customers', config: {}, expect: { columns: [{ name: 'vip', type: 'string', title: 'VIP' }] } }),
+    }]);
+    expect(fixture?.case).toMatchObject({ kind: 'suggest', stream: 'customers', table: 'customers' });
+    expect(formatError(() => parseFixtures([{ path: 'streams/customers/tests/s1/case.json', content: JSON.stringify({ kind: 'suggest', table: 'customers', config: {} }) }])).message)
+      .toContain('columns');
+    expect(formatError(() => parseFixtures([{ path: 'pushes/default/tests/s1/case.json', content: JSON.stringify({ kind: 'suggest', table: 'customers', config: {}, expect: { columns: [] } }) }])).message)
+      .toContain('kind');
+  });
+
+  test('dot files are ignored and cases come back sorted by name', () => {
+    const fixtures = parseFixtures([
+      { path: `${T}/zeta/case.json`, content: PULL_CASE },
+      { path: `${T}/.DS_Store`, content: '' },
+      { path: `${T}/alpha/case.json`, content: PULL_CASE },
+    ]);
+    expect(fixtures.map((fixture) => fixture.name)).toEqual(['alpha', 'zeta']);
+  });
+});
+
+describe('serializeFixture', () => {
+  const exchanges: FixtureExchange[] = [
+    {
+      seq: 1, kind: 'http',
+      request: { method: 'POST', url: 'https://api.example.com/v1/items?a=1&b=2', headers: { authorization: '***' }, body: '{"q":"ontos:secret:token"}', bodyEncoding: 'utf8' },
+      response: { status: 200, headers: { 'content-type': 'application/json' }, body: '{"ok":true}', bodyEncoding: 'utf8' },
+      error: null,
+    },
+    { seq: 2, kind: 'http', request: { method: 'GET', url: 'https://api.example.com/v1/x', headers: {}, body: null, bodyEncoding: 'utf8' }, response: null, error: { code: 'EGRESS_TIMEOUT', message: 'timed out' } },
+    { seq: 3, kind: 'db', sql: 'select 1 as n', params: [1, 'a', null, { k: [1] }], fields: [{ name: 'n', dataTypeId: 23 }], rows: [{ n: 1 }], error: null },
+    { seq: 5, kind: 'crypto', request: { op: 'hmac', algorithm: 'sha256', key: 'ontos:secret:token', data: 'payload', encoding: 'hex' }, value: 'abc' },
+  ];
+
+  test('serialize then parse is lossless (pull with every exchange kind)', () => {
+    const fixtureCase: FixtureCase = {
+      kind: 'pull', stream: 'items', mode: 'incremental', state: { cursor: 3 }, streamConfig: { pageSize: 2 }, config: { baseUrl: 'https://api.example.com' },
+      secrets: { token: '***', pin: 'x1' }, limit: 10, expect: { records: { items: 2 }, removals: {}, rejected: 0, checkpoints: 1 },
+    };
+    const files = serializeFixture('basic', { case: fixtureCase, exchanges });
+    expect(files.map((file) => file.path)).toEqual([`${T}/basic/case.json`, `${T}/basic/exchanges.ndjson`]);
+    // kind 与数据流名不写进 case.json
+    expect(Object.keys(JSON.parse(files[0]?.content ?? '{}'))).not.toContain('kind');
+    expect(Object.keys(JSON.parse(files[0]?.content ?? '{}'))).not.toContain('stream');
+    for (const file of files) expect(file.content.endsWith('\n')).toBe(true);
+    expect(files[1]?.content.split('\n')).toHaveLength(exchanges.length + 1);
+    expect(parseFixtures(files)).toEqual([{ capability: 'streams/items', name: 'basic', case: fixtureCase, exchanges, requests: [] }]);
+    // 键按插入顺序输出
+    expect(files[1]?.content.startsWith('{"seq":1,"kind":"http","request":{"method":"POST"')).toBe(true);
+  });
+
+  test('serialize then parse is lossless (push with requests)', () => {
+    const fixtureCase: FixtureCase = { kind: 'push', push: 'default', config: {} };
+    const requests: FixtureRequest[] = [
+      { requestId: 'r1', receivedAt: '2026-10-25T00:00:00.000Z', headers: { 'content-type': 'application/json' }, body: '{"a":1}' },
+      { requestId: 'r2', receivedAt: '2026-10-25T00:00:01.000Z', headers: {}, body: '' },
+    ];
+    const files = serializeFixture('hook', { case: fixtureCase, exchanges: [], requests });
+    expect(files.map((file) => file.path)).toEqual(['pushes/default/tests/hook/case.json', 'pushes/default/tests/hook/requests.ndjson']);
+    expect(parseFixtures(files)).toEqual([{ capability: 'pushes/default', name: 'hook', case: fixtureCase, exchanges: [], requests }]);
+  });
+
+  test('suggest cases keep kind suggest in case.json', () => {
+    const fixtureCase: FixtureCase = { kind: 'suggest', stream: 'customers', table: 'customers', config: {}, expect: { columns: [{ name: 'vip', type: 'string', title: 'VIP' }] } };
+    const files = serializeFixture('s1', { case: fixtureCase, exchanges: [] });
+    expect(files.map((file) => file.path)).toEqual(['streams/customers/tests/s1/case.json']);
+    expect(JSON.parse(files[0]?.content ?? '{}')).toMatchObject({ kind: 'suggest', table: 'customers' });
+    expect(parseFixtures(files)).toEqual([{ capability: 'streams/customers', name: 's1', case: fixtureCase, exchanges: [], requests: [] }]);
+  });
+
+  test('case.json secrets of 4 bytes or more are written as ***', () => {
+    const files = serializeFixture('basic', { case: { kind: 'pull', stream: 'items', mode: 'full', config: {}, secrets: { token: 'abcd1234', pin: 'x1' } }, exchanges: [] });
+    expect(JSON.parse(files[0]?.content ?? '{}').secrets).toEqual({ token: '***', pin: 'x1' });
+  });
+
+  test('an invalid case name is refused', () => {
+    expect(() => serializeFixture('Bad Name', { case: { kind: 'pull', stream: 'items', mode: 'full', config: {} }, exchanges: [] })).toThrow(FixtureFormatError);
+  });
+});
+
+describe('readFixtureDir', () => {
+  const temps: string[] = [];
+  afterAll(async () => {
+    await Promise.all(temps.map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  async function project(): Promise<string> {
+    const dir = await mkdtemp(path.join(os.tmpdir(), 'sdk-fixtures-'));
+    temps.push(dir);
+    return dir;
+  }
+
+  test('reads <capability>/tests/** relative to the project, sorted, skipping dot files and other directories', async () => {
+    const dir = await project();
+    await mkdir(path.join(dir, 'streams', 'items', 'tests', 'b'), { recursive: true });
+    await mkdir(path.join(dir, 'streams', 'items', 'tests', 'a'), { recursive: true });
+    await mkdir(path.join(dir, 'operations', 'create_followup', 'tests', 'ok'), { recursive: true });
+    await mkdir(path.join(dir, 'fixtures', 'old'), { recursive: true });
+    const OPERATION_CASE = JSON.stringify({ params: {}, idempotencyKey: 'k1', config: {}, expect: { ok: {} } });
+    await writeFile(path.join(dir, 'streams', 'items', 'tests', 'b', 'case.json'), PULL_CASE);
+    await writeFile(path.join(dir, 'streams', 'items', 'tests', 'a', 'case.json'), PULL_CASE);
+    await writeFile(path.join(dir, 'streams', 'items', 'tests', '.DS_Store'), 'x');
+    await writeFile(path.join(dir, 'streams', 'items', 'index.ts'), 'export {};');
+    await writeFile(path.join(dir, 'operations', 'create_followup', 'tests', 'ok', 'case.json'), OPERATION_CASE);
+    await writeFile(path.join(dir, 'fixtures', 'old', 'case.json'), PULL_CASE);
+    await writeFile(path.join(dir, 'package.json'), '{}');
+    const files = await readFixtureDir(dir);
+    expect(files.map((file) => file.path).sort()).toEqual([
+      'operations/create_followup/tests/ok/case.json',
+      `${T}/a/case.json`,
+      `${T}/b/case.json`,
+    ]);
+    expect(parseFixtures(files).map((fixture) => `${fixture.capability}/${fixture.name}`)).toEqual([
+      'operations/create_followup/ok', 'streams/items/a', 'streams/items/b',
+    ]);
+  });
+
+  test('no tests directory gives an empty list; a symbolic link fails', async () => {
+    expect(await readFixtureDir(await project())).toEqual([]);
+    const dir = await project();
+    await mkdir(path.join(dir, 'streams', 'items', 'tests', 'a'), { recursive: true });
+    await writeFile(path.join(dir, 'outside.json'), PULL_CASE);
+    await symlink(path.join(dir, 'outside.json'), path.join(dir, 'streams', 'items', 'tests', 'a', 'case.json'));
+    const error = await readFixtureDir(dir).then(() => null, (caught: unknown) => caught);
+    expect(error).toBeInstanceOf(FixtureFormatError);
+    expect((error as FixtureFormatError).file).toBe(`${T}/a/case.json`);
+  });
+});
+
+describe('compliance codes', () => {
+  test('COMPLIANCE_CODES lists every code, including UNDECLARED_FIELDS', () => {
+    expect([...COMPLIANCE_CODES].sort()).toEqual([
+      'CHECKPOINT_NOT_MONOTONIC', 'EXPECTATION_FAILED', 'FIXTURE_EXCHANGE_MISMATCH', 'FIXTURE_EXCHANGE_UNUSED',
+      'FULL_READ_NOT_REPEATABLE', 'PRIMARY_KEY_DUPLICATE', 'RECORD_SCHEMA_MISMATCH', 'UNDECLARED_FIELDS', 'UNDECLARED_TABLE',
+    ]);
+  });
+});