create-appraisejs 0.1.9 → 0.1.10-alpha.1

package/templates/default/package.json

@@ -1,19 +1,20 @@
 {
   "name": "appraise",
-  "version": "0.1.0",
+  "version": "0.1.9-alpha",
   "private": false,
   "type": "module",
   "scripts": {
     "dev": "next dev",
     "init": "DISABLE_DEVTOOLS=1 NEXT_PUBLIC_DISABLE_DEVTOOLS=1 next dev",
-    "build": "next build",
+    "build:cucumber-runtime": "tsc -p packages/cucumber-runtime/tsconfig.json",
+    "build": "npm run build:local",
     "start": "next start",
     "lint": "eslint .",
-    "install-playwright": "npx playwright install && npx playwright install-deps",
+    "install-playwright": "npx playwright install",
     "install-dependencies": "npm install --legacy-peer-deps",
     "setup-env": "npx tsx scripts/setup-env.ts",
-    "migrate-db": "npx prisma migrate dev",
-    "setup": "npm run install-dependencies && npm run setup-env && npm run migrate-db && npm run install-playwright && npm run sync-all",
+    "migrate-db": "npx prisma migrate deploy",
+    "setup": "npm run install-dependencies && npm run setup:db && npm run build:local",
     "sync-features": "npx tsx scripts/regenerate-features.ts",
     "sync-features:dry-run": "npx tsx scripts/regenerate-features.ts --dry-run",
     "sync-locator-groups": "npx tsx scripts/sync-locator-groups.ts",
@@ -28,6 +29,10 @@
     "sync-all": "npx tsx scripts/sync-all.ts",
     "sync-template": "npx tsx scripts/sync-appraise-base-template.ts",
     "test": "cucumber-js",
+    "build:local": "npm run generate-db-client && npm run build:cucumber-runtime && next build",
+    "generate-db-client": "npx prisma generate --schema prisma/schema.prisma",
+    "setup:db": "npm run setup-env && npm run generate-db-client && npm run migrate-db && npm run sync-all",
+    "setup:full": "npm run install-dependencies && npm run setup:db && npm run build:local",
     "appraisejs:setup": "npm run setup",
     "appraisejs:sync": "npm run sync-all"
   },
@@ -121,6 +126,7 @@
   "overrides": {
     "react-is": "^19.2.1",
     "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3"
+    "@types/react-dom": "^19.2.3",
+    "minimatch": ">=10.2.1"
   }
 }

package/templates/default/packages/cucumber-runtime/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@appraise/cucumber-runtime",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}

package/templates/default/packages/cucumber-runtime/src/cache.util.ts

@@ -0,0 +1,93 @@
+import { readFileSync } from 'fs'
+import { globSync } from 'glob'
+import * as path from 'path'
+import { LocatorCollection, LocatorMap } from './types.js'
+import { getAutomationLocatorMapPath, getAutomationLocatorsDir } from './paths.js'
+
+function toGlobPath(targetPath: string): string {
+  return targetPath.split(path.sep).join('/')
+}
+
+export class LocatorCache {
+  private static instance: LocatorCache
+  private data: Record<string, LocatorCollection> = {}
+  private filePaths: Record<string, string> = {}
+  private loadedFiles: Set<string> = new Set()
+
+  private constructor() {
+    globSync(`${toGlobPath(getAutomationLocatorsDir())}/**/*.json`).forEach(file => {
+      const fileName = path.basename(file, path.extname(file))
+      this.filePaths[fileName ?? file] = file
+    })
+  }
+
+  public static getInstance(): LocatorCache {
+    if (!LocatorCache.instance) {
+      LocatorCache.instance = new LocatorCache()
+    }
+    return LocatorCache.instance
+  }
+
+  public get(key: string): LocatorCollection | null {
+    if (!this.loadedFiles.has(key) && this.filePaths[key]) {
+      try {
+        const filePath = this.filePaths[key]
+        const data = JSON.parse(readFileSync(filePath, 'utf8'))
+        this.data[key] = data as LocatorCollection
+        this.loadedFiles.add(key)
+      } catch (error) {
+        console.error(`Error loading locator file for key "${key}":`, error)
+        return null
+      }
+    }
+
+    return this.data[key] ? { ...this.data[key] } : null
+  }
+
+  public preloadAll(): void {
+    Object.keys(this.filePaths).forEach(key => {
+      if (!this.loadedFiles.has(key)) {
+        this.get(key)
+      }
+    })
+  }
+
+  public getAvailableKeys(): string[] {
+    return Object.keys(this.filePaths)
+  }
+
+  public isLoaded(key: string): boolean {
+    return this.loadedFiles.has(key)
+  }
+}
+
+export class LocatorMapCache {
+  private static instance: LocatorMapCache
+  private data: LocatorMap[] = []
+
+  private constructor() {
+    this.data = JSON.parse(readFileSync(getAutomationLocatorMapPath(), 'utf8'))
+  }
+
+  public static getInstance(): LocatorMapCache {
+    if (!LocatorMapCache.instance) {
+      LocatorMapCache.instance = new LocatorMapCache()
+    }
+    return LocatorMapCache.instance
+  }
+
+  public get(key: string): LocatorMap {
+    try {
+      return this.data.find(map => map.path === key) as LocatorMap
+    } catch {
+      return {
+        name: '',
+        path: '',
+      }
+    }
+  }
+
+  public getAll(): LocatorMap[] {
+    return this.data
+  }
+}

package/templates/default/packages/cucumber-runtime/src/cli.ts

@@ -0,0 +1,68 @@
+import { Command, Option, OptionValues } from 'commander'
+import parseTagExpression from '@cucumber/tag-expressions'
+import { getAllEnvironments } from './environment.util.js'
+import { BrowserName } from './types.js'
+
+export interface CliOptions extends OptionValues {
+  environment: string
+  tags: string
+  parallel: number
+  browser: BrowserName
+  headless: 'true' | 'false'
+}
+
+const BROWSER_CHOICES = ['chromium', 'firefox', 'webkit'] as const
+const HEADLESS_CHOICES = ['true', 'false'] as const
+const DEFAULT_PARALLEL_WORKERS = 1
+const DEFAULT_BROWSER: BrowserName = 'chromium'
+const DEFAULT_HEADLESS = 'true'
+
+const program = new Command()
+
+let environmentNames: string[] = []
+try {
+  environmentNames = Object.keys(getAllEnvironments())
+} catch (error) {
+  console.error('Failed to load environments:', error instanceof Error ? error.message : 'Unknown error')
+  process.exit(1)
+}
+
+function parsePositiveInt(value: string): number {
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`--parallel must be a positive integer, got "${value}"`)
+  }
+  return parsed
+}
+
+function validateCucumberTagExpression(value: string): string {
+  try {
+    parseTagExpression(value)
+    return value
+  } catch (error) {
+    throw new Error(`Invalid tag expression: ${error instanceof Error ? error.message : 'Unknown error'}`)
+  }
+}
+
+program
+  .name('cucumber-runtime')
+  .description('CLI for running Appraise cucumber automation')
+  .version('1.0.0')
+  .addOption(
+    new Option('-e, --environment <environment>', 'The environment to run the tests on')
+      .choices(environmentNames)
+      .makeOptionMandatory(),
+  )
+  .addOption(
+    new Option('-t, --tags <tags>', 'The tags to run the tests on')
+      .argParser(validateCucumberTagExpression)
+      .makeOptionMandatory(),
+  )
+  .option('-p, --parallel <parallel>', 'The number of parallel workers to run', parsePositiveInt, DEFAULT_PARALLEL_WORKERS)
+  .addOption(new Option('-b, --browser <browser>', 'The browser to run').choices(BROWSER_CHOICES).default(DEFAULT_BROWSER))
+  .addOption(new Option('--headless <headless>', 'Whether to run headless').choices(HEADLESS_CHOICES).default(DEFAULT_HEADLESS))
+
+export function startCli(): CliOptions {
+  program.parse()
+  return program.opts() as CliOptions
+}

package/templates/default/packages/cucumber-runtime/src/environment.util.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from 'fs'
+import { getAutomationEnvironmentsFilePath } from './paths.js'
+
+interface EnvironmentConfig {
+  baseUrl: string
+  apiBaseUrl: string
+  email: string
+  password: string
+}
+
+export function getEnvironment(environment: string): EnvironmentConfig {
+  const environmentConfig: Record<string, EnvironmentConfig> = JSON.parse(
+    readFileSync(getAutomationEnvironmentsFilePath(), 'utf8'),
+  )
+
+  return environmentConfig[environment.toLowerCase()] as EnvironmentConfig
+}
+
+export function getAllEnvironments(): Record<string, EnvironmentConfig> {
+  return JSON.parse(readFileSync(getAutomationEnvironmentsFilePath(), 'utf8'))
+}

package/templates/default/packages/cucumber-runtime/src/executor.ts

@@ -0,0 +1,32 @@
+import { execa } from 'execa'
+import { config } from 'dotenv'
+import { startCli } from './cli.js'
+
+async function bootstrap(): Promise<void> {
+  config()
+
+  try {
+    const { environment, tags, parallel, browser, headless } = startCli()
+
+    process.env.ENVIRONMENT = environment
+    process.env.HEADLESS = headless
+    process.env.BROWSER = browser
+
+    const cucumberArgs: string[] = ['cucumber-js', '-t', tags]
+    if (parallel > 1) {
+      cucumberArgs.push('--parallel', parallel.toString())
+    }
+
+    const subprocess = execa('npx', cucumberArgs, {
+      stdio: 'inherit',
+    })
+
+    const result = await subprocess
+    process.exit(result.exitCode ?? 0)
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : 'Unknown error')
+    process.exit(1)
+  }
+}
+
+bootstrap()

package/templates/default/{src/tests/hooks → packages/cucumber-runtime/src}/hooks.ts

@@ -1,36 +1,29 @@
 import { After, AfterAll, AfterStep, Before, BeforeAll, setDefaultTimeout } from '@cucumber/cucumber'
-import { CustomWorld } from '../config/executor/world.js'
-import { BrowserName } from '@/types/executor/browser.type'
 import { config } from 'dotenv'
-import { chromium, ChromiumBrowser, firefox, FirefoxBrowser, webkit, WebKitBrowser } from 'playwright'
+import { promises as fs } from 'fs'
+import { chromium, firefox, webkit, ChromiumBrowser, FirefoxBrowser, WebKitBrowser } from 'playwright'
+import { getAutomationTraceDir } from './paths.js'
+import { BrowserName } from './types.js'
+import { CustomWorld } from './world.js'
 
-// Load environment variables
 config()
 
-// Initialize browser
 let browser: ChromiumBrowser | FirefoxBrowser | WebKitBrowser
-
-// Track scenario status
-let currentScenarioStatus: string = 'unknown'
+let currentScenarioStatus = 'unknown'
 
 BeforeAll(async function () {
   setDefaultTimeout(60000)
   const browserName = (process.env.BROWSER as BrowserName) || 'chromium'
+
   switch (browserName) {
     case 'chromium':
-      browser = await chromium.launch({
-        headless: process.env.HEADLESS === 'true',
-      })
+      browser = await chromium.launch({ headless: process.env.HEADLESS === 'true' })
       break
     case 'firefox':
-      browser = await firefox.launch({
-        headless: process.env.HEADLESS === 'true',
-      })
+      browser = await firefox.launch({ headless: process.env.HEADLESS === 'true' })
       break
     case 'webkit':
-      browser = await webkit.launch({
-        headless: process.env.HEADLESS === 'true',
-      })
+      browser = await webkit.launch({ headless: process.env.HEADLESS === 'true' })
       break
     default:
       throw new Error(`Invalid browser name: ${browserName}`)
@@ -49,7 +42,6 @@ Before(async function (this: CustomWorld) {
 })
 
 AfterStep(async function (this: CustomWorld, result) {
-  // Track the worst status encountered (failed > skipped > passed)
   const status = result.result?.status
   if (status === 'FAILED') {
     currentScenarioStatus = 'failed'
@@ -61,33 +53,26 @@ AfterStep(async function (this: CustomWorld, result) {
 })
 
 After(async function (this: CustomWorld, scenario) {
-  // Emit scenario end event as JSON to stdout
-  // ProcessManager will parse this and re-emit it as an event
   let tracePath: string | undefined
   if (scenario.result?.status === 'FAILED') {
-    tracePath = `${process.cwd()}/src/tests/reports/traces/${crypto.randomUUID()}.zip`
-    await this.context.tracing.stop({
-      path: tracePath,
-    })
+    const traceDir = getAutomationTraceDir()
+    await fs.mkdir(traceDir, { recursive: true })
+    tracePath = `${traceDir}/${crypto.randomUUID()}.zip`
+    await this.context.tracing.stop({ path: tracePath })
   }
 
-  const eventData = {
+  const eventJson = JSON.stringify({
     event: 'scenario::end',
     data: {
       scenarioName: scenario.pickle.name,
       status: currentScenarioStatus,
-      tracePath: tracePath,
+      tracePath,
     },
-  }
+  })
 
-  // Write to stdout in a parseable JSON format
-  // Use process.stdout.write to ensure it's captured by TaskSpawner
-  const eventJson = JSON.stringify(eventData)
   console.log(eventJson)
-  // Also write directly to stdout to ensure it's captured
   process.stdout.write(eventJson + '\n')
 
-  // Reset status for next scenario
   currentScenarioStatus = 'unknown'
 
   await this.page.close()

package/templates/default/packages/cucumber-runtime/src/index.ts

@@ -0,0 +1,17 @@
+export {
+  After,
+  AfterAll,
+  AfterStep,
+  Before,
+  BeforeAll,
+  Given,
+  Then,
+  When,
+  defineParameterType,
+  setDefaultTimeout,
+} from '@cucumber/cucumber'
+export { CustomWorld, expect } from './world.js'
+export { getEnvironment, getAllEnvironments } from './environment.util.js'
+export { resolveLocator, retry, waitForRouteSettled } from './locator.util.js'
+export { generateRandomData, RandomDataType } from './random-data.util.js'
+export type { BrowserName, Locator, LocatorCollection, LocatorMap, Selector, SelectorName } from './types.js'

package/templates/default/{src/tests/utils → packages/cucumber-runtime/src}/locator.util.ts

@@ -1,11 +1,8 @@
 import { Page } from 'playwright'
 import { LocatorCache, LocatorMapCache } from './cache.util.js'
 
-const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
 
-/**
- * Retry helper: immediate first attempt, exponential backoff, selective retry.
- */
 export async function retry<T>(
   fn: () => Promise<T>,
   {
@@ -17,7 +14,7 @@ export async function retry<T>(
     retries?: number
     delayMs?: number
     backoff?: number
-    shouldRetry?: (e: unknown) => boolean
+    shouldRetry?: (error: unknown) => boolean
   } = {},
 ): Promise<T> {
   let lastErr: unknown
@@ -26,9 +23,11 @@ export async function retry<T>(
   for (let i = 0; i <= retries; i++) {
     try {
       return await fn()
-    } catch (e) {
-      lastErr = e
-      if (i === retries || !shouldRetry(e)) break
+    } catch (error) {
+      lastErr = error
+      if (i === retries || !shouldRetry(error)) {
+        break
+      }
       await sleep(delay)
       delay = Math.floor(delay * backoff)
     }
@@ -38,20 +37,14 @@ export async function retry<T>(
 }
 
 const routeKey = (page: Page, includeSearch = false) => {
-  const u = new URL(page.url())
-  return includeSearch ? `${u.pathname}${u.search}` : u.pathname
+  const url = new URL(page.url())
+  return includeSearch ? `${url.pathname}${url.search}` : url.pathname
 }
 
-/**
- * Wait for route to be "settled" without AUT changes:
- * - URL stable for urlStableMs
- * - no frame navigations during that window
- * - DOM quiet (no mutations) for domQuietMs
- */
 export async function waitForRouteSettled(
   page: Page,
   {
-    timeoutMs = 15_000,
+    timeoutMs = 15000,
     pollMs = 50,
     urlStableMs = 500,
     domQuietMs = 300,
@@ -65,16 +58,16 @@ export async function waitForRouteSettled(
   } = {},
 ): Promise<string> {
   const deadline = Date.now() + timeoutMs
-
   await page.waitForLoadState('domcontentloaded', { timeout: timeoutMs })
 
   let lastKey = routeKey(page, includeSearch)
   let stableSince = Date.now()
-
   let navBumpedAt = Date.now()
+
   const onFrameNav = () => {
     navBumpedAt = Date.now()
   }
+
   page.on('framenavigated', onFrameNav)
 
   try {
@@ -91,31 +84,36 @@ export async function waitForRouteSettled(
       const now = Date.now()
       const urlStableLongEnough = now - stableSince >= urlStableMs
       const noRecentNav = now - navBumpedAt >= urlStableMs
-      if (!urlStableLongEnough || !noRecentNav) continue
+      if (!urlStableLongEnough || !noRecentNav) {
+        continue
+      }
 
       const domQuiet = await page
         .evaluate(quietMs => {
           return new Promise<boolean>(resolve => {
             let lastMutation = Date.now()
-            const obs = new MutationObserver(() => {
+            const observer = new MutationObserver(() => {
               lastMutation = Date.now()
             })
-            obs.observe(document, { subtree: true, childList: true, attributes: true })
+            observer.observe(document, { subtree: true, childList: true, attributes: true })
 
             const tick = () => {
               if (Date.now() - lastMutation >= quietMs) {
-                obs.disconnect()
+                observer.disconnect()
                 resolve(true)
                 return
               }
               setTimeout(tick, 50)
             }
+
             tick()
           })
         }, domQuietMs)
         .catch(() => false)
 
-      if (domQuiet) return lastKey
+      if (domQuiet) {
+        return lastKey
+      }
     }
 
     return routeKey(page, includeSearch)
@@ -124,24 +122,18 @@ export async function waitForRouteSettled(
   }
 }
 
-/**
- * Throw tagged error so we only retry on "map missing" cases.
- */
 const getLocatorMapData = async (page: Page) => {
   const locatorMap = LocatorMapCache.getInstance()
   const currentPath = new URL(page.url()).pathname
-
   const data = locatorMap.get(currentPath)
-  if (!data) throw new Error(`LOCATOR_MAP_NOT_FOUND::${currentPath}`)
+
+  if (!data) {
+    throw new Error(`LOCATOR_MAP_NOT_FOUND::${currentPath}`)
+  }
+
   return data
 }
 
-/**
- * Validate that a selector "belongs" to the current page state.
- * - attached: element exists in DOM
- * - visible: element is visible (optional but very useful to avoid stale hidden elements)
- * - unique: avoids matching some leftover layout/header element found everywhere
- */
 async function validateResolvedSelector(
   page: Page,
   selector: string,
@@ -156,19 +148,18 @@ async function validateResolvedSelector(
   } = {},
 ): Promise<boolean> {
   try {
-    const loc = page.locator(selector)
-
-    // "attached" (exists) quickly
-    await loc.first().waitFor({ state: 'attached', timeout: timeoutMs })
+    const locator = page.locator(selector)
+    await locator.first().waitFor({ state: 'attached', timeout: timeoutMs })
 
     if (requireVisible) {
-      // visible check helps avoid stale hidden DOM (old route kept around)
-      await loc.first().waitFor({ state: 'visible', timeout: timeoutMs })
+      await locator.first().waitFor({ state: 'visible', timeout: timeoutMs })
     }
 
     if (requireUnique) {
-      const c = await loc.count()
-      if (c !== 1) return false
+      const count = await locator.count()
+      if (count !== 1) {
+        return false
+      }
     }
 
     return true
@@ -177,13 +168,6 @@ async function validateResolvedSelector(
   }
 }
 
-/**
- * Resolve locator with:
- * - route settled
- * - map lookup retry
- * - selector validation (protects against stale "same key across pages")
- * - rerun if validation fails or route changes mid-flight
- */
 export async function resolveLocator(
   page: Page,
   locatorName: string,
@@ -202,11 +186,11 @@ export async function resolveLocator(
       requireUnique?: boolean
     }
   } = {},
-) {
+): Promise<string | null> {
   try {
     for (let pass = 0; pass < maxResolvePasses; pass++) {
       await waitForRouteSettled(page, {
-        timeoutMs: 15_000,
+        timeoutMs: 15000,
         urlStableMs: 500,
         domQuietMs: 300,
         pollMs: 50,
@@ -214,30 +198,32 @@ export async function resolveLocator(
       })
 
       const beforePath = new URL(page.url()).pathname
-
       const locatorMapData = await retry(() => getLocatorMapData(page), {
         retries: 6,
         delayMs: 80,
         backoff: 1.5,
-        shouldRetry: e => e instanceof Error && e.message.startsWith('LOCATOR_MAP_NOT_FOUND::'),
+        shouldRetry: error => error instanceof Error && error.message.startsWith('LOCATOR_MAP_NOT_FOUND::'),
       })
 
       const locators = LocatorCache.getInstance().get(locatorMapData.name)
-      if (!locators) throw new Error(`Locator bundle not found for name ${locatorMapData.name}`)
+      if (!locators) {
+        throw new Error(`Locator bundle not found for name ${locatorMapData.name}`)
+      }
 
       const selector = locators[locatorName]
-      if (!selector) throw new Error(`Locator "${locatorName}" not found for name ${locatorMapData.name}`)
+      if (!selector) {
+        throw new Error(`Locator "${locatorName}" not found for name ${locatorMapData.name}`)
+      }
 
-      // Guard: route changed mid-resolution → re-run
       const afterPath = new URL(page.url()).pathname
-      if (afterPath !== beforePath) continue
-
-      // Critical: validate selector matches current page state.
-      const ok = await validateResolvedSelector(page, selector as unknown as string, validate)
-      if (ok) return selector as unknown as string
+      if (afterPath !== beforePath) {
+        continue
+      }
 
-      // If validation failed, likely stale bundle (same locator key on multiple pages),
-      // or transition still in progress. Loop and re-resolve after settling again.
+      const isValid = await validateResolvedSelector(page, selector as unknown as string, validate)
+      if (isValid) {
+        return selector as unknown as string
+      }
     }
 
     throw new Error(`Failed to resolve a valid locator for "${locatorName}" after ${maxResolvePasses} passes`)

package/templates/default/packages/cucumber-runtime/src/parameter-types.ts

@@ -0,0 +1,7 @@
+import { defineParameterType } from '@cucumber/cucumber'
+
+defineParameterType({
+  name: 'boolean',
+  regexp: /true|false/,
+  transformer: (s: string) => s === 'true',
+})

package/templates/default/packages/cucumber-runtime/src/paths.ts

@@ -0,0 +1,33 @@
+import path from 'path'
+
+export function getAutomationRoot(): string {
+  return path.join(process.cwd(), 'automation')
+}
+
+export function getAutomationConfigDir(): string {
+  return path.join(getAutomationRoot(), 'config')
+}
+
+export function getAutomationEnvironmentsFilePath(): string {
+  return path.join(getAutomationConfigDir(), 'environments', 'environments.json')
+}
+
+export function getAutomationFeaturesDir(): string {
+  return path.join(getAutomationRoot(), 'features')
+}
+
+export function getAutomationLocatorsDir(): string {
+  return path.join(getAutomationRoot(), 'locators')
+}
+
+export function getAutomationLocatorMapPath(): string {
+  return path.join(getAutomationRoot(), 'mapping', 'locator-map.json')
+}
+
+export function getAutomationReportsDir(): string {
+  return path.join(getAutomationRoot(), 'reports')
+}
+
+export function getAutomationTraceDir(): string {
+  return path.join(getAutomationReportsDir(), 'traces')
+}