@cementic/cementic-test 0.2.12 → 0.2.13

package/dist/cli.js

@@ -501,6 +501,315 @@ function buildProviderConfigs(env) {
 function getAvailableCtVarKeys() {
   return Object.keys(process.env).filter((key) => /^CT_VAR_[A-Z0-9_]+$/.test(key)).sort();
 }
+var RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE = `
+RULE 10 - PLAYWRIGHT KNOWLEDGE BASE
+(sourced from playwright.dev official documentation)
+
+You are an expert in Playwright TypeScript. Apply this knowledge
+when generating test code. Always use web-first assertions that
+auto-wait. Never use manual waits or non-awaited assertions.
+
+LOCATOR PRIORITY (use in this order)
+1. page.getByRole('button', { name: 'Submit' })     <- best
+2. page.getByLabel('Email address')
+3. page.getByPlaceholder('Enter email')
+4. page.getByText('Welcome')
+5. page.getByAltText('logo')
+6. page.getByTitle('Close')
+7. page.getByTestId('submit-btn')
+8. page.locator('#id') or page.locator('.class')    <- last resort
+
+Chain locators to narrow scope:
+  page.getByRole('listitem').filter({ hasText: 'Product 2' })
+    .getByRole('button', { name: 'Add to cart' }).click()
+
+LOCATOR ASSERTIONS (always await, always web-first)
+Visibility:
+  await expect(locator).toBeVisible()
+  await expect(locator).toBeHidden()
+  await expect(locator).toBeInViewport()
+
+State:
+  await expect(locator).toBeEnabled()
+  await expect(locator).toBeDisabled()
+  await expect(locator).toBeChecked()
+  await expect(locator).not.toBeChecked()
+  await expect(locator).toBeFocused()
+  await expect(locator).toBeEditable()
+  await expect(locator).toBeEmpty()
+  await expect(locator).toBeAttached()
+
+Text content:
+  await expect(locator).toHaveText('exact text')
+  await expect(locator).toHaveText(/regex/)
+  await expect(locator).toContainText('partial')
+  await expect(locator).toContainText(['item1', 'item2'])
+
+Value and attributes:
+  await expect(locator).toHaveValue('input value')
+  await expect(locator).toHaveValues(['opt1', 'opt2'])  // multi-select
+  await expect(locator).toHaveAttribute('href', /pattern/)
+  await expect(locator).toHaveClass(/active/)
+  await expect(locator).toHaveCSS('color', 'rgb(0,0,0)')
+  await expect(locator).toHaveId('submit-btn')
+  await expect(locator).toHaveAccessibleName('Submit form')
+  await expect(locator).toHaveAccessibleDescription('...')
+
+Counting (PREFER toHaveCount over .count() to avoid flakiness):
+  await expect(locator).toHaveCount(3)
+  await expect(locator).toHaveCount(0)   // none exist
+  // Only use .count() when you need the actual number:
+  const n = await page.getByRole('button').count();
+  console.log(\`Found \${n} buttons\`);
+
+PAGE ASSERTIONS
+  await expect(page).toHaveTitle(/Playwright/)
+  await expect(page).toHaveTitle('Exact Title')
+  await expect(page).toHaveURL('https://example.com/dashboard')
+  await expect(page).toHaveURL(/\\/dashboard/)
+
+ACTIONS (Playwright auto-waits before each action)
+Navigation:
+  await page.goto('https://example.com')
+  await page.goBack()
+  await page.goForward()
+  await page.reload()
+
+Clicking:
+  await locator.click()
+  await locator.dblclick()
+  await locator.click({ button: 'right' })
+  await locator.click({ modifiers: ['Shift'] })
+
+Forms:
+  await locator.fill('text')           // clears then types
+  await locator.clear()
+  await locator.pressSequentially('slow typing', { delay: 50 })
+  await locator.selectOption('value')
+  await locator.selectOption({ label: 'Blue' })
+  await locator.check()
+  await locator.uncheck()
+  await locator.setInputFiles('path/to/file.pdf')
+
+Hover and focus:
+  await locator.hover()
+  await locator.focus()
+  await locator.blur()
+
+Keyboard:
+  await page.keyboard.press('Enter')
+  await page.keyboard.press('Tab')
+  await page.keyboard.press('Escape')
+  await page.keyboard.press('Control+A')
+
+Scroll:
+  await locator.scrollIntoViewIfNeeded()
+  await page.mouse.wheel(0, 500)
+
+BEST PRACTICES (from playwright.dev/docs/best-practices)
+DO use web-first assertions:
+   await expect(page.getByText('welcome')).toBeVisible()
+
+NEVER use synchronous assertions:
+   expect(await page.getByText('welcome').isVisible()).toBe(true)
+
+DO chain locators:
+   page.getByRole('listitem').filter({ hasText: 'Product 2' })
+     .getByRole('button', { name: 'Add to cart' })
+
+NEVER use fragile CSS/XPath selectors:
+   page.locator('button.buttonIcon.episode-actions-later')
+
+DO use role-based locators:
+   page.getByRole('button', { name: 'submit' })
+
+INTENT -> PATTERN MAPPING
+
+COUNTING:
+  "how many X" / "count X" / "number of X" / "return the count"
+  -> const n = await page.getByRole('X').count();
+    console.log(\`Found \${n} X elements\`);
+    expect(n).toBeGreaterThan(0);
+
+  "there are N X" / "exactly N X"
+  -> await expect(page.getByRole('X')).toHaveCount(N);
+
+  CRITICAL: Never use getByText("how many X") - count intent
+  means call .count() or toHaveCount(), not search for text.
+
+PRESENCE:
+  "X is present/visible/shown/exists"
+  -> await expect(locator).toBeVisible()
+
+  "X is hidden/not present/gone"
+  -> await expect(locator).toBeHidden()
+
+TEXT:
+  "text says X" / "shows X" / "message is X"
+  -> await expect(locator).toHaveText('X')
+
+  "contains X" / "includes X"
+  -> await expect(locator).toContainText('X')
+
+  "page title is X"
+  -> await expect(page).toHaveTitle(/X/i)
+
+  "heading says X"
+  -> await expect(page.getByRole('heading')).toContainText('X')
+
+  "error says X"
+  -> await expect(page.getByRole('alert')).toContainText('X')
+
+STATE:
+  "X is enabled/disabled"
+  -> await expect(locator).toBeEnabled() / toBeDisabled()
+
+  "X is checked/unchecked"
+  -> await expect(locator).toBeChecked() / not.toBeChecked()
+
+  "X has value Y"
+  -> await expect(locator).toHaveValue('Y')
+
+  "X is active / has class Y"
+  -> await expect(locator).toHaveClass(/Y/)
+
+NAVIGATION:
+  "redirects to X" / "goes to X" / "URL contains X"
+  -> await expect(page).toHaveURL(/X/)
+
+  "stays on same page"
+  -> await expect(page).toHaveURL(/currentPath/)
+
+  "opens new tab"
+  -> const [newPage] = await Promise.all([
+      context.waitForEvent('page'),
+      locator.click()
+    ]);
+
+FORMS:
+  "form submits successfully"
+  -> fill fields + click submit + assert URL change or success message
+
+  "validation error shown"
+  -> submit empty + await expect(page.getByRole('alert')).toBeVisible()
+
+  "required field X"
+  -> submit without X + assert error message for X visible
+
+AUTH:
+  "login with valid credentials"
+  -> fill(CT_VAR_USERNAME) + fill(CT_VAR_PASSWORD) + click login
+    + await expect(page).toHaveURL(/dashboard|home|app/)
+
+  "login fails / invalid credentials"
+  -> fill bad values + click login
+    + await expect(page.getByRole('alert')).toBeVisible()
+
+  "logout works"
+  -> click logout + await expect(page).toHaveURL(/login|home/)
+
+THEME / VISUAL:
+  "dark mode / theme toggle"
+  -> await locator.click()
+    + await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark')
+    // OR: await expect(page.locator('body')).toHaveClass(/dark/)
+
+TIMING:
+  "X loads / X appears"
+  -> await expect(locator).toBeVisible({ timeout: 10000 })
+
+  "spinner disappears / loader gone"
+  -> await expect(spinner).toBeHidden({ timeout: 10000 })
+
+  "modal closes"
+  -> await expect(modal).toBeHidden()
+
+ACCESSIBILITY:
+  "has alt text"
+  -> await expect(page.locator('img')).toHaveAttribute('alt', /.+/)
+
+  "keyboard navigable"
+  -> await page.keyboard.press('Tab')
+    + await expect(firstFocusable).toBeFocused()
+
+CRITICAL RULES
+1. NEVER use intent words as locator text.
+   "count buttons" != getByText("count buttons")
+   "verify heading" != getByText("verify heading")
+
+2. ALWAYS use web-first assertions (await expect).
+   NEVER use: expect(await locator.isVisible()).toBe(true)
+
+3. For counting, prefer toHaveCount() over .count() unless
+   you need the actual number for logging.
+
+4. Auto-waiting: Playwright automatically waits for elements
+   to be actionable before click/fill/etc. Do not add
+   manual waitForTimeout() unless testing timing specifically.
+
+5. Use not. prefix for negative assertions:
+   await expect(locator).not.toBeVisible()
+   await expect(locator).not.toBeChecked()
+`.trim();
+var ADVANCED_DOC_MAP = {
+  upload: "https://playwright.dev/docs/input",
+  "file upload": "https://playwright.dev/docs/input",
+  intercept: "https://playwright.dev/docs/mock",
+  mock: "https://playwright.dev/docs/mock",
+  "api mock": "https://playwright.dev/docs/mock",
+  accessibility: "https://playwright.dev/docs/accessibility-testing",
+  "screen reader": "https://playwright.dev/docs/accessibility-testing",
+  visual: "https://playwright.dev/docs/screenshots",
+  screenshot: "https://playwright.dev/docs/screenshots",
+  mobile: "https://playwright.dev/docs/emulation",
+  responsive: "https://playwright.dev/docs/emulation",
+  viewport: "https://playwright.dev/docs/emulation",
+  network: "https://playwright.dev/docs/network",
+  "api call": "https://playwright.dev/docs/network",
+  iframe: "https://playwright.dev/docs/frames",
+  frame: "https://playwright.dev/docs/frames",
+  auth: "https://playwright.dev/docs/auth",
+  "sign in": "https://playwright.dev/docs/auth",
+  "stay logged": "https://playwright.dev/docs/auth",
+  cookie: "https://playwright.dev/docs/auth",
+  storage: "https://playwright.dev/docs/auth",
+  download: "https://playwright.dev/docs/downloads",
+  pdf: "https://playwright.dev/docs/downloads",
+  dialog: "https://playwright.dev/docs/dialogs",
+  alert: "https://playwright.dev/docs/dialogs",
+  confirm: "https://playwright.dev/docs/dialogs",
+  "new tab": "https://playwright.dev/docs/pages",
+  "new page": "https://playwright.dev/docs/pages",
+  popup: "https://playwright.dev/docs/pages"
+};
+async function fetchDocContext(intent) {
+  const intentLower = intent.toLowerCase();
+  const matched = /* @__PURE__ */ new Set();
+  for (const [keyword, url] of Object.entries(ADVANCED_DOC_MAP)) {
+    if (intentLower.includes(keyword)) {
+      matched.add(url);
+    }
+  }
+  if (matched.size === 0) return "";
+  const fetched = [];
+  for (const url of matched) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
+      const html = await res.text();
+      const text = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s{3,}/g, "\n\n").slice(0, 3e3);
+      fetched.push(`
+// From ${url}:
+${text}`);
+    } catch {
+    }
+  }
+  if (fetched.length === 0) return "";
+  return `
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ADDITIONAL PLAYWRIGHT DOCS (fetched for this intent)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501${fetched.join("\n")}`;
+}
 function buildSystemMessage() {
   return `
 You are a senior software test architect with 10 years of Playwright experience.
@@ -567,6 +876,8 @@ Match scenario count to intent complexity:
 - Full flow: 4 to 8 scenarios maximum
 Never exceed 8 scenarios.
 
+${RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE}
+
 COMMON TESTING VOCABULARY
 "verify/check X is present/visible" -> toBeVisible()
 "verify title/heading" -> heading is visible
@@ -725,7 +1036,8 @@ async function callOpenAiCompatible(apiKey, model, baseUrl, displayName, system,
 }
 async function generateTcMarkdownWithAi(ctx) {
   const providerConfig = resolveLlmProvider();
-  const system = buildSystemMessage();
+  const docContext = await fetchDocContext(ctx.feature);
+  const system = buildSystemMessage() + docContext;
   const user = buildUserMessage(ctx);
   console.log(`\u{1F916} Using ${providerConfig.displayName} (${providerConfig.model})`);
   if (providerConfig.transport === "anthropic") {
@@ -742,13 +1054,323 @@ async function generateTcMarkdownWithAi(ctx) {
 }
 
 // src/core/analyse.ts
+var RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE2 = `
+RULE 10 - PLAYWRIGHT KNOWLEDGE BASE
+(sourced from playwright.dev official documentation)
+
+You are an expert in Playwright TypeScript. Apply this knowledge
+when generating test code. Always use web-first assertions that
+auto-wait. Never use manual waits or non-awaited assertions.
+
+LOCATOR PRIORITY (use in this order)
+1. page.getByRole('button', { name: 'Submit' })     <- best
+2. page.getByLabel('Email address')
+3. page.getByPlaceholder('Enter email')
+4. page.getByText('Welcome')
+5. page.getByAltText('logo')
+6. page.getByTitle('Close')
+7. page.getByTestId('submit-btn')
+8. page.locator('#id') or page.locator('.class')    <- last resort
+
+Chain locators to narrow scope:
+  page.getByRole('listitem').filter({ hasText: 'Product 2' })
+    .getByRole('button', { name: 'Add to cart' }).click()
+
+LOCATOR ASSERTIONS (always await, always web-first)
+Visibility:
+  await expect(locator).toBeVisible()
+  await expect(locator).toBeHidden()
+  await expect(locator).toBeInViewport()
+
+State:
+  await expect(locator).toBeEnabled()
+  await expect(locator).toBeDisabled()
+  await expect(locator).toBeChecked()
+  await expect(locator).not.toBeChecked()
+  await expect(locator).toBeFocused()
+  await expect(locator).toBeEditable()
+  await expect(locator).toBeEmpty()
+  await expect(locator).toBeAttached()
+
+Text content:
+  await expect(locator).toHaveText('exact text')
+  await expect(locator).toHaveText(/regex/)
+  await expect(locator).toContainText('partial')
+  await expect(locator).toContainText(['item1', 'item2'])
+
+Value and attributes:
+  await expect(locator).toHaveValue('input value')
+  await expect(locator).toHaveValues(['opt1', 'opt2'])  // multi-select
+  await expect(locator).toHaveAttribute('href', /pattern/)
+  await expect(locator).toHaveClass(/active/)
+  await expect(locator).toHaveCSS('color', 'rgb(0,0,0)')
+  await expect(locator).toHaveId('submit-btn')
+  await expect(locator).toHaveAccessibleName('Submit form')
+  await expect(locator).toHaveAccessibleDescription('...')
+
+Counting (PREFER toHaveCount over .count() to avoid flakiness):
+  await expect(locator).toHaveCount(3)
+  await expect(locator).toHaveCount(0)   // none exist
+  // Only use .count() when you need the actual number:
+  const n = await page.getByRole('button').count();
+  console.log(\`Found \${n} buttons\`);
+
+PAGE ASSERTIONS
+  await expect(page).toHaveTitle(/Playwright/)
+  await expect(page).toHaveTitle('Exact Title')
+  await expect(page).toHaveURL('https://example.com/dashboard')
+  await expect(page).toHaveURL(/\\/dashboard/)
+
+ACTIONS (Playwright auto-waits before each action)
+Navigation:
+  await page.goto('https://example.com')
+  await page.goBack()
+  await page.goForward()
+  await page.reload()
+
+Clicking:
+  await locator.click()
+  await locator.dblclick()
+  await locator.click({ button: 'right' })
+  await locator.click({ modifiers: ['Shift'] })
+
+Forms:
+  await locator.fill('text')           // clears then types
+  await locator.clear()
+  await locator.pressSequentially('slow typing', { delay: 50 })
+  await locator.selectOption('value')
+  await locator.selectOption({ label: 'Blue' })
+  await locator.check()
+  await locator.uncheck()
+  await locator.setInputFiles('path/to/file.pdf')
+
+Hover and focus:
+  await locator.hover()
+  await locator.focus()
+  await locator.blur()
+
+Keyboard:
+  await page.keyboard.press('Enter')
+  await page.keyboard.press('Tab')
+  await page.keyboard.press('Escape')
+  await page.keyboard.press('Control+A')
+
+Scroll:
+  await locator.scrollIntoViewIfNeeded()
+  await page.mouse.wheel(0, 500)
+
+BEST PRACTICES (from playwright.dev/docs/best-practices)
+DO use web-first assertions:
+   await expect(page.getByText('welcome')).toBeVisible()
+
+NEVER use synchronous assertions:
+   expect(await page.getByText('welcome').isVisible()).toBe(true)
+
+DO chain locators:
+   page.getByRole('listitem').filter({ hasText: 'Product 2' })
+     .getByRole('button', { name: 'Add to cart' })
+
+NEVER use fragile CSS/XPath selectors:
+   page.locator('button.buttonIcon.episode-actions-later')
+
+DO use role-based locators:
+   page.getByRole('button', { name: 'submit' })
+
+INTENT -> PATTERN MAPPING
+
+COUNTING:
+  "how many X" / "count X" / "number of X" / "return the count"
+  -> const n = await page.getByRole('X').count();
+    console.log(\`Found \${n} X elements\`);
+    expect(n).toBeGreaterThan(0);
+
+  "there are N X" / "exactly N X"
+  -> await expect(page.getByRole('X')).toHaveCount(N);
+
+  CRITICAL: Never use getByText("how many X") - count intent
+  means call .count() or toHaveCount(), not search for text.
+
+PRESENCE:
+  "X is present/visible/shown/exists"
+  -> await expect(locator).toBeVisible()
+
+  "X is hidden/not present/gone"
+  -> await expect(locator).toBeHidden()
+
+TEXT:
+  "text says X" / "shows X" / "message is X"
+  -> await expect(locator).toHaveText('X')
+
+  "contains X" / "includes X"
+  -> await expect(locator).toContainText('X')
+
+  "page title is X"
+  -> await expect(page).toHaveTitle(/X/i)
+
+  "heading says X"
+  -> await expect(page.getByRole('heading')).toContainText('X')
+
+  "error says X"
+  -> await expect(page.getByRole('alert')).toContainText('X')
+
+STATE:
+  "X is enabled/disabled"
+  -> await expect(locator).toBeEnabled() / toBeDisabled()
+
+  "X is checked/unchecked"
+  -> await expect(locator).toBeChecked() / not.toBeChecked()
+
+  "X has value Y"
+  -> await expect(locator).toHaveValue('Y')
+
+  "X is active / has class Y"
+  -> await expect(locator).toHaveClass(/Y/)
+
+NAVIGATION:
+  "redirects to X" / "goes to X" / "URL contains X"
+  -> await expect(page).toHaveURL(/X/)
+
+  "stays on same page"
+  -> await expect(page).toHaveURL(/currentPath/)
+
+  "opens new tab"
+  -> const [newPage] = await Promise.all([
+      context.waitForEvent('page'),
+      locator.click()
+    ]);
+
+FORMS:
+  "form submits successfully"
+  -> fill fields + click submit + assert URL change or success message
+
+  "validation error shown"
+  -> submit empty + await expect(page.getByRole('alert')).toBeVisible()
+
+  "required field X"
+  -> submit without X + assert error message for X visible
+
+AUTH:
+  "login with valid credentials"
+  -> fill(CT_VAR_USERNAME) + fill(CT_VAR_PASSWORD) + click login
+    + await expect(page).toHaveURL(/dashboard|home|app/)
+
+  "login fails / invalid credentials"
+  -> fill bad values + click login
+    + await expect(page.getByRole('alert')).toBeVisible()
+
+  "logout works"
+  -> click logout + await expect(page).toHaveURL(/login|home/)
+
+THEME / VISUAL:
+  "dark mode / theme toggle"
+  -> await locator.click()
+    + await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark')
+    // OR: await expect(page.locator('body')).toHaveClass(/dark/)
+
+TIMING:
+  "X loads / X appears"
+  -> await expect(locator).toBeVisible({ timeout: 10000 })
+
+  "spinner disappears / loader gone"
+  -> await expect(spinner).toBeHidden({ timeout: 10000 })
+
+  "modal closes"
+  -> await expect(modal).toBeHidden()
+
+ACCESSIBILITY:
+  "has alt text"
+  -> await expect(page.locator('img')).toHaveAttribute('alt', /.+/)
+
+  "keyboard navigable"
+  -> await page.keyboard.press('Tab')
+    + await expect(firstFocusable).toBeFocused()
+
+CRITICAL RULES
+1. NEVER use intent words as locator text.
+   "count buttons" != getByText("count buttons")
+   "verify heading" != getByText("verify heading")
+
+2. ALWAYS use web-first assertions (await expect).
+   NEVER use: expect(await locator.isVisible()).toBe(true)
+
+3. For counting, prefer toHaveCount() over .count() unless
+   you need the actual number for logging.
+
+4. Auto-waiting: Playwright automatically waits for elements
+   to be actionable before click/fill/etc. Do not add
+   manual waitForTimeout() unless testing timing specifically.
+
+5. Use not. prefix for negative assertions:
+   await expect(locator).not.toBeVisible()
+   await expect(locator).not.toBeChecked()
+`.trim();
+var ADVANCED_DOC_MAP2 = {
+  upload: "https://playwright.dev/docs/input",
+  "file upload": "https://playwright.dev/docs/input",
+  intercept: "https://playwright.dev/docs/mock",
+  mock: "https://playwright.dev/docs/mock",
+  "api mock": "https://playwright.dev/docs/mock",
+  accessibility: "https://playwright.dev/docs/accessibility-testing",
+  "screen reader": "https://playwright.dev/docs/accessibility-testing",
+  visual: "https://playwright.dev/docs/screenshots",
+  screenshot: "https://playwright.dev/docs/screenshots",
+  mobile: "https://playwright.dev/docs/emulation",
+  responsive: "https://playwright.dev/docs/emulation",
+  viewport: "https://playwright.dev/docs/emulation",
+  network: "https://playwright.dev/docs/network",
+  "api call": "https://playwright.dev/docs/network",
+  iframe: "https://playwright.dev/docs/frames",
+  frame: "https://playwright.dev/docs/frames",
+  auth: "https://playwright.dev/docs/auth",
+  "sign in": "https://playwright.dev/docs/auth",
+  "stay logged": "https://playwright.dev/docs/auth",
+  cookie: "https://playwright.dev/docs/auth",
+  storage: "https://playwright.dev/docs/auth",
+  download: "https://playwright.dev/docs/downloads",
+  pdf: "https://playwright.dev/docs/downloads",
+  dialog: "https://playwright.dev/docs/dialogs",
+  alert: "https://playwright.dev/docs/dialogs",
+  confirm: "https://playwright.dev/docs/dialogs",
+  "new tab": "https://playwright.dev/docs/pages",
+  "new page": "https://playwright.dev/docs/pages",
+  popup: "https://playwright.dev/docs/pages"
+};
+async function fetchDocContext2(intent) {
+  const intentLower = intent.toLowerCase();
+  const matched = /* @__PURE__ */ new Set();
+  for (const [keyword, url] of Object.entries(ADVANCED_DOC_MAP2)) {
+    if (intentLower.includes(keyword)) {
+      matched.add(url);
+    }
+  }
+  if (matched.size === 0) return "";
+  const fetched = [];
+  for (const url of matched) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
+      const html = await res.text();
+      const text = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s{3,}/g, "\n\n").slice(0, 3e3);
+      fetched.push(`
+// From ${url}:
+${text}`);
+    } catch {
+    }
+  }
+  if (fetched.length === 0) return "";
+  return `
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ADDITIONAL PLAYWRIGHT DOCS (fetched for this intent)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501${fetched.join("\n")}`;
+}
 async function analyseElements(elementMap, options = {}) {
   const { verbose = false, feature } = options;
   const providerConfig = resolveLlmProvider();
   const requestedFeature = normalizeRequestedFeature(feature, elementMap);
   log(verbose, `
 [analyse] Sending capture to ${providerConfig.displayName} (${providerConfig.model})`);
-  const systemPrompt = buildSystemPrompt();
+  const docContext = await fetchDocContext2(requestedFeature);
+  const systemPrompt = buildSystemPrompt() + docContext;
   const userPrompt = buildUserPrompt(elementMap, requestedFeature);
   const rawResponse = providerConfig.transport === "anthropic" ? await callAnthropic2(providerConfig.apiKey, providerConfig.model, systemPrompt, userPrompt) : await callOpenAiCompatible2(
     providerConfig.apiKey,
@@ -778,11 +1400,12 @@ RULES:
 7. If no status or alert region was captured, avoid scenarios that depend on unseen server-side validation messages.
 8. Scope must match intent complexity. Simple 1 to 2 claim requests should produce only 1 to 2 scenarios.
 9. For presence-only intents such as "verify X" or "X is present", only assert visibility. Do not click and do not assert outcomes after clicking.
-10. For fill steps, never use the literal word "value". If matching CT_VAR_* variables are listed in the prompt, use them in human-readable step text and use a realistic non-generic runtime value in the JSON value field. Otherwise use a field-specific fallback such as test-username or test-password.
-11. The "selector" field must be a raw selector expression such as locator("#username") or getByRole('button', { name: "Login" }). Never wrap selectors in page. or page.locator("...") inside JSON.
-12. Tie-breaker for multiple matching elements: prefer highest confidence, then interactive elements, then the first visible-looking candidate.
-13. If a page clearly contains login or auth fields, do not create submit scenarios that only click the button. Include realistic fill steps for captured username/email and password inputs when the intent asks for auth interaction.
-14. "verify title" means the main visible heading on the page, not the browser tab title, unless the intent explicitly says browser title, tab title, or page title.
+${RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE2}
+11. For fill steps, never use the literal word "value". If matching CT_VAR_* variables are listed in the prompt, use them in human-readable step text and use a realistic non-generic runtime value in the JSON value field. Otherwise use a field-specific fallback such as test-username or test-password.
+12. The "selector" field must be a raw selector expression such as locator("#username") or getByRole('button', { name: "Login" }). Never wrap selectors in page. or page.locator("...") inside JSON.
+13. Tie-breaker for multiple matching elements: prefer highest confidence, then interactive elements, then the first visible-looking candidate.
+14. If a page clearly contains login or auth fields, do not create submit scenarios that only click the button. Include realistic fill steps for captured username/email and password inputs when the intent asks for auth interaction.
+15. "verify title" means the main visible heading on the page, not the browser tab title, unless the intent explicitly says browser title, tab title, or page title.
 
 OUTPUT SCHEMA:
 {
@@ -1298,17 +1921,18 @@ function getAvailableCtVarKeys2() {
 }
 function buildIntentProfile(feature) {
   const normalized = feature.toLowerCase();
+  const countIntent = /\b(?:how many|count|number of|return the count|exactly\s+\d+|there (?:is|are)\s+\d+)/.test(normalized);
   const wantsHeading = /\b(?:title|heading)\b/.test(normalized) && !/\b(?:browser title|tab title|page title)\b/.test(normalized);
   const presenceOnly = isPresenceOnlyIntent(normalized);
   const authIntent = /\b(?:login|log in|sign in|auth|credentials?)\b/.test(normalized) && !presenceOnly;
   const formIntent = /\b(?:form|submit|field|input|enter|fill|type)\b/.test(normalized) && !presenceOnly && !authIntent;
   const flowIntent = /\b(?:flow|journey|checkout|purchase|complete|works?)\b/.test(normalized) && !presenceOnly && !authIntent && !formIntent;
-  const mode = presenceOnly ? "presence" : authIntent ? "auth" : formIntent ? "form" : flowIntent ? "flow" : "generic";
+  const mode = countIntent ? "count" : presenceOnly ? "presence" : authIntent ? "auth" : formIntent ? "form" : flowIntent ? "flow" : "generic";
   const claimCount = countIntentClaims(feature);
   return {
     feature,
     mode,
-    maxScenarios: mode === "presence" ? Math.min(Math.max(claimCount, 1), 2) : mode === "auth" || mode === "form" ? Math.min(Math.max(claimCount, 3), 5) : mode === "flow" ? Math.min(Math.max(claimCount, 4), 6) : Math.min(Math.max(claimCount, 1), 3),
+    maxScenarios: mode === "count" ? 1 : mode === "presence" ? Math.min(Math.max(claimCount, 1), 2) : mode === "auth" || mode === "form" ? Math.min(Math.max(claimCount, 3), 5) : mode === "flow" ? Math.min(Math.max(claimCount, 4), 6) : Math.min(Math.max(claimCount, 1), 3),
     wantsHeading
   };
 }
@@ -1323,11 +1947,42 @@ function isPresenceOnlyIntent(normalizedFeature) {
   return presenceWords && !actionWords;
 }
 function applyIntentPolicy(scenarios, elementMap, intentProfile, prefix) {
+  if (intentProfile.mode === "count") {
+    return buildCountScenarios(elementMap, intentProfile.feature, prefix);
+  }
   if (intentProfile.mode !== "presence") {
     return scenarios.slice(0, intentProfile.maxScenarios);
   }
   return buildPresenceOnlyScenarios(elementMap, intentProfile.feature, prefix);
 }
+function buildCountScenarios(elementMap, feature, prefix) {
+  const normalized = feature.toLowerCase();
+  const countedElements = pickCountedElements(elementMap, normalized);
+  const selector = countSelectorForFeature(normalized, countedElements);
+  const count = countedElements.length;
+  return [{
+    id: `${prefix}-${String(1).padStart(3, "0")}`,
+    title: feature,
+    tags: ["@smoke", "@ui"],
+    steps: [
+      {
+        action: "navigate",
+        selector: "page",
+        value: elementMap.url,
+        human: `Navigate to ${elementMap.url}`
+      }
+    ],
+    assertions: [{
+      type: "count",
+      selector,
+      expected: String(count),
+      human: `There are exactly ${count} matching elements`,
+      playwright: `await expect(page.${selector}).toHaveCount(${count});`
+    }],
+    narrator: "We count only the element type requested by the user.",
+    codeLevel: "beginner"
+  }];
+}
 function buildPresenceOnlyScenarios(elementMap, feature, prefix) {
   const claims = extractPresenceClaims(feature, elementMap);
   if (claims.length === 0) return buildFallbackScenarios(elementMap, prefix).slice(0, 1);
@@ -1360,11 +2015,9 @@ function extractPresenceClaims(feature, elementMap) {
   for (const segment of segments) {
     const normalized = segment.toLowerCase();
     if (/\b(?:title|heading)\b/.test(normalized) && !/\b(?:browser title|tab title|page title)\b/.test(normalized)) {
-      const heading = chooseHeadingElement(elementMap);
-      const selector2 = heading?.selector ?? `getByRole('heading')`;
       claims.push({
-        selector: selector2,
-        human: `${heading?.name || "Main page heading"} is visible`
+        selector: `getByRole('heading')`,
+        human: `${chooseHeadingElement(elementMap)?.name || "Main page heading"} is visible`
       });
       continue;
     }
@@ -1432,7 +2085,7 @@ function detectAuthElements(elementMap) {
   return { usernameInput, passwordInput, submitButton, heading };
 }
 function shouldUseAuthFallback(authElements, scenarios, intentProfile) {
-  if (intentProfile.mode === "presence") return false;
+  if (intentProfile.mode !== "auth" && intentProfile.mode !== "form") return false;
   if (!authElements.usernameInput || !authElements.passwordInput || !authElements.submitButton) return false;
   if (scenarios.length === 0) return true;
   const hasCredentialEntry = scenarios.some((scenario) => {
@@ -1456,8 +2109,26 @@ function defaultStepHuman(action, selector, value) {
 function normalizeStepHuman(human, action, selector, value) {
   if (action !== "fill" && action !== "select") return human;
   if (!value) return human;
-  if (/\bwith\s+['"`]/i.test(human) || /\$\{CT_VAR_[A-Z0-9_]+\}/.test(human)) return human;
-  return buildFillHuman(human, selector, value);
+  const explicitTemplate = /\$\{CT_VAR_[A-Z0-9_]+\}/.test(human);
+  const quotedValue = human.match(/\bwith\s+['"`]([^'"`]+)['"`]/i)?.[1];
+  if (explicitTemplate) return human;
+  if (quotedValue && !isGenericFillValue(quotedValue)) return human;
+  const rewrittenBase = human.replace(/\s+with\s+['"`][^'"`]+['"`]\s*$/i, "").trim() || human;
+  return buildFillHuman(rewrittenBase, selector, value);
+}
+function pickCountedElements(elementMap, normalizedFeature) {
+  const category = /\bbutton/.test(normalizedFeature) ? "button" : /\blink/.test(normalizedFeature) ? "link" : /\bheading|title/.test(normalizedFeature) ? "heading" : /\binput|field|textbox|text box/.test(normalizedFeature) ? "input" : void 0;
+  if (category) {
+    return elementMap.elements.filter((element) => element.category === category);
+  }
+  return elementMap.elements.filter((element) => element.category === "button" || element.category === "link" || element.category === "input");
+}
+function countSelectorForFeature(normalizedFeature, elements) {
+  if (/\bbutton/.test(normalizedFeature)) return `getByRole('button')`;
+  if (/\blink/.test(normalizedFeature)) return `getByRole('link')`;
+  if (/\bheading|title/.test(normalizedFeature)) return `getByRole('heading')`;
+  if (/\binput|field|textbox|text box/.test(normalizedFeature)) return `getByRole('textbox')`;
+  return elements[0]?.selector ?? `locator('*')`;
 }
 function normalizePlaywrightAssertion(assertion) {
   const repaired = scopeBareSelectorsInAssertion(unwrapWrappedSelectorAssertion(assertion.playwright));
@@ -2251,7 +2922,7 @@ function saveSpecPreview(analysis, outputDir = "tests/preview") {
       if (step.action === "hover") lines.push(`  await ${selector}.hover();`);
     }
     for (const assertion of scenario.assertions) {
-      lines.push(`  ${ensureStatement2(assertion.playwright)}`);
+      lines.push(`  ${renderPreviewAssertion(assertion.playwright, assertion.human)}`);
     }
     lines.push("});");
     lines.push("");
@@ -2275,6 +2946,15 @@ function ensureStatement2(value) {
   if (!trimmed) return "// TODO: add assertion";
   return trimmed.endsWith(";") ? trimmed : `${trimmed};`;
 }
+function renderPreviewAssertion(playwright, human) {
+  const statement = ensureStatement2(playwright);
+  const headingMatch = statement.match(/^await expect\(page\.getByRole\((['"])heading\1\)\)\.toBeVisible\(\);$/);
+  const visibleSubject = String(human ?? "").match(/^(.+?) is visible$/)?.[1]?.trim();
+  if (headingMatch && visibleSubject && !/main page heading/i.test(visibleSubject)) {
+    return `await expect(page.getByRole("heading", { name: ${JSON.stringify(visibleSubject)} })).toBeVisible();`;
+  }
+  return statement;
+}
 
 // src/commands/tc.ts
 function slugify2(text) {