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

package/templates/starter/src/lib/appraise-test-case-metadata.test.ts

@@ -0,0 +1,78 @@
+import { promises as fs } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { expect, test } from 'vitest'
+
+import {
+  buildAppraiseMetadata,
+  getAppraiseMetadataPath,
+  readAppraiseMetadataFile,
+} from '@/lib/appraise-test-case-metadata'
+
+test('serializes title, stable nodes, and flow blocks by identifier tag', () => {
+  const metadata = buildAppraiseMetadata({
+    testSuiteName: 'Checkout suite',
+    modulePath: '/commerce/checkout',
+    testCases: [
+      {
+        title: 'Buys item',
+        description: 'Happy path',
+        tags: [{ tagExpression: '@tc_checkout_buy' }, { tagExpression: '@smoke' }],
+        steps: [
+          { flowNodeId: 'node-open', order: 1, label: 'Open checkout' },
+          { flowNodeId: 'node-pay', order: 2, label: 'Pay with card' },
+        ],
+        flowBlocks: [
+          {
+            id: 'block-payment',
+            name: 'Payment',
+            order: 0,
+            nodes: [{ flowNodeId: 'node-pay' }, { flowNodeId: 'missing-node' }],
+          },
+        ],
+      },
+    ],
+  })
+
+  expect(metadata).toEqual({
+    version: 1,
+    testSuite: {
+      name: 'Checkout suite',
+      modulePath: '/commerce/checkout',
+    },
+    testCases: [
+      {
+        identifierTag: '@tc_checkout_buy',
+        title: 'Buys item',
+        description: 'Happy path',
+        nodes: [
+          { nodeId: 'node-open', order: 1, label: 'Open checkout' },
+          { nodeId: 'node-pay', order: 2, label: 'Pay with card' },
+        ],
+        flowBlocks: [
+          {
+            id: 'block-payment',
+            name: 'Payment',
+            order: 0,
+            nodeIds: ['node-pay'],
+          },
+        ],
+      },
+    ],
+  })
+})
+
+test('reads missing and malformed sidecars without throwing', async () => {
+  const dir = await fs.mkdtemp(join(tmpdir(), 'appraise-metadata-'))
+  const featurePath = join(dir, 'sample.feature')
+  const metadataPath = getAppraiseMetadataPath(featurePath)
+
+  await expect(readAppraiseMetadataFile(metadataPath)).resolves.toEqual({ metadata: null, warnings: [] })
+
+  await fs.writeFile(metadataPath, '{', 'utf8')
+
+  const result = await readAppraiseMetadataFile(metadataPath)
+
+  expect(result.metadata).toBeNull()
+  expect(result.warnings).toHaveLength(1)
+})

package/templates/starter/src/lib/appraise-test-case-metadata.ts

@@ -0,0 +1,220 @@
+import { promises as fs } from 'fs'
+
+export const APPRAISE_METADATA_VERSION = 1
+export const APPRAISE_METADATA_EXTENSION = '.appraise.json'
+
+export type AppraiseTestCaseMetadataNode = {
+  nodeId: string
+  order: number
+  label: string
+}
+
+export type AppraiseTestCaseMetadataFlowBlock = {
+  id: string
+  name: string
+  order: number
+  nodeIds: string[]
+}
+
+export type AppraiseTestCaseMetadataEntry = {
+  identifierTag: string
+  title: string
+  description: string
+  nodes: AppraiseTestCaseMetadataNode[]
+  flowBlocks: AppraiseTestCaseMetadataFlowBlock[]
+}
+
+export type AppraiseTestCaseMetadata = {
+  version: typeof APPRAISE_METADATA_VERSION
+  testSuite: {
+    name: string
+    modulePath: string
+  }
+  testCases: AppraiseTestCaseMetadataEntry[]
+}
+
+export type AppraiseMetadataReadResult =
+  | { metadata: AppraiseTestCaseMetadata | null; warnings: string[] }
+  | { metadata: null; warnings: string[] }
+
+type MetadataInputTestCase = {
+  title: string
+  description: string
+  tags?: Array<{ tagExpression: string }>
+  steps?: Array<{
+    flowNodeId: string | null
+    order: number
+    label: string
+  }>
+  flowBlocks?: Array<{
+    id: string
+    name: string
+    order: number
+    nodes: Array<{ flowNodeId: string }>
+  }>
+}
+
+export function getAppraiseMetadataPath(featureFilePath: string): string {
+  return featureFilePath.replace(/\.feature$/, APPRAISE_METADATA_EXTENSION)
+}
+
+export function normalizeMetadataTag(tagExpression: string): string {
+  return tagExpression.startsWith('@') ? tagExpression : `@${tagExpression}`
+}
+
+export function findIdentifierTag(tags: Array<{ tagExpression: string } | string> = []): string | null {
+  for (const tag of tags) {
+    const tagExpression = typeof tag === 'string' ? tag : tag.tagExpression
+    const normalized = normalizeMetadataTag(tagExpression)
+    if (normalized.replace(/^@/, '').startsWith('tc_')) {
+      return normalized
+    }
+  }
+
+  return null
+}
+
+export function buildAppraiseMetadata(input: {
+  testSuiteName: string
+  modulePath: string
+  testCases: MetadataInputTestCase[]
+}): AppraiseTestCaseMetadata {
+  return {
+    version: APPRAISE_METADATA_VERSION,
+    testSuite: {
+      name: input.testSuiteName,
+      modulePath: input.modulePath,
+    },
+    testCases: input.testCases.flatMap(testCase => {
+      const identifierTag = findIdentifierTag(testCase.tags)
+      if (!identifierTag) {
+        return []
+      }
+
+      const nodes = (testCase.steps ?? [])
+        .filter(step => step.flowNodeId)
+        .map(step => ({
+          nodeId: step.flowNodeId as string,
+          order: step.order,
+          label: step.label,
+        }))
+
+      const validNodeIds = new Set(nodes.map(node => node.nodeId))
+
+      return [
+        {
+          identifierTag,
+          title: testCase.title,
+          description: testCase.description,
+          nodes,
+          flowBlocks: (testCase.flowBlocks ?? []).map(block => ({
+            id: block.id,
+            name: block.name,
+            order: block.order,
+            nodeIds: block.nodes.map(node => node.flowNodeId).filter(nodeId => validNodeIds.has(nodeId)),
+          })),
+        },
+      ]
+    }),
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === 'string'
+}
+
+function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+function validateMetadata(value: unknown): AppraiseTestCaseMetadata {
+  if (!isRecord(value) || value.version !== APPRAISE_METADATA_VERSION) {
+    throw new Error(`Unsupported Appraise metadata version`)
+  }
+
+  if (!isRecord(value.testSuite) || !isString(value.testSuite.name) || !isString(value.testSuite.modulePath)) {
+    throw new Error('Invalid Appraise metadata testSuite')
+  }
+
+  if (!Array.isArray(value.testCases)) {
+    throw new Error('Invalid Appraise metadata testCases')
+  }
+
+  return {
+    version: APPRAISE_METADATA_VERSION,
+    testSuite: {
+      name: value.testSuite.name,
+      modulePath: value.testSuite.modulePath,
+    },
+    testCases: value.testCases.map((entry, index) => {
+      if (!isRecord(entry) || !isString(entry.identifierTag) || !isString(entry.title)) {
+        throw new Error(`Invalid Appraise metadata testCases[${index}]`)
+      }
+
+      if (!Array.isArray(entry.nodes) || !Array.isArray(entry.flowBlocks)) {
+        throw new Error(`Invalid Appraise metadata arrays for ${entry.identifierTag}`)
+      }
+
+      return {
+        identifierTag: normalizeMetadataTag(entry.identifierTag),
+        title: entry.title,
+        description: isString(entry.description) ? entry.description : '',
+        nodes: entry.nodes.map((node, nodeIndex) => {
+          if (!isRecord(node) || !isString(node.nodeId) || !isNumber(node.order) || !isString(node.label)) {
+            throw new Error(`Invalid Appraise metadata node ${nodeIndex} for ${entry.identifierTag}`)
+          }
+
+          return {
+            nodeId: node.nodeId,
+            order: node.order,
+            label: node.label,
+          }
+        }),
+        flowBlocks: entry.flowBlocks.map((block, blockIndex) => {
+          if (!isRecord(block) || !isString(block.id) || !isString(block.name) || !isNumber(block.order)) {
+            throw new Error(`Invalid Appraise metadata flowBlock ${blockIndex} for ${entry.identifierTag}`)
+          }
+
+          if (!Array.isArray(block.nodeIds) || !block.nodeIds.every(isString)) {
+            throw new Error(`Invalid Appraise metadata flowBlock nodeIds for ${entry.identifierTag}`)
+          }
+
+          return {
+            id: block.id,
+            name: block.name,
+            order: block.order,
+            nodeIds: block.nodeIds,
+          }
+        }),
+      }
+    }),
+  }
+}
+
+export async function readAppraiseMetadataFile(metadataPath: string): Promise<AppraiseMetadataReadResult> {
+  try {
+    const content = await fs.readFile(metadataPath, 'utf-8')
+    return {
+      metadata: validateMetadata(JSON.parse(content)),
+      warnings: [],
+    }
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return { metadata: null, warnings: [] }
+    }
+
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      metadata: null,
+      warnings: [`Unable to read Appraise metadata ${metadataPath}: ${message}`],
+    }
+  }
+}
+
+export function getMetadataByIdentifier(metadata: AppraiseTestCaseMetadata | null) {
+  return new Map((metadata?.testCases ?? []).map(testCase => [testCase.identifierTag, testCase]))
+}

package/templates/starter/src/lib/automation/automation-path-roots.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { buildJsonReportFormat } from './automation-path-roots'
+
+describe('buildJsonReportFormat', () => {
+  it('uses a project-relative path so Windows drive letters stay unambiguous', () => {
+    const reportPath = `${process.cwd()}\\automation\\reports\\run-1\\cucumber.json`
+    expect(buildJsonReportFormat(reportPath)).toBe('json:automation/reports/run-1/cucumber.json')
+  })
+
+  it('normalizes relative report paths to forward slashes', () => {
+    const reportPath = 'automation\\reports\\run-1\\cucumber.json'
+    expect(buildJsonReportFormat(reportPath)).toBe('json:automation/reports/run-1/cucumber.json')
+  })
+})

package/templates/starter/src/lib/automation/automation-path-roots.ts

@@ -54,6 +54,10 @@ export function getAutomationRunReportPath(runId: string): string {
   return path.join(getAutomationReportRunDir(runId), 'cucumber.json')
 }
 
+export function buildJsonReportFormat(reportPath: string): string {
+  return `json:${toProjectRelativePath(reportPath)}`
+}
+
 function getAutomationReportLogsDir(runId: string): string {
   return path.join(getAutomationReportRunDir(runId), 'logs')
 }
@@ -63,8 +67,12 @@ export function getAutomationRunLogPath(runId: string): string {
 }
 
 export function toProjectRelativePath(targetPath: string): string {
-  const normalizedPath = path.isAbsolute(targetPath) ? path.relative(getRepoRoot(), targetPath) : targetPath
-  return normalizedPath.replace(/\\/g, '/')
+  const normalizedTargetPath = targetPath.replace(/\\/g, '/')
+  const normalizedRepoRoot = getRepoRoot().replace(/\\/g, '/')
+  const normalizedPath = path.isAbsolute(targetPath)
+    ? path.posix.relative(normalizedRepoRoot, normalizedTargetPath)
+    : normalizedTargetPath
+  return normalizedPath
 }
 
 export function resolveStoredPath(storedPath: string): string {

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

@@ -4,6 +4,40 @@ import { buildModuleHierarchy } from './module-hierarchy-builder'
 import { Prisma, TemplateStepType, TemplateStepIcon, TestCase, TagType } from '@prisma/client'
 import { getTagTypeFromExpression } from './tag-identifiers'
 import { getFeatureModulePath } from './path-helpers/feature-path'
+import { getTestSuiteFilesystemKey } from './sync/projected-feature-utils'
+
+function splitTagLine(tagLine: string): string[] {
+  return tagLine
+    .split(/\s+/)
+    .filter(tag => tag.trim().startsWith('@'))
+    .map(tag => tag.trim())
+}
+
+function flattenFeatureTags(tags: string[]): string[] {
+  return tags.flatMap(tag => (tag.startsWith('@') ? splitTagLine(tag) : [tag]))
+}
+
+function extractTestSuiteNameFromFilename(filePath: string): string {
+  const fileName = filePath.split(/[/\\]/).pop() || ''
+  return fileName.replace(/\.feature$/, '')
+}
+
+function parseScenarioTitle(
+  scenarioName: string,
+  scenarioDescription?: string,
+): { title: string; description: string } {
+  if (scenarioDescription) {
+    return {
+      title: scenarioDescription.trim(),
+      description: scenarioName.trim(),
+    }
+  }
+
+  return {
+    title: scenarioName.trim(),
+    description: '',
+  }
+}
 
 /**
  * Determines the tag type based on the tag expression pattern
@@ -268,6 +302,7 @@ function determineStepTypeAndIcon(keyword: string): { type: TemplateStepType; ic
  * Creates or updates a test case step
  */
 async function createOrUpdateTestCaseStep(testCaseId: string, step: ParsedStep, templateStepId: string): Promise<void> {
+  const metadataNode = step.appraiseNode
   try {
     // Check if step already exists
     const existingStep = await prisma.testCaseStep.findFirst({
@@ -284,7 +319,8 @@ async function createOrUpdateTestCaseStep(testCaseId: string, step: ParsedStep,
         where: { id: existingStep.id },
         data: {
           gherkinStep: `${step.keyword} ${step.text}`,
-          label: step.text,
+          flowNodeId: metadataNode?.nodeId ?? existingStep.flowNodeId,
+          label: metadataNode?.label ?? step.text,
           templateStepId: templateStepId,
         },
       })
@@ -295,8 +331,9 @@ async function createOrUpdateTestCaseStep(testCaseId: string, step: ParsedStep,
           testCaseId: testCaseId,
           order: step.order,
           gherkinStep: `${step.keyword} ${step.text}`,
+          flowNodeId: metadataNode?.nodeId,
           icon: determineStepTypeAndIcon(step.keyword).icon,
-          label: step.text,
+          label: metadataNode?.label ?? step.text,
           templateStepId: templateStepId,
         },
       })
@@ -308,14 +345,25 @@ async function createOrUpdateTestCaseStep(testCaseId: string, step: ParsedStep,
 }
 
 type ParsedScenario = ParsedFeature['scenarios'][number]
+
+const testSuiteInclude = {
+  testCases: {
+    include: {
+      tags: true,
+      steps: true,
+    },
+  },
+} as const
+
 type ExistingTestSuite = Prisma.TestSuiteGetPayload<{
-  include: {
-    testCases: true
-  }
+  include: typeof testSuiteInclude
 }>
 
 async function createScenarioTestCase(scenario: ParsedScenario, testSuiteId: string): Promise<string | null> {
-  return findOrCreateTestCase(scenario.name, scenario.description || '', testSuiteId, scenario.tags)
+  const parsedTitle = parseScenarioTitle(scenario.name, scenario.description)
+  const title = scenario.appraiseMetadata?.title ?? parsedTitle.title
+  const description = scenario.appraiseMetadata?.description ?? parsedTitle.description
+  return findOrCreateTestCase(title, description, testSuiteId, scenario.tags)
 }
 
 async function createScenarioSteps(testCaseId: string, steps: ParsedStep[]): Promise<number> {
@@ -333,15 +381,84 @@ async function createScenarioSteps(testCaseId: string, steps: ParsedStep[]): Pro
   return createdTemplateSteps
 }
 
+function applyScenarioMetadataToSteps(scenario: ParsedScenario): ParsedStep[] {
+  const nodesByOrder = new Map((scenario.appraiseMetadata?.nodes ?? []).map(node => [node.order, node]))
+  return scenario.steps.map(step => ({
+    ...step,
+    appraiseNode: nodesByOrder.get(step.order),
+  }))
+}
+
+async function replaceScenarioFlowBlocks(testCaseId: string, scenario: ParsedScenario): Promise<void> {
+  if (!scenario.appraiseMetadata) {
+    return
+  }
+
+  const validNodeIds = new Set(scenario.appraiseMetadata.nodes.map(node => node.nodeId))
+
+  await prisma.testCaseFlowBlock.deleteMany({
+    where: { testCaseId },
+  })
+
+  if (scenario.appraiseMetadata.flowBlocks.length === 0) {
+    return
+  }
+
+  await prisma.testCase.update({
+    where: { id: testCaseId },
+    data: {
+      flowBlocks: {
+        create: scenario.appraiseMetadata.flowBlocks.map(block => ({
+          id: block.id,
+          name: block.name,
+          order: block.order,
+          nodes: {
+            create: block.nodeIds.filter(nodeId => validNodeIds.has(nodeId)).map(nodeId => ({ flowNodeId: nodeId })),
+          },
+        })),
+      },
+    },
+  })
+}
+
 async function findExistingTestSuite(feature: ParsedFeature, moduleId: string): Promise<ExistingTestSuite | null> {
+  const suiteIdentifierTag = flattenFeatureTags(feature.tags).find(tag => tag.replace(/^@/, '').startsWith('ts_'))
+
+  if (suiteIdentifierTag) {
+    const suiteByTag = await prisma.testSuite.findFirst({
+      where: {
+        moduleId,
+        tags: {
+          some: {
+            tagExpression: suiteIdentifierTag,
+          },
+        },
+      },
+      include: testSuiteInclude,
+    })
+
+    if (suiteByTag) {
+      return suiteByTag
+    }
+  }
+
+  const filesystemKey = getTestSuiteFilesystemKey(extractTestSuiteNameFromFilename(feature.filePath))
+  const suitesInModule = await prisma.testSuite.findMany({
+    where: { moduleId },
+    include: testSuiteInclude,
+  })
+  const suiteByFilename = suitesInModule.find(suite => getTestSuiteFilesystemKey(suite.name) === filesystemKey)
+
+  if (suiteByFilename) {
+    return suiteByFilename
+  }
+
   return prisma.testSuite.findFirst({
     where: {
       name: feature.featureName,
-      moduleId: moduleId,
-    },
-    include: {
-      testCases: true,
+      moduleId,
     },
+    include: testSuiteInclude,
   })
 }
 
@@ -362,13 +479,29 @@ async function connectTagsToTestSuite(testSuiteId: string, tags?: string[]): Pro
   })
 }
 
+function findExistingScenarioTestCase(
+  scenario: ParsedScenario,
+  testCases: ExistingTestSuite['testCases'],
+): ExistingTestSuite['testCases'][number] | undefined {
+  const identifierTag = flattenFeatureTags(scenario.tags).find(tag => tag.replace(/^@/, '').startsWith('tc_'))
+
+  if (identifierTag) {
+    return testCases.find(testCase => testCase.tags.some(tag => tag.tagExpression === identifierTag))
+  }
+
+  const { title } = parseScenarioTitle(scenario.name, scenario.description)
+  return testCases.find(testCase => testCase.title === title)
+}
+
 async function addMissingScenariosToTestSuite(feature: ParsedFeature, testSuite: ExistingTestSuite): Promise<number> {
   let addedScenarios = 0
 
   for (const scenario of feature.scenarios) {
-    const existingTestCase = testSuite.testCases.find(tc => tc.title === scenario.name)
+    const existingTestCase = findExistingScenarioTestCase(scenario, testSuite.testCases)
 
-    if (!existingTestCase && (await addScenarioToTestSuite(scenario, testSuite.id))) {
+    if (existingTestCase) {
+      await updateExistingScenarioMetadata(existingTestCase.id, scenario)
+    } else if (await addScenarioToTestSuite(scenario, testSuite.id)) {
       addedScenarios++
     }
   }
@@ -383,10 +516,28 @@ async function addScenarioToTestSuite(scenario: ParsedScenario, testSuiteId: str
     return false
   }
 
-  await createScenarioSteps(testCaseId, scenario.steps)
+  await createScenarioSteps(testCaseId, applyScenarioMetadataToSteps(scenario))
+  await replaceScenarioFlowBlocks(testCaseId, scenario)
   return true
 }
 
+async function updateExistingScenarioMetadata(testCaseId: string, scenario: ParsedScenario): Promise<void> {
+  if (!scenario.appraiseMetadata) {
+    return
+  }
+
+  await prisma.testCase.update({
+    where: { id: testCaseId },
+    data: {
+      title: scenario.appraiseMetadata.title,
+      description: scenario.appraiseMetadata.description,
+    },
+  })
+
+  await createScenarioSteps(testCaseId, applyScenarioMetadataToSteps(scenario))
+  await replaceScenarioFlowBlocks(testCaseId, scenario)
+}
+
 async function createTestSuiteWithScenarios(
   feature: ParsedFeature,
   moduleId: string,
@@ -395,8 +546,8 @@ async function createTestSuiteWithScenarios(
   addedScenarios: number
 }> {
   const testSuiteId = await findOrCreateTestSuite(
-    feature.featureName,
-    feature.featureDescription,
+    extractTestSuiteNameFromFilename(feature.filePath),
+    feature.featureDescription || feature.featureName,
     moduleId,
     feature.tags,
   )

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

@@ -1,6 +1,10 @@
 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 {
+  buildJsonReportFormat,
+  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'
@@ -39,7 +43,7 @@ class LocalExecutorAdapter implements ExecutorAdapter {
       HEADLESS: headless.toString(),
       BROWSER: browserName,
       REPORT_PATH: reportPath,
-      REPORT_FORMAT: `json:${reportPath}`,
+      REPORT_FORMAT: buildJsonReportFormat(reportPath),
       TEST_RUN_ID: testRunId,
     }