create-appraisejs 0.2.0 → 0.3.0-alpha.1

package/templates/starter/packages/cucumber-runtime/src/locator.util.ts

@@ -0,0 +1,234 @@
+import { Page } from 'playwright'
+import { LocatorCache, LocatorMapCache } from './cache.util.js'
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
+export async function retry<T>(
+  fn: () => Promise<T>,
+  {
+    retries = 5,
+    delayMs = 100,
+    backoff = 1.6,
+    shouldRetry = () => true,
+  }: {
+    retries?: number
+    delayMs?: number
+    backoff?: number
+    shouldRetry?: (error: unknown) => boolean
+  } = {},
+): Promise<T> {
+  let lastErr: unknown
+  let delay = delayMs
+
+  for (let i = 0; i <= retries; i++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastErr = error
+      if (i === retries || !shouldRetry(error)) {
+        break
+      }
+      await sleep(delay)
+      delay = Math.floor(delay * backoff)
+    }
+  }
+
+  throw lastErr
+}
+
+const routeKey = (page: Page, includeSearch = false) => {
+  const url = new URL(page.url())
+  return includeSearch ? `${url.pathname}${url.search}` : url.pathname
+}
+
+export async function waitForRouteSettled(
+  page: Page,
+  {
+    timeoutMs = 15000,
+    pollMs = 50,
+    urlStableMs = 500,
+    domQuietMs = 300,
+    includeSearch = false,
+  }: {
+    timeoutMs?: number
+    pollMs?: number
+    urlStableMs?: number
+    domQuietMs?: number
+    includeSearch?: boolean
+  } = {},
+): 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 {
+    while (Date.now() < deadline) {
+      await sleep(pollMs)
+
+      const key = routeKey(page, includeSearch)
+      if (key !== lastKey) {
+        lastKey = key
+        stableSince = Date.now()
+        continue
+      }
+
+      const now = Date.now()
+      const urlStableLongEnough = now - stableSince >= urlStableMs
+      const noRecentNav = now - navBumpedAt >= urlStableMs
+      if (!urlStableLongEnough || !noRecentNav) {
+        continue
+      }
+
+      const domQuiet = await page
+        .evaluate(quietMs => {
+          return new Promise<boolean>(resolve => {
+            let lastMutation = Date.now()
+            const observer = new MutationObserver(() => {
+              lastMutation = Date.now()
+            })
+            observer.observe(document, { subtree: true, childList: true, attributes: true })
+
+            const tick = () => {
+              if (Date.now() - lastMutation >= quietMs) {
+                observer.disconnect()
+                resolve(true)
+                return
+              }
+              setTimeout(tick, 50)
+            }
+
+            tick()
+          })
+        }, domQuietMs)
+        .catch(() => false)
+
+      if (domQuiet) {
+        return lastKey
+      }
+    }
+
+    return routeKey(page, includeSearch)
+  } finally {
+    page.off('framenavigated', onFrameNav)
+  }
+}
+
+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}`)
+  }
+
+  return data
+}
+
+async function validateResolvedSelector(
+  page: Page,
+  selector: string,
+  {
+    timeoutMs = 1500,
+    requireVisible = true,
+    requireUnique = false,
+  }: {
+    timeoutMs?: number
+    requireVisible?: boolean
+    requireUnique?: boolean
+  } = {},
+): Promise<boolean> {
+  try {
+    const locator = page.locator(selector)
+    await locator.first().waitFor({ state: 'attached', timeout: timeoutMs })
+
+    if (requireVisible) {
+      await locator.first().waitFor({ state: 'visible', timeout: timeoutMs })
+    }
+
+    if (requireUnique) {
+      const count = await locator.count()
+      if (count !== 1) {
+        return false
+      }
+    }
+
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function resolveLocator(
+  page: Page,
+  locatorName: string,
+  {
+    maxResolvePasses = 2,
+    validate = {
+      timeoutMs: 1500,
+      requireVisible: true,
+      requireUnique: false,
+    },
+  }: {
+    maxResolvePasses?: number
+    validate?: {
+      timeoutMs?: number
+      requireVisible?: boolean
+      requireUnique?: boolean
+    }
+  } = {},
+): Promise<string | null> {
+  try {
+    for (let pass = 0; pass < maxResolvePasses; pass++) {
+      await waitForRouteSettled(page, {
+        timeoutMs: 15000,
+        urlStableMs: 500,
+        domQuietMs: 300,
+        pollMs: 50,
+        includeSearch: false,
+      })
+
+      const beforePath = new URL(page.url()).pathname
+      const locatorMapData = await retry(() => getLocatorMapData(page), {
+        retries: 6,
+        delayMs: 80,
+        backoff: 1.5,
+        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}`)
+      }
+
+      const selector = locators[locatorName]
+      if (!selector) {
+        throw new Error(`Locator "${locatorName}" not found for name ${locatorMapData.name}`)
+      }
+
+      const afterPath = new URL(page.url()).pathname
+      if (afterPath !== beforePath) {
+        continue
+      }
+
+      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`)
+  } catch (error) {
+    console.error(error)
+    return null
+  }
+}

package/templates/starter/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/starter/packages/cucumber-runtime/src/paths.ts

@@ -0,0 +1,98 @@
+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 getAutomationReportRunDir(runId: string): string {
+  return path.join(getAutomationReportsDir(), runId)
+}
+
+export function resolveProjectPath(targetPath: string): string {
+  return path.isAbsolute(targetPath) ? targetPath : path.join(process.cwd(), targetPath)
+}
+
+export function toProjectRelativePath(targetPath: string): string {
+  const normalizedPath = path.isAbsolute(targetPath) ? path.relative(process.cwd(), targetPath) : targetPath
+  return normalizedPath.replace(/\\/g, '/')
+}
+
+export function getAutomationReportRunDirFromReportPath(reportPath: string): string {
+  return path.dirname(resolveProjectPath(reportPath))
+}
+
+function extractReportPathFromFormat(reportFormat = process.env.REPORT_FORMAT): string | null {
+  if (!reportFormat?.startsWith('json:')) {
+    return null
+  }
+
+  const reportPath = reportFormat.slice('json:'.length).trim()
+  return reportPath.length > 0 ? reportPath : null
+}
+
+function getRuntimeReportRunDir(
+  reportPath = process.env.REPORT_PATH,
+  reportFormat = process.env.REPORT_FORMAT,
+  testRunId = process.env.TEST_RUN_ID,
+): string | null {
+  const resolvedReportPath = reportPath ?? extractReportPathFromFormat(reportFormat)
+  if (resolvedReportPath) {
+    return getAutomationReportRunDirFromReportPath(resolvedReportPath)
+  }
+
+  if (testRunId) {
+    return getAutomationReportRunDir(testRunId)
+  }
+
+  return null
+}
+
+export function getAutomationTraceDir(
+  reportPath = process.env.REPORT_PATH,
+  testRunId = process.env.TEST_RUN_ID,
+  reportFormat = process.env.REPORT_FORMAT,
+): string {
+  const runDir = getRuntimeReportRunDir(reportPath, reportFormat, testRunId)
+  if (runDir) {
+    return path.join(runDir, 'traces')
+  }
+
+  return path.join(getAutomationReportsDir(), 'traces')
+}
+
+export function getAutomationScreenshotDir(
+  reportPath = process.env.REPORT_PATH,
+  testRunId = process.env.TEST_RUN_ID,
+  reportFormat = process.env.REPORT_FORMAT,
+): string {
+  const runDir = getRuntimeReportRunDir(reportPath, reportFormat, testRunId)
+  if (runDir) {
+    return path.join(runDir, 'screenshots')
+  }
+
+  return path.join(getAutomationReportsDir(), 'screenshots')
+}

package/templates/starter/packages/cucumber-runtime/src/random-data.util.ts

@@ -0,0 +1,35 @@
+import { faker } from '@faker-js/faker'
+
+export enum RandomDataType {
+  FULL_NAME = 'fullName',
+  FIRST_NAME = 'firstName',
+  LAST_NAME = 'lastName',
+  EMAIL = 'email',
+  PASSWORD = 'password',
+  PHONE = 'phone',
+  ADDRESS = 'address',
+  UNIQUE_TEXT = 'uniqueText',
+}
+
+export function generateRandomData(randomDataType: RandomDataType): string {
+  switch (randomDataType) {
+    case RandomDataType.FULL_NAME:
+      return faker.person.fullName()
+    case RandomDataType.FIRST_NAME:
+      return faker.person.firstName()
+    case RandomDataType.LAST_NAME:
+      return faker.person.lastName()
+    case RandomDataType.EMAIL:
+      return faker.internet.email()
+    case RandomDataType.PASSWORD:
+      return faker.internet.password()
+    case RandomDataType.PHONE:
+      return faker.phone.number()
+    case RandomDataType.ADDRESS:
+      return faker.location.streetAddress()
+    case RandomDataType.UNIQUE_TEXT:
+      return faker.string.uuid()
+    default:
+      throw new Error(`Invalid random data type: ${randomDataType}`)
+  }
+}

package/templates/starter/packages/cucumber-runtime/src/types.ts

@@ -0,0 +1,13 @@
+export type BrowserName = 'chromium' | 'firefox' | 'webkit'
+
+export type CSSSelector = string
+export type XPathSelector = `/${string}` | `//${string}`
+export type SelectorName = string
+export type Selector = CSSSelector | XPathSelector
+export type Locator = Record<string, Selector>
+export type LocatorMap = {
+  name: string
+  path: string
+}
+
+export type LocatorCollection = Record<string, Locator>

package/templates/starter/packages/cucumber-runtime/src/world.ts

@@ -0,0 +1,44 @@
+import { World, IWorldOptions, setWorldConstructor, setDefaultTimeout } from '@cucumber/cucumber'
+import * as chai from 'chai'
+import chaiAsPromised from 'chai-as-promised'
+import { BrowserContext, Page } from 'playwright'
+
+setDefaultTimeout(120 * 1000)
+
+export interface ScenarioData {
+  token?: string
+  vars: Record<string, unknown>
+}
+
+export class CustomWorld extends World {
+  context!: BrowserContext
+  page!: Page
+  data: ScenarioData = {
+    vars: {},
+  }
+
+  constructor(options: IWorldOptions) {
+    super(options)
+  }
+
+  setVar(key: string, value: unknown): void {
+    this.data.vars[key] = value
+  }
+
+  getVar<T = unknown>(key: string): T {
+    if (!(key in this.data.vars)) {
+      throw new Error(`Variable ${key} not found`)
+    }
+
+    return this.data.vars[key] as T
+  }
+
+  clearVars(): void {
+    this.data.vars = {}
+  }
+}
+
+setWorldConstructor(CustomWorld)
+chai.use(chaiAsPromised)
+
+export const expect = chai.expect

package/templates/starter/packages/cucumber-runtime/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": false
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/starter/packages/locator-picker-companion/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};