@relaybus/testing 0.3.1 → 0.4.0

package/README.md

@@ -40,6 +40,37 @@ claimer that keeps claiming drains the workload. Pass `keepsCompletedRecords:
 true` when the store keeps a completion history; run the suite once per mode the
 store supports.
 
+## Codec contract
+
+Before adopting a wire format that other services already use, prove that a codec writes and reads it exactly. Give
+`kafkaCodecContract` or `rabbitMqCodecContract` captured messages and the events they carry; each case is one test that
+checks `encode(event)` against the captured message (value or body byte for byte or as canonical JSON, key, headers,
+timestamp or properties) and that decoding the captured message gives the event:
+
+```ts
+import { kafkaCodecContract } from '@relaybus/testing';
+import { decodeKafkaRecord } from '@relaybus/kafka';
+
+kafkaCodecContract('orders format', {
+  encode: orderCodec.encode,
+  decode: (record) => decodeKafkaRecord(orderCodec, record),
+  compare: 'bytes', // or 'json' to ignore key order and spacing
+  ignoreHeaders: ['traceparent'],
+  cases: [
+    {
+      name: 'order placed',
+      envelope, // the event
+      record: { topic: 'orders', key: 'order-1', headers: {}, value: '{"orderId":"1"}' }, // the captured record
+      // only: 'decode', // for a message only other producers write
+    },
+  ],
+});
+```
+
+`rabbitMqCodecContract` takes the same shape with `decodeRabbitMqMessage` from `@relaybus/rabbitmq` and captured messages
+(routing key, properties, headers, body). `kafkaCodecMismatches` and `rabbitMqCodecMismatches` return the differences as
+text lines instead of registering tests.
+
 ## FakeClock
 
 ```ts

package/dist/index.cjs

@@ -1406,17 +1406,185 @@ var InMemoryTransport = class {
   }
 };
 async function deliverWithRedeliveries(handler, delivery) {
-  for (let attempt = 0; ; attempt += 1) {
+  for (let attempt2 = 0; ; attempt2 += 1) {
     try {
       await handler(delivery.envelope, { destination: delivery.destination });
-      return attempt + 1;
+      return attempt2 + 1;
     } catch (error) {
-      if (attempt >= delivery.maxRedeliveries) {
+      if (attempt2 >= delivery.maxRedeliveries) {
         throw error;
       }
     }
   }
 }
+function toBuffer(bytes) {
+  return typeof bytes === "string" ? Buffer.from(bytes, "utf8") : Buffer.from(bytes);
+}
+function canonicalJson(value) {
+  return JSON.stringify(sortKeys(JSON.parse(JSON.stringify(value) ?? "null")));
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.keys(value).sort().map((name) => [name, sortKeys(value[name])])
+  );
+}
+function compareBodies(label, {
+  expected,
+  encoded,
+  comparison
+}) {
+  const text = (bytes) => bytes === null ? "null" : toBuffer(bytes).toString("utf8");
+  const same = expected === null || encoded === null ? expected === encoded : comparison === "json" ? canonicalJson(JSON.parse(text(expected))) === canonicalJson(JSON.parse(text(encoded))) : toBuffer(expected).equals(toBuffer(encoded));
+  return same ? [] : [`${label}: expected ${text(expected)}, encoded ${text(encoded)}`];
+}
+function compareObjects(label, {
+  expected,
+  encoded,
+  ignored
+}) {
+  const kept = (object) => canonicalJson(
+    Object.fromEntries(Object.entries(object).filter(([name]) => !ignored.includes(name)))
+  );
+  const [left, right] = [kept(expected), kept(encoded)];
+  return left === right ? [] : [`${label}: expected ${left}, encoded ${right}`];
+}
+function compareDecoded(expected, decoded) {
+  const [left, right] = [canonicalJson(expected), canonicalJson(decoded)];
+  return left === right ? [] : [`decoded: expected ${left}, decoded ${right}`];
+}
+async function attempt(label, step) {
+  try {
+    return { result: await step(), mismatches: [] };
+  } catch (error) {
+    return { mismatches: [`${label} threw: ${core.toErrorInfo(error).message}`] };
+  }
+}
+
+// src/codec-contract/kafka.ts
+async function kafkaCodecMismatches(options, testCase) {
+  const { record } = testCase;
+  const encoding = testCase.only === "decode" ? { mismatches: [] } : await attempt("encode", () => options.encode(testCase.envelope));
+  const encoded = encoding.result;
+  const decoding = testCase.only === "encode" ? { mismatches: [] } : await attempt("decode", () => options.decode(delivered(record)));
+  return [
+    ...encoding.mismatches,
+    ...encoded === void 0 ? [] : compareRecords(options, { record, encoded }),
+    ...decoding.mismatches,
+    ...decoding.result === void 0 ? [] : compareDecoded(testCase.decoded ?? testCase.envelope, decoding.result)
+  ];
+}
+function kafkaCodecContract(name, options) {
+  vitest.describe(`${name} writes and reads the captured Kafka records`, () => {
+    vitest.it.each(options.cases.map((testCase) => [testCase.name, testCase]))(
+      "%s",
+      async (_name, testCase) => {
+        vitest.expect(await kafkaCodecMismatches(options, testCase)).toEqual([]);
+      }
+    );
+  });
+}
+function compareRecords(options, {
+  record,
+  encoded
+}) {
+  const text = (bytes) => bytes === null ? null : toBuffer(bytes).toString("utf8");
+  const timestamp = encoded.timestamp;
+  return [
+    ...text(record.key) === text(encoded.key) ? [] : [`key: expected ${text(record.key)}, encoded ${text(encoded.key)}`],
+    ...compareBodies("value", {
+      expected: record.value,
+      encoded: encoded.value,
+      comparison: options.compare ?? "bytes"
+    }),
+    ...compareObjects("headers", {
+      expected: textHeaders(record.headers ?? {}),
+      encoded: textHeaders(encoded.headers),
+      ignored: options.ignoreHeaders ?? []
+    }),
+    ...timestamp === void 0 || timestamp === record.timestamp ? [] : [`timestamp: expected ${record.timestamp}, encoded ${timestamp}`]
+  ];
+}
+function textHeaders(headers) {
+  return Object.fromEntries(
+    Object.entries(headers).map(([name, value]) => [
+      name,
+      toBuffer(Array.isArray(value) ? value.at(-1) : value).toString(
+        "utf8"
+      )
+    ])
+  );
+}
+function delivered(record) {
+  return {
+    topic: record.topic,
+    partition: record.partition ?? 0,
+    offset: record.offset ?? "0",
+    key: record.key === null ? null : toBuffer(record.key),
+    value: record.value === null ? null : toBuffer(record.value),
+    headers: Object.fromEntries(
+      Object.entries(record.headers ?? {}).map(([name, value]) => [name, toBuffer(value)])
+    ),
+    ...record.timestamp === void 0 ? {} : { timestamp: record.timestamp }
+  };
+}
+async function rabbitMqCodecMismatches(options, testCase) {
+  const { message } = testCase;
+  const encoding = testCase.only === "decode" ? { mismatches: [] } : await attempt("encode", () => options.encode(testCase.envelope));
+  const encoded = encoding.result;
+  const decoding = testCase.only === "encode" ? { mismatches: [] } : await attempt("decode", () => options.decode(delivered2(message)));
+  return [
+    ...encoding.mismatches,
+    ...encoded === void 0 ? [] : compareMessages(options, { message, encoded }),
+    ...decoding.mismatches,
+    ...decoding.result === void 0 ? [] : compareDecoded(testCase.decoded ?? testCase.envelope, decoding.result)
+  ];
+}
+function rabbitMqCodecContract(name, options) {
+  vitest.describe(`${name} writes and reads the captured RabbitMQ messages`, () => {
+    vitest.it.each(options.cases.map((testCase) => [testCase.name, testCase]))(
+      "%s",
+      async (_name, testCase) => {
+        vitest.expect(await rabbitMqCodecMismatches(options, testCase)).toEqual([]);
+      }
+    );
+  });
+}
+function compareMessages(options, {
+  message,
+  encoded
+}) {
+  const { headers, ...properties } = encoded.options;
+  return [
+    ...compareObjects("properties", {
+      expected: message.properties ?? {},
+      encoded: properties,
+      ignored: options.ignoreProperties ?? []
+    }),
+    ...compareObjects("headers", {
+      expected: message.headers ?? {},
+      encoded: headers ?? {},
+      ignored: options.ignoreHeaders ?? []
+    }),
+    ...compareBodies("body", {
+      expected: message.body,
+      encoded: encoded.content,
+      comparison: options.compare ?? "bytes"
+    })
+  ];
+}
+function delivered2(message) {
+  return {
+    content: toBuffer(message.body),
+    fields: { routingKey: message.routingKey },
+    properties: { ...message.properties, headers: { ...message.headers } }
+  };
+}
 
 exports.FakeClock = FakeClock;
 exports.InMemoryTransport = InMemoryTransport;
@@ -1424,5 +1592,9 @@ exports.at = at;
 exports.createDelivery = createDelivery;
 exports.createEnvelope = createEnvelope;
 exports.eventStoreContract = eventStoreContract;
+exports.kafkaCodecContract = kafkaCodecContract;
+exports.kafkaCodecMismatches = kafkaCodecMismatches;
+exports.rabbitMqCodecContract = rabbitMqCodecContract;
+exports.rabbitMqCodecMismatches = rabbitMqCodecMismatches;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map