@igstack/app-catalog-test-kit 0.18.6

package/src/setup/polyfillLocalStorage.ts

@@ -0,0 +1,34 @@
+/**
+ * Polyfill localStorage for jsdom environments where it's missing or incomplete.
+ *
+ * jsdom only provides localStorage when initialized with a valid URL (not about:blank).
+ * Even with environmentOptions.jsdom.url set, some CI environments (GitHub Actions)
+ * still don't provide a fully functional localStorage. This polyfill ensures it works.
+ */
+if (
+  typeof globalThis.localStorage === 'undefined' ||
+  typeof globalThis.localStorage.clear !== 'function'
+) {
+  const store = new Map<string, string>()
+  const storage: Storage = {
+    getItem: (key: string) => store.get(key) ?? null,
+    setItem: (key: string, value: string) => {
+      store.set(key, String(value))
+    },
+    removeItem: (key: string) => {
+      store.delete(key)
+    },
+    clear: () => {
+      store.clear()
+    },
+    get length() {
+      return store.size
+    },
+    key: (index: number) => [...store.keys()][index] ?? null,
+  }
+  Object.defineProperty(globalThis, 'localStorage', {
+    value: storage,
+    writable: true,
+    configurable: true,
+  })
+}

package/src/setup/svgMock.tsx

@@ -0,0 +1,3 @@
+export default function SvgMock(props: React.SVGProps<SVGSVGElement>) {
+  return <svg data-testid="svg-mock" {...props} />
+}

package/src/setup/testSetup.ts

@@ -0,0 +1,58 @@
+import 'fake-indexeddb/auto'
+import './polyfillLocalStorage'
+import { afterEach, vi } from 'vitest'
+import { cleanup } from '@testing-library/react'
+import { cleanupTestResources } from '../harness/given'
+import React from 'react'
+
+// Mock SVG React component imports (vite-plugin-svgr ?react suffix)
+vi.mock('~/assets/app-catalog.svg?react', () => ({
+  default: (props: React.SVGProps<SVGSVGElement>) =>
+    React.createElement('svg', { 'data-testid': 'svg-mock', ...props }),
+}))
+
+// Mock scrollIntoView — not implemented in jsdom
+Element.prototype.scrollIntoView = vi.fn()
+
+// Clean up after each test
+afterEach(async () => {
+  cleanup()
+  await cleanupTestResources()
+  localStorage.clear()
+  sessionStorage.clear()
+})
+
+// Mock window.matchMedia — required by embla-carousel in jsdom environment
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: (query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  }),
+})
+
+// Mock IntersectionObserver — required by embla-carousel SlidesInView in jsdom
+globalThis.IntersectionObserver = class IntersectionObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+  takeRecords() {
+    return []
+  }
+  readonly root = null
+  readonly rootMargin = ''
+  readonly thresholds = []
+} as unknown as typeof IntersectionObserver
+
+// Mock ResizeObserver — required by embla-carousel ResizeHandler in jsdom
+globalThis.ResizeObserver = class ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+} as unknown as typeof ResizeObserver

package/src/tools/AppDetailTools.ts

@@ -0,0 +1,240 @@
+import { screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+export interface AppVisibleData {
+  title: string
+  description: string | null
+  url: string | null
+  tags: string[]
+  screenshots: { count: number }
+  deprecation: { type: string; comment: string } | null
+}
+
+export class AppDetailTools {
+  private user = userEvent.setup()
+
+  /**
+   * Scrape all visible data from the app detail panel into a structured object.
+   */
+  getVisibleData(): AppVisibleData {
+    const panel = this.getPanel()
+
+    // Title: the large text in the header area
+    const titleEl = panel.querySelector('.text-2xl')
+    const title = titleEl?.textContent.trim() ?? ''
+
+    // Description
+    const descHeading = this.findHeading(panel, 'Description')
+    const description = descHeading
+      ? this.getNextSiblingText(descHeading)
+      : null
+
+    // URL
+    const urlLink = panel.querySelector('a[href][target="_blank"]')
+    const url = urlLink?.getAttribute('href') ?? null
+
+    // Tags
+    const tagsHeading = this.findHeading(panel, 'Tags')
+    const tags: string[] = []
+    if (tagsHeading) {
+      const container = tagsHeading.nextElementSibling
+      if (container) {
+        container
+          .querySelectorAll('[class*="badge"], [data-slot="badge"]')
+          .forEach((badge) => {
+            const text = badge.textContent.trim()
+            if (text) tags.push(text)
+          })
+      }
+    }
+
+    // Screenshots
+    const screenshotHeading = this.findHeading(panel, 'Screenshots')
+    let screenshotCount = 0
+    if (screenshotHeading) {
+      const match = screenshotHeading.textContent.match(/\((\d+)\)/)
+      screenshotCount = match?.[1] ? parseInt(match[1], 10) : 0
+    }
+
+    // Deprecation
+    let deprecation: AppVisibleData['deprecation'] = null
+    const deprecationEl = panel.querySelector(
+      '[class*="border-destructive"], [class*="border-yellow"]',
+    )
+    if (deprecationEl) {
+      const typeEl = deprecationEl.querySelector('h3')
+      const commentEl = deprecationEl.querySelector('p')
+      deprecation = {
+        type: typeEl?.textContent.toLowerCase().includes('discouraged')
+          ? 'discouraged'
+          : 'deprecated',
+        comment: commentEl?.textContent.trim() ?? '',
+      }
+    }
+
+    return {
+      title,
+      description,
+      url,
+      tags,
+      screenshots: { count: screenshotCount },
+      deprecation,
+    }
+  }
+
+  /**
+   * Get the sub-resources section data from the detail panel.
+   * Returns null if no sub-resources section is visible.
+   */
+  getSubResources(): {
+    total: number
+    visible: number
+    names: string[]
+  } | null {
+    const panel = this.getPanel()
+    const heading = Array.from(panel.querySelectorAll('div')).find((el) =>
+      el.textContent.match(/Sub-Resources \(\d+ of \d+\)/),
+    )
+    if (!heading) return null
+
+    const match = heading.textContent.match(/Sub-Resources \((\d+) of (\d+)\)/)
+    const visible = match?.[1] ? parseInt(match[1], 10) : 0
+    const total = match?.[2] ? parseInt(match[2], 10) : 0
+
+    const names: string[] = []
+    const rows = panel.querySelectorAll('table tbody tr')
+    rows.forEach((row) => {
+      const nameCell = row.querySelector('td .font-medium')
+      if (nameCell?.textContent) {
+        names.push(nameCell.textContent.trim())
+      }
+    })
+
+    return { total, visible, names }
+  }
+
+  /**
+   * Read the "How to get access" section text from the detail panel.
+   * Returns null if the section is not present.
+   */
+  getAccessText(): string | null {
+    const panel = this.getPanel()
+    const heading = this.findHeading(panel, 'How to get access')
+    if (!heading) return null
+    // The section is the heading plus its following content wrapper.
+    const container = heading.parentElement ?? heading
+    return container.textContent.trim()
+  }
+
+  screenshots = {
+    /**
+     * Click the screenshot preview to open the gallery modal.
+     */
+    open: async (): Promise<void> => {
+      const panel = this.getPanel()
+      const screenshotArea = panel.querySelector('.cursor-pointer')
+      if (!screenshotArea) {
+        throw new Error('No clickable screenshot found in detail panel')
+      }
+      await this.user.click(screenshotArea)
+    },
+  }
+
+  /** Click the "View replacement: <App>" link in a deprecated app's panel. */
+  async clickViewReplacement(): Promise<void> {
+    const btn = screen.getByRole('button', { name: /View replacement:/i })
+    await this.user.click(btn)
+  }
+
+  /** The title shown in the currently open detail panel (empty if none). */
+  getOpenTitle(): string {
+    const panel = this.getPanel()
+    return panel.querySelector('.text-2xl')?.textContent.trim() ?? ''
+  }
+
+  /**
+   * The prominent primary "Open" button in the app detail card.
+   * Returns the anchor element when the app has an appUrl, null otherwise.
+   */
+  getOpenButton(): HTMLAnchorElement | null {
+    const panel = this.getPanel()
+    return (
+      panel.querySelector<HTMLAnchorElement>('[aria-label^="Open "]') ?? null
+    )
+  }
+
+  /**
+   * Get sub-resource detail panel data when a sub-resource is selected.
+   * Returns null if the sub-resource detail panel is not shown.
+   */
+  getSubResourceDetail(): {
+    subResourceName: string
+    hasStep1: boolean
+    hasStep2: boolean
+    backButtonLabel: string | null
+  } | null {
+    const panel = document.querySelector<HTMLElement>(
+      '[aria-label^="Back to "]',
+    )
+    if (!panel) return null
+
+    const backButtonEl = document.querySelector<HTMLElement>(
+      '[aria-label^="Back to "]',
+    )
+    const backButtonLabel = backButtonEl?.getAttribute('aria-label') ?? null
+
+    // Sub-resource name: h2 in the detail panel area
+    const h2 = document.querySelector('h2.text-xl')
+    const subResourceName = (h2?.textContent ?? '').trim()
+
+    // Step badges: circles with "1" and "2" text
+    const stepBadges = Array.from(
+      document.querySelectorAll<HTMLElement>('span.rounded-full'),
+    )
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const getText = (el: HTMLElement) => (el.textContent ?? '').trim()
+    const hasStep1 = stepBadges.some((el) => getText(el) === '1')
+    const hasStep2 = stepBadges.some((el) => getText(el) === '2')
+
+    return { subResourceName, hasStep1, hasStep2, backButtonLabel }
+  }
+
+  async clickBackToParent(): Promise<void> {
+    const backButton = document.querySelector<HTMLButtonElement>(
+      '[aria-label^="Back to "]',
+    )
+    if (!backButton) {
+      throw new Error('Back-to-parent button not found in detail panel')
+    }
+    await this.user.click(backButton)
+  }
+
+  private getPanel(): HTMLElement {
+    const closeButton = screen.queryByLabelText('Close details panel')
+    if (!closeButton) {
+      throw new Error('App detail panel is not open')
+    }
+    // The panel is the closest scrollable container
+    const panel = closeButton.closest('[class*="overflow-y-auto"]')
+    if (!panel) {
+      throw new Error('Could not find detail panel container')
+    }
+    return panel as HTMLElement
+  }
+
+  private findHeading(
+    container: HTMLElement,
+    text: string,
+  ): HTMLElement | null {
+    const headings = container.querySelectorAll('h3')
+    for (const h of headings) {
+      if (h.textContent.includes(text)) return h as HTMLElement
+    }
+    return null
+  }
+
+  private getNextSiblingText(heading: HTMLElement): string | null {
+    const sibling = heading.nextElementSibling
+    return sibling?.textContent.trim() ?? null
+  }
+}

package/src/tools/BrowserState.ts

@@ -0,0 +1,41 @@
+import type { AppCatalogData } from '@igstack/app-catalog-backend-core'
+import {
+  AcDb,
+  dbCacheDbKeys,
+} from '@igstack/app-catalog-frontend-core/internal'
+
+/**
+ * Pre-populate the browser's local state to simulate a returning user.
+ * Call before `given()` to set up IndexedDB cache and localStorage flags.
+ *
+ * Usage:
+ *   await browserState.seedCatalogCache(data)
+ *   browserState.dismissOnboarding()
+ */
+export const browserState = {
+  /**
+   * Seed the IndexedDB cache with app catalog data,
+   * as if the user has previously loaded the app.
+   */
+  async seedCatalogCache(data: AppCatalogData): Promise<void> {
+    const db = new AcDb()
+    await db.appCatalog.put(data, dbCacheDbKeys.AppCatalog)
+    db.close()
+  },
+
+  /**
+   * Mark the onboarding card as dismissed in localStorage,
+   * as if the user has already seen and closed it.
+   */
+  dismissOnboarding(): void {
+    localStorage.setItem('app-catalog-onboarding-dismissed', 'true')
+  },
+
+  /**
+   * Simulate a returning user: onboarding dismissed + catalog data cached.
+   */
+  async returningUser(data: AppCatalogData): Promise<void> {
+    this.dismissOnboarding()
+    await this.seedCatalogCache(data)
+  },
+}

package/src/tools/CatalogTools.ts

@@ -0,0 +1,254 @@
+import { fireEvent, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+export interface TableRow {
+  name: string
+  description: string
+}
+
+export class CatalogTools {
+  private user = userEvent.setup()
+
+  /**
+   * Click an app row by display name.
+   * Works against both the table/grid view and the launcher home (#38), which
+   * renders app rows as buttons rather than a <table>.
+   * Throws with list of visible apps if name not found.
+   */
+  async openApp(name: string): Promise<void> {
+    const table = this.getCatalogTable()
+    if (table) {
+      const rows = within(table).getAllByRole('row')
+      for (const row of rows) {
+        const nameEl = row.querySelector('.font-medium')
+        if (nameEl?.textContent.trim() === name) {
+          await this.user.click(row)
+          return
+        }
+      }
+    } else {
+      // Launcher home: rows are buttons titled "View <name>".
+      const btn = screen.queryByTitle(`View ${name}`)
+      if (btn) {
+        await this.user.click(btn)
+        return
+      }
+    }
+
+    const visibleNames = this.getTableData().map((r) => r.name)
+    throw new Error(
+      `App "${name}" not found. Visible apps: [${visibleNames.join(', ')}]`,
+    )
+  }
+
+  /**
+   * Type into the search input.
+   */
+  async search(text: string): Promise<void> {
+    const input = screen.getByLabelText('Search apps')
+    fireEvent.change(input, { target: { value: text } })
+  }
+
+  /** The catalog search input. */
+  getSearchInput(): HTMLInputElement {
+    return screen.getByLabelText<HTMLInputElement>('Search apps')
+  }
+
+  /**
+   * Parse the catalog table into structured data.
+   * Skips group header rows (colspan rows).
+   */
+  getTableData(): TableRow[] {
+    const table = this.getCatalogTable()
+    if (!table) {
+      // Check if there's a global error — throw with details for debugging
+      const bodyText = document.body.textContent
+      if (
+        bodyText.includes('Something went wrong') ||
+        bodyText.includes('Ooops')
+      ) {
+        throw new Error(
+          `Cannot read table — global error on page: ${bodyText.slice(0, 500)}`,
+        )
+      }
+      // Launcher home (#38): no <table>; read the app row buttons instead.
+      const launcherRows = this.getLauncherRows()
+      if (launcherRows.length > 0) return launcherRows
+      throw new Error('No table or launcher rows found on page')
+    }
+
+    const rows = within(table).getAllByRole('row')
+    const result: TableRow[] = []
+
+    for (const row of rows) {
+      const cells = within(row).queryAllByRole('cell')
+      // Skip header rows and group header rows (single cell with colspan)
+      if (cells.length < 2) continue
+
+      const nameEl = cells[0]?.querySelector('.font-medium')
+      if (!nameEl) continue
+
+      result.push({
+        name: nameEl.textContent.trim(),
+        description: cells[1]?.textContent.trim() ?? '',
+      })
+    }
+
+    return result
+  }
+
+  /**
+   * The secondary "open in new tab" launch link for a row, by app name.
+   * Returns null if the row has no launch link.
+   */
+  getLaunchLink(name: string): HTMLAnchorElement | null {
+    // The launch link's aria-label starts with "Open <name> in a new tab" and
+    // may append the destination URL, e.g. "… in a new tab (foo.example.com)".
+    return screen.queryByLabelText<HTMLAnchorElement>(
+      new RegExp(`^Open ${name} in a new tab`),
+    )
+  }
+
+  /**
+   * Whether the right detail panel is currently visible.
+   */
+  isDetailPanelOpen(): boolean {
+    return !!screen.queryByLabelText('Close details panel')
+  }
+
+  /** Whether the "Show Deprecated Apps" toggle is currently checked. */
+  isShowDeprecatedChecked(): boolean {
+    const cb = screen.getByRole('checkbox', { name: /Show Deprecated Apps/i })
+    return (
+      cb.getAttribute('aria-checked') === 'true' ||
+      cb.getAttribute('data-state') === 'checked'
+    )
+  }
+
+  /** Whether the "showing deprecated matches" fallback notice is visible. */
+  hasDeprecatedFallbackNotice(): boolean {
+    return !!screen.queryByText(/showing deprecated matches/i)
+  }
+
+  /** Whether the "No apps found" empty state or search-morph "No results for" is visible. */
+  isEmptyStateVisible(): boolean {
+    return (
+      !!screen.queryByText(/No apps found/i) ||
+      !!screen.queryByText(/No results for/i)
+    )
+  }
+
+  /**
+   * Whether the onboarding/welcome card is visible.
+   */
+  isOnboardingVisible(): boolean {
+    return !!screen.queryByText('Welcome to App Catalog')
+  }
+
+  /**
+   * Read app rows from the launcher home (#38): buttons titled "View <name>".
+   * Name is the first `.font-semibold`/`.font-bold` span; description the
+   * `.text-muted-foreground` span. Deduped by name (an app can appear both in
+   * "Your apps" and "Browse all").
+   */
+  private getLauncherRows(): TableRow[] {
+    const buttons = Array.from(
+      document.querySelectorAll<HTMLElement>('button[title^="View "]'),
+    )
+    const seen = new Set<string>()
+    const result: TableRow[] = []
+    for (const btn of buttons) {
+      const name = (btn.getAttribute('title') ?? '')
+        .replace(/^View\s+/, '')
+        .trim()
+      if (!name || seen.has(name)) continue
+      seen.add(name)
+      const descEl = btn.querySelector('.text-muted-foreground')
+      result.push({ name, description: descEl?.textContent.trim() ?? '' })
+    }
+    return result
+  }
+
+  /**
+   * Get expandable subresource rows shown under parents in search results.
+   * Returns null if no sub-rows are visible.
+   */
+  getSubResourceRows(): {
+    visible: number
+    total: number
+    hasExpandRow: boolean
+    names: string[]
+  } | null {
+    const subButtons = Array.from(
+      document.querySelectorAll<HTMLButtonElement>(
+        'button[class*="border-l-2"]',
+      ),
+    )
+    if (subButtons.length === 0) return null
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const getText = (el: HTMLButtonElement) => (el.textContent ?? '').trim()
+    const isExpandRow = (el: HTMLButtonElement) => getText(el).startsWith('...')
+
+    const expandButton = subButtons.find(isExpandRow)
+    const hasExpandRow = !!expandButton
+
+    let hiddenCount = 0
+    if (expandButton) {
+      const match = /\d+/.exec(getText(expandButton))
+      hiddenCount = match?.[0] ? parseInt(match[0], 10) : 0
+    }
+
+    const visibleSubs = subButtons.filter((b) => !isExpandRow(b))
+
+    return {
+      visible: visibleSubs.length,
+      total: visibleSubs.length + hiddenCount,
+      hasExpandRow,
+      names: visibleSubs.map((b) => getText(b)),
+    }
+  }
+
+  async clickSubResource(displayName: string): Promise<void> {
+    const subButtons = Array.from(
+      document.querySelectorAll<HTMLButtonElement>(
+        'button[class*="border-l-2"]',
+      ),
+    )
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const getText = (el: HTMLButtonElement) => (el.textContent ?? '').trim()
+    const target = subButtons.find(
+      (b) =>
+        getText(b) === displayName && !getText(b).trimStart().startsWith('...'),
+    )
+    if (!target) {
+      throw new Error(
+        `Sub-resource "${displayName}" not found in search result rows`,
+      )
+    }
+    await this.user.click(target)
+  }
+
+  async expandSubResources(): Promise<void> {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const getText = (el: HTMLButtonElement) => (el.textContent ?? '').trim()
+    const expandButtons = Array.from(
+      document.querySelectorAll<HTMLButtonElement>(
+        'button[class*="border-l-2"]',
+      ),
+    ).filter((b) => getText(b).trimStart().startsWith('...'))
+    if (expandButtons.length === 0) {
+      throw new Error('No expand ("...N more") button found')
+    }
+    await this.user.click(expandButtons[0]!)
+  }
+
+  /**
+   * Get the main catalog table (first table on page, skipping sub-resource tables in detail panel).
+   */
+  private getCatalogTable(): HTMLElement | null {
+    const tables = screen.queryAllByRole('table')
+    // The catalog table is the first table; sub-resource tables appear later in the detail panel
+    return tables[0] ?? null
+  }
+}

package/src/tools/ErrorTools.ts

@@ -0,0 +1,49 @@
+import { screen } from '@testing-library/react'
+
+export interface GlobalError {
+  title: string
+  message: string
+  element: HTMLElement
+}
+
+/**
+ * Find the global error on page.
+ *
+ * Checks for:
+ * 1. Our custom DefaultErrorComponent (role="alert" with "Ooops!")
+ * 2. TanStack Router's built-in error boundary ("Something went wrong!")
+ *
+ * Throws with page content dump if no error is found — makes debugging easier.
+ */
+export function getGlobalError(): GlobalError {
+  // Check our custom error component first
+  const alertElement = screen.queryByRole('alert')
+  if (alertElement) {
+    const messageEl = alertElement.querySelector('i')
+    return {
+      title: 'Ooops!',
+      message: messageEl?.textContent ?? alertElement.textContent,
+      element: alertElement,
+    }
+  }
+
+  // Check TanStack Router's built-in error boundary
+  const bodyText = document.body.textContent
+  if (bodyText.includes('Something went wrong')) {
+    const codeEl = document.querySelector('code')
+    const errorContainer =
+      document.querySelector('[style*="padding"]') ?? document.body
+    return {
+      title: 'Something went wrong!',
+      message: codeEl?.textContent ?? bodyText,
+      element: errorContainer as HTMLElement,
+    }
+  }
+
+  // No error found — dump page for debugging
+  const body = document.body.innerHTML
+  const snippet = body.length > 2000 ? body.slice(0, 2000) + '...' : body
+  throw new Error(
+    `No global error found on page. Expected a role="alert" or "Something went wrong" element.\n\nPage content:\n${snippet}`,
+  )
+}