@cementic/cementic-test 0.2.13 → 0.2.14

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   genCmd
-} from "./chunk-RG26I5FB.js";
+} from "./chunk-3S26OWNR.js";
 
 // src/cli.ts
 import { Command as Command9 } from "commander";
@@ -18,6 +18,8 @@ import { platform, release } from "os";
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname(__filename);
 var LEGACY_MACOS_DARWIN_MAJOR = 23;
+var LEGACY_PLAYWRIGHT_VERSION = "^1.48.2";
+var LEGACY_ALLURE_VERSION = "^2.15.1";
 function resolveTemplatePath(templateDir) {
   const candidates = [
     resolve(__dirname, `templates/${templateDir}`),
@@ -27,13 +29,73 @@ function resolveTemplatePath(templateDir) {
   ];
   return candidates.find((candidate) => existsSync(candidate));
 }
+function getHostPlatform(env = process.env) {
+  return (env.CT_OS_PLATFORM_OVERRIDE ?? platform()).trim().toLowerCase();
+}
+function getHostRelease(env = process.env) {
+  return (env.CT_OS_RELEASE_OVERRIDE ?? release()).trim();
+}
+function isLegacyMacOs(env = process.env) {
+  if (getHostPlatform(env) !== "darwin") return false;
+  const majorVersion = parseInt(getHostRelease(env).split(".")[0], 10);
+  return Number.isFinite(majorVersion) && majorVersion < LEGACY_MACOS_DARWIN_MAJOR;
+}
+function resolveBrowserInstallProfile(raw) {
+  const profile = String(raw ?? "auto").trim().toLowerCase();
+  if (profile === "auto" || profile === "all" || profile === "chromium") return profile;
+  console.error(`\u274C Unsupported browser install profile "${raw}". Use "auto", "all", or "chromium".`);
+  process.exit(1);
+}
+function resolveBootstrapPlan(browserProfile, env = process.env) {
+  const legacyMacOs = isLegacyMacOs(env);
+  const resolvedProfile = browserProfile === "auto" ? legacyMacOs ? "chromium" : "all" : browserProfile;
+  return {
+    browserInstallArgs: resolvedProfile === "chromium" ? ["playwright", "install", "chromium"] : ["playwright", "install"],
+    browserProfile: resolvedProfile,
+    isLegacyMacOs: legacyMacOs,
+    packageVersionOverrides: legacyMacOs ? {
+      "@playwright/test": LEGACY_PLAYWRIGHT_VERSION,
+      "allure-playwright": LEGACY_ALLURE_VERSION
+    } : {},
+    reason: legacyMacOs ? "Detected macOS 13 or older. Using a legacy-compatible Playwright toolchain and Chromium-only browser install." : void 0
+  };
+}
+function applyPackageVersionOverrides(projectPath, versionOverrides) {
+  if (Object.keys(versionOverrides).length === 0) return;
+  const pkgJsonPath = join(projectPath, "package.json");
+  if (!existsSync(pkgJsonPath)) return;
+  try {
+    const pkgContent = readFileSync(pkgJsonPath, "utf-8");
+    const pkg = JSON.parse(pkgContent);
+    const devDependencies = pkg.devDependencies ?? {};
+    let changed = false;
+    for (const [name, version2] of Object.entries(versionOverrides)) {
+      if (typeof devDependencies[name] !== "string") continue;
+      devDependencies[name] = version2;
+      changed = true;
+    }
+    if (!changed) return;
+    pkg.devDependencies = devDependencies;
+    writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2));
+    console.log("\u2705 Applied compatibility dependency pins for this machine.");
+  } catch (err) {
+    console.warn("\u26A0\uFE0F Failed to adjust package.json for OS compatibility:", err);
+  }
+}
 function newCmd() {
   const cmd = new Command("new").arguments("<projectName>").description("Scaffold a new CementicTest + Playwright project from scratch").addHelpText("after", `
 Examples:
   $ ct new my-awesome-test-suite
   $ ct new e2e-ts --lang ts
   $ ct new e2e-tests --no-browsers
-`).option("--mode <mode>", "greenfield|enhance", "greenfield").option("--lang <lang>", "Scaffold language (js|ts)", "js").option("--no-browsers", 'do not run "npx playwright install" during setup').action((projectName, opts) => {
+`).option("--mode <mode>", "greenfield|enhance", "greenfield").option("--lang <lang>", "Scaffold language (js|ts)", "js").option("--browser-set <profile>", "Browser install profile (auto|all|chromium)", "auto").option("--no-browsers", 'do not run "npx playwright install" during setup').action((projectName, opts) => {
+    const mode = String(opts.mode ?? "greenfield").trim().toLowerCase();
+    if (mode !== "greenfield") {
+      console.error(`\u274C Unsupported scaffold mode "${opts.mode}". Only "greenfield" is currently implemented.`);
+      process.exit(1);
+    }
+    const browserInstallProfile = resolveBrowserInstallProfile(opts.browserSet);
+    const bootstrapPlan = resolveBootstrapPlan(browserInstallProfile);
     const root = process.cwd();
     const projectPath = join(root, projectName);
     console.log(`\u{1F680} Initializing new CementicTest project in ${projectName}...`);
@@ -62,25 +124,10 @@ Examples:
       }
     }
     copyRecursive(templatePath, projectPath);
-    const legacyMacOs = isLegacyMacOs();
-    if (legacyMacOs) {
-      console.log("\u{1F34E} Detected macOS 13 or older. Adjusting versions for compatibility...");
-      const pkgJsonPath = join(projectPath, "package.json");
-      if (existsSync(pkgJsonPath)) {
-        try {
-          const pkgContent = readFileSync(pkgJsonPath, "utf-8");
-          const pkg = JSON.parse(pkgContent);
-          if (pkg.devDependencies) {
-            pkg.devDependencies["@playwright/test"] = "^1.48.2";
-            pkg.devDependencies["allure-playwright"] = "^2.15.1";
-            writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2));
-            console.log("\u2705 Pinned Playwright packages for legacy macOS compatibility.");
-          }
-        } catch (err) {
-          console.warn("\u26A0\uFE0F Failed to adjust package.json for OS compatibility:", err);
-        }
-      }
+    if (bootstrapPlan.reason) {
+      console.log(`\u{1F34E} ${bootstrapPlan.reason}`);
     }
+    applyPackageVersionOverrides(projectPath, bootstrapPlan.packageVersionOverrides);
     try {
       execSync("git init", { cwd: projectPath, stdio: "ignore" });
       const gitignorePath = join(projectPath, ".gitignore");
@@ -101,17 +148,19 @@ Examples:
     if (opts.browsers !== false && dependenciesInstalled) {
       console.log("\u{1F310} Installing Playwright browsers...");
       try {
-        if (legacyMacOs) {
+        const installCommand = `npx ${bootstrapPlan.browserInstallArgs.join(" ")}`;
+        if (bootstrapPlan.browserProfile === "chromium" && bootstrapPlan.isLegacyMacOs) {
           console.log("\u26A0\uFE0F WebKit is not supported on this macOS version. Installing Chromium only...");
-          execSync("npx playwright install chromium", { cwd: projectPath, stdio: "inherit" });
-          console.log("\u2705 Chromium installed successfully.");
-        } else {
-          execSync("npx playwright install", { cwd: projectPath, stdio: "inherit" });
-          console.log("\u2705 Playwright browsers installed successfully.");
+        } else if (bootstrapPlan.browserProfile === "chromium") {
+          console.log("\u2139\uFE0F Installing Chromium only because --browser-set chromium was requested.");
         }
+        execSync(installCommand, { cwd: projectPath, stdio: "inherit" });
+        console.log(
+          bootstrapPlan.browserProfile === "chromium" ? "\u2705 Chromium installed successfully." : "\u2705 Playwright browsers installed successfully."
+        );
       } catch (e) {
         console.warn("\u26A0\uFE0F Browser installation did not complete. You can finish setup with:");
-        console.warn("  npx playwright install chromium");
+        console.warn(`  npx ${bootstrapPlan.browserInstallArgs.join(" ")}`);
       }
     }
     console.log(`
@@ -126,11 +175,6 @@ Happy testing! \u{1F9EA}`);
   });
   return cmd;
 }
-function isLegacyMacOs() {
-  if (platform() !== "darwin") return false;
-  const majorVersion = parseInt(release().split(".")[0], 10);
-  return Number.isFinite(majorVersion) && majorVersion < LEGACY_MACOS_DARWIN_MAJOR;
-}
 
 // src/commands/normalize.ts
 import { Command as Command2 } from "commander";
@@ -321,7 +365,7 @@ Examples:
     }
     console.log(`\u2705 Normalized ${index.summary.parsed} case(s). Output \u2192 .cementic/normalized/`);
     if (opts.andGen) {
-      const { gen } = await import("./gen-6Y65IYXO.js");
+      const { gen } = await import("./gen-AGWFMHTO.js");
       await gen({ lang: opts.lang || "ts", out: "tests/generated" });
     }
   });
@@ -1054,6 +1098,9 @@ async function generateTcMarkdownWithAi(ctx) {
 }
 
 // src/core/analyse.ts
+function escapeForRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\\/]/g, "\\$&");
+}
 var RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE2 = `
 RULE 10 - PLAYWRIGHT KNOWLEDGE BASE
 (sourced from playwright.dev official documentation)
@@ -1365,23 +1412,37 @@ ADDITIONAL PLAYWRIGHT DOCS (fetched for this intent)
 }
 async function analyseElements(elementMap, options = {}) {
   const { verbose = false, feature } = options;
-  const providerConfig = resolveLlmProvider();
   const requestedFeature = normalizeRequestedFeature(feature, elementMap);
+  let providerConfig;
+  try {
+    providerConfig = resolveLlmProvider();
+  } catch (error) {
+    log(verbose, `
+[analyse] ${shortErrorMessage(error)}`);
+    log(verbose, "[analyse] Falling back to deterministic capture analysis.");
+    return buildDeterministicAnalysis(elementMap, requestedFeature);
+  }
   log(verbose, `
 [analyse] Sending capture to ${providerConfig.displayName} (${providerConfig.model})`);
-  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,
-    providerConfig.model,
-    providerConfig.baseUrl ?? "https://api.openai.com/v1",
-    providerConfig.displayName,
-    systemPrompt,
-    userPrompt
-  );
-  const parsed = parseAnalysisJson(rawResponse);
-  return sanitizeAnalysis(parsed, elementMap, requestedFeature);
+  try {
+    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,
+      providerConfig.model,
+      providerConfig.baseUrl ?? "https://api.openai.com/v1",
+      providerConfig.displayName,
+      systemPrompt,
+      userPrompt
+    );
+    const parsed = parseAnalysisJson(rawResponse);
+    return sanitizeAnalysis(parsed, elementMap, requestedFeature);
+  } catch (error) {
+    log(verbose, `[analyse] Remote analysis failed: ${shortErrorMessage(error)}`);
+    log(verbose, "[analyse] Falling back to deterministic capture analysis.");
+    return buildDeterministicAnalysis(elementMap, requestedFeature);
+  }
 }
 function buildSystemPrompt() {
   return `
@@ -1605,7 +1666,7 @@ function sanitizeAnalysis(analysis, elementMap, requestedFeature) {
     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 fallbackScenarios = intentProfile.mode === "presence" ? buildPresenceOnlyScenarios(elementMap, requestedFeature, resolvedPrefix) : useAuthFallback ? buildAuthFallbackScenarios(elementMap, resolvedPrefix, authElements, requestedFeature) : buildFallbackScenarios(elementMap, resolvedPrefix, requestedFeature);
   const finalScenarios = useAuthFallback ? fallbackScenarios.slice(0, intentProfile.maxScenarios) : intentAlignedScenarios.length > 0 ? intentAlignedScenarios : fallbackScenarios.slice(0, intentProfile.maxScenarios);
   return {
     ...analysis,
@@ -1671,13 +1732,72 @@ function normalizeAssertion(candidate, selectors) {
   return assertion;
 }
 function buildFallbackScenarios(elementMap, prefix) {
+  return buildFallbackScenariosForFeature(elementMap, prefix, "");
+}
+function buildFallbackScenariosForFeature(elementMap, prefix, feature) {
+  const normalizedFeature = feature.toLowerCase();
   const heading = elementMap.elements.find((element) => element.category === "heading");
   const emailInput = elementMap.elements.find((element) => element.category === "input" && (element.attributes.type === "email" || /email/.test(`${element.name ?? ""} ${String(element.attributes.label ?? "")}`.toLowerCase())));
   const passwordInput = elementMap.elements.find((element) => element.category === "input" && element.attributes.type === "password");
   const submitButton = elementMap.elements.find((element) => element.category === "button" && /login|sign in|submit|continue/i.test(element.name ?? "")) ?? elementMap.elements.find((element) => element.category === "button");
+  const alert = findAlertElement(elementMap);
   const scenarios = [];
   const tag = (value) => normalizeTag(value);
   const nextId = (index) => `${prefix}-${String(900 + index).padStart(3, "0")}`;
+  const wantsHiddenAlertOnLoad = /\b(error|alert|message)\b/.test(normalizedFeature) && /\b(not shown|not visible|hidden|not present|gone|absent)\b/.test(normalizedFeature) && /\b(first load|first loads|first loads?|page first loads|initial load|on load)\b/.test(normalizedFeature);
+  const wantsVisibleAlert = /\b(error|alert|message|invalid|incorrect|required|validation)\b/.test(normalizedFeature) && !wantsHiddenAlertOnLoad;
+  if (wantsHiddenAlertOnLoad && alert) {
+    return [{
+      id: `${prefix}-001`,
+      title: "Error message is hidden on initial load",
+      tags: [tag("negative"), tag("ui")],
+      steps: [
+        {
+          action: "navigate",
+          selector: "page",
+          value: elementMap.url,
+          human: "Navigate to the captured page"
+        }
+      ],
+      assertions: [
+        {
+          type: "hidden",
+          selector: alert.selector,
+          expected: "hidden",
+          human: `${alert.name || "Error message"} is not shown when the page first loads`,
+          playwright: `await expect(page.${alert.selector}).toBeHidden();`
+        }
+      ],
+      narrator: "We verify that the page does not expose an error surface before any user action.",
+      codeLevel: "beginner"
+    }];
+  }
+  if (wantsVisibleAlert && alert) {
+    return [{
+      id: `${prefix}-001`,
+      title: "Page exposes an alert message when requested",
+      tags: [tag("negative"), tag("ui")],
+      steps: [
+        {
+          action: "navigate",
+          selector: "page",
+          value: elementMap.url,
+          human: "Navigate to the captured page"
+        }
+      ],
+      assertions: [
+        {
+          type: "text",
+          selector: alert.selector,
+          expected: alert.name || "error",
+          human: "An alert message is shown",
+          playwright: `await expect(page.${alert.selector}).toContainText(/invalid|error|required/i);`
+        }
+      ],
+      narrator: "We validate the alert channel directly when the intent asks about an error message.",
+      codeLevel: "beginner"
+    }];
+  }
   if (heading) {
     scenarios.push({
       id: nextId(scenarios.length + 1),
@@ -1752,16 +1872,115 @@ function buildFallbackScenarios(elementMap, prefix) {
   }
   return scenarios.slice(0, 5);
 }
-function buildAuthFallbackScenarios(elementMap, prefix, authElements) {
+function buildAuthFallbackScenarios(elementMap, prefix, authElements, feature) {
   const { usernameInput, passwordInput, submitButton, heading } = authElements;
   if (!usernameInput || !passwordInput || !submitButton) {
-    return buildFallbackScenarios(elementMap, prefix);
+    return buildFallbackScenariosForFeature(elementMap, prefix, feature);
   }
+  const normalizedFeature = feature.toLowerCase();
   const scenarios = [];
   const tag = (value) => normalizeTag(value);
   const nextId = (index) => `${prefix}-${String(index).padStart(3, "0")}`;
   const usernameValue = inferAuthValue(usernameInput, "username");
   const passwordValue = inferAuthValue(passwordInput, "password");
+  const alert = findAlertElement(elementMap);
+  const wantsNavigation = /\b(valid credentials|correct credentials|successful login|log in successfully|login succeeds|sign in succeeds)\b/.test(normalizedFeature) || /\b(redirect|redirects|redirected|secure area|dashboard|redirected to|goes to|navigates? to)\b/.test(normalizedFeature);
+  const wantsError = /\b(wrong password|wrong credentials|invalid|incorrect|error message|shows an error|alert)\b/.test(normalizedFeature);
+  const successUrlPattern = deriveSuccessUrlPattern(elementMap, normalizedFeature);
+  if (wantsNavigation) {
+    return [{
+      id: `${prefix}-001`,
+      title: "Valid credentials redirect to the authenticated area",
+      tags: [tag("auth"), tag("happy-path")],
+      steps: [
+        {
+          action: "navigate",
+          selector: "page",
+          value: elementMap.url,
+          human: "Navigate to the login page"
+        },
+        {
+          action: "fill",
+          selector: usernameInput.selector,
+          value: usernameValue,
+          human: buildFillHuman("Fill in the username field", usernameInput.selector, usernameValue)
+        },
+        {
+          action: "fill",
+          selector: passwordInput.selector,
+          value: passwordValue,
+          human: buildFillHuman("Fill in the password field", passwordInput.selector, passwordValue)
+        },
+        {
+          action: "click",
+          selector: submitButton.selector,
+          value: "",
+          human: "Click the login button"
+        }
+      ],
+      assertions: [
+        {
+          type: "url",
+          selector: "page",
+          expected: successUrlPattern,
+          human: "User is redirected to the secure area",
+          playwright: `await expect(page).toHaveURL(/${successUrlPattern}/);`
+        }
+      ],
+      narrator: "We submit valid credentials and confirm that authentication changes the page URL.",
+      codeLevel: "beginner"
+    }];
+  }
+  if (wantsError) {
+    return [{
+      id: `${prefix}-001`,
+      title: "Wrong password shows an authentication error",
+      tags: [tag("auth"), tag("negative")],
+      steps: [
+        {
+          action: "navigate",
+          selector: "page",
+          value: elementMap.url,
+          human: "Navigate to the login page"
+        },
+        {
+          action: "fill",
+          selector: usernameInput.selector,
+          value: usernameValue,
+          human: buildFillHuman("Fill in the username field", usernameInput.selector, usernameValue)
+        },
+        {
+          action: "fill",
+          selector: passwordInput.selector,
+          value: "wrong-password",
+          human: buildFillHuman("Fill in the password field", passwordInput.selector, "wrong-password")
+        },
+        {
+          action: "click",
+          selector: submitButton.selector,
+          value: "",
+          human: "Click the login button"
+        }
+      ],
+      assertions: [
+        alert ? {
+          type: "text",
+          selector: alert.selector,
+          expected: alert.name || "error",
+          human: "An alert communicates the login failure",
+          playwright: `await expect(page.${alert.selector}).toContainText(/invalid|error|required/i);`
+        } : {
+          type: "text",
+          selector: usernameInput.selector,
+          expected: "error",
+          human: "An authentication error message is shown",
+          playwright: `await expect(page.getByRole('alert')).toContainText(/invalid|error|required/i);`
+        }
+      ],
+      narrator: "We use an invalid password and confirm the page surfaces an authentication error.",
+      codeLevel: "beginner"
+    }];
+  }
   scenarios.push({
     id: nextId(1),
     title: "Login form renders expected controls",
@@ -2084,6 +2303,53 @@ 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 findAlertElement(elementMap) {
+  return elementMap.elements.find((element) => element.role === "alert" || element.category === "status" || String(element.attributes.role ?? "").toLowerCase() === "alert");
+}
+function deriveSuccessUrlPattern(elementMap, normalizedFeature) {
+  const explicitPath = normalizedFeature.match(/\/[a-z0-9/_-]+/i)?.[0] ?? (/\bsecure area\b/.test(normalizedFeature) ? "/secure" : void 0);
+  if (explicitPath) {
+    return explicitPath.replace(/^\/+/, "").split("/").map(escapeForRegex).join("\\/");
+  }
+  const authLink = elementMap.elements.find((element) => {
+    if (element.category !== "link") return false;
+    const href2 = String(element.attributes.href ?? "");
+    const label = `${element.name ?? ""} ${href2}`.toLowerCase();
+    return /\b(secure|dashboard|home|app)\b/.test(label);
+  });
+  const href = String(authLink?.attributes.href ?? "");
+  if (href.startsWith("/")) {
+    return href.replace(/^\/+/, "").split("/").map(escapeForRegex).join("\\/");
+  }
+  return "secure|dashboard|home|app";
+}
+function buildDeterministicAnalysis(elementMap, requestedFeature) {
+  const intentProfile = buildIntentProfile(requestedFeature);
+  const suggestedPrefix = inferPrefix({
+    featureText: requestedFeature,
+    url: elementMap.url
+  }).toUpperCase();
+  const authElements = detectAuthElements(elementMap);
+  let scenarios = intentProfile.mode === "count" ? buildCountScenarios(elementMap, requestedFeature, suggestedPrefix) : intentProfile.mode === "presence" ? buildPresenceOnlyScenarios(elementMap, requestedFeature, suggestedPrefix) : intentProfile.mode === "auth" || intentProfile.mode === "form" ? buildAuthFallbackScenarios(elementMap, suggestedPrefix, authElements, requestedFeature) : buildFallbackScenariosForFeature(elementMap, suggestedPrefix, requestedFeature);
+  if (scenarios.length === 0 && (authElements.usernameInput || authElements.passwordInput || authElements.submitButton)) {
+    scenarios = buildAuthFallbackScenarios(elementMap, suggestedPrefix, authElements, requestedFeature);
+  }
+  if (scenarios.length === 0) {
+    scenarios = buildFallbackScenariosForFeature(elementMap, suggestedPrefix, requestedFeature);
+  }
+  const finalScenarios = scenarios.slice(0, intentProfile.maxScenarios);
+  return {
+    url: elementMap.url,
+    feature: requestedFeature,
+    suggestedPrefix,
+    scenarios: finalScenarios,
+    analysisNotes: "Generated deterministic capture-backed scenarios because LLM analysis was unavailable.",
+    audioSummary: buildAudioSummary(requestedFeature, finalScenarios)
+  };
+}
+function shortErrorMessage(error) {
+  return String(error?.message ?? error ?? "Unknown error").split("\n")[0];
+}
 function shouldUseAuthFallback(authElements, scenarios, intentProfile) {
   if (intentProfile.mode !== "auth" && intentProfile.mode !== "form") return false;
   if (!authElements.usernameInput || !authElements.passwordInput || !authElements.submitButton) return false;