@nhonh/qabot 1.2.1 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhonh/qabot",
-  "version": "1.2.1",
+  "version": "2.0.0",
   "description": "AI-powered universal QA automation tool. Import any project, AI analyzes and runs tests across all layers.",
   "main": "src/index.js",
   "bin": {

package/src/cli/commands/test.js

@@ -9,6 +9,7 @@ import { loadConfig } from "../../core/config.js";
 import { analyzeProject } from "../../analyzers/project-analyzer.js";
 import { AIEngine } from "../../ai/ai-engine.js";
 import { UseCaseParser } from "../../ai/usecase-parser.js";
+import { runPreflight } from "../../e2e/preflight.js";
 import {
   ensurePlaywright,
   ensureE2EStructure,
@@ -70,6 +71,39 @@ async function runTest(feature, options) {
   console.log(DIM("  Browser: ") + W(options.headed ? "Headed" : "Headless"));
   logger.blank();
 
+  const preflightSpinner = ora({
+    text: V(" Analyzing project routes & auth..."),
+    spinner: "dots",
+  }).start();
+  let preflight;
+  try {
+    preflight = await runPreflight(projectDir, feature, config);
+    const authStatus = preflight.featureRequiresAuth
+      ? Y("requires auth")
+      : G("public");
+    preflightSpinner.succeed(
+      G(` Route analysis complete — ${feature}: ${authStatus}`),
+    );
+
+    if (preflight.featureRequiresAuth) {
+      logger.dim(`  Sign-in URL: ${preflight.routes.authUrl}`);
+      logger.dim(
+        `  Credentials: ${preflight.credentials.email ? G("ready") : Y("will prompt")}`,
+      );
+    }
+    if (preflight.permissions.geolocation)
+      logger.dim(`  Geolocation: ${G("mock granted (SF, CA)")}`);
+  } catch (err) {
+    preflightSpinner.succeed(G(" Route analysis done (partial)"));
+    preflight = {
+      routes: { private: [], public: [] },
+      credentials: {},
+      permissions: {},
+      featureRequiresAuth: false,
+      routeIntelligence: "",
+    };
+  }
+
   const spinner = ora({
     text: V(" Setting up Playwright..."),
     spinner: "dots",
@@ -77,7 +111,12 @@ async function runTest(feature, options) {
   try {
     await ensurePlaywright(projectDir);
     await ensureE2EStructure(projectDir);
-    await writePlaywrightConfig(projectDir, config, baseUrl);
+    await writePlaywrightConfig(
+      projectDir,
+      config,
+      baseUrl,
+      preflight.permissions,
+    );
     await writeAuthHelper(projectDir, config);
     spinner.succeed(G(" Playwright ready"));
   } catch (err) {
@@ -168,8 +207,12 @@ async function runTest(feature, options) {
         baseUrl,
         sourceCode,
         route,
-        routes: routesContext,
+        routeIntelligence: preflight.routeIntelligence,
         authProvider: config.auth?.provider || "none",
+        authUrl: preflight.routes.authUrl,
+        signupUrl: preflight.routes.signupUrl,
+        featureRequiresAuth: preflight.featureRequiresAuth,
+        permissions: preflight.permissions,
         useCases,
       });
       specFile = path.join(specDir, `${feature}.spec.js`);

package/src/core/constants.js

@@ -1,4 +1,4 @@
-export const VERSION = "1.2.1";
+export const VERSION = "2.0.0";
 export const TOOL_NAME = "qabot";
 
 export const PROJECT_TYPES = [

package/src/e2e/e2e-prompts.js

@@ -3,11 +3,7 @@ export function buildE2EPrompt(featureName, context) {
     ? `\n## Source Code (analyze navigation, hooks, API calls, user actions, conditions)\n\`\`\`\n${context.sourceCode.slice(0, 10000)}\n\`\`\`\n`
     : "";
 
-  const routeSection = context.routes
-    ? `\n## All Application Routes\n${context.routes}\n`
-    : context.route
-      ? `\n## Feature Route: ${context.route}\n`
-      : "";
+  const routeIntelligence = context.routeIntelligence || "";
 
   const useCaseSection = context.useCases?.length
     ? `\n## QA Use Cases\n${context.useCases.map((uc) => `### ${uc.scenario}\n${uc.steps.map((s, i) => `${i + 1}. ${s}`).join("\n")}`).join("\n\n")}\n`
@@ -15,29 +11,40 @@ export function buildE2EPrompt(featureName, context) {
 
   const baseUrl = context.baseUrl || "http://localhost:3000";
   const route = context.route || "/" + featureName;
+  const requiresAuth = context.featureRequiresAuth !== false;
+  const authUrl = context.authUrl || "/signin";
+  const signupUrl = context.signupUrl || "/signup";
+  const hasGeolocation = context.permissions?.geolocation || false;
 
-  return `You are an expert QA automation engineer designing REAL user journey tests.
+  return `You are an expert QA automation engineer. You deeply understand web app testing.
 
-## Feature: ${featureName}
+## Feature Under Test: ${featureName}
 ## Base URL: ${baseUrl}
-## Auth: ${context.authProvider || "none"}
-${routeSection}${sourceSection}${useCaseSection}
+## Auth Provider: ${context.authProvider || "none"}
+## Feature Route: ${route}
+## Feature Requires Auth: ${requiresAuth ? "YES" : "NO"}
+## Sign In URL: ${baseUrl}${authUrl}
+## Sign Up URL: ${baseUrl}${signupUrl}
+## Geolocation Required: ${hasGeolocation ? "YES (already granted via Playwright config)" : "NO"}
 
-## CRITICAL: This is a JOURNEY-BASED test, not a page screenshot test.
+${routeIntelligence}
+${sourceSection}${useCaseSection}
 
-You MUST test REAL USER FLOWS across multiple pages. A user does NOT just open one page — they:
-1. Land on the app → see landing/home page
-2. Sign in or are already signed in
-3. Navigate to the feature via menu/link/URL
-4. Interact with the feature (click buttons, fill forms, read data)
-5. Feature may redirect them to other pages (FAQ, account, modals)
-6. Come back, verify state changed
+## YOUR JOB: Write a REAL user journey test — not a page screenshot test.
 
-## ARCHITECTURE — Single Browser, Serial Tests
+A real QA engineer:
+1. Opens the app at ${baseUrl}/
+2. ${requiresAuth ? `Clicks "Sign In", enters email/password from env vars (process.env.E2E_TEST_EMAIL, process.env.E2E_TEST_PASSWORD), submits, waits for redirect` : "Directly navigates to the feature page"}
+3. Navigates to the feature: ${baseUrl}${route}
+4. Tests EVERY interaction: clicks buttons, reads data, verifies states
+5. Tests cross-page navigation (feature links to FAQ, account, etc.)
+6. Verifies error handling, loading states, empty states
+
+## ARCHITECTURE
 
 \`\`\`javascript
 const { test, expect } = require("@playwright/test");
-const { login } = require("../helpers/auth.js");
+${requiresAuth ? `const { login } = require("../helpers/auth.js");` : ""}
 
 test.describe.serial("${featureName} - User Journey", () => {
   let page;
@@ -50,68 +57,68 @@ test.describe.serial("${featureName} - User Journey", () => {
     if (page) await page.close();
   });
 
-  // Tests use shared 'page' — same browser, same session, same cookies
-  // Each test() does NOT take { page } argument
+  // ALL tests share this 'page' — single browser session
+  // Each test() does NOT take { page } argument — uses shared variable
 });
 \`\`\`
 
-## GENERATE 10-15 TEST CASES as a SEQUENTIAL USER JOURNEY:
-
-### Phase 1: Entry & Authentication (TC-01 to TC-03)
-- TC-01: Open app landing page → verify it loads → screenshot
-- TC-02: Sign in flow → click sign in → fill credentials → submit → verify redirect to lobby/home
-- TC-03: Verify authenticated state → user menu visible, correct username/avatar
-
-### Phase 2: Navigation to Feature (TC-04 to TC-05)
-- TC-04: Navigate to "${featureName}" → via menu, link, or direct URL "${route}" → verify page loads
-- TC-05: Verify feature page layout → key sections, headers, data loaded (not empty/loading)
-
-### Phase 3: Core Feature Interactions (TC-06 to TC-10)
-READ THE SOURCE CODE and generate tests for the ACTUAL user interactions:
-- What buttons does the page have? Test clicking them.
-- What data does the page display? Verify it shows correctly.
-- What actions can the user take? (share, copy, claim, submit, toggle, select)
-- What modals/popups appear? Verify they open and close.
-- What state changes happen? (loading → loaded, button text changes, counters update)
+## TEST CASES — Generate 10-15 sequential tests:
 
-### Phase 4: Cross-Page Navigation (TC-11 to TC-12)
-- Does the feature link to other pages? (FAQ, account, game details, etc.)
-- Test navigating AWAY and coming BACK — verify state is preserved or reset correctly
-- Test browser back button behavior
-
-### Phase 5: Edge Cases & Cleanup (TC-13 to TC-15)
-- Test with different viewport (mobile: 375x667)
-- Test error states if possible (disconnect, slow network)
-- Verify page after refresh (F5) — does state persist?
-
-## PLAYWRIGHT RULES:
-1. Use \`test.describe.serial\` — all tests share ONE page
-2. \`let page\` at describe scope — shared across ALL tests
-3. \`test.beforeAll\` → \`browser.newPage()\` ONLY (login happens in TC-02)
-4. Each \`test()\` does NOT take \`{ page }\` argument
-5. Use \`page.goto("${baseUrl}${route}")\` with FULL URL for navigation
-6. After navigation: \`await page.waitForLoadState("networkidle")\`
-7. Screenshot EVERY test: \`await page.screenshot({ path: "e2e/screenshots/${featureName}-TC{XX}.png", fullPage: true })\`
-8. Selectors priority: \`getByRole()\` > \`getByText()\` > \`getByTestId()\` > \`locator()\`
-9. For slow elements: \`{ timeout: 15000 }\`
-10. For navigation between pages, always verify URL changed: \`expect(page).toHaveURL()\`
-11. After clicking links/buttons that navigate: \`await page.waitForLoadState("networkidle")\`
-12. For modals: \`await expect(page.getByRole("dialog")).toBeVisible()\`
-13. Use \`try/catch\` for optional elements that may not exist (feature flags, A/B tests)
-14. If auth is "${context.authProvider}":
+### Phase 1: App Entry${requiresAuth ? " & Login" : ""} (TC-01 to TC-0${requiresAuth ? "3" : "2"})
+- TC-01: Navigate to ${baseUrl}/ → verify landing page loads → screenshot
+${
+  requiresAuth
+    ? `- TC-02: Login flow:
     \`\`\`
-    const { login } = require("../helpers/auth.js");
-    // In TC-02:
     await login(page, "${baseUrl}");
+    // login() navigates to ${baseUrl}/, clicks sign in, fills email/password from env, submits
+    // After login, verify user is redirected (URL no longer contains "signin")
+    await expect(page).not.toHaveURL(/signin/);
     \`\`\`
+    Take screenshot after login.
+- TC-03: Verify authenticated state → look for user avatar, account menu, or logged-in indicator`
+    : `- TC-02: Verify page is accessible without login`
+}
 
-## IMPORTANT:
-- Tests are SEQUENTIAL — TC-02 login result carries to TC-03, TC-04, etc.
-- Do NOT navigate to "${route}" in beforeAll — let TC-01 to TC-04 handle the journey
-- TC-01 starts at "${baseUrl}/" (landing page)
-- Generate MEANINGFUL assertions, not just "page exists"
-- Each test must VERIFY something specific with expect()
+### Phase 2: Navigate to Feature (TC-0${requiresAuth ? "4" : "3"} to TC-0${requiresAuth ? "5" : "4"})
+- Navigate to ${baseUrl}${route} via page.goto()
+- Wait for networkidle
+- Verify URL contains "${route}"
+- Verify feature-specific content is visible (NOT loading spinner)
+- Screenshot
+
+### Phase 3: Feature Interactions (TC-06 to TC-10)
+READ THE SOURCE CODE CAREFULLY. Generate tests for ACTUAL elements:
+- Buttons: what do they do when clicked? Test each one.
+- Data display: verify numbers, text, images are correct
+- Actions: share link, copy, claim rewards, submit form — test the real action
+- Modals: do any actions open popups? Verify they appear and can be closed
+- State changes: loading→loaded, button disabled→enabled, counter changes
 
-Return ONLY JavaScript code. No markdown fences. No explanation.
-Generate a COMPLETE spec file with 10-15 tests.`;
+### Phase 4: Cross-Page Navigation (TC-11 to TC-12)
+- If feature has links to other pages, CLICK THEM and verify navigation
+- Test going BACK to the feature page after navigating away
+- Verify the feature state after returning
+
+### Phase 5: Responsive & Edge Cases (TC-13 to TC-15)
+- Resize viewport to mobile (375x667) → verify layout adapts
+- Refresh the page → verify data reloads
+- Verify error states if applicable
+
+## RULES:
+1. \`test.describe.serial\` — tests run IN ORDER, sharing state
+2. \`let page\` at describe scope — NEVER use \`{ page }\` in test arguments
+3. \`test.beforeAll\` = \`browser.newPage()\` ONLY — login is a test case, not setup
+4. Use FULL URLs: \`page.goto("${baseUrl}${route}")\` — not relative paths
+5. After navigation: \`await page.waitForLoadState("networkidle")\`
+6. Screenshot every test: \`await page.screenshot({ path: "e2e/screenshots/${featureName}-TC{XX}.png", fullPage: true })\`
+7. Selectors: getByRole > getByText > getByTestId > locator (CSS last resort)
+8. Slow elements: \`{ timeout: 15000 }\`
+9. After clicks that navigate: \`await page.waitForLoadState("networkidle")\`
+10. Verify URLs after navigation: \`await expect(page).toHaveURL()\`
+11. Use \`try/catch\` for elements that might not exist (feature flags, A/B tests)
+${requiresAuth ? `12. Login uses helper: \`await login(page, "${baseUrl}");\` — credentials come from process.env` : ""}
+${hasGeolocation ? `13. Geolocation is pre-granted in Playwright config — no need to handle permission popup` : ""}
+
+Return ONLY JavaScript code. No markdown fences. No explanation.`;
 }

package/src/e2e/playwright-setup.js

@@ -47,6 +47,7 @@ export async function writePlaywrightConfig(
   projectDir,
   config,
   overrideBaseUrl,
+  permissions = {},
 ) {
   const configPath = path.join(projectDir, "e2e", "playwright.config.js");
 
@@ -83,7 +84,7 @@ module.exports = defineConfig({
     video: "retain-on-failure",
     ignoreHTTPSErrors: true,
     actionTimeout: 15000,
-    navigationTimeout: 30000,
+    navigationTimeout: 30000,${permissions.geolocation ? `\n    geolocation: { latitude: 37.7749, longitude: -122.4194 },\n    permissions: ["geolocation"],` : ""}${permissions.notifications ? `\n    permissions: [...(${permissions.geolocation ? '["geolocation"]' : "[]"}), "notifications"],` : ""}
     launchOptions: {
       slowMo: 100,
     },

package/src/e2e/preflight.js

@@ -0,0 +1,217 @@
+import path from "node:path";
+import Enquirer from "enquirer";
+import chalk from "chalk";
+import { findFiles, safeReadFile } from "../utils/file-utils.js";
+import { logger } from "../core/logger.js";
+
+const V = chalk.hex("#A78BFA");
+const DIM = chalk.hex("#6B7280");
+const W = chalk.hex("#F3F4F6");
+const Y = chalk.hex("#FBBF24");
+const G = chalk.hex("#34D399");
+
+export async function runPreflight(projectDir, feature, config) {
+  const result = {
+    routes: { private: [], public: [], authUrl: null, signupUrl: null },
+    credentials: { email: "", password: "" },
+    permissions: { geolocation: false, notifications: false },
+    featureRequiresAuth: false,
+    routeIntelligence: "",
+  };
+
+  result.routes = await analyzeRoutes(projectDir);
+
+  const featureRoute = guessFeatureRoute(feature);
+  result.featureRequiresAuth = result.routes.private.some((r) =>
+    matchRoute(r, featureRoute),
+  );
+
+  result.routeIntelligence = buildRouteIntelligence(
+    result.routes,
+    feature,
+    featureRoute,
+  );
+
+  result.permissions = await detectPermissions(projectDir);
+
+  if (result.featureRequiresAuth) {
+    result.credentials = await resolveCredentials(config);
+  }
+
+  return result;
+}
+
+async function analyzeRoutes(projectDir) {
+  const routes = {
+    private: [],
+    public: [],
+    authUrl: "/signin",
+    signupUrl: "/signup",
+  };
+
+  const routeFiles = await findFiles(
+    projectDir,
+    "src/routes/*.{js,jsx,ts,tsx}",
+  );
+  for (const file of routeFiles) {
+    const content = await safeReadFile(file);
+    if (!content) continue;
+
+    const pathMatches = content.matchAll(/path:\s*["'`]([^"'`]+)["'`]/g);
+    const privateMatches = content.matchAll(
+      /path:\s*["'`]([^"'`]+)["'`][^}]*isPrivate:\s*true/gs,
+    );
+    const publicMatches = content.matchAll(
+      /path:\s*["'`]([^"'`]+)["'`][^}]*isPrivate:\s*false/gs,
+    );
+
+    for (const m of privateMatches) routes.private.push(m[1]);
+    for (const m of publicMatches) routes.public.push(m[1]);
+
+    const signInMatch = content.match(/pageSignIn:\s*["'`]([^"'`]+)["'`]/);
+    if (signInMatch) routes.authUrl = signInMatch[1];
+
+    const signUpMatch = content.match(/pageSignUp:\s*["'`]([^"'`]+)["'`]/);
+    if (signUpMatch) routes.signupUrl = signUpMatch[1];
+  }
+
+  if (routes.private.length === 0 && routes.public.length === 0) {
+    const allRouteFiles = await findFiles(
+      projectDir,
+      "src/**/{routes,router,routing}*.{js,jsx,ts,tsx}",
+    );
+    for (const file of allRouteFiles) {
+      const content = await safeReadFile(file);
+      if (!content) continue;
+      const matches = content.matchAll(/path:\s*["'`]([^"'`]+)["'`]/g);
+      for (const m of matches) routes.public.push(m[1]);
+    }
+  }
+
+  return routes;
+}
+
+async function detectPermissions(projectDir) {
+  const permissions = { geolocation: false, notifications: false };
+
+  const geoFiles = await findFiles(
+    projectDir,
+    "src/**/*{geo,location,radar}*.{js,jsx,ts,tsx}",
+  );
+  if (geoFiles.length > 0) permissions.geolocation = true;
+
+  const notifFiles = await findFiles(
+    projectDir,
+    "src/**/*{notification,push}*.{js,jsx,ts,tsx}",
+  );
+  if (notifFiles.length > 0) permissions.notifications = true;
+
+  return permissions;
+}
+
+async function resolveCredentials(config) {
+  const email =
+    process.env.E2E_TEST_EMAIL || config.auth?.credentials?.email || "";
+  const password =
+    process.env.E2E_TEST_PASSWORD || config.auth?.credentials?.password || "";
+
+  if (
+    email &&
+    password &&
+    !email.includes("ENV_") &&
+    !password.includes("ENV_")
+  ) {
+    return { email, password };
+  }
+
+  if (process.env.E2E_TEST_EMAIL && process.env.E2E_TEST_PASSWORD) {
+    return {
+      email: process.env.E2E_TEST_EMAIL,
+      password: process.env.E2E_TEST_PASSWORD,
+    };
+  }
+
+  logger.blank();
+  logger.warn("This feature requires authentication.");
+  logger.dim(
+    "Credentials not found in env vars (E2E_TEST_EMAIL, E2E_TEST_PASSWORD)",
+  );
+  logger.blank();
+
+  const enquirer = new Enquirer();
+  const answers = await enquirer.prompt([
+    {
+      type: "input",
+      name: "email",
+      message: V("\u25C6") + W(" Test account email"),
+      validate: (v) => (v.includes("@") ? true : "Enter a valid email"),
+    },
+    {
+      type: "password",
+      name: "password",
+      message: V("\u25C6") + W(" Test account password"),
+      validate: (v) => (v.length >= 1 ? true : "Password required"),
+    },
+  ]);
+
+  process.env.E2E_TEST_EMAIL = answers.email;
+  process.env.E2E_TEST_PASSWORD = answers.password;
+
+  logger.success("Credentials set for this session");
+  return { email: answers.email, password: answers.password };
+}
+
+function buildRouteIntelligence(routes, feature, featureRoute) {
+  const lines = [];
+
+  lines.push("## Route Intelligence (analyzed from source code)");
+  lines.push("");
+
+  if (routes.private.length > 0) {
+    lines.push("### Routes requiring authentication (isPrivate: true):");
+    routes.private.forEach((r) => lines.push(`- ${r}`));
+    lines.push("");
+  }
+
+  if (routes.public.length > 0) {
+    lines.push("### Public routes (no auth required):");
+    routes.public.slice(0, 15).forEach((r) => lines.push(`- ${r}`));
+    lines.push("");
+  }
+
+  lines.push(`### Auth URLs:`);
+  lines.push(`- Sign In: ${routes.authUrl || "/signin"}`);
+  lines.push(`- Sign Up: ${routes.signupUrl || "/signup"}`);
+  lines.push("");
+
+  const requiresAuth = routes.private.some((r) => matchRoute(r, featureRoute));
+  lines.push(`### Feature "${feature}" (${featureRoute}):`);
+  lines.push(
+    `- Requires auth: ${requiresAuth ? "YES — must login first" : "NO — public page"}`,
+  );
+  lines.push(
+    `- Test strategy: ${requiresAuth ? "Login → Navigate → Test" : "Direct access → Test"}`,
+  );
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function guessFeatureRoute(feature) {
+  const map = {
+    home: "/",
+    lobby: "/lobby",
+    auth: "/signin",
+    account: "/account",
+    redemption: "/redemption",
+    "refer-a-friend": "/refer-a-friend",
+    faq: "/faq",
+    promotions: "/promotions",
+  };
+  return map[feature] || `/${feature}`;
+}
+
+function matchRoute(routePattern, target) {
+  const normalized = routePattern.replace(/:[^/]+/g, "[^/]+");
+  return new RegExp(`^${normalized}$`).test(target) || routePattern === target;
+}