create-appraisejs 0.3.0-alpha.0 → 0.3.0

package/templates/starter/src/lib/executor/local-executor-adapter.ts

@@ -0,0 +1,97 @@
+import { dirname } from 'path'
+import { spawnTask, taskSpawner, type SpawnedProcess, waitForTask, killTask } from '@/lib/process/task-spawner'
+import { getAutomationRunReportPath, toProjectRelativePath } from '@/lib/automation/automation-path-roots'
+import { ensureAutomationWorkspaceReady } from '@/lib/automation/automation-workspace'
+import type { ExecutorAdapter, TestRunExecutionRequest, TestRunExecutionResult } from './types'
+import { processManager } from '@/lib/test-run/process-manager'
+import { promises as fs } from 'fs'
+
+function mapBrowserEngineToName(
+  browserEngine: TestRunExecutionRequest['browserEngine'],
+): 'chromium' | 'firefox' | 'webkit' {
+  switch (browserEngine) {
+    case 'CHROMIUM':
+      return 'chromium'
+    case 'FIREFOX':
+      return 'firefox'
+    case 'WEBKIT':
+      return 'webkit'
+    default:
+      return 'chromium'
+  }
+}
+
+function generateReportPath(testRunId: string): string {
+  return getAutomationRunReportPath(testRunId)
+}
+
+export class LocalExecutorAdapter implements ExecutorAdapter {
+  async executeTestRun(config: TestRunExecutionRequest): Promise<TestRunExecutionResult> {
+    await ensureAutomationWorkspaceReady()
+
+    const { testRunId, environment, tagExpression, testWorkersCount, browserEngine, headless = true } = config
+    const reportPath = generateReportPath(testRunId)
+    const browserName = mapBrowserEngineToName(browserEngine)
+    await fs.mkdir(dirname(reportPath), { recursive: true })
+    const childEnv = {
+      ...process.env,
+      ENVIRONMENT: environment.name,
+      HEADLESS: headless.toString(),
+      BROWSER: browserName,
+      REPORT_PATH: reportPath,
+      REPORT_FORMAT: `json:${reportPath}`,
+      TEST_RUN_ID: testRunId,
+    }
+
+    const cucumberArgs: string[] = ['cucumber-js']
+
+    if (tagExpression) {
+      cucumberArgs.push('-t', tagExpression)
+    }
+
+    if (testWorkersCount > 1) {
+      cucumberArgs.push('--parallel', testWorkersCount.toString())
+    }
+
+    const spawnedProcess = await spawnTask('npx', cucumberArgs, {
+      streamLogs: true,
+      prefixLogs: true,
+      logPrefix: `test-run-${testRunId}`,
+      captureOutput: true,
+      env: childEnv,
+    })
+
+    processManager.register(testRunId, spawnedProcess)
+    spawnedProcess.process.on('exit', () => {
+      processManager.unregister(testRunId)
+    })
+
+    return {
+      process: spawnedProcess,
+      reportPath: toProjectRelativePath(reportPath),
+    }
+  }
+
+  waitForProcess(processName: string): Promise<number | null> {
+    return waitForTask(processName)
+  }
+
+  killProcess(processName: string, signal?: NodeJS.Signals): boolean {
+    return killTask(processName, signal)
+  }
+
+  getProcess(processName: string): SpawnedProcess | undefined {
+    return taskSpawner.getProcess(processName)
+  }
+
+  spawnTraceViewer(testCaseId: string, tracePath: string): Promise<SpawnedProcess> {
+    return taskSpawner.spawn('npx', ['playwright', 'show-trace', tracePath], {
+      streamLogs: true,
+      prefixLogs: true,
+      logPrefix: `trace-viewer-${testCaseId}`,
+      captureOutput: false,
+    })
+  }
+}
+
+export const localExecutorAdapter = new LocalExecutorAdapter()

package/templates/starter/src/lib/executor/types.ts

@@ -0,0 +1,24 @@
+import type { BrowserEngine, Environment } from '@prisma/client'
+import type { SpawnedProcess } from '@/lib/process/task-spawner'
+
+export interface TestRunExecutionRequest {
+  testRunId: string
+  environment: Environment
+  tagExpression: string | null
+  testWorkersCount: number
+  browserEngine: BrowserEngine
+  headless?: boolean
+}
+
+export interface TestRunExecutionResult {
+  process: SpawnedProcess
+  reportPath: string
+}
+
+export interface ExecutorAdapter {
+  executeTestRun(config: TestRunExecutionRequest): Promise<TestRunExecutionResult>
+  waitForProcess(processName: string): Promise<number | null>
+  killProcess(processName: string, signal?: NodeJS.Signals): boolean
+  getProcess(processName: string): SpawnedProcess | undefined
+  spawnTraceViewer(testCaseId: string, tracePath: string): Promise<SpawnedProcess>
+}

package/templates/starter/src/lib/feature-file-generator.ts

@@ -0,0 +1,261 @@
+import { promises as fs } from 'fs'
+import { join, dirname } from 'path'
+import prisma from '@/config/db-config'
+import { buildModulePath } from '@/lib/path-helpers/module-path'
+import { getAutomationFeaturesDir } from '@/lib/automation/automation-path-roots'
+import { ensureAutomationWorkspaceReady } from '@/lib/automation/automation-workspace'
+import { generateProjectedGherkinSteps, getTestSuiteFilesystemKey } from '@/lib/sync/projected-feature-utils'
+
+async function isDirectoryEmpty(dirPath: string): Promise<boolean> {
+  try {
+    const entries = await fs.readdir(dirPath)
+    return entries.length === 0
+  } catch {
+    return true
+  }
+}
+
+async function removeEmptyDirectoriesUp(dirPath: string, basePath: string): Promise<void> {
+  let currentPath = dirPath
+
+  while (currentPath !== basePath && currentPath !== dirname(currentPath)) {
+    try {
+      if (await isDirectoryEmpty(currentPath)) {
+        await fs.rmdir(currentPath)
+        currentPath = dirname(currentPath)
+      } else {
+        break
+      }
+    } catch {
+      break
+    }
+  }
+}
+
+export async function generateFeatureFile(
+  testSuiteId: string,
+  testSuiteName: string,
+  testSuiteDescription?: string,
+): Promise<string> {
+  try {
+    await ensureAutomationWorkspaceReady()
+    const [testSuite, allModules] = await Promise.all([
+      prisma.testSuite.findUnique({
+        where: { id: testSuiteId },
+        include: {
+          testCases: {
+            include: {
+              steps: {
+                include: {
+                  parameters: true,
+                },
+                orderBy: {
+                  order: 'asc',
+                },
+              },
+              tags: true,
+            },
+          },
+          module: true,
+          tags: true,
+        },
+      }),
+      prisma.module.findMany(),
+    ])
+
+    if (!testSuite) {
+      throw new Error(`Test suite with ID ${testSuiteId} not found`)
+    }
+
+    const modulePath = buildModulePath(allModules, testSuite.module)
+    const featureContent = generateFeatureContent(
+      testSuiteDescription || testSuiteName,
+      testSuite.testCases,
+      testSuite.tags,
+    )
+
+    const featuresBaseDir = getAutomationFeaturesDir()
+    const moduleDir = join(featuresBaseDir, modulePath.substring(1))
+    await fs.mkdir(moduleDir, { recursive: true })
+
+    const safeFileName = getTestSuiteFilesystemKey(testSuiteName)
+    const featureFilePath = join(moduleDir, `${safeFileName}.feature`)
+
+    await fs.writeFile(featureFilePath, featureContent, 'utf8')
+    return featureFilePath
+  } catch (error) {
+    console.error('Error generating feature file:', error)
+    throw error
+  }
+}
+
+function generateFeatureContent(
+  featureTitle: string,
+  testCases: Array<{
+    title: string
+    description: string
+    steps: Array<{
+      gherkinStep: string
+      order: number
+    }>
+    tags?: Array<{
+      tagExpression: string
+    }>
+  }>,
+  testSuiteTags?: Array<{
+    tagExpression: string
+  }>,
+): string {
+  const lines: string[] = []
+
+  lines.push('# AUTO-GENERATED FILE - DO NOT EDIT MANUALLY')
+  lines.push('# This file is automatically generated from Test Suite data.')
+  lines.push('# Any manual changes will be overwritten when the Test Suite is updated.')
+  lines.push('# To modify this feature, update the corresponding Test Suite in the application.')
+  lines.push('')
+
+  if (testSuiteTags && testSuiteTags.length > 0) {
+    testSuiteTags.forEach(tag => {
+      lines.push(tag.tagExpression)
+    })
+  }
+
+  lines.push(`Feature: ${featureTitle}`)
+  lines.push('')
+
+  const testSuiteTagExpressions = new Set((testSuiteTags || []).map(tag => tag.tagExpression.toLowerCase()))
+  let scenarioCount = 0
+
+  testCases.forEach(testCase => {
+    if (testCase.steps && testCase.steps.length > 0) {
+      const gherkinSteps = generateProjectedGherkinSteps(testCase.steps)
+
+      if (gherkinSteps.length > 0) {
+        if (scenarioCount > 0) {
+          lines.push('')
+        }
+
+        if (testCase.tags && testCase.tags.length > 0) {
+          testCase.tags.forEach(tag => {
+            if (!testSuiteTagExpressions.has(tag.tagExpression.toLowerCase())) {
+              lines.push(`  ${tag.tagExpression}`)
+            }
+          })
+        }
+
+        lines.push(`  Scenario: [${testCase.title}] ${testCase.description}`)
+        gherkinSteps.forEach(step => {
+          lines.push(`    ${step}`)
+        })
+        scenarioCount++
+      }
+    }
+  })
+
+  return lines.join('\n') + '\n'
+}
+
+export async function deleteFeatureFile(testSuiteId: string): Promise<boolean> {
+  try {
+    await ensureAutomationWorkspaceReady()
+    const [testSuite, allModules] = await Promise.all([
+      prisma.testSuite.findUnique({
+        where: { id: testSuiteId },
+        include: {
+          module: true,
+        },
+      }),
+      prisma.module.findMany(),
+    ])
+
+    if (!testSuite) {
+      return false
+    }
+
+    const modulePath = buildModulePath(allModules, testSuite.module)
+    const safeFileName = getTestSuiteFilesystemKey(testSuite.name)
+
+    const featuresBaseDir = getAutomationFeaturesDir()
+    const moduleDir = join(featuresBaseDir, modulePath.substring(1))
+    const featureFilePath = join(moduleDir, `${safeFileName}.feature`)
+
+    try {
+      await fs.unlink(featureFilePath)
+      await removeEmptyDirectoriesUp(moduleDir, featuresBaseDir)
+      return true
+    } catch (error: unknown) {
+      if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+        return false
+      }
+      throw error
+    }
+  } catch (error) {
+    console.error('Error deleting feature file:', error)
+    throw error
+  }
+}
+
+export async function regenerateAllFeatureFiles(): Promise<string[]> {
+  try {
+    await ensureAutomationWorkspaceReady()
+    const featuresBaseDir = getAutomationFeaturesDir()
+
+    try {
+      await fs.rm(featuresBaseDir, { recursive: true, force: true })
+    } catch (error) {
+      console.warn('Could not clear features directory:', error)
+    }
+
+    await fs.mkdir(featuresBaseDir, { recursive: true })
+
+    const testSuites = await prisma.testSuite.findMany({
+      include: {
+        testCases: {
+          include: {
+            steps: {
+              include: {
+                parameters: true,
+              },
+              orderBy: {
+                order: 'asc',
+              },
+            },
+            tags: true,
+          },
+        },
+        module: true,
+        tags: true,
+      },
+    })
+
+    const allModules = await prisma.module.findMany()
+    const generatedFiles: string[] = []
+
+    for (const testSuite of testSuites) {
+      try {
+        const modulePath = buildModulePath(allModules, testSuite.module)
+        const featureContent = generateFeatureContent(
+          testSuite.description || testSuite.name,
+          testSuite.testCases,
+          testSuite.tags,
+        )
+
+        const moduleDir = join(featuresBaseDir, modulePath.substring(1))
+        await fs.mkdir(moduleDir, { recursive: true })
+
+        const safeFileName = getTestSuiteFilesystemKey(testSuite.name)
+        const featureFilePath = join(moduleDir, `${safeFileName}.feature`)
+
+        await fs.writeFile(featureFilePath, featureContent, 'utf8')
+        generatedFiles.push(featureFilePath)
+      } catch (error) {
+        console.error(`Error generating feature file for test suite ${testSuite.name}:`, error)
+      }
+    }
+
+    return generatedFiles
+  } catch (error) {
+    console.error('Error during feature files regeneration:', error)
+    throw error
+  }
+}

package/templates/starter/src/lib/gherkin-parser.test.ts

@@ -0,0 +1,44 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { promises as fs } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { parseFeatureFile } from '@/lib/gherkin-parser'
+
+async function withTempFeatureFile(content: string): Promise<string> {
+  const dir = await fs.mkdtemp(join(tmpdir(), 'gherkin-parser-'))
+  const filePath = join(dir, 'sample.feature')
+  await fs.writeFile(filePath, content, 'utf8')
+  return filePath
+}
+
+test('uses Feature line text as feature description', async () => {
+  const filePath = await withTempFeatureFile(`
+@smoke
+Feature: Login workflow
+
+Scenario: logs in
+  Given user opens app
+`)
+
+  const parsed = await parseFeatureFile(filePath)
+
+  assert.ok(parsed)
+  assert.equal(parsed?.featureName, 'Login workflow')
+  assert.equal(parsed?.featureDescription, 'Login workflow')
+})
+
+test('keeps Feature line as description even when free text follows', async () => {
+  const filePath = await withTempFeatureFile(`
+Feature: Checkout flow
+Legacy block text that should not override the description
+
+Scenario: buys item
+  Given user adds item to cart
+`)
+
+  const parsed = await parseFeatureFile(filePath)
+
+  assert.ok(parsed)
+  assert.equal(parsed?.featureDescription, 'Checkout flow')
+})

package/templates/starter/src/lib/gherkin-parser.ts

@@ -0,0 +1,251 @@
+import { promises as fs } from 'fs'
+import { join, relative } from 'path'
+
+/**
+ * Represents a parsed feature file with its scenarios and steps
+ */
+export interface ParsedFeature {
+  filePath: string
+  featureName: string
+  featureDescription?: string
+  tags: string[]
+  scenarios: ParsedScenario[]
+}
+
+/**
+ * Represents a parsed scenario from a feature file
+ */
+export interface ParsedScenario {
+  name: string
+  description?: string
+  tags: string[]
+  steps: ParsedStep[]
+}
+
+/**
+ * Represents a parsed step from a feature file
+ */
+export interface ParsedStep {
+  keyword: string
+  text: string
+  order: number
+}
+
+/**
+ * Parses a Gherkin feature file and extracts scenarios and steps
+ * @param filePath - Path to the feature file
+ * @returns Promise<ParsedFeature | null> - Parsed feature data or null if parsing fails
+ */
+export async function parseFeatureFile(filePath: string): Promise<ParsedFeature | null> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+
+    // Simple Gherkin parser implementation
+    const lines = content.split('\n').map(line => line.trim())
+    const scenarios: ParsedScenario[] = []
+
+    let featureName = ''
+    let featureDescription = ''
+    const featureTags: string[] = []
+    let currentScenario: ParsedScenario | null = null
+    let stepOrder = 1
+
+    // Find feature line and extract tags before it
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].startsWith('Feature:')) {
+        // Look backwards for tags (skip comments and empty lines)
+        for (let j = i - 1; j >= 0; j--) {
+          const prevLine = lines[j]
+          if (prevLine === '' || prevLine.startsWith('#')) {
+            continue
+          }
+          if (prevLine.startsWith('@')) {
+            featureTags.unshift(prevLine) // Add to beginning to maintain order
+          } else {
+            break // Stop when we hit a non-tag line
+          }
+        }
+        break
+      }
+    }
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+
+      // Skip comments and empty lines
+      if (line.startsWith('#') || line === '') {
+        continue
+      }
+
+      // Parse Feature line
+      if (line.startsWith('Feature:')) {
+        const featureLineText = line.replace('Feature:', '').trim()
+        featureName = featureLineText
+        featureDescription = featureLineText
+        continue
+      }
+
+      // Parse Scenario line
+      if (line.startsWith('Scenario:')) {
+        // Save previous scenario if exists
+        if (currentScenario) {
+          scenarios.push(currentScenario)
+        }
+
+        // Extract tags before this scenario
+        const scenarioTags: string[] = []
+        for (let j = i - 1; j >= 0; j--) {
+          const prevLine = lines[j]
+          if (prevLine === '' || prevLine.startsWith('#')) {
+            continue
+          }
+          if (prevLine.startsWith('@')) {
+            scenarioTags.unshift(prevLine) // Add to beginning to maintain order
+          } else {
+            break // Stop when we hit a non-tag line
+          }
+        }
+
+        const scenarioText = line.replace('Scenario:', '').trim()
+        const [name, description] =
+          scenarioText.split(']').length > 1
+            ? [scenarioText.split(']')[1].trim(), scenarioText.split(']')[0].replace('[', '').trim()]
+            : [scenarioText, '']
+
+        currentScenario = {
+          name: name,
+          description: description || undefined,
+          tags: scenarioTags,
+          steps: [],
+        }
+        stepOrder = 1
+        continue
+      }
+
+      // Parse steps (Given, When, Then, And, But)
+      if (
+        currentScenario &&
+        (line.startsWith('Given ') ||
+          line.startsWith('When ') ||
+          line.startsWith('Then ') ||
+          line.startsWith('And ') ||
+          line.startsWith('But '))
+      ) {
+        const keyword = line.split(' ')[0]
+        const text = line.substring(keyword.length).trim()
+
+        currentScenario.steps.push({
+          keyword: keyword,
+          text: text,
+          order: stepOrder++,
+        })
+      }
+    }
+
+    // Add the last scenario
+    if (currentScenario) {
+      scenarios.push(currentScenario)
+    }
+
+    if (!featureName) {
+      console.warn(`No feature found in file: ${filePath}`)
+      return null
+    }
+
+    return {
+      filePath,
+      featureName,
+      featureDescription: featureDescription || undefined,
+      tags: featureTags,
+      scenarios,
+    }
+  } catch (error) {
+    console.error(`Error parsing feature file ${filePath}:`, error)
+    return null
+  }
+}
+
+/**
+ * Scans a directory for feature files and parses them
+ * @param directoryPath - Path to scan for feature files
+ * @returns Promise<ParsedFeature[]> - Array of parsed feature files
+ */
+export async function scanFeatureFiles(directoryPath: string): Promise<ParsedFeature[]> {
+  const parsedFeatures: ParsedFeature[] = []
+
+  try {
+    const entries = await fs.readdir(directoryPath, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = join(directoryPath, entry.name)
+
+      if (entry.isDirectory()) {
+        // Recursively scan subdirectories
+        const subFeatures = await scanFeatureFiles(fullPath)
+        parsedFeatures.push(...subFeatures)
+      } else if (entry.isFile() && entry.name.endsWith('.feature')) {
+        // Parse feature file
+        const parsedFeature = await parseFeatureFile(fullPath)
+        if (parsedFeature) {
+          parsedFeatures.push(parsedFeature)
+        }
+      }
+    }
+  } catch (error) {
+    console.error(`Error scanning directory ${directoryPath}:`, error)
+  }
+
+  return parsedFeatures
+}
+
+/**
+ * Extracts module path from feature file path
+ * Works cross-platform (Windows, Mac, Linux)
+ * @param featureFilePath - Full path to the feature file
+ * @param featuresBaseDir - Base directory for features
+ * @returns string - Module path (e.g., "/module1/submodule")
+ */
+export function extractModulePathFromFilePath(featureFilePath: string, featuresBaseDir: string): string {
+  // Use path.relative for cross-platform path handling
+  const relativePath = relative(featuresBaseDir, featureFilePath)
+
+  // Normalize to forward slashes for module path format (database uses /)
+  const normalizedPath = relativePath.replace(/\\/g, '/')
+  const pathParts = normalizedPath.split('/').filter(part => part && part !== '')
+
+  // Remove the filename and join the remaining parts
+  const moduleParts = pathParts.slice(0, -1)
+  return moduleParts.length > 0 ? '/' + moduleParts.join('/') : '/'
+}
+
+/**
+ * Generates a safe test suite name from feature name
+ * @param featureName - Name of the feature
+ * @returns string - Safe test suite name
+ */
+export function generateSafeTestSuiteName(featureName: string): string {
+  return featureName
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]+/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/**
+ * Generates a safe test case name from scenario name
+ * @param scenarioName - Name of the scenario
+ * @returns string - Safe test case name
+ */
+export function generateSafeTestCaseName(scenarioName: string): string {
+  // Remove scenario prefix if present and clean up the name
+  const cleanName = scenarioName
+    .replace(/^Scenario:\s*/i, '')
+    .replace(/^\[.*?\]\s*/, '') // Remove [brackets] prefix
+    .trim()
+
+  return cleanName
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]+/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}