Comparator

Functions

`compareOutput`

function compareOutput(actual: string, expected: string, mode: 'exact' | 'contains' = 'exact'): { match: boolean; diff: string }

TypeScript

Use compareOutput to validate generated documentation against expected output, catching regressions before they ship.

Reach for this when testing your skrypt generate pipeline — for example, asserting that a function's generated docs match a golden file, or that a required phrase appears somewhere in the output.

In 'exact' mode, both strings are normalized before comparison (whitespace, line endings) so minor formatting differences don't cause false failures. In 'contains' mode, the check passes as long as expected appears anywhere within actual, which is useful for partial snapshot testing.

Parameters

Name	Type	Required	Description
`actual`	`string`	Yes	The generated documentation string you want to validate — typically the output of a `skrypt generate` run read from disk.
`expected`	`string`	Yes	The reference string to compare against. In `'exact'` mode this is the full expected output; in `'contains'` mode it's a substring that must appear somewhere in `actual`.
`mode`	`'exact' \| 'contains'`	No	Controls how the comparison is performed. Defaults to `'exact'`. Use `'contains'` when you only care that a specific phrase or block appears in the output, not the full content.

Returns

Returns an object with match (whether the comparison passed) and diff (a human-readable description of what differed, empty string if match is true). Log or surface diff in your test output to immediately see what changed without re-running the generator.

Heads up

Both strings are normalized before comparison, so differences in trailing newlines or carriage returns won't cause a mismatch — but intentional whitespace changes inside content will still be caught.
In 'contains' mode, diff describes what was searched for and where the mismatch occurred, not a line-by-line diff — keep this in mind when debugging failures.

Example:

import * as fs from "fs";
import * as path from "path";

// Inline implementation — do not import from autodocs
function normalize(str: string): string {
  return str.replace(/\r\n/g, "\n").trim();
}

function compareOutput(
  actual: string,
  expected: string,
  mode: "exact" | "contains" = "exact"
): { match: boolean; diff: string } {
  const normalizedActual = normalize(actual);
  const normalizedExpected = normalize(expected);

  if (mode === "exact") {
    const match = normalizedActual === normalizedExpected;
    return {
      match,
      diff: match
        ? ""
        : `Expected output to exactly match.\nExpected:\n${normalizedExpected}\n\nActual:\n${normalizedActual}`,
    };
  }

  const match = normalizedActual.includes(normalizedExpected);
  return {
    match,
    diff: match
      ? ""
      : `Expected output to contain:\n"${normalizedExpected}"\n\nActual output:\n${normalizedActual}`,
  };
}

// Simulate generated docs output from skrypt generate
const generatedDocs = `
## createUser

Use createUser to register a new user in your system.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| email | string | Yes | The user's email address. |
| role | string | No | Defaults to 'viewer'. |
`;

// Test 1: Exact match against a golden file snapshot
const goldenSnapshot = generatedDocs;
const exactResult = compareOutput(generatedDocs, goldenSnapshot, "exact");
console.log("Exact match test:", exactResult.match); // true
console.log("Diff:", exactResult.diff || "(none)");

// Test 2: Partial check — confirm required section is present
const partialResult = compareOutput(
  generatedDocs,
  "Use createUser to register a new user",
  "contains"
);
console.log("\nContains test:", partialResult.match); // true
console.log("Diff:", partialResult.diff || "(none)");

// Test 3: Catch a regression — missing parameter row
const regressedDocs = generatedDocs.replace("| role | string | No | Defaults to 'viewer'. |", "");
const regressionResult = compareOutput(
  regressedDocs,
  "| role | string | No | Defaults to 'viewer'. |",
  "contains"
);
console.log("\nRegression test:", regressionResult.match); // false
console.log("Diff:", regressionResult.diff);

TypeScript

test — comparator

Comparator

Functions

compareOutput

`compareOutput`