create-appraisejs 0.3.1-alpha.0 → 0.4.0-alpha.0

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

@@ -4,6 +4,7 @@ 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 { buildAppraiseMetadata, getAppraiseMetadataPath } from '@/lib/appraise-test-case-metadata'
 import { generateProjectedGherkinSteps, getTestSuiteFilesystemKey } from '@/lib/sync/projected-feature-utils'
 
 async function isDirectoryEmpty(dirPath: string): Promise<boolean> {
@@ -32,6 +33,18 @@ async function removeEmptyDirectoriesUp(dirPath: string, basePath: string): Prom
   }
 }
 
+async function unlinkIfExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.unlink(filePath)
+    return true
+  } catch (error: unknown) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return false
+    }
+    throw error
+  }
+}
+
 export async function generateFeatureFile(
   testSuiteId: string,
   testSuiteName: string,
@@ -53,6 +66,14 @@ export async function generateFeatureFile(
                   order: 'asc',
                 },
               },
+              flowBlocks: {
+                include: {
+                  nodes: true,
+                },
+                orderBy: {
+                  order: 'asc',
+                },
+              },
               tags: true,
             },
           },
@@ -73,6 +94,15 @@ export async function generateFeatureFile(
       testSuite.testCases,
       testSuite.tags,
     )
+    const metadataContent = JSON.stringify(
+      buildAppraiseMetadata({
+        testSuiteName,
+        modulePath,
+        testCases: testSuite.testCases,
+      }),
+      null,
+      2,
+    )
 
     const featuresBaseDir = getAutomationFeaturesDir()
     const moduleDir = join(featuresBaseDir, modulePath.substring(1))
@@ -82,6 +112,7 @@ export async function generateFeatureFile(
     const featureFilePath = join(moduleDir, `${safeFileName}.feature`)
 
     await fs.writeFile(featureFilePath, featureContent, 'utf8')
+    await fs.writeFile(getAppraiseMetadataPath(featureFilePath), `${metadataContent}\n`, 'utf8')
     return featureFilePath
   } catch (error) {
     console.error('Error generating feature file:', error)
@@ -178,17 +209,12 @@ export async function deleteFeatureFile(testSuiteId: string): Promise<boolean> {
     const featuresBaseDir = getAutomationFeaturesDir()
     const moduleDir = join(featuresBaseDir, modulePath.substring(1))
     const featureFilePath = join(moduleDir, `${safeFileName}.feature`)
+    const metadataFilePath = getAppraiseMetadataPath(featureFilePath)
 
-    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
-    }
+    const deletedFeature = await unlinkIfExists(featureFilePath)
+    const deletedMetadata = await unlinkIfExists(metadataFilePath)
+    await removeEmptyDirectoriesUp(moduleDir, featuresBaseDir)
+    return deletedFeature || deletedMetadata
   } catch (error) {
     console.error('Error deleting feature file:', error)
     throw error
@@ -220,6 +246,14 @@ export async function regenerateAllFeatureFiles(): Promise<string[]> {
                 order: 'asc',
               },
             },
+            flowBlocks: {
+              include: {
+                nodes: true,
+              },
+              orderBy: {
+                order: 'asc',
+              },
+            },
             tags: true,
           },
         },
@@ -239,6 +273,15 @@ export async function regenerateAllFeatureFiles(): Promise<string[]> {
           testSuite.testCases,
           testSuite.tags,
         )
+        const metadataContent = JSON.stringify(
+          buildAppraiseMetadata({
+            testSuiteName: testSuite.name,
+            modulePath,
+            testCases: testSuite.testCases,
+          }),
+          null,
+          2,
+        )
 
         const moduleDir = join(featuresBaseDir, modulePath.substring(1))
         await fs.mkdir(moduleDir, { recursive: true })
@@ -247,6 +290,7 @@ export async function regenerateAllFeatureFiles(): Promise<string[]> {
         const featureFilePath = join(moduleDir, `${safeFileName}.feature`)
 
         await fs.writeFile(featureFilePath, featureContent, 'utf8')
+        await fs.writeFile(getAppraiseMetadataPath(featureFilePath), `${metadataContent}\n`, 'utf8')
         generatedFiles.push(featureFilePath)
       } catch (error) {
         console.error(`Error generating feature file for test suite ${testSuite.name}:`, error)

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

@@ -3,6 +3,7 @@ import { join } from 'path'
 import { tmpdir } from 'os'
 import { expect, test } from 'vitest'
 
+import { getAppraiseMetadataPath } from '@/lib/appraise-test-case-metadata'
 import { parseFeatureFile } from '@/lib/gherkin-parser'
 
 async function withTempFeatureFile(content: string): Promise<string> {
@@ -42,3 +43,54 @@ Scenario: buys item
   expect(parsed).not.toBeNull()
   expect(parsed?.featureDescription).toBe('Checkout flow')
 })
+
+test('attaches adjacent Appraise metadata to matching scenarios', async () => {
+  const filePath = await withTempFeatureFile(`
+Feature: Checkout flow
+
+@tc_checkout_buy @smoke
+Scenario: [Legacy description] Legacy title
+  Given user adds item to cart
+`)
+  await fs.writeFile(
+    getAppraiseMetadataPath(filePath),
+    JSON.stringify({
+      version: 1,
+      testSuite: { name: 'checkout-flow', modulePath: '/checkout' },
+      testCases: [
+        {
+          identifierTag: '@tc_checkout_buy',
+          title: 'Buys item',
+          description: 'Happy path',
+          nodes: [{ nodeId: 'node-cart', order: 1, label: 'Add item' }],
+          flowBlocks: [{ id: 'block-cart', name: 'Cart', order: 0, nodeIds: ['node-cart'] }],
+        },
+      ],
+    }),
+    'utf8',
+  )
+
+  const parsed = await parseFeatureFile(filePath)
+
+  expect(parsed?.scenarios[0]?.appraiseMetadata).toMatchObject({
+    title: 'Buys item',
+    description: 'Happy path',
+    nodes: [{ nodeId: 'node-cart', order: 1, label: 'Add item' }],
+  })
+})
+
+test('falls back to feature-only parsing when sidecar is malformed', async () => {
+  const filePath = await withTempFeatureFile(`
+Feature: Checkout flow
+
+@tc_checkout_buy
+Scenario: buys item
+  Given user adds item to cart
+`)
+  await fs.writeFile(getAppraiseMetadataPath(filePath), '{', 'utf8')
+
+  const parsed = await parseFeatureFile(filePath)
+
+  expect(parsed?.scenarios[0]?.appraiseMetadata).toBeUndefined()
+  expect(parsed?.metadataWarnings).toHaveLength(1)
+})

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

@@ -1,5 +1,11 @@
 import { promises as fs } from 'fs'
 import { join } from 'path'
+import {
+  getAppraiseMetadataPath,
+  getMetadataByIdentifier,
+  readAppraiseMetadataFile,
+  type AppraiseTestCaseMetadataEntry,
+} from '@/lib/appraise-test-case-metadata'
 import { getFeatureModulePath } from '@/lib/path-helpers/feature-path'
 
 /**
@@ -11,6 +17,7 @@ export interface ParsedFeature {
   featureDescription?: string
   tags: string[]
   scenarios: ParsedScenario[]
+  metadataWarnings: string[]
 }
 
 /**
@@ -21,6 +28,7 @@ export interface ParsedScenario {
   description?: string
   tags: string[]
   steps: ParsedStep[]
+  appraiseMetadata?: AppraiseTestCaseMetadataEntry
 }
 
 /**
@@ -30,6 +38,7 @@ export interface ParsedStep {
   keyword: string
   text: string
   order: number
+  appraiseNode?: AppraiseTestCaseMetadataEntry['nodes'][number]
 }
 
 const STEP_KEYWORDS = ['Given', 'When', 'Then', 'And', 'But'] as const
@@ -103,6 +112,23 @@ function parseFeatureLine(line: string) {
   return line.replace('Feature:', '').trim()
 }
 
+function normalizeTagExpression(tagExpression: string): string {
+  return tagExpression.startsWith('@') ? tagExpression : `@${tagExpression}`
+}
+
+function getScenarioIdentifierTag(scenario: ParsedScenario): string | null {
+  for (const tagLine of scenario.tags) {
+    const tags = tagLine.split(/\s+/).filter(tag => tag.trim().startsWith('@'))
+    const identifierTag = tags.find(tag => normalizeTagExpression(tag).replace(/^@/, '').startsWith('tc_'))
+
+    if (identifierTag) {
+      return normalizeTagExpression(identifierTag)
+    }
+  }
+
+  return null
+}
+
 function startScenario(lines: string[], index: number): ParsedScenario {
   const { name, description } = parseScenarioHeader(lines[index])
 
@@ -170,10 +196,21 @@ function parseGherkinLines(lines: string[]) {
  */
 export async function parseFeatureFile(filePath: string): Promise<ParsedFeature | null> {
   try {
-    const content = await fs.readFile(filePath, 'utf-8')
+    const [content, metadataResult] = await Promise.all([
+      fs.readFile(filePath, 'utf-8'),
+      readAppraiseMetadataFile(getAppraiseMetadataPath(filePath)),
+    ])
     const lines = normalizeGherkinLines(content)
     const featureTags = getFeatureTags(lines)
     const { featureName, featureDescription, scenarios } = parseGherkinLines(lines)
+    const metadataByIdentifier = getMetadataByIdentifier(metadataResult.metadata)
+
+    for (const scenario of scenarios) {
+      const identifierTag = getScenarioIdentifierTag(scenario)
+      if (identifierTag) {
+        scenario.appraiseMetadata = metadataByIdentifier.get(identifierTag)
+      }
+    }
 
     if (!featureName) {
       console.warn(`No feature found in file: ${filePath}`)
@@ -186,6 +223,7 @@ export async function parseFeatureFile(filePath: string): Promise<ParsedFeature
       featureDescription: featureDescription || undefined,
       tags: featureTags,
       scenarios,
+      metadataWarnings: metadataResult.warnings,
     }
   } catch (error) {
     console.error(`Error parsing feature file ${filePath}:`, error)

package/templates/starter/src/lib/locator-group-file-utils.ts

@@ -144,7 +144,11 @@ async function cleanupEmptyDirectories(filePath: string): Promise<void> {
   let currentDir = path.dirname(filePath)
   const locatorsRoot = getAutomationLocatorsDir()
 
-  while (currentDir.startsWith(locatorsRoot) && currentDir !== locatorsRoot && currentDir !== path.dirname(currentDir)) {
+  while (
+    currentDir.startsWith(locatorsRoot) &&
+    currentDir !== locatorsRoot &&
+    currentDir !== path.dirname(currentDir)
+  ) {
     try {
       const files = await fs.readdir(currentDir)
       if (files.length === 0) {

package/templates/starter/src/lib/locator-picker/session-manager.ts

@@ -143,8 +143,7 @@ async function cleanupLingeringCompanionSessions(currentSessionId?: string): Pro
     const isTerminal = isTerminalStatus(session.status)
     const shouldTerminate = Boolean(session.companionPid)
     const shouldCloseStaleSession = !session.companionPid && !isTerminal && ageMs > ACTIVE_SESSION_STALE_MS
-    const shouldPruneSessionFile =
-      (isTerminal && ageMs > TERMINAL_SESSION_RETENTION_MS) || shouldCloseStaleSession
+    const shouldPruneSessionFile = (isTerminal && ageMs > TERMINAL_SESSION_RETENTION_MS) || shouldCloseStaleSession
 
     if (shouldTerminate && session.companionPid) {
       await shutdownCompanionProcess(session.companionPid).catch(() => undefined)

package/templates/starter/src/lib/metrics/metric-calculator.test.ts

@@ -1,10 +1,26 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { TestRunTestCaseResult, TestRunTestCaseStatus } from '@prisma/client'
 
-const { mockTestRunTestCaseFindMany, mockTestRunTestCaseFindFirst, mockTestCaseMetricsUpsert } = vi.hoisted(() => ({
+const {
+  mockTestRunTestCaseFindMany,
+  mockTestRunTestCaseFindFirst,
+  mockTestCaseMetricsUpsert,
+  mockTestCaseCount,
+  mockTestSuiteCount,
+  mockTestRunCount,
+  mockDashboardMetricsFindFirst,
+  mockDashboardMetricsUpdate,
+  mockDashboardMetricsCreate,
+} = vi.hoisted(() => ({
   mockTestRunTestCaseFindMany: vi.fn(),
   mockTestRunTestCaseFindFirst: vi.fn(),
   mockTestCaseMetricsUpsert: vi.fn(),
+  mockTestCaseCount: vi.fn(),
+  mockTestSuiteCount: vi.fn(),
+  mockTestRunCount: vi.fn(),
+  mockDashboardMetricsFindFirst: vi.fn(),
+  mockDashboardMetricsUpdate: vi.fn(),
+  mockDashboardMetricsCreate: vi.fn(),
 }))
 
 vi.mock('@/config/db-config', () => ({
@@ -18,23 +34,29 @@ vi.mock('@/config/db-config', () => ({
       upsert: mockTestCaseMetricsUpsert,
       count: vi.fn(),
     },
+    testCase: {
+      count: mockTestCaseCount,
+    },
     testSuiteMetrics: {
       upsert: vi.fn(),
       count: vi.fn(),
     },
+    testSuite: {
+      count: mockTestSuiteCount,
+    },
     testRun: {
-      count: vi.fn(),
+      count: mockTestRunCount,
       findUnique: vi.fn(),
     },
     dashboardMetrics: {
-      findFirst: vi.fn(),
-      update: vi.fn(),
-      create: vi.fn(),
+      findFirst: mockDashboardMetricsFindFirst,
+      update: mockDashboardMetricsUpdate,
+      create: mockDashboardMetricsCreate,
     },
   },
 }))
 
-import { recalculateTestCaseMetrics } from './metric-calculator'
+import { recalculateTestCaseMetrics, updateDashboardMetrics } from './metric-calculator'
 
 function completedCase(result: TestRunTestCaseResult, completedAt: Date) {
   return {
@@ -154,3 +176,80 @@ describe('recalculateTestCaseMetrics', () => {
     })
   })
 })
+
+describe('updateDashboardMetrics', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-05-12T00:00:00.000Z'))
+    vi.clearAllMocks()
+    mockTestRunCount.mockResolvedValue(4)
+    mockTestCaseCount.mockResolvedValueOnce(2).mockResolvedValueOnce(1)
+    mockTestSuiteCount.mockResolvedValue(3)
+    mockDashboardMetricsFindFirst.mockResolvedValue({ id: 'dashboard-metrics-1' })
+    mockDashboardMetricsUpdate.mockResolvedValue({})
+    mockDashboardMetricsCreate.mockResolvedValue({})
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('counts attention metrics from live entities instead of orphaned metric rows', async () => {
+    await updateDashboardMetrics()
+
+    expect(mockTestCaseCount).toHaveBeenNthCalledWith(1, {
+      where: {
+        metrics: {
+          is: {
+            isRepeatedlyFailing: true,
+          },
+        },
+      },
+    })
+    expect(mockTestCaseCount).toHaveBeenNthCalledWith(2, {
+      where: {
+        metrics: {
+          is: {
+            isFlaky: true,
+          },
+        },
+      },
+    })
+    expect(mockTestSuiteCount).toHaveBeenCalledWith({
+      where: {
+        OR: [
+          {
+            metrics: {
+              is: null,
+            },
+          },
+          {
+            metrics: {
+              is: {
+                lastExecutedAt: null,
+              },
+            },
+          },
+          {
+            metrics: {
+              is: {
+                lastExecutedAt: {
+                  lt: new Date('2026-05-05T00:00:00.000Z'),
+                },
+              },
+            },
+          },
+        ],
+      },
+    })
+    expect(mockDashboardMetricsUpdate).toHaveBeenCalledWith({
+      where: { id: 'dashboard-metrics-1' },
+      data: expect.objectContaining({
+        failedRecentRunsCount: 4,
+        repeatedlyFailingTestsCount: 2,
+        flakyTestsCount: 1,
+        suitesNotExecutedRecentlyCount: 3,
+      }),
+    })
+  })
+})

package/templates/starter/src/lib/metrics/metric-calculator.ts

@@ -57,9 +57,7 @@ function getRecentPeriodDate(): Date {
 
 function summarizeRecentTestCaseRuns(recentTestRunTestCases: CompletedTestRunTestCase[]): TestCaseMetricSummary {
   const totalRecentRuns = recentTestRunTestCases.length
-  const failedRecentRuns = recentTestRunTestCases.filter(
-    trtc => trtc.result === TestRunTestCaseResult.FAILED,
-  ).length
+  const failedRecentRuns = recentTestRunTestCases.filter(trtc => trtc.result === TestRunTestCaseResult.FAILED).length
   const failureRate = totalRecentRuns > 0 ? failedRecentRuns / totalRecentRuns : 0
   const consecutiveFailures = countConsecutiveFailures(recentTestRunTestCases)
 
@@ -138,14 +136,8 @@ export async function updateTestCaseMetrics(
 
     const recentTestRunTestCases = await findRecentCompletedTestRunTestCases(testCaseId, recentPeriodDate)
 
-    const {
-      totalRecentRuns,
-      failedRecentRuns,
-      failureRate,
-      isFlaky,
-      consecutiveFailures,
-      isRepeatedlyFailing,
-    } = summarizeRecentTestCaseRuns(recentTestRunTestCases)
+    const { totalRecentRuns, failedRecentRuns, failureRate, isFlaky, consecutiveFailures, isRepeatedlyFailing } =
+      summarizeRecentTestCaseRuns(recentTestRunTestCases)
 
     // Determine which date fields to update
     const updateData: {
@@ -194,10 +186,7 @@ export async function updateTestCaseMetrics(
  * @param testSuiteId - The test suite ID
  * @param executedAt - When the test suite was executed
  */
-export async function updateTestSuiteMetrics(
-  testSuiteId: string,
-  executedAt: Date,
-): Promise<void> {
+export async function updateTestSuiteMetrics(testSuiteId: string, executedAt: Date): Promise<void> {
   try {
     await prisma.testSuiteMetrics.upsert({
       where: { testSuiteId },
@@ -220,10 +209,7 @@ export async function updateTestSuiteMetrics(
  * @param testRunId - The test run ID
  * @param executedAt - When the test run was executed
  */
-async function updateTestSuitesForTestRun(
-  testRunId: string,
-  executedAt: Date,
-): Promise<void> {
+async function updateTestSuitesForTestRun(testRunId: string, executedAt: Date): Promise<void> {
   try {
     // Get all test cases in the test run
     const testRunTestCases = await prisma.testRunTestCase.findMany({
@@ -290,31 +276,52 @@ export async function updateDashboardMetrics(): Promise<void> {
       },
     })
 
-    // Count repeatedly failing tests
-    const repeatedlyFailingTestsCount = await prisma.testCaseMetrics.count({
+    // Count repeatedly failing live tests
+    const repeatedlyFailingTestsCount = await prisma.testCase.count({
       where: {
-        isRepeatedlyFailing: true,
+        metrics: {
+          is: {
+            isRepeatedlyFailing: true,
+          },
+        },
       },
     })
 
-    // Count flaky tests
-    const flakyTestsCount = await prisma.testCaseMetrics.count({
+    // Count flaky live tests
+    const flakyTestsCount = await prisma.testCase.count({
       where: {
-        isFlaky: true,
+        metrics: {
+          is: {
+            isFlaky: true,
+          },
+        },
       },
     })
 
-    // Count suites not executed recently
-    const suitesNotExecutedRecentlyCount = await prisma.testSuiteMetrics.count({
+    // Count live suites with no execution metrics or stale execution metrics
+    const suitesNotExecutedRecentlyCount = await prisma.testSuite.count({
       where: {
         OR: [
           {
-            lastExecutedAt: {
-              lt: recentPeriodDate,
+            metrics: {
+              is: null,
             },
           },
           {
-            lastExecutedAt: null,
+            metrics: {
+              is: {
+                lastExecutedAt: null,
+              },
+            },
+          },
+          {
+            metrics: {
+              is: {
+                lastExecutedAt: {
+                  lt: recentPeriodDate,
+                },
+              },
+            },
           },
         ],
       },
@@ -364,11 +371,7 @@ export async function recalculateTestCaseMetrics(testCaseId: string): Promise<vo
     const recentTestRunTestCases = await findRecentCompletedTestRunTestCases(testCaseId, recentPeriodDate)
 
     const metricSummary = summarizeRecentTestCaseRuns(recentTestRunTestCases)
-    const recalculatedDates = await resolveRecalculatedMetricDates(
-      testCaseId,
-      recentPeriodDate,
-      recentTestRunTestCases,
-    )
+    const recalculatedDates = await resolveRecalculatedMetricDates(testCaseId, recentPeriodDate, recentTestRunTestCases)
     const updateData = buildRecalculatedMetricUpdateData(metricSummary, recalculatedDates)
 
     // Upsert the metrics
@@ -572,11 +575,7 @@ export async function updateMetricsForTestRun(testRunId: string): Promise<void>
     // Update metrics for all test cases in the run
     for (const testRunTestCase of testRun.testCases) {
       if (testRunTestCase.status === TestRunTestCaseStatus.COMPLETED) {
-        await updateTestCaseMetrics(
-          testRunTestCase.testCaseId,
-          testRunTestCase.result,
-          executedAt,
-        )
+        await updateTestCaseMetrics(testRunTestCase.testCaseId, testRunTestCase.result, executedAt)
       }
     }
 

package/templates/starter/src/lib/sync/projected-feature-utils.ts

@@ -7,6 +7,8 @@ type StoredProjectedStep = {
 }
 
 type StoredProjectedDbStep = StoredProjectedStep & {
+  flowNodeId: string | null
+  label: string
   TemplateStep: { signature: string } | null
   parameters: Array<{ name: string; value: string; order: number; type: StepParameterType }>
 }
@@ -16,6 +18,7 @@ export type ProjectedDbTestCaseStep = {
   keyword: string
   text: string
   gherkinStep: string
+  flowNodeId: string | null
   label: string
   icon: TemplateStepIcon
   templateStepSignature: string | null
@@ -64,7 +67,8 @@ export function normalizeProjectedDbTestCaseSteps(steps: StoredProjectedDbStep[]
       keyword,
       text,
       gherkinStep,
-      label: text,
+      flowNodeId: step.flowNodeId,
+      label: step.label,
       icon: determineProjectedStepIcon(keyword),
       templateStepSignature: step.TemplateStep?.signature ?? null,
       parameters: step.parameters,

package/templates/starter/src/lib/sync/sync-executor.ts

@@ -64,10 +64,7 @@ function parseSyncFailureCause(result: ScriptExecutionOutput | { error: unknown
     return result.error instanceof Error ? result.error.message : String(result.error)
   }
 
-  return selectMostRelevantLine([
-    ...normalizeOutputLines(result.stderr),
-    ...normalizeOutputLines(result.stdout),
-  ])
+  return selectMostRelevantLine([...normalizeOutputLines(result.stderr), ...normalizeOutputLines(result.stdout)])
 }
 
 async function executeSyncScript(scriptId: SyncScriptId): Promise<ScriptExecutionOutput> {