@cementic/cementic-test 0.2.11 → 0.2.12

package/README.md

@@ -365,6 +365,13 @@ And start automating.
 
 ## Changelog
 
+### v0.2.12
+
+- made both AI generation paths intent-first so markdown and capture-based scenario generation follow the same scope and presence-only rules
+- tightened capture-based scenario generation to preserve presence-only checks as visibility assertions, honor intent-based selector fallback, and avoid generic `'value'` placeholders
+- added regression coverage for the new markdown prompt contract and capture-path intent enforcement
+- breaking change: none
+
 ### v0.2.11
 
 - AI no longer writes `'value'` as a step input and now prefers matching `CT_VAR_*` references or `test-{fieldname}` fallbacks

package/dist/cli.js

@@ -503,37 +503,114 @@ function getAvailableCtVarKeys() {
 }
 function buildSystemMessage() {
   return `
-You are a senior QA engineer and test automation specialist.
+You are a senior software test architect with 10 years of Playwright experience.
+You translate user requirements into precise, minimal, executable test scenarios.
 
-Your job:
-- Receive context about a web feature or page
-- Generate high-quality, realistic UI test cases
-- Format them in strict Markdown that a downstream parser will process
+RULE 1 - INTENT IS THE REQUIREMENT
+Parse the user's feature description into specific testable claims BEFORE examining page context.
+Generate scenarios for the user's intent, not for every element on the page.
 
-You MUST follow this format exactly for each test case:
+RULE 2 - GENERATE TESTS FOR THE INTENT, NOT THE PAGE INVENTORY
+Only generate tests for claims extracted from the intent.
+Never generate tests for page elements that were not requested.
+Page context improves selector quality and wording, but it does not define test scope.
+
+RULE 3 - SELECTOR HIERARCHY
+When choosing selectors, prefer:
+1. Exact page-context match when available
+2. getByRole() with text from the intent
+3. getByLabel() for form inputs
+4. getByText() with text from the intent
+5. getByPlaceholder() for inputs
+6. locator('#id') only when the id appears stable
+
+Tie-breaker when multiple elements match:
+1. Prefer the highest-confidence page-context match
+2. Prefer visible elements over hidden
+3. Prefer interactive elements over static elements
+4. If still ambiguous, use the first match and note it with a short comment in the step text
+
+RULE 4 - TITLE DISAMBIGUATION
+"verify title" means the main visible heading on the page.
+Use a heading assertion first.
+Do NOT treat "title" as the browser tab title unless the intent explicitly says "browser title", "tab title", or "page title".
+
+RULE 5 - PRESENCE-ONLY INTENTS
+For presence-only intents such as "verify X", "check X is present", or "X is visible":
+- Only assert visibility
+- Do NOT click the element
+- Do NOT assert redirects, state changes, or side effects
+
+RULE 6 - NEGATIVE CASES
+Generate negative scenarios only when the intent implies interaction:
+- Form testing: always include an invalid-input scenario
+- Authentication: always include a wrong-credentials scenario
+- Presence checks: no negative case needed
+- Button click: negative case only if the button can be disabled
+
+RULE 7 - SETUP DEPENDENCIES
+If authentication is required to reach the page:
+- Add setup steps using CT_VAR_USERNAME and CT_VAR_PASSWORD
+- Tag the scenario with @requires-auth
+- Mention the dependency in a short step or assertion note when needed
+
+RULE 8 - TEST DATA
+Never use the literal word 'value' as a placeholder.
+When filling a field:
+- If the user context lists a matching CT_VAR_* variable, write it exactly as '\${CT_VAR_FIELDNAME}` + `'
+- Otherwise use a field-specific fallback such as 'test-username', 'test-email@example.com', 'test-password', or 'test-search'
+
+RULE 9 - SCOPE DISCIPLINE
+Match scenario count to intent complexity:
+- 1 to 2 claims: 1 to 2 scenarios maximum
+- 3 to 5 claims: 3 to 5 scenarios maximum
+- Full flow: 4 to 8 scenarios maximum
+Never exceed 8 scenarios.
+
+COMMON TESTING VOCABULARY
+"verify/check X is present/visible" -> toBeVisible()
+"verify title/heading" -> heading is visible
+"button/link is present" -> button or link is visible
+"can click X" -> click then assert visible outcome
+"form submits" -> fill + click + assert success or URL
+"error shows" -> trigger error + assert error visible
+"redirects to X" -> URL contains or equals X
+"text says X" -> text equals or contains X
+"page loads" -> main heading or key element is visible
+
+OUTPUT FORMAT - EXACT MARKDOWN SCHEMA
+Output valid markdown in this exact format. No preamble. No explanation. Just the markdown.
+
+# {PREFIX}-001 - {scenario-slug} - {Human readable title} @tag1 @tag2
+
+## Steps
+1. Navigate to {url}
+2. {action verb} {target description}
+
+## Expected Results
+- {specific observable assertion}
+- {specific observable assertion}
+
+---
+
+# {PREFIX}-002 - {scenario-slug} - {Human readable title} @tag1 @tag2
 
-# <ID> \u2014 <Short title> @<tag1> @<tag2>
 ## Steps
-1. <user action>
-2. <user action>
+1. Navigate to {url}
+2. {action verb} {target description}
 
 ## Expected Results
-- <verifiable outcome>
-- <verifiable outcome>
+- {specific observable assertion}
 
-Rules:
-- ID must be PREFIX-NNN where NNN is zero-padded 3 digits starting from startIndex
-- Use 1\u20133 tags: @smoke @regression @auth @ui @critical @happy-path @negative
-- Steps = concrete user actions ("Click the 'Sign In' button", "Fill in email with 'user@example.com'")
-- When writing fill steps, always use meaningful values
-- Never use the literal word 'value' as a placeholder in any fill step
-- If the user context lists available CT_VAR_* variables for a field, reference them in steps as '\${CT_VAR_FIELDNAME}` + `'
-- If no CT_VAR_* variable is available for a field, use a field-based placeholder like 'test-username', 'test-email', 'test-password', or 'test-phone'
-- If you do not know the real value, use the pattern 'test-{fieldname}'
-- Expected Results = verifiable UI outcomes ("Error message 'Invalid credentials' is visible", "Page redirects to /dashboard")
-- Include both happy-path AND negative/edge-case tests
-- Do NOT explain or add preamble \u2014 output ONLY the test cases
-- No code blocks, no extra headings outside the pattern
+Rules for the markdown schema:
+- id format: PREFIX-NNN using the provided prefix and numbering
+- slug format: kebab-case, max 5 words, derived from the scenario subject
+- title: human readable and aligned to the user's intent
+- tags: include at least one of @smoke @regression @negative @happy-path plus a relevant domain tag such as @auth @ui @navigation @form @checkout
+- steps: numbered, start with Navigate, then actions, written in plain English
+- assertions: bullet points with observable outcomes only
+- never write "test passes" or "works correctly"
+- do NOT wrap the output in code fences
 `.trim();
 }
 function buildUserMessage(ctx) {
@@ -542,9 +619,12 @@ function buildUserMessage(ctx) {
   lines.push(`App / product description:`);
   lines.push(ctx.appDescription || "N/A");
   lines.push("");
-  lines.push(`Feature or page to test:`);
+  lines.push(`Primary test intent:`);
   lines.push(ctx.feature);
   lines.push("");
+  lines.push(`Interpret the feature text above as the source of truth.`);
+  lines.push(`Only generate scenarios for claims that are explicitly implied by that intent.`);
+  lines.push("");
   if (ctx.url) {
     lines.push(`Page URL: ${ctx.url}`);
     lines.push("");
@@ -588,9 +668,9 @@ function buildUserMessage(ctx) {
   }
   lines.push(`Test ID prefix: ${ctx.prefix}`);
   lines.push(`Start numbering from: ${String(ctx.startIndex).padStart(3, "0")}`);
-  lines.push(`Number of test cases: ${ctx.numCases}`);
+  lines.push(`Requested number of test cases: ${ctx.numCases}`);
   lines.push("");
-  lines.push(`Include a mix of: happy-path flows, validation/error cases, and edge cases.`);
+  lines.push(`Use the requested count only when it fits the intent complexity. Prefer fewer scenarios when the request is simple.`);
   lines.push(`Output ONLY the test cases. No explanation, no preamble.`);
   return lines.join("\n");
 }
@@ -663,12 +743,13 @@ async function generateTcMarkdownWithAi(ctx) {
 
 // src/core/analyse.ts
 async function analyseElements(elementMap, options = {}) {
-  const { verbose = false } = 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 userPrompt = buildUserPrompt(elementMap);
+  const userPrompt = buildUserPrompt(elementMap, requestedFeature);
   const rawResponse = providerConfig.transport === "anthropic" ? await callAnthropic2(providerConfig.apiKey, providerConfig.model, systemPrompt, userPrompt) : await callOpenAiCompatible2(
     providerConfig.apiKey,
     providerConfig.model,
@@ -678,7 +759,7 @@ async function analyseElements(elementMap, options = {}) {
     userPrompt
   );
   const parsed = parseAnalysisJson(rawResponse);
-  return sanitizeAnalysis(parsed, elementMap);
+  return sanitizeAnalysis(parsed, elementMap, requestedFeature);
 }
 function buildSystemPrompt() {
   return `
@@ -688,16 +769,20 @@ Your job is to analyse a structured map of interactive elements extracted from a
 then produce a complete set of Playwright test scenarios.
 
 RULES:
-1. Use only selectors provided in the ElementMap.
+1. The user's feature description is the PRIMARY requirement. Generate scenarios that test what the user asked for.
 2. Every assertion must include an exact "playwright" field with a complete await expect(...) statement.
-3. Use clearly fake data like user@example.com.
-4. Include both happy-path and negative scenarios, but stay evidence-backed.
+3. Use captured elements as the first selector source. If the intent names text that was not captured, you may fall back to a safe Playwright selector derived from the intent such as getByRole(), getByText(), getByLabel(), getByPlaceholder(), or locator('#id').
+4. Include happy-path and negative scenarios only when the intent implies interaction, and stay evidence-backed.
 5. Output only valid JSON matching the requested schema.
 6. Do not invent redirect targets, success pages, error text, password clearing, or security scenarios unless the capture explicitly supports them.
 7. If no status or alert region was captured, avoid scenarios that depend on unseen server-side validation messages.
-8. Prefer 3 to 5 realistic scenarios.
-9. The "selector" field must be the raw selector expression from the ElementMap, such as locator("#username") or getByRole('button', { name: "Login" }). Never wrap selectors in page. or page.locator("...") inside JSON.
-10. 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.
+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.
 
 OUTPUT SCHEMA:
 {
@@ -734,9 +819,16 @@ OUTPUT SCHEMA:
   "audioSummary": string
 }`.trim();
 }
-function buildUserPrompt(elementMap) {
+function buildUserPrompt(elementMap, feature) {
   const lines = [];
   const authElements = detectAuthElements(elementMap);
+  const availableCtVarKeys = getAvailableCtVarKeys2();
+  const intentProfile = buildIntentProfile(feature);
+  lines.push("USER INTENT");
+  lines.push(`Feature description: ${feature}`);
+  lines.push(`Intent mode: ${intentProfile.mode}`);
+  lines.push(`Maximum scenarios for this request: ${intentProfile.maxScenarios}`);
+  lines.push("");
   lines.push("PAGE INFORMATION");
   lines.push(`URL: ${elementMap.url}`);
   lines.push(`Title: ${elementMap.title}`);
@@ -762,6 +854,13 @@ function buildUserPrompt(elementMap) {
     }
     lines.push("");
   }
+  if (availableCtVarKeys.length > 0) {
+    lines.push("AVAILABLE CT_VAR_* VARIABLES:");
+    for (const envKey of availableCtVarKeys) {
+      lines.push(`  - ${envKey}`);
+    }
+    lines.push("");
+  }
   const interactiveCount = elementMap.elements.filter((element) => element.category === "input" || element.category === "button" || element.category === "link").length;
   const statusCount = elementMap.elements.filter((element) => element.category === "status").length;
   lines.push("EVIDENCE CONSTRAINTS:");
@@ -769,6 +868,7 @@ function buildUserPrompt(elementMap) {
   lines.push(`  - Status or alert regions captured: ${statusCount}`);
   lines.push("  - If no redirect target is explicitly captured, do not assert a destination path.");
   lines.push("  - If no status region was captured, avoid exact server-side credential error claims.");
+  lines.push("  - Generate scenarios only for the requested feature description.");
   if (authElements.usernameInput && authElements.passwordInput && authElements.submitButton) {
     lines.push("  - This page contains a captured auth form. Include fill steps for the username/email and password fields in credential-submission scenarios.");
     lines.push("  - For auth pages without captured post-submit evidence, prefer evidence-backed form-state assertions over invented success redirects.");
@@ -837,15 +937,21 @@ ${raw.slice(0, 500)}`
     );
   }
 }
-function sanitizeAnalysis(analysis, elementMap) {
+function sanitizeAnalysis(analysis, elementMap, requestedFeature) {
   const selectors = /* @__PURE__ */ new Set();
   for (const element of elementMap.elements) {
     selectors.add(element.selector);
     for (const alt of element.selectorAlt) selectors.add(alt);
   }
   const rawScenarios = Array.isArray(analysis.scenarios) ? analysis.scenarios : [];
+  const intentProfile = buildIntentProfile(requestedFeature);
   const currentUrl = new URL(elementMap.url);
   const authElements = detectAuthElements(elementMap);
+  const resolvedFeature = requestedFeature || analysis.feature || inferFeatureName(elementMap);
+  const resolvedPrefix = (analysis.suggestedPrefix || inferPrefix({
+    featureText: resolvedFeature,
+    url: elementMap.url
+  })).toUpperCase();
   const knownPaths = /* @__PURE__ */ new Set([
     currentUrl.pathname,
     ...elementMap.elements.filter((element) => element.category === "link").map((element) => {
@@ -868,21 +974,28 @@ function sanitizeAnalysis(analysis, elementMap) {
       if (!pathMatch) return true;
       return knownPaths.has(pathMatch[0]);
     })
-  })).filter((scenario) => scenario.assertions.length > 0).slice(0, 5);
-  const useAuthFallback = shouldUseAuthFallback(authElements, sanitizedScenarios);
-  const finalScenarios = useAuthFallback ? buildAuthFallbackScenarios(elementMap, analysis.suggestedPrefix || inferPrefix2(elementMap), authElements) : sanitizedScenarios.length > 0 ? sanitizedScenarios : buildFallbackScenarios(elementMap, analysis.suggestedPrefix || "FLOW");
+  })).filter((scenario) => scenario.assertions.length > 0);
+  const intentAlignedScenarios = applyIntentPolicy(
+    sanitizedScenarios,
+    elementMap,
+    intentProfile,
+    resolvedPrefix
+  ).slice(0, intentProfile.maxScenarios);
+  const useAuthFallback = shouldUseAuthFallback(authElements, intentAlignedScenarios, intentProfile);
+  const fallbackScenarios = intentProfile.mode === "presence" ? buildPresenceOnlyScenarios(elementMap, requestedFeature, resolvedPrefix) : useAuthFallback ? buildAuthFallbackScenarios(elementMap, resolvedPrefix, authElements) : buildFallbackScenarios(elementMap, resolvedPrefix);
+  const finalScenarios = useAuthFallback ? fallbackScenarios.slice(0, intentProfile.maxScenarios) : intentAlignedScenarios.length > 0 ? intentAlignedScenarios : fallbackScenarios.slice(0, intentProfile.maxScenarios);
   return {
     ...analysis,
     url: analysis.url || elementMap.url,
-    feature: analysis.feature || inferFeatureName(elementMap),
-    suggestedPrefix: (analysis.suggestedPrefix || inferPrefix2(elementMap)).toUpperCase(),
+    feature: resolvedFeature,
+    suggestedPrefix: resolvedPrefix,
     scenarios: finalScenarios,
     analysisNotes: [
       analysis.analysisNotes,
       useAuthFallback ? "Replaced low-evidence auth scenarios with deterministic evidence-backed auth coverage." : "",
       `Sanitized to ${finalScenarios.length} evidence-backed scenario(s) from ${rawScenarios.length} raw scenario(s).`
     ].filter(Boolean).join(" "),
-    audioSummary: analysis.audioSummary || buildAudioSummary(analysis.feature || inferFeatureName(elementMap), finalScenarios)
+    audioSummary: analysis.audioSummary || buildAudioSummary(resolvedFeature, finalScenarios)
   };
 }
 function normalizeScenario(candidate, selectors, url) {
@@ -902,20 +1015,28 @@ function normalizeScenario(candidate, selectors, url) {
 function normalizeStep(candidate, selectors) {
   if (!candidate) return null;
   const selector = String(candidate.selector ?? "").trim();
-  if (selector !== "page" && !selectors.has(selector)) return null;
+  if (!isAllowedSelector(selector, selectors)) return null;
   const action = String(candidate.action ?? "").trim();
   if (!["navigate", "fill", "click", "select", "check", "keyboard", "hover"].includes(action)) return null;
+  const rawValue = String(candidate.value ?? "");
+  const value = action === "fill" || action === "select" ? resolveFieldRuntimeValue(selector, rawValue) : rawValue;
+  const human = normalizeStepHuman(
+    String(candidate.human ?? "").trim() || defaultStepHuman(action, selector, value),
+    action,
+    selector,
+    value
+  );
   return {
     action,
     selector,
-    value: String(candidate.value ?? ""),
-    human: String(candidate.human ?? "").trim() || defaultStepHuman(action, selector, String(candidate.value ?? ""))
+    value,
+    human
   };
 }
 function normalizeAssertion(candidate, selectors) {
   if (!candidate) return null;
   const selector = String(candidate.selector ?? "").trim();
-  if (selector !== "page" && !selectors.has(selector)) return null;
+  if (!isAllowedSelector(selector, selectors)) return null;
   const assertion = {
     type: String(candidate.type ?? "visible").trim() || "visible",
     selector,
@@ -961,6 +1082,7 @@ function buildFallbackScenarios(elementMap, prefix) {
     });
   }
   if (emailInput && passwordInput && submitButton) {
+    const emailValue = resolveFieldRuntimeValue(emailInput.selector, "");
     scenarios.push({
       id: nextId(scenarios.length + 1),
       title: "Submitting without a password keeps the user on the form",
@@ -975,8 +1097,8 @@ function buildFallbackScenarios(elementMap, prefix) {
         {
           action: "fill",
           selector: emailInput.selector,
-          value: "user@example.com",
-          human: "Fill in the email field"
+          value: emailValue,
+          human: buildFillHuman("Fill in the email field", emailInput.selector, emailValue)
         },
         {
           action: "click",
@@ -1077,13 +1199,13 @@ function buildAuthFallbackScenarios(elementMap, prefix, authElements) {
         action: "fill",
         selector: usernameInput.selector,
         value: usernameValue,
-        human: "Fill in the username field"
+        human: buildFillHuman("Fill in the username field", usernameInput.selector, usernameValue)
       },
       {
         action: "fill",
         selector: passwordInput.selector,
         value: passwordValue,
-        human: "Fill in the password field"
+        human: buildFillHuman("Fill in the password field", passwordInput.selector, passwordValue)
       }
     ],
     assertions: [
@@ -1127,7 +1249,7 @@ function buildAuthFallbackScenarios(elementMap, prefix, authElements) {
         action: "fill",
         selector: usernameInput.selector,
         value: usernameValue,
-        human: "Fill in the username field"
+        human: buildFillHuman("Fill in the username field", usernameInput.selector, usernameValue)
       },
       {
         action: "click",
@@ -1164,16 +1286,136 @@ function buildAuthFallbackScenarios(elementMap, prefix, authElements) {
   });
   return scenarios;
 }
+function normalizeRequestedFeature(feature, elementMap) {
+  return String(feature ?? "").trim() || inferFeatureName(elementMap);
+}
 function inferFeatureName(elementMap) {
   const heading = elementMap.elements.find((element) => element.category === "heading" && element.name);
   return heading?.name || elementMap.title || "Captured page";
 }
-function inferPrefix2(elementMap) {
-  const source = `${elementMap.title} ${elementMap.url}`.toLowerCase();
-  if (/\blogin|sign in|auth/.test(source)) return "AUTH";
-  if (/\bcheckout|cart|payment/.test(source)) return "CHK";
-  if (/\bdashboard/.test(source)) return "DASH";
-  return "FLOW";
+function getAvailableCtVarKeys2() {
+  return Object.keys(process.env).filter((key) => /^CT_VAR_[A-Z0-9_]+$/.test(key)).sort();
+}
+function buildIntentProfile(feature) {
+  const normalized = feature.toLowerCase();
+  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 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),
+    wantsHeading
+  };
+}
+function countIntentClaims(feature) {
+  const quoted = Array.from(feature.matchAll(/["“”']([^"“”']+)["“”']/g)).length;
+  const segments = feature.split(/\s+(?:and|&)\s+|,\s*/i).map((segment) => segment.trim()).filter(Boolean);
+  return Math.max(quoted, segments.length || 1);
+}
+function isPresenceOnlyIntent(normalizedFeature) {
+  const presenceWords = /\b(?:verify|check|confirm|ensure|present|visible|shown|showing|available|exists?|title|heading)\b/.test(normalizedFeature);
+  const actionWords = /\b(?:click|submit|fill|type|enter|login|log in|sign in|checkout|purchase|complete|flow|journey|error|invalid|disabled|enabled)\b/.test(normalizedFeature);
+  return presenceWords && !actionWords;
+}
+function applyIntentPolicy(scenarios, elementMap, intentProfile, prefix) {
+  if (intentProfile.mode !== "presence") {
+    return scenarios.slice(0, intentProfile.maxScenarios);
+  }
+  return buildPresenceOnlyScenarios(elementMap, intentProfile.feature, prefix);
+}
+function buildPresenceOnlyScenarios(elementMap, feature, prefix) {
+  const claims = extractPresenceClaims(feature, elementMap);
+  if (claims.length === 0) return buildFallbackScenarios(elementMap, prefix).slice(0, 1);
+  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: claims.map((claim) => ({
+      type: "visible",
+      selector: claim.selector,
+      expected: "visible",
+      human: claim.human,
+      playwright: visibleAssertion(claim.selector)
+    })),
+    narrator: "We verify only the elements explicitly requested by the user.",
+    codeLevel: "beginner"
+  }];
+}
+function extractPresenceClaims(feature, elementMap) {
+  const segments = feature.split(/\s+(?:and|&)\s+|,\s*/i).map((segment) => segment.trim()).filter(Boolean);
+  const claims = [];
+  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`
+      });
+      continue;
+    }
+    const text = extractIntentLabel(segment);
+    if (!text) continue;
+    const match = findBestMatchingElement(elementMap, text, normalized);
+    const selector = match?.selector ?? buildFallbackSelector(text, normalized);
+    claims.push({
+      selector,
+      human: `${text} is visible`
+    });
+  }
+  return claims;
+}
+function chooseHeadingElement(elementMap) {
+  return rankElements(
+    elementMap.elements.filter((element) => element.category === "heading")
+  )[0];
+}
+function extractIntentLabel(segment) {
+  const unquoted = Array.from(segment.matchAll(/["“”']([^"“”']+)["“”']/g)).map((match) => match[1].trim());
+  if (unquoted.length > 0) return unquoted[0];
+  return segment.replace(/\b(?:verify|check|confirm|ensure)\b/gi, " ").replace(/\b(?:the|a|an)\b/gi, " ").replace(/\b(?:is|are|be|should be)\b/gi, " ").replace(/\b(?:present|visible|shown|showing|available|exists?)\b/gi, " ").replace(/\b(?:button|link|cta|label|text)\b/gi, " ").replace(/[.?!,:;]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function findBestMatchingElement(elementMap, text, segment) {
+  const preferredCategory = /\bbutton\b/.test(segment) ? "button" : /\blink\b/.test(segment) ? "link" : /\bheading\b/.test(segment) ? "heading" : void 0;
+  const query = text.toLowerCase();
+  const candidates = elementMap.elements.filter((element) => {
+    if (preferredCategory && element.category !== preferredCategory) return false;
+    const haystack = `${element.name ?? ""} ${element.purpose}`.toLowerCase();
+    return haystack.includes(query);
+  });
+  return rankElements(candidates)[0];
+}
+function rankElements(elements) {
+  const confidenceWeight = (confidence) => confidence === "high" ? 3 : confidence === "medium" ? 2 : 1;
+  const interactiveWeight = (category) => category === "button" || category === "link" || category === "input" ? 2 : 1;
+  return [...elements].sort((left, right) => {
+    const confidenceDelta = confidenceWeight(right.confidence) - confidenceWeight(left.confidence);
+    if (confidenceDelta !== 0) return confidenceDelta;
+    const interactiveDelta = interactiveWeight(right.category) - interactiveWeight(left.category);
+    if (interactiveDelta !== 0) return interactiveDelta;
+    return 0;
+  });
+}
+function buildFallbackSelector(text, segment) {
+  const safeRegex = text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (/\bbutton\b/.test(segment)) return `getByRole('button', { name: /${safeRegex}/i })`;
+  if (/\blink\b/.test(segment)) return `getByRole('link', { name: /${safeRegex}/i })`;
+  if (/\b(?:title|heading)\b/.test(segment)) return `getByRole('heading', { name: /${safeRegex}/i })`;
+  return `getByText(${JSON.stringify(text)})`;
 }
 function buildAudioSummary(feature, scenarios) {
   return `We finished validating ${feature || "the captured page"} with ${scenarios.length} evidence-backed scenario${scenarios.length === 1 ? "" : "s"}.`;
@@ -1189,7 +1431,8 @@ function detectAuthElements(elementMap) {
   const heading = elementMap.elements.find((element) => element.category === "heading" && /login|sign in|auth/.test((element.name ?? "").toLowerCase())) ?? elementMap.elements.find((element) => element.category === "heading");
   return { usernameInput, passwordInput, submitButton, heading };
 }
-function shouldUseAuthFallback(authElements, scenarios) {
+function shouldUseAuthFallback(authElements, scenarios, intentProfile) {
+  if (intentProfile.mode === "presence") return false;
   if (!authElements.usernameInput || !authElements.passwordInput || !authElements.submitButton) return false;
   if (scenarios.length === 0) return true;
   const hasCredentialEntry = scenarios.some((scenario) => {
@@ -1203,13 +1446,19 @@ function shouldUseAuthFallback(authElements, scenarios) {
 }
 function defaultStepHuman(action, selector, value) {
   if (action === "navigate") return `Navigate to ${value || "the page"}`;
-  if (action === "fill") return `Fill the field ${selector}`;
+  if (action === "fill") return buildFillHuman(`Fill the field ${selector}`, selector, value);
   if (action === "click") return `Click ${selector}`;
   if (action === "select") return `Select ${value} in ${selector}`;
   if (action === "check") return `Check ${selector}`;
   if (action === "keyboard") return `Press ${value}`;
   return `Interact with ${selector}`;
 }
+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);
+}
 function normalizePlaywrightAssertion(assertion) {
   const repaired = scopeBareSelectorsInAssertion(unwrapWrappedSelectorAssertion(assertion.playwright));
   if (repaired) return ensureStatement(repaired);
@@ -1264,10 +1513,54 @@ function valueAssertion(selector, value) {
   return `await expect(${selectorTarget(selector)}).toHaveValue(${JSON.stringify(value)});`;
 }
 function inferAuthValue(element, kind) {
-  if (kind === "password") return "Secret123!";
-  const haystack = `${element.name ?? ""} ${String(element.attributes.label ?? "")} ${String(element.attributes.name ?? "")}`.toLowerCase();
-  if (/email/.test(haystack)) return "user@example.com";
-  return "testuser";
+  if (kind === "password") return resolveFieldRuntimeValue(element.selector, "test-password");
+  return resolveFieldRuntimeValue(element.selector, "");
+}
+function buildFillHuman(base, selector, runtimeValue) {
+  const displayValue = resolveFieldDisplayValue(selector, runtimeValue);
+  return `${base} with '${displayValue}'`;
+}
+function resolveFieldRuntimeValue(selector, currentValue) {
+  if (currentValue && !isGenericFillValue(currentValue) && !extractCtVarTemplate(currentValue)) {
+    return currentValue;
+  }
+  const envKey = matchCtVarKey(selector);
+  if (envKey && process.env[envKey]) {
+    return String(process.env[envKey]);
+  }
+  return fallbackFieldValue(selector);
+}
+function resolveFieldDisplayValue(selector, runtimeValue) {
+  const envKey = matchCtVarKey(selector);
+  if (envKey) return `\${${envKey}}`;
+  return runtimeValue;
+}
+function matchCtVarKey(selectorOrText) {
+  const haystack = selectorOrText.toLowerCase();
+  const preferred = /\bemail\b/.test(haystack) ? "CT_VAR_EMAIL" : /\bpassword\b/.test(haystack) ? "CT_VAR_PASSWORD" : /\bsearch\b/.test(haystack) ? "CT_VAR_SEARCH" : /\bphone|tel\b/.test(haystack) ? "CT_VAR_PHONE" : /\bname\b/.test(haystack) ? "CT_VAR_NAME" : /\buser(?:name)?|login\b/.test(haystack) ? "CT_VAR_USERNAME" : void 0;
+  if (preferred && process.env[preferred] !== void 0) return preferred;
+  return getAvailableCtVarKeys2().find((key) => new RegExp(key.replace(/^CT_VAR_/, "").toLowerCase()).test(haystack));
+}
+function fallbackFieldValue(selectorOrText) {
+  const haystack = selectorOrText.toLowerCase();
+  if (/\bemail\b/.test(haystack)) return "test-email@example.com";
+  if (/\bpassword\b/.test(haystack)) return "test-password";
+  if (/\bsearch\b/.test(haystack)) return "test-search";
+  if (/\bphone|tel\b/.test(haystack)) return "test-phone";
+  if (/\bname\b/.test(haystack) && !/\buser(?:name)?\b/.test(haystack)) return "test-name";
+  if (/\buser(?:name)?|login\b/.test(haystack)) return "test-username";
+  return "test-input";
+}
+function isGenericFillValue(value) {
+  return /^(?:value|text|input|option|selection|selected value|default)$/i.test(value.trim());
+}
+function extractCtVarTemplate(value) {
+  return value.match(/^\$\{(CT_VAR_[A-Z0-9_]+)\}$/)?.[1];
+}
+function isAllowedSelector(selector, selectors) {
+  if (selector === "page") return true;
+  if (selectors.has(selector)) return true;
+  return /^(?:getByRole|getByText|getByLabel|getByPlaceholder|getByTestId)\(/.test(selector) || /^locator\((['"])(#.+?)\1\)$/.test(selector);
 }
 function ensureStatement(value) {
   const trimmed = String(value ?? "").trim();
@@ -2074,7 +2367,7 @@ async function runTcInteractive(params) {
           console.log("Capture-only mode requested. No test cases were generated.");
           return;
         }
-        const analysis = await analyseElements(elementMap, { verbose: true });
+        const analysis = await analyseElements(elementMap, { verbose: true, feature });
         printCaptureReport(elementMap, analysis);
         const previewPath = saveSpecPreview(analysis);
         if (previewPath) {