@letsrunit/playwright 0.1.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@letsrunit/playwright",
+  "version": "0.1.0",
+  "description": "Playwright extensions and utilities for letsrunit",
+  "keywords": [
+    "testing",
+    "playwright",
+    "automation",
+    "letsrunit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/letsrunit/letsrunit.git",
+    "directory": "packages/playwright"
+  },
+  "bugs": "https://github.com/letsrunit/letsrunit/issues",
+  "homepage": "https://github.com/letsrunit/letsrunit#readme",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "../../node_modules/.bin/tsup",
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "packageManager": "yarn@4.10.3",
+  "dependencies": {
+    "@letsrunit/utils": "workspace:*",
+    "@playwright/test": "^1.57.0",
+    "case": "^1.6.3",
+    "diff": "^8.0.3",
+    "fast-json-stable-stringify": "^2.1.0",
+    "jsdom": "^27.4.0",
+    "metascraper-description": "^5.49.15",
+    "metascraper-image": "^5.49.15",
+    "metascraper-logo": "^5.49.15",
+    "metascraper-logo-favicon": "^5.49.15",
+    "metascraper-title": "^5.49.15",
+    "metascraper-url": "^5.49.15",
+    "rehype-format": "^5.0.1",
+    "rehype-parse": "^9.0.1",
+    "rehype-stringify": "^10.0.1",
+    "unified": "^11.0.5"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^27.0.0",
+    "vitest": "^4.0.17"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}

package/src/browser.ts

@@ -0,0 +1,20 @@
+import type { Browser, BrowserContextOptions, Page } from '@playwright/test';
+
+// Launch a minimal, headless Chromium instance.
+export async function browse(browser: Browser, options: BrowserContextOptions = {}): Promise<Page> {
+  const context = await browser.newContext({
+    viewport: { width: 1920, height: 1080 },
+    userAgent:
+      'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    locale: 'en-US',
+    ...options,
+  });
+
+  // Safety net against bundler-injected helpers inside page.evaluate
+  await context.addInitScript(() => {
+    // define __name as a no-op if present
+    (window as any).__name = (window as any).__name || ((fn: any) => fn);
+  });
+
+  return await context.newPage();
+}

package/src/field/calendar.ts

@@ -0,0 +1,300 @@
+import { isArray, isDate, isRange } from '@letsrunit/utils';
+import { uniqueItem } from '@letsrunit/utils/src/array';
+import type { Locator } from '@playwright/test';
+import { formatDate, formatDateForInput, getMonthNames } from '../utils/date';
+import { waitForAnimationsToFinish } from '../wait';
+import type { Loc, SetOptions, Value } from './types';
+
+type MonthYear = { month: number; year: number };
+
+async function getDialog(root: Locator, options?: SetOptions) {
+  const role = await root.getAttribute('role', options).catch(() => null);
+
+  if (role !== 'combobox') return null;
+
+  const ariaControls = await root.getAttribute('aria-controls', options).catch(() => null);
+  if (!ariaControls) return null;
+
+  const calendar = root.page().locator(`#${ariaControls}`);
+  if ((await calendar.count()) === 0) {
+    await root.click(options);
+  }
+
+  const count = await calendar.count();
+  return count > 0 ? calendar : null;
+}
+
+async function isCalendarGrid(grid: Locator): Promise<boolean> {
+  const cells = grid.locator('td, [role="gridcell"]');
+  const cellCount = await cells.count();
+  if (cellCount < 28 || cellCount > 80) return false; // Sanity check
+
+  const texts = await cells.allTextContents();
+  const days = texts
+    .map((t) => t.trim())
+    .filter((t) => /^\d{1,2}$/.test(t))
+    .map(Number)
+    .filter((n) => n >= 1 && n <= 31);
+
+  // Expect sequential numbering from 1 to at least 28. Ignore other cells with other content.
+  const last = days.reduce((max, cur) => (cur === max + 1 ? cur : max), 0);
+  return last >= 28;
+}
+
+export async function getCalendar(
+  root: Locator,
+  options?: SetOptions,
+): Promise<{ calendar: Locator; tables: Locator[] } | null> {
+  const gridSelector = 'table, [role="grid"]';
+
+  // 1. Identify the container (either the root itself or a linked dialog/popup)
+  let container: Locator | null =
+    (await root.locator(gridSelector).count()) > 0 ? root : await getDialog(root, options);
+
+  // Fallback: Check if the root itself is a valid grid (e.g. inline MUI DateCalendar)
+  if (!container && (await isCalendarGrid(root))) {
+    return { calendar: root, tables: [root] };
+  }
+  if (!container) return null;
+
+  // 2. Find all valid calendar grids within the container
+  // This handles both <table> and <div role="grid">
+  const found = await container.locator(gridSelector).all();
+  const tables: Locator[] = [];
+
+  // If the container itself matches the selector, check it first
+  if (await isCalendarGrid(container)) {
+    tables.push(container);
+  }
+
+  for (const grid of found) {
+    if (await isCalendarGrid(grid)) {
+      tables.push(grid);
+    }
+  }
+
+  // 3. Deduplicate (prevents issues if container == grid)
+  const uniqueTables = tables.filter((t, i, self) => self.indexOf(t) === i);
+
+  return uniqueTables.length > 0 ? { calendar: container, tables: uniqueTables } : null;
+}
+
+function uniqueMonthYearPairs(pairs: MonthYear[]): MonthYear[] {
+  const map = pairs.reduce(
+    (acc, r) => acc.set(`${r.year}-${r.month}`, r),
+    new Map<string, { month: number; year: number }>(),
+  );
+  return Array.from(map.values());
+}
+
+function inferYearForMonth(target: Date, month: number): number {
+  const ty = target.getFullYear();
+  const tm = target.getMonth();
+  const targetTotal = ty * 12 + tm;
+
+  const candidates = [ty - 1, ty, ty + 1].map((y) => ({ year: y, total: y * 12 + month }));
+  candidates.sort((a, b) => Math.abs(a.total - targetTotal) - Math.abs(b.total - targetTotal));
+  return candidates[0].year;
+}
+
+export async function getCurrentMonthsAndYears(root: Locator, target: Date): Promise<MonthYear[]> {
+  const lang = await root
+    .page()
+    .locator('html')
+    .getAttribute('lang')
+    .catch(() => undefined);
+  const locales = lang && !lang.startsWith('en') ? [lang, 'en-US'] : ['en-US'];
+
+  const text = await root.innerText();
+  const monthSets = locales.map(getMonthNames);
+
+  // Look for month year pairs
+  const pairs = monthSets.flatMap((months) => {
+    const matches = text.matchAll(new RegExp(`(${months.join('|')})\\W*(\\d{4})`, 'gi'));
+    return Array.from(matches)
+      .map((m) => ({
+        month: months.findIndex((x) => x.toLowerCase() === m[1].toLowerCase()),
+        year: Number.parseInt(m[2], 10),
+      }))
+      .filter((r) => r.month !== -1);
+  });
+
+  if (pairs.length) {
+    return uniqueMonthYearPairs(pairs);
+  }
+
+  // Fallback looking for months only
+  const months = monthSets
+    .flatMap((ms) => ms.map((name, i) => (new RegExp(name, 'i').test(text) ? i : -1)))
+    .filter(uniqueItem)
+    .filter((i) => i >= 0)
+    .sort((a, b) => a - b);
+
+  const years = (text.match(/\b20\d{2}\b/g) ?? [])
+    .map((y) => Number.parseInt(y, 10))
+    .filter(uniqueItem)
+    .sort((a, b) => a - b);
+
+  if (!months.length) return [];
+
+  if (years.length === 1) {
+    return months.map((month) => ({ month, year: years[0] }));
+  }
+
+  // Heuristic: months >= July belong to y0 and <= June belongs to y1
+  if (years.length === 2) {
+    return months
+      .map((month) => ({ month, year: month >= 6 ? years[0] : years[1] }))
+      .sort((a, b) => a.year * 12 + a.month - (b.year * 12 + b.month));
+  }
+
+  // Year can't be determined, infer from target date
+  return months
+    .map((month) => ({ month, year: inferYearForMonth(target, month) }))
+    .sort((a, b) => a.year * 12 + a.month - (b.year * 12 + b.month));
+}
+
+async function navigateToMonth(
+  root: Locator,
+  target: Date,
+  options?: SetOptions & { wait?: number; retry?: number },
+): Promise<boolean> {
+  const currentMonths = await getCurrentMonthsAndYears(root, target);
+  if (currentMonths.length === 0) return false;
+
+  const targetTotal = target.getFullYear() * 12 + target.getMonth();
+  if (currentMonths.find((m) => m.year * 12 + m.month === targetTotal)) {
+    return true;
+  }
+
+  const firstMonthTotal = currentMonths[0].year * 12 + currentMonths[0].month;
+  const diff = targetTotal - firstMonthTotal;
+
+  const btn =
+    diff < 0
+      ? root.locator('button[aria-label*="prev"], button[class*="prev"]').filter({ visible: true }).first()
+      : root.locator('button[aria-label*="next"], button[class*="next"]').filter({ visible: true }).first();
+
+  if (!(await btn.count())) return false;
+
+  for (let i = 0; i < Math.abs(diff); i++) {
+    await btn.click(options);
+    await root.page().waitForTimeout(options?.wait ?? 50);
+  }
+
+  await waitForAnimationsToFinish(root);
+
+  const afterMonths = await getCurrentMonthsAndYears(root, target);
+  if (afterMonths.some((m) => m.year * 12 + m.month === targetTotal)) return true;
+
+  if ((options?.retry ?? 0) < 3) {
+    const retry = (options?.retry ?? 0) + 1;
+    return await navigateToMonth(root, target, { ...options, wait: 50 + 50 * retry, retry }); // Retry max 3x
+  }
+
+  return false;
+}
+
+async function setDayByAriaLabel(table: Locator, value: Date, options?: SetOptions): Promise<boolean> {
+  const formats = ['DD/MM/YYYY', 'MM/DD/YYYY', 'DD-MM-YYYY', 'YYYY-MM-DD'];
+  const candidateLabels = [value.toDateString(), ...formats.map((fmt) => formatDate(value, fmt))];
+
+  const cells = (
+    await Promise.all(
+      candidateLabels.map(async (label) => {
+        const cell = table.locator(`[aria-label="${label}"], [aria-label*="${label}"]`).first();
+        return (await cell.isVisible(options)) ? cell : null;
+      }),
+    )
+  ).filter((l): l is Locator => l !== null);
+
+  if (cells.length === 0) return false;
+
+  if (cells.length === 1) {
+    await cells[0].click(options);
+    return true;
+  }
+
+  // Disambiguate using day 22 in case of dd/mm/yyyy vs mm/dd/yyyy
+  const probeDate = new Date(value.getFullYear(), value.getMonth(), 22);
+  const probeResults = await Promise.all(
+    formats.map(async (fmt) => {
+      const label = formatDate(probeDate, fmt);
+      const cell = table.locator(`[aria-label="${label}"], [aria-label*="${label}"]`).first();
+      return (await cell.isVisible(options)) ? fmt : null;
+    }),
+  );
+
+  const finalFormat = probeResults.find((fmt) => fmt !== null);
+  const finalCell = finalFormat
+    ? table
+        .locator(`[aria-label="${formatDate(value, finalFormat)}"], [aria-label*="${formatDate(value, finalFormat)}"]`)
+        .first()
+    : cells[0];
+
+  await finalCell.click(options);
+  return true;
+}
+
+async function setDayByByCellText(table: Locator, value: Date, options?: SetOptions): Promise<boolean> {
+  const day = value.getDate();
+  const cells = table.locator('td, [role="gridcell"]').filter({ visible: true });
+
+  const allTexts = await cells.allInnerTexts();
+  const foundIndices = allTexts.map((text, i) => (text.trim() === String(day) ? i : -1)).filter((i) => i !== -1);
+
+  if (foundIndices.length === 0) return false;
+
+  const index = foundIndices.length === 1 || day < 15 ? foundIndices[0] : foundIndices[foundIndices.length - 1];
+  await cells.nth(index).click(options);
+
+  return true;
+}
+
+async function setDates(calendar: Locator, tables: Locator[], dates: Date[], options?: SetOptions): Promise<void> {
+  let method: 'aria' | 'text' | undefined = undefined;
+
+  for (const date of dates) {
+    if (!(await navigateToMonth(calendar, date, options))) {
+      throw new Error(`Failed to navigate to "${formatDateForInput(date, 'month')}"`);
+    }
+
+    const currentMonths = await getCurrentMonthsAndYears(calendar, date);
+    const targetTotal = date.getFullYear() * 12 + date.getMonth();
+    const tableIndex = currentMonths.findIndex((m) => m.year * 12 + m.month === targetTotal);
+    const table = tables[tableIndex] ?? tables[0];
+
+    if (method !== 'text' && (await setDayByAriaLabel(table, date, options))) {
+      method ??= 'aria';
+      continue;
+    }
+
+    if (method !== 'aria' && (await setDayByByCellText(table, date, options))) {
+      method ??= 'text';
+      continue;
+    }
+
+    throw new Error(`Failed to set date "${formatDateForInput(date, 'date')}"`);
+  }
+}
+
+export async function setCalendarDate({ el, tag }: Loc, value: Value, options?: SetOptions): Promise<boolean> {
+  if (!(value instanceof Date) && !isArray(value, isDate) && !isRange(value, isDate)) return false;
+
+  const dates = isArray(value, isDate) ? value : isRange(value) ? [value.from, value.to] : [value];
+
+  const { calendar, tables } = (await getCalendar(el, options)) ?? {};
+  if (!calendar || !tables || tables.length === 0) return false;
+
+  try {
+    await setDates(calendar, tables, dates, options);
+  } finally {
+    // Close the dialog
+    if (tag === 'input') {
+      await el.page().keyboard.press('Escape').catch();
+      await el.blur().catch();
+    }
+  }
+
+  return true;
+}

package/src/field/date-group.ts

@@ -0,0 +1,253 @@
+import type { Locator } from '@playwright/test';
+import { clearSelect } from './native-select';
+import type { Loc, SetOptions, Value } from './types';
+
+type CandidateInfo = {
+  el: Locator;
+  tag: string;
+  type: string | null;
+  name: string | null;
+  id: string | null;
+  ariaLabel: string | null;
+  placeholder: string | null;
+  min: string | null;
+  max: string | null;
+  inputMode: string | null;
+  attrs: Record<string, string>;
+  options: { value: string; text: string }[];
+};
+
+type Score = { day: number; month: number; year: number };
+
+async function getCandidateLocs(el: Locator, options?: SetOptions): Promise<CandidateInfo[]> {
+  const candidates = await el.locator('input, select').all();
+  if (candidates.length < 2 || candidates.length > 3) return [];
+
+  return Promise.all(
+    candidates.map(async (c) => {
+      const info = await c.evaluate((node) => {
+        const e = node as HTMLInputElement | HTMLSelectElement;
+        const attrs: Record<string, string> = {};
+        for (const attr of e.attributes) {
+          attrs[attr.name] = attr.value;
+        }
+
+        let options: { value: string; text: string }[] = [];
+        if (e.tagName.toLowerCase() === 'select') {
+          options = Array.from((e as HTMLSelectElement).options).map((o) => ({
+            value: o.value,
+            text: o.text,
+          }));
+        }
+
+        return {
+          tag: e.tagName.toLowerCase(),
+          type: e.getAttribute('type'),
+          name: e.getAttribute('name'),
+          id: e.getAttribute('id'),
+          ariaLabel: e.getAttribute('aria-label'),
+          placeholder: e.getAttribute('placeholder'),
+          min: e.getAttribute('min'),
+          max: e.getAttribute('max'),
+          inputMode: e.getAttribute('inputmode'),
+          attrs,
+          options,
+        };
+      }, options);
+      return { el: c, ...info };
+    }),
+  );
+}
+
+function scoreByAttributes(candidateLocs: CandidateInfo[]): Score[] {
+  const scores: Score[] = candidateLocs.map(() => ({ day: 0, month: 0, year: 0 }));
+
+  candidateLocs.forEach((loc, i) => {
+    const text = [loc.name, loc.id, loc.ariaLabel, loc.placeholder, ...Object.values(loc.attrs)]
+      .join(' ')
+      .toLowerCase();
+
+    // 1. Text signals
+    if (/\b(day|dd|d)\b/i.test(text)) scores[i].day += 5;
+    if (/\b(month|mm|m)\b/i.test(text)) scores[i].month += 5;
+    if (/\b(year|yyyy|yy|y)\b/i.test(text)) scores[i].year += 5;
+
+    // 2. Attribute signals
+    if (loc.max) {
+      const max = parseInt(loc.max, 10);
+      if (max >= 1 && max <= 31) scores[i].day += 2;
+      if (max >= 1 && max <= 12) scores[i].month += 2;
+      if (max > 1900) scores[i].year += 2;
+    }
+
+    if (loc.tag === 'select') {
+      if (loc.options.length >= 12 && loc.options.length <= 13) {
+        scores[i].month += 3;
+      }
+      const allNumeric = loc.options.every((o) => !isNaN(parseInt(o.value, 10)) || !o.value);
+      if (allNumeric && loc.options.length >= 12 && loc.options.length <= 13) {
+        scores[i].month += 2;
+      }
+    }
+  });
+
+  return scores;
+}
+
+async function behavioralProbe(candidateLocs: CandidateInfo[], scores: Score[], options?: SetOptions) {
+  const sorted = [...scores].sort((a, b) => Math.max(b.day, b.month, b.year) - Math.max(a.day, a.month, a.year));
+  if (sorted[0].day < 2 && sorted[0].month < 2 && sorted[0].year < 2) {
+    for (let i = 0; i < candidateLocs.length; i++) {
+      const loc = candidateLocs[i];
+      if (loc.tag === 'input') {
+        const can_be_day = await loc.el.evaluate((node) => {
+          const e = node as HTMLInputElement;
+          const old = e.value;
+          e.value = '31';
+          const valid = e.checkValidity();
+          e.value = old;
+          return valid;
+        }, options);
+        if (can_be_day) scores[i].day += 1;
+
+        const cannot_be_day = await loc.el.evaluate((node) => {
+          const e = node as HTMLInputElement;
+          const old = e.value;
+          e.value = '32';
+          const valid = !e.checkValidity();
+          e.value = old;
+          return valid;
+        }, options);
+        if (cannot_be_day) scores[i].day += 1;
+
+        const can_be_month = await loc.el.evaluate((node) => {
+          const e = node as HTMLInputElement;
+          const old = e.value;
+          e.value = '12';
+          const valid = e.checkValidity();
+          e.value = old;
+          return valid;
+        }, options);
+        if (can_be_month) scores[i].month += 1;
+
+        const cannot_be_month = await loc.el.evaluate((node) => {
+          const e = node as HTMLInputElement;
+          const old = e.value;
+          e.value = '13';
+          const valid = !e.checkValidity();
+          e.value = old;
+          return valid;
+        }, options);
+        if (cannot_be_month) scores[i].month += 1;
+
+        const can_be_year = await loc.el.evaluate((node) => {
+          const e = node as HTMLInputElement;
+          const old = e.value;
+          e.value = '2024';
+          const valid = e.checkValidity();
+          e.value = old;
+          return valid;
+        }, options);
+        if (can_be_year) scores[i].year += 1;
+      }
+    }
+  }
+}
+
+function applyTieBreakers(candidateLocs: CandidateInfo[], scores: Score[]) {
+  // Tie-breaker: typical order D-M-Y or Y-M-D
+  if (candidateLocs.length === 3) {
+    scores[0].day += 0.1;
+    scores[1].month += 0.1;
+    scores[2].year += 0.1;
+  }
+}
+
+function resolveDateFields(
+  scores: Score[],
+): { day: number; month: number; year: number } | null {
+  const result: { day?: number; month?: number; year?: number } = {};
+  const used = new Set<number>();
+
+  for (const field of ['year', 'month', 'day'] as const) {
+    let bestIdx = -1;
+    let bestScore = -1;
+    for (let i = 0; i < scores.length; i++) {
+      if (!used.has(i) && scores[i][field] > bestScore) {
+        bestScore = scores[i][field];
+        bestIdx = i;
+      }
+    }
+    if (bestIdx !== -1 && bestScore > 0) {
+      result[field] = bestIdx;
+      used.add(bestIdx);
+    }
+  }
+
+  if (result.day === undefined || result.month === undefined || result.year === undefined) {
+    return null;
+  }
+
+  return result as { day: number; month: number; year: number };
+}
+
+async function setMonthField(monthLoc: CandidateInfo, monthVal: number, options?: SetOptions) {
+  if (monthLoc.tag === 'select') {
+    const options_list = monthLoc.options;
+    const valueMatch = options_list.find((o) => parseInt(o.value, 10) === monthVal);
+    if (valueMatch) {
+      await monthLoc.el.selectOption(valueMatch.value, options);
+    } else {
+      // Try to match by index (considering common 0-indexed or 1-indexed headers)
+      // Usually month selects have 12 or 13 (with placeholder) options
+      const offset = options_list.length === 13 ? 1 : 0;
+      await monthLoc.el.selectOption({ index: monthVal - 1 + offset }, options);
+    }
+  } else {
+    await monthLoc.el.fill(String(monthVal), options);
+  }
+}
+
+async function clearFields(locs: CandidateInfo[], options?: SetOptions) {
+  for (const loc of locs) {
+    if (loc.tag === 'select') {
+      await clearSelect(loc.el, options);
+    } else {
+      await loc.el.clear(options);
+    }
+  }
+}
+
+export async function setDateGroup({ el, tag }: Loc, value: Value, options?: SetOptions): Promise<boolean> {
+  if (!(value instanceof Date) && value !== null) return false;
+  if (tag === 'input' || tag === 'textarea' || tag === 'select') return false;
+
+  const candidateLocs = await getCandidateLocs(el, options);
+  if (candidateLocs.length === 0) return false;
+
+  if (value === null) {
+    await clearFields(candidateLocs, options);
+    return true;
+  }
+
+  const scores = scoreByAttributes(candidateLocs);
+  await behavioralProbe(candidateLocs, scores, options);
+  applyTieBreakers(candidateLocs, scores);
+
+  const result = resolveDateFields(scores);
+
+  if (!result) {
+    const candidatesStr = candidateLocs.map((c) => `${c.tag}[name=${c.name}]`).join(', ');
+    throw new Error(`Could not reliably detect date fields for ${tag}. Detected candidates: ${candidatesStr}`);
+  }
+
+  const dayVal = value.getDate();
+  const monthVal = value.getMonth() + 1;
+  const yearVal = value.getFullYear();
+
+  await candidateLocs[result.day].el.fill(String(dayVal), options);
+  await setMonthField(candidateLocs[result.month], monthVal, options);
+  await candidateLocs[result.year].el.fill(String(yearVal), options);
+
+  return true;
+}