@shanyucoder/flowgrid 0.1.0

package/engines/testcase/_staging-from-portal/runners/lib/semantic-plan.mjs

@@ -0,0 +1,178 @@
+import {
+  bundleIdsFromTags,
+  loadE2eTestRegistry,
+  resolveBundleMatchers,
+  skipMatchersFromTags
+} from './e2e-registry.mjs'
+
+const SECTION_KEYS = ['level1', 'layout', 'accessibility', 'designToken']
+
+/**
+ * @param {string} root
+ * @param {Record<string, unknown>} testcase
+ */
+export async function resolveSemanticPlan(root, testcase) {
+  const { registry } = await loadE2eTestRegistry(root)
+  const tags = testcase.tags ?? []
+  const semantic = testcase.assertions?.semantic ?? {}
+  const warnings = []
+
+  const skipMatchers = skipMatchersFromTags(tags, registry)
+  const bundleIds = bundleIdsFromTags(tags, registry)
+  const bundles = registry.bundles ?? {}
+  const matcherMeta = registry.matchers ?? {}
+
+  /** @type {string[]} */
+  const ordered = []
+
+  for (const bundleId of bundleIds) {
+    ordered.push(...resolveBundleMatchers(bundleId, bundles))
+  }
+
+  for (const key of SECTION_KEYS) {
+    const list = semantic[key]
+    if (Array.isArray(list)) {
+      ordered.push(...list.map(String))
+    }
+  }
+
+  const seen = new Set()
+  /** @type {string[]} */
+  const matchers = []
+  for (const name of ordered) {
+    if (skipMatchers.has(name)) continue
+    if (seen.has(name)) continue
+    const meta = matcherMeta[name]
+    if (!meta) {
+      warnings.push(`unknown semantic matcher "${name}" — add to portal-e2e-test.registry.json`)
+      continue
+    }
+    if (meta.status === 'planned') {
+      warnings.push(`semantic matcher "${name}" is planned — skipped in codegen`)
+      continue
+    }
+    seen.add(name)
+    matchers.push(name)
+  }
+
+  const semanticReady = semantic.ready ?? null
+  const rootTestId = semanticReady?.rootTestId ?? semantic.rootTestId ?? null
+  const tableTestId =
+    semantic.tableTestId ??
+    semanticReady?.waitForTestIds?.find((id) => String(id).includes('table')) ??
+    null
+
+  const layoutOptions = semantic.layoutOptions ?? {}
+  const skipOverlap = layoutOptions.skipOverlap === true
+  const a11y = testcase.a11y && typeof testcase.a11y === 'object' ? testcase.a11y : null
+
+  const matchersNeedingRoot = new Set([
+    'toHaveNoTextOverflow',
+    'toHaveNoElementOverlap',
+    'toHaveValidTableLayout',
+    'toMatchShadcnTableToken',
+  ])
+  if (matchers.some((name) => matchersNeedingRoot.has(name)) && !rootTestId) {
+    warnings.push(
+      'layout/table semantic matchers require assertions.semantic.ready.rootTestId (or semantic.rootTestId)',
+    )
+  }
+
+  if (matchers.includes('toHaveValidTableLayout') && !tableTestId) {
+    warnings.push('toHaveValidTableLayout requires semantic.tableTestId or waitForTestIds containing "table"')
+  }
+
+  const needsConsoleErrors = matchers.some(
+    (name) => matcherMeta[name]?.needsConsoleErrors === true
+  )
+  const useSemanticFixture = matchers.length > 0
+
+  const codegenLines = matchers
+    .map((name) => codegenMatcher(name, { rootTestId, tableTestId, skipOverlap, a11y }))
+    .filter(Boolean)
+
+  return {
+    semanticReady,
+    useSemanticFixture,
+    needsConsoleErrors,
+    semanticCodegenLines: codegenLines,
+    semanticMatchers: matchers,
+    rootTestId,
+    a11y,
+    warnings
+  }
+}
+
+/**
+ * @param {string} matcher
+ * @param {{
+ *   rootTestId: string | null,
+ *   tableTestId: string | null,
+ *   skipOverlap: boolean,
+ *   a11y?: Record<string, unknown> | null
+ * }} ctx
+ */
+function codegenMatcher(matcher, ctx) {
+  const { rootTestId, tableTestId, skipOverlap, a11y } = ctx
+  const a11yOptsLiteral = formatA11yOpts(a11y, rootTestId)
+  const include = rootTestId ? `[data-testid="${rootTestId}"]` : undefined
+  const rootLoc = rootTestId ? `page.getByTestId('${rootTestId}')` : 'page.locator("body")'
+  const scrollOpts = include ? `{ rootSelector: '${include}' }` : '{}'
+  const overflowOpts = `{ allowTruncate: true }`
+
+  switch (matcher) {
+    case 'toHaveNoConsoleErrors':
+      return 'await expect(page).toHaveNoConsoleErrors(consoleErrors)'
+    case 'toHaveNoHorizontalScroll':
+      return `await expect(page).toHaveNoHorizontalScroll(${scrollOpts})`
+    case 'toHaveNoBrokenImages':
+      return 'await expect(page).toHaveNoBrokenImages()'
+    case 'toHaveNoTextOverflow':
+      return `await expect(${rootLoc}).toHaveNoTextOverflow(${overflowOpts})`
+    case 'toHaveNoElementOverlap':
+      if (skipOverlap) return null
+      return `await expect(${rootLoc}).toHaveNoElementOverlap()`
+    case 'toHaveValidTableLayout':
+      if (!tableTestId) return null
+      return `await expect(page.getByTestId('${tableTestId}')).toHaveValidTableLayout()`
+    case 'toHaveNoA11yViolations':
+      return `await expect(page).toHaveNoA11yViolations(${a11yOptsLiteral})`
+    case 'toHaveValidAccessibleNames':
+      return `await expect(page).toHaveValidAccessibleNames(${a11yOptsLiteral})`
+    case 'toHaveValidAria':
+      return `await expect(page).toHaveValidAria(${a11yOptsLiteral})`
+    case 'toHaveAccessibleMedia':
+      return `await expect(page).toHaveAccessibleMedia(${a11yOptsLiteral})`
+    case 'toHaveReadableContrast':
+      return `await expect(page).toHaveReadableContrast(${a11yOptsLiteral})`
+    case 'toHaveValidDocumentSemantics':
+      return `await expect(page).toHaveValidDocumentSemantics(${a11yOptsLiteral})`
+    case 'toMatchShadcnTableToken':
+      if (!tableTestId) return null
+      return `await expect(page.getByTestId('${tableTestId}')).toMatchShadcnTableToken()`
+    default:
+      return null
+  }
+}
+
+/**
+ * Build Playwright expect a11y options from hub `a11y:` block.
+ * @param {Record<string, unknown> | null | undefined} a11y
+ * @param {string | null} rootTestId
+ */
+function formatA11yOpts(a11y, rootTestId) {
+  /** @type {Record<string, unknown>} */
+  const opts = {}
+  if (a11y?.include?.length) {
+    opts.include = Array.isArray(a11y.include) ? a11y.include[0] : a11y.include
+  } else if (rootTestId) {
+    opts.include = `[data-testid="${rootTestId}"]`
+  }
+  if (Array.isArray(a11y?.exclude) && a11y.exclude.length) opts.exclude = a11y.exclude
+  if (Array.isArray(a11y?.tags) && a11y.tags.length) opts.tags = a11y.tags
+  if (Array.isArray(a11y?.disableRules) && a11y.disableRules.length) {
+    opts.disableRules = a11y.disableRules
+  }
+  if (!Object.keys(opts).length) return '{}'
+  return JSON.stringify(opts)
+}

package/engines/testcase/_staging-from-portal/runners/lib/write-files.mjs

@@ -0,0 +1,42 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * @param {string} root
+ * @param {{ relativePath: string, content: string }[]} outputs
+ * @param {{ dryRun?: boolean, force?: boolean }} options
+ */
+export async function writeOutputs(root, outputs, options = {}) {
+  const written = []
+  const skipped = []
+
+  for (const { relativePath, content } of outputs) {
+    const absolutePath = path.join(root, relativePath)
+    const exists = await fileExists(absolutePath)
+
+    if (exists && !options.force) {
+      skipped.push({ relativePath, reason: 'exists (use --force)' })
+      continue
+    }
+
+    if (options.dryRun) {
+      written.push({ relativePath, dryRun: true })
+      continue
+    }
+
+    await mkdir(path.dirname(absolutePath), { recursive: true })
+    await writeFile(absolutePath, content, 'utf8')
+    written.push({ relativePath })
+  }
+
+  return { written, skipped }
+}
+
+async function fileExists(filePath) {
+  try {
+    await readFile(filePath)
+    return true
+  } catch {
+    return false
+  }
+}

package/engines/testcase/_staging-from-portal/runners/validate-registry.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { access } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+import { loadE2eTestRegistry, REGISTRY_REL, resolveBundleMatchers } from './lib/e2e-registry.mjs'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+
+async function pathExists(relativePath) {
+  try {
+    await access(path.join(root, relativePath))
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function main() {
+  const { registry } = await loadE2eTestRegistry(root)
+  const errors = []
+  const warnings = []
+  const bundles = registry.bundles ?? {}
+  const matchers = registry.matchers ?? {}
+
+  console.log(`portal-e2e-test.registry v${registry.version}`)
+  console.log(`  path: ${REGISTRY_REL}`)
+  console.log(`  bundles: ${Object.keys(bundles).join(', ')}`)
+
+  if (registry.fixture) {
+    const exists = await pathExists(registry.fixture)
+    if (!exists) errors.push(`fixture: missing ${registry.fixture}`)
+  }
+
+  for (const [id, bundle] of Object.entries(bundles)) {
+    if (bundle.status === 'planned') {
+      warnings.push(`bundle ${id}: planned`)
+      continue
+    }
+    for (const matcher of resolveBundleMatchers(id, bundles)) {
+      if (!matchers[matcher]) {
+        errors.push(`bundle ${id}: unknown matcher "${matcher}"`)
+      }
+    }
+    for (const parent of bundle.extends ?? []) {
+      if (!bundles[parent]) {
+        errors.push(`bundle ${id}: extends unknown bundle "${parent}"`)
+      }
+    }
+  }
+
+  for (const [id, meta] of Object.entries(matchers)) {
+    if (!meta.layer) {
+      warnings.push(`matcher ${id}: missing layer`)
+    }
+  }
+
+  for (const warning of warnings) {
+    console.warn(`  warn: ${warning}`)
+  }
+
+  if (errors.length) {
+    for (const error of errors) {
+      console.error(`  error: ${error}`)
+    }
+    process.exit(1)
+  }
+
+  console.log('portal:e2e-registry OK')
+}
+
+main().catch((error) => {
+  console.error(error.message ?? error)
+  process.exit(1)
+})

package/engines/testcase/_staging-from-portal/templates/page.ts.hbs

@@ -0,0 +1,52 @@
+// Generated by testcase:gen — edit via testcase YAML + re-gen with --force
+import type { Page } from '@playwright/test'
+import { expect } from '@playwright/test'
+
+import { waitForSemanticUiReady } from '../../helpers/semantic-ui/renderReady'
+
+export class {{pageClassName}} {
+  constructor(private readonly page: Page) {}
+
+  async goto(path = '{{routePath}}') {
+    await this.page.goto(path)
+  }
+
+  async waitForTestId(testId: string) {
+    await expect(this.page.getByTestId(testId)).toBeVisible()
+  }
+
+  async waitForRole(role: string, name?: RegExp | string) {
+    const locator = name !== undefined
+      ? this.page.getByRole(role as Parameters<Page['getByRole']>[0], { name })
+      : this.page.getByRole(role as Parameters<Page['getByRole']>[0])
+    await locator.waitFor()
+  }
+
+  async fill(testId: string, value: string) {
+    await this.page.getByTestId(testId).fill(value)
+  }
+
+  async click(testId: string) {
+    await this.page.getByTestId(testId).click()
+  }
+
+  async expectTestIdVisible(testId: string, visible: boolean) {
+    const locator = this.page.getByTestId(testId)
+    if (visible) {
+      await expect(locator).toBeVisible()
+    } else {
+      await expect(locator).not.toBeAttached()
+    }
+  }
+
+{{#if semanticReady}}
+  async waitForSemanticReady() {
+    await waitForSemanticUiReady(this.page, {
+      rootTestId: '{{semanticReady.rootTestId}}'{{#if semanticReady.waitForTestIds}},
+      waitForTestIds: [{{#each semanticReady.waitForTestIds}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}]{{/if}}{{#if semanticReady.waitForFonts}},
+      waitForFonts: true{{/if}}{{#if semanticReady.waitForImages}},
+      waitForImages: '{{semanticReady.waitForImages}}'{{/if}}
+    })
+  }
+{{/if}}
+}

package/engines/testcase/_staging-from-portal/templates/partials/README.md

@@ -0,0 +1,5 @@
+# testcase-gen partials
+
+Semantic + axe assertion **code** is generated in `lib/semantic-plan.mjs` from `registries/e2e-test.registry.json`.
+
+Handlebars partials for functional steps remain in `spec.ts.hbs`. Future flow partials (delete, confirm dialog) will land here as `partials/flow-*.hbs`.

package/engines/testcase/_staging-from-portal/templates/spec.ts.hbs

@@ -0,0 +1,214 @@
+// Generated by testcase:gen — edit via testcase YAML + re-gen with --force
+
+{{#if useSemanticFixture}}
+
+import { expect, test } from '../fixtures/semantic-ui'
+
+{{else}}
+
+import { test } from '@playwright/test'
+
+{{/if}}
+
+
+
+import { applyTestcaseMocks, applyTestcaseSession } from '../helpers/applyTestcaseMocks'
+
+import { assertRequestMatches, expectNewTabWithUrl, whenNetworkRequest } from '../helpers/testcaseAssertions'
+
+{{#if hasLegacyLayoutOnly}}
+
+import { assertLayoutIntegrity } from '../helpers/assertLayoutIntegrity'
+
+{{/if}}
+
+import { resolvePlaceholder, resolveTestcaseData, resolveTestIdTemplate } from '../helpers/testcaseData'
+
+import { {{pageClassName}} } from '../pages/{{module}}/{{pageClassName}}'
+
+
+
+const TESTCASE_MOCKS = {{json mocks}}
+
+{{#if hasData}}
+
+const TESTCASE_DATA = resolveTestcaseData({{{json data}}})
+
+{{/if}}
+
+
+
+test.describe('{{testcaseId}}', () => {
+
+  test.beforeEach(async ({ page }) => {
+
+{{#if session}}
+
+    await applyTestcaseSession(page, '{{session}}')
+
+{{/if}}
+
+    await applyTestcaseMocks(page, TESTCASE_MOCKS)
+
+  })
+
+
+
+  test('{{testcaseTitle}}', async ({ page{{#if needsConsoleErrors}}, consoleErrors{{/if}} }) => {
+
+    const po = new {{pageClassName}}(page)
+
+{{#if hasData}}
+
+    const data = TESTCASE_DATA
+
+{{/if}}
+
+
+
+{{#each setupSteps}}
+
+{{#if (eq action 'goto')}}
+
+    await po.goto('{{path}}')
+
+{{/if}}
+
+{{#if (eq action 'waitFor')}}
+
+{{#if testId}}
+
+    await po.waitForTestId('{{testId}}')
+
+{{else if role}}
+
+    await po.waitForRole('{{role}}'{{#if roleNameExpr}}, {{roleNameExpr}}{{/if}})
+
+{{/if}}
+
+{{/if}}
+
+{{#if (eq action 'fill')}}
+
+    await po.fill('{{testId}}', {{#if (startsWith value '{{')}}resolvePlaceholder('{{value}}', data){{else}}'{{value}}'{{/if}})
+
+{{/if}}
+
+{{/each}}
+
+{{#each uiVisibility}}
+
+    await po.expectTestIdVisible('{{testId}}', {{visible}})
+
+{{/each}}
+
+{{#if (and networkAssertions.length (not hasNewTabAction))}}
+
+{{#each networkAssertions}}
+
+    const networkResponse{{@index}} = whenNetworkRequest(page, {
+
+      method: '{{method}}',
+
+      path: '{{path}}',
+
+      bodyContains: {{{json bodyContains}}}
+
+    })
+
+{{/each}}
+
+{{#each clickSteps}}
+
+{{#if (includes testId '{{')}}
+
+    await po.click(resolveTestIdTemplate('{{testId}}', data))
+
+{{else}}
+
+    await po.click('{{testId}}')
+
+{{/if}}
+
+{{/each}}
+
+{{#each networkAssertions}}
+
+    await assertRequestMatches(await networkResponse{{@index}}, {
+
+      method: '{{method}}',
+
+      path: '{{path}}',
+
+      bodyContains: {{{json bodyContains}}}
+
+    }, {{#if ../hasData}}data{{else}}{}{{/if}})
+
+{{/each}}
+
+{{/if}}
+
+{{#each uiActions}}
+
+{{#if (eq action 'newTabOpened')}}
+
+{{#if ../primaryNetwork}}
+
+    const networkResponseTab = whenNetworkRequest(page, {
+
+      method: '{{../primaryNetwork.method}}',
+
+      path: '{{../primaryNetwork.path}}',
+
+      bodyContains: {{{json ../primaryNetwork.bodyContains}}}
+
+    })
+
+{{/if}}
+
+    await expectNewTabWithUrl(page, async () => {
+
+      await po.click(resolveTestIdTemplate('{{clickTemplate}}', data))
+
+    }, '{{urlContains}}')
+
+{{#if ../primaryNetwork}}
+
+    await assertRequestMatches(await networkResponseTab, {
+
+      method: '{{../primaryNetwork.method}}',
+
+      path: '{{../primaryNetwork.path}}',
+
+      bodyContains: {{{json ../primaryNetwork.bodyContains}}}
+
+    }, data)
+
+{{/if}}
+
+{{/if}}
+
+{{/each}}
+
+{{#if semanticReady}}
+
+    await po.waitForSemanticReady()
+
+{{/if}}
+
+{{#each semanticCodegenLines}}
+
+    {{{this}}}
+
+{{/each}}
+
+{{#if hasLegacyLayoutOnly}}
+
+    await assertLayoutIntegrity(page, { skipOverlap: true })
+
+{{/if}}
+
+  })
+
+})
+

package/engines/testcase/runners/README.md

@@ -0,0 +1,27 @@
+# testcase:gen
+
+Reads **plans** from the tests hub → writes `tests/e2e/` in the FE project.
+
+```bash
+pnpm testcase:gen:dry --id TC-LOGIN-VALID
+pnpm testcase:gen --id W-AD-AUTH-001
+pnpm testcase:gen --id smoke
+pnpm testcase:gen --testcase "$FLOWGRID_TESTS_DOC/cases/W-AD-AUTH-001/TC-LOGIN-VALID.yaml"
+pnpm testcase:gen --feature W-AD-AUTH-001   # all TC-* under cases/{id}/
+```
+
+Author/edit plans in the **tests hub** (`/testcase`), not in the code project.
+
+## Output containment
+
+Every generated output path is preflighted before any write (dry-run
+included). Targets must resolve lexically beneath `<projectRoot>/tests/e2e`;
+absolute paths, `..` traversal, siblings such as `tests/e2e-evil`, and
+existing symlink path components (which are never followed) are rejected with
+an actionable error. Validation is all-or-nothing: if any output in a batch is
+rejected, nothing is written.
+
+Design `ir/design.yaml` (testIds) is optional enrichment loaded from the **docs
+hub** via `refs.screen` when available. Set `FLOWGRID_DOCS_ROOT` explicitly for
+a non-local docs hub; generation continues with testcase-only context if it is
+unavailable.