Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
test(openapi): require the contract to declare codes docs/06 lists
Yudhi Armyndharis8a757f294c08
diff --git a/src/common/openapi/docs-06-contract.spec.ts b/src/common/openapi/docs-06-contract.spec.tsindex 8acf7c1fc..f207e5073 100644--- a/src/common/openapi/docs-06-contract.spec.ts+++ b/src/common/openapi/docs-06-contract.spec.ts@@ -128,15 +128,18 @@ describe('docs/06 matches the published contract', () => {*/const ROUTE_SPECIFIC_CODES = new Set(['409', '413', '415', '422', '429', '501', '502', '503']);- it('documents every route-specific status code the contract declares for the operation', () => {- const spec = JSON.parse(read('openapi.json')) as {+ const readContract = () =>+ JSON.parse(read('openapi.json')) as {paths: Record<string, Record<string, { responses?: Record<string, unknown> }>>;};++ /** The status codes each operation's `**Errors:**` block names, keyed like the contract operations. */+ const documentedErrors = (): Map<string, string[]> => {const doc = read('docs', '06-api-specification.md');// Slice the document into per-heading sections so each Errors line is matched to its operation.const headings = [...doc.matchAll(/^#### (GET|POST|PUT|PATCH|DELETE) (\S+)$/gm)];- const errorsOf = new Map<string, string>();+ const errorsOf = new Map<string, string[]>();for (let i = 0; i < headings.length; i++) {const key = `${headings[i][1]} ${normalise(headings[i][2])}`;const body = doc.slice(headings[i].index, (headings[i + 1] ?? { index: doc.length }).index);@@ -150,8 +153,14 @@ describe('docs/06 matches the published contract', () => {if (capturing) blockLines.push(raw);}const line = blockLines.join('\n');- errorsOf.set(key, [...line.matchAll(/`(\d{3})`/g)].map(match => match[1]).join(','));+ errorsOf.set(key, [...new Set([...line.matchAll(/`(\d{3})`/g)].map(match => match[1]))]);}+ return errorsOf;+ };++ it('documents every route-specific status code the contract declares for the operation', () => {+ const spec = readContract();+ const errorsOf = documentedErrors();const missing: string[] = [];let checked = 0;@@ -162,7 +171,7 @@ describe('docs/06 matches the published contract', () => {const declared = Object.keys(item[method].responses ?? {}).filter(code => ROUTE_SPECIFIC_CODES.has(code));if (declared.length === 0) continue;checked++;- const documented = errorsOf.get(key) ?? '';+ const documented = errorsOf.get(key) ?? [];for (const code of declared) {if (!documented.includes(code)) missing.push(`${key} misses ${code}`);}@@ -173,6 +182,37 @@ describe('docs/06 matches the published contract', () => {expect(missing).toEqual([]);});+ /**+ * The reverse direction: a code the section promises must be one the contract declares, or a+ * generated client and the published schema disagree with the prose about what the route answers.+ * `415`/`429`/`500`/`503` can come from any route (compressed body, rate limiter, unexpected+ * error, body budget or a dependency not ready) and `400`/`404` are the universal validation and+ * existence answers, so the General Error Codes table covers them and a section may restate them+ * without the operation declaring them.+ */+ const UNDECLARED_ALLOWED = new Set(['400', '404', '415', '429', '500', '503']);++ it('declares in the contract every status code the section documents', () => {+ const spec = readContract();+ const undeclared: string[] = [];+ let checked = 0;+ for (const [key, codes] of documentedErrors()) {+ const [method, path] = key.split(' ');+ const operation = Object.entries(spec.paths).find(([candidate]) => normalise(candidate) === path)?.[1][+ method.toLowerCase()+ ];+ if (!operation) continue;+ for (const code of codes) {+ if (UNDECLARED_ALLOWED.has(code)) continue;+ checked++;+ if (!operation.responses?.[code]) undeclared.push(`${key} documents ${code}`);+ }+ }+ // Non-vacuity: nearly every section names its auth and conflict answers.+ expect(checked).toBeGreaterThan(400);+ expect(undeclared.sort()).toEqual([]);+ });+// The gate's own controls. Without these, a matcher that silently stops working is// indistinguishable from a document that is correct.describe('the checks themselves can fail', () => {