@specific.dev/spectest 0.66.0 → 0.68.0

package/src/text-match.ts

@@ -0,0 +1,285 @@
+// Text comparison for the web-first matchers, and readable notes for the
+// failures that invisible characters cause.
+//
+// Two rules, and they are deliberately different:
+//
+//   * **Matching is Playwright's.** `expect(locator).toHaveText(...)` and
+//     `toContainText(...)` normalize whitespace on BOTH sides exactly as
+//     playwright's own text engine does (`normalizeWhiteSpace` in
+//     playwright-core). Without this the SDK disagreed with itself: the same
+//     string matched through `getByText("15 000 kr")` (playwright's engine,
+//     which normalizes) and failed through `toContainText("15 000 kr")`
+//     (ours, which did a raw `includes`). The case that reported it is
+//     Swedish number formatting — `Intl.NumberFormat("sv-SE")` groups
+//     thousands with U+00A0 NO-BREAK SPACE, and JavaScript's `\s` covers
+//     U+00A0, so normalization makes a typed space match it.
+//
+//   * **Diagnostics are wider.** A value the author compares themselves
+//     (`expect(body).toContain(...)`, `toHaveValue`) is still exact, as it
+//     must be — so when such a comparison fails on characters that print the
+//     same, the message has to say so. `textDifferenceNote` reports the
+//     invisible or look-alike characters that are the whole difference, and
+//     `escapeInvisible` makes the two printed strings differ on screen.
+
+/** Characters that are invisible on screen (or print as an ordinary space)
+ *  and their Unicode names, for a message a reader can act on. */
+const INVISIBLE_NAMES: Record<number, string> = {
+  0x0009: "TAB",
+  0x000a: "LINE FEED",
+  0x000b: "LINE TABULATION",
+  0x000c: "FORM FEED",
+  0x000d: "CARRIAGE RETURN",
+  0x00a0: "NO-BREAK SPACE",
+  0x00ad: "SOFT HYPHEN",
+  0x1680: "OGHAM SPACE MARK",
+  0x2000: "EN QUAD",
+  0x2001: "EM QUAD",
+  0x2002: "EN SPACE",
+  0x2003: "EM SPACE",
+  0x2004: "THREE-PER-EM SPACE",
+  0x2005: "FOUR-PER-EM SPACE",
+  0x2006: "SIX-PER-EM SPACE",
+  0x2007: "FIGURE SPACE",
+  0x2008: "PUNCTUATION SPACE",
+  0x2009: "THIN SPACE",
+  0x200a: "HAIR SPACE",
+  0x200b: "ZERO WIDTH SPACE",
+  0x200c: "ZERO WIDTH NON-JOINER",
+  0x200d: "ZERO WIDTH JOINER",
+  0x200e: "LEFT-TO-RIGHT MARK",
+  0x200f: "RIGHT-TO-LEFT MARK",
+  0x2028: "LINE SEPARATOR",
+  0x2029: "PARAGRAPH SEPARATOR",
+  0x202f: "NARROW NO-BREAK SPACE",
+  0x205f: "MEDIUM MATHEMATICAL SPACE",
+  0x2060: "WORD JOINER",
+  0x3000: "IDEOGRAPHIC SPACE",
+  0xfeff: "ZERO WIDTH NO-BREAK SPACE",
+};
+
+/** Visible characters an author reaches for on the keyboard, and the
+ *  typographic look-alikes a CMS, a text editor or `Intl` substitutes for
+ *  them. Reported, never matched through — two strings that differ by an em
+ *  dash really are different strings. */
+const LOOKALIKES: Record<number, { ascii: string; name: string }> = {
+  0x2010: { ascii: "-", name: "HYPHEN" },
+  0x2011: { ascii: "-", name: "NON-BREAKING HYPHEN" },
+  0x2012: { ascii: "-", name: "FIGURE DASH" },
+  0x2013: { ascii: "-", name: "EN DASH" },
+  0x2014: { ascii: "-", name: "EM DASH" },
+  0x2212: { ascii: "-", name: "MINUS SIGN" },
+  0x2018: { ascii: "'", name: "LEFT SINGLE QUOTATION MARK" },
+  0x2019: { ascii: "'", name: "RIGHT SINGLE QUOTATION MARK" },
+  0x201c: { ascii: '"', name: "LEFT DOUBLE QUOTATION MARK" },
+  0x201d: { ascii: '"', name: "RIGHT DOUBLE QUOTATION MARK" },
+  0x2026: { ascii: "...", name: "HORIZONTAL ELLIPSIS" },
+};
+
+/**
+ * Playwright's whitespace normalization, character for character
+ * (`normalizeWhiteSpace`, playwright-core): drop zero-width spaces and soft
+ * hyphens, trim, then collapse every run of whitespace to one space. `\s`
+ * covers U+00A0 and the rest of the Unicode space characters, which is what
+ * makes a typed space match a no-break one.
+ */
+export function normalizeWhiteSpace(text: string): string {
+  return text.replace(/[\u200b\u00ad]/g, "").trim().replace(/\s+/g, " ");
+}
+
+export interface TextMatchOptions {
+  /** Compare without regard to letter case. On a RegExp this adds the `i`
+   *  flag, as playwright's own `ignoreCase` does. */
+  ignoreCase?: boolean;
+}
+
+function caseFold(s: string, opts?: TextMatchOptions): string {
+  return opts?.ignoreCase ? s.toLowerCase() : s;
+}
+
+function withIgnoreCase(re: RegExp, opts?: TextMatchOptions): RegExp {
+  if (!opts?.ignoreCase || re.flags.includes("i")) return re;
+  return new RegExp(re.source, `${re.flags}i`);
+}
+
+/** The element's text equals `expected`, with whitespace normalized on both
+ *  sides. A RegExp is tested against the normalized text. */
+export function matchesText(
+  actual: string,
+  expected: string | RegExp,
+  opts?: TextMatchOptions,
+): boolean {
+  const a = normalizeWhiteSpace(actual);
+  if (expected instanceof RegExp) return withIgnoreCase(expected, opts).test(a);
+  return caseFold(a, opts) === caseFold(normalizeWhiteSpace(expected), opts);
+}
+
+/** The element's text contains `expected`, with whitespace normalized on both
+ *  sides. A RegExp is tested against the normalized text. */
+export function containsText(
+  actual: string,
+  expected: string | RegExp,
+  opts?: TextMatchOptions,
+): boolean {
+  const a = normalizeWhiteSpace(actual);
+  if (expected instanceof RegExp) return withIgnoreCase(expected, opts).test(a);
+  return caseFold(a, opts).includes(caseFold(normalizeWhiteSpace(expected), opts));
+}
+
+// ── Diagnostics ───────────────────────────────────────────────────────────
+
+/** `" "` for an invisible character, the character itself otherwise.
+ *  Applied to an ALREADY `JSON.stringify`-ed string, so the result stays a
+ *  valid JSON string literal. */
+export function escapeInvisible(s: string): string {
+  let out = "";
+  for (const ch of s) {
+    const code = ch.codePointAt(0)!;
+    // Control characters are already escaped by JSON.stringify; what is left
+    // is the invisible-but-not-control set, which prints as nothing (or as an
+    // ordinary space) and so must be spelled out.
+    out += code > 0x1f && code in INVISIBLE_NAMES
+      ? `\\u${code.toString(16).padStart(4, "0")}`
+      : ch;
+  }
+  return out;
+}
+
+/** The name of a character worth reporting, or `undefined` when it is an
+ *  ordinary one. */
+function suspectName(code: number): string | undefined {
+  if (code === 0x20) return undefined;
+  return INVISIBLE_NAMES[code] ?? LOOKALIKES[code]?.name;
+}
+
+/** Map a character onto the plain one it prints as, so two strings that only
+ *  *look* the same can be told apart from two that really differ. */
+function foldChar(ch: string): string {
+  const code = ch.codePointAt(0)!;
+  if (code in LOOKALIKES) return LOOKALIKES[code]!.ascii;
+  if (code in INVISIBLE_NAMES) {
+    // Zero-width characters print as nothing; the rest print as a space.
+    return code === 0x200b ||
+        code === 0x200c ||
+        code === 0x200d ||
+        code === 0x200e ||
+        code === 0x200f ||
+        code === 0x00ad ||
+        code === 0x2060 ||
+        code === 0xfeff
+      ? ""
+      : " ";
+  }
+  return ch;
+}
+
+/** The string as it appears on screen: every look-alike replaced by the plain
+ *  character it resembles, every zero-width one dropped, whitespace collapsed. */
+function fold(s: string): string {
+  let out = "";
+  for (const ch of s) out += foldChar(ch);
+  return out.trim().replace(/ +/g, " ");
+}
+
+interface Suspect {
+  name: string;
+  index: number;
+}
+
+/** Every reportable character in `s`, first occurrence only, in order. */
+function suspects(s: string): Suspect[] {
+  const seen = new Set<string>();
+  const out: Suspect[] = [];
+  let index = 0;
+  for (const ch of s) {
+    const name = suspectName(ch.codePointAt(0)!);
+    if (name && !seen.has(name)) {
+      seen.add(name);
+      out.push({ name, index });
+    }
+    index += ch.length;
+  }
+  return out;
+}
+
+function listSuspects(items: Suspect[]): string {
+  return items
+    .slice(0, 3)
+    .map((s) => `${s.name} at index ${s.index}`)
+    .join(", ");
+}
+
+/**
+ * A sentence to append to a failed string comparison when the two strings
+ * print the same, or differ only in letter case — the failure a reader cannot
+ * see. Returns `""` for every other case, so a caller can concatenate it
+ * unconditionally.
+ *
+ * `mode` is how the two were compared: `"equal"` for the equality matchers,
+ * `"contains"` for the substring ones.
+ */
+export function textDifferenceNote(
+  actual: unknown,
+  expected: unknown,
+  mode: "equal" | "contains",
+): string {
+  if (typeof actual !== "string" || typeof expected !== "string") return "";
+  const matched = (a: string, e: string): boolean =>
+    mode === "equal" ? a === e : a.includes(e);
+  if (matched(actual, expected)) return "";
+
+  const fa = fold(actual);
+  const fe = fold(expected);
+  if (matched(fa, fe)) {
+    const inActual = suspects(actual);
+    const inExpected = suspects(expected);
+    const where = inActual.length
+      ? `the actual text has ${listSuspects(inActual)}`
+      : `the expected string has ${listSuspects(inExpected)}`;
+    return ` — the two print the same: they differ only in invisible or look-alike characters (${where})`;
+  }
+  if (matched(fa.toLowerCase(), fe.toLowerCase())) {
+    return " — they differ only in letter case";
+  }
+  return "";
+}
+
+// ── Array forms (`toHaveText([...])` / `toContainText([...])`) ────────────
+//
+// Playwright's own rule, from its injected script: the expected items are
+// matched against the received texts **greedily, in order**, and the lengths
+// must agree for `toHaveText` but not for `toContainText`. So
+// `toContainText(["Two", "Four"])` passes against a four-row list, while
+// `toHaveText(["Two", "Four"])` does not.
+
+function matchesInOrder(
+  actual: string[],
+  expected: (string | RegExp)[],
+  item: (a: string, e: string | RegExp) => boolean,
+): boolean {
+  let want = 0;
+  for (let i = 0; i < actual.length && want < expected.length; i++) {
+    if (item(actual[i]!, expected[want]!)) want++;
+  }
+  return want === expected.length;
+}
+
+/** Every element's text equals the item at its position, and there are
+ *  exactly as many elements as items. */
+export function matchesTextArray(
+  actual: string[],
+  expected: (string | RegExp)[],
+  opts?: TextMatchOptions,
+): boolean {
+  if (actual.length !== expected.length) return false;
+  return matchesInOrder(actual, expected, (a, e) => matchesText(a, e, opts));
+}
+
+/** The elements' texts contain every item, in order. Extra elements between
+ *  the matches are allowed. */
+export function containsTextArray(
+  actual: string[],
+  expected: (string | RegExp)[],
+  opts?: TextMatchOptions,
+): boolean {
+  return matchesInOrder(actual, expected, (a, e) => containsText(a, e, opts));
+}