create-appraisejs 0.3.0 → 0.3.1-alpha.1

package/templates/starter/automation/steps/actions/store.step.ts

@@ -1,87 +1,76 @@
 import { When, Then, CustomWorld, expect, SelectorName, resolveLocator, getEnvironment, generateRandomData, RandomDataType } from '../../../packages/cucumber-runtime/src/index.js'
 /**
  * @name store
- * @description Template steps that handle data storage
+ * @description Template step group for storing runtime values
  * @type ACTION
  */
 
-// This file is generated automatically. Add template steps to this group to generate content.
-
 /**
  * @name store element text
- * @description Template step for storing element text inside a data variable to be referenced in later steps
+ * @description Store an element's text content inside a runtime variable
  * @icon STORE
  */
 When(
   'the user stores the {string} element text inside the variable {string}',
-  async function (
-    this: CustomWorld,
-    elementName: SelectorName,
-    storeVariableName: string
-  ) {
-    const selector = await resolveLocator(this.page, elementName);
+  async function (this: CustomWorld, elementName: SelectorName, variableName: string) {
+    const selector = await resolveLocator(this.page, elementName)
     if (!selector) {
-      throw new Error(`Selector ${elementName} not found`);
+      throw new Error(`Selector ${elementName} not found`)
     }
+
     try {
-      const text = await this.page.locator(selector).textContent();
-      this.setVar(storeVariableName, text);
+      const value = await this.page.locator(selector).textContent()
+      this.setVar(variableName, value ?? '')
     } catch (error) {
-      throw new Error(
-        `Failed to store the ${elementName} element text: ${error}`
-      );
+      throw new Error(`Failed to store the ${elementName} element text inside the variable ${variableName}: ${error}`)
     }
-  }
-);
+  },
+)
 
 /**
  * @name store text input text
- * @description Template step for storing text input element values inside a variable
+ * @description Store a text input value inside a runtime variable
  * @icon STORE
  */
 When(
   'the user stores the {string} text input value inside the variable {string}',
-  async function (
-    this: CustomWorld,
-    fieldName: SelectorName,
-    variableName: string
-  ) {
-    const selector = await resolveLocator(this.page, fieldName);
+  async function (this: CustomWorld, elementName: SelectorName, variableName: string) {
+    const selector = await resolveLocator(this.page, elementName)
     if (!selector) {
-      throw new Error(`Selector ${fieldName} not found`);
+      throw new Error(`Selector ${elementName} not found`)
     }
+
     try {
-      const value = await this.page.locator(selector).inputValue();
-      this.setVar(variableName, value);
+      const value = await this.page.locator(selector).inputValue()
+      this.setVar(variableName, value)
     } catch (error) {
       throw new Error(
-        `Failed to store the ${fieldName} text input value: ${error}`
-      );
+        `Failed to store the ${elementName} text input value inside the variable ${variableName}: ${error}`,
+      )
     }
-  }
-);
+  },
+)
 
 /**
  * @name store textarea text
- * @description Template step for storing textarea content inside a variable
+ * @description Store a textarea value inside a runtime variable
  * @icon STORE
  */
 When(
   'the user stores the {string} textarea input value inside the variable {string}',
-  async function (
-    this: CustomWorld,
-    elementName: SelectorName,
-    variableName: string
-  ) {
-    const selector = await resolveLocator(this.page, elementName);
+  async function (this: CustomWorld, elementName: SelectorName, variableName: string) {
+    const selector = await resolveLocator(this.page, elementName)
     if (!selector) {
-      throw new Error(`Selector ${elementName} not found`);
+      throw new Error(`Selector ${elementName} not found`)
     }
+
     try {
-      const text = await this.page.locator(selector).inputValue();
-      this.setVar(variableName, text);
+      const value = await this.page.locator(selector).inputValue()
+      this.setVar(variableName, value)
     } catch (error) {
-      throw new Error(`Failed to store the ${elementName} textarea input value inside the variable ${variableName}: ${error}`);
+      throw new Error(
+        `Failed to store the ${elementName} textarea input value inside the variable ${variableName}: ${error}`,
+      )
     }
-  }
-);
+  },
+)

package/templates/starter/automation/steps/actions/wait.step.ts

@@ -1,111 +1,91 @@
 import { When, Then, CustomWorld, expect, SelectorName, resolveLocator, getEnvironment, generateRandomData, RandomDataType } from '../../../packages/cucumber-runtime/src/index.js'
 /**
  * @name wait
- * @description Template steps that handles waiting
+ * @description Template step group for waiting on time or page state
  * @type ACTION
  */
+
 /**
- * @name wait for page load
- * @description Template step for waiting till page becomes interactive
+ * @name wait for element
+ * @description Wait for an element to become visible
  * @icon WAIT
  */
 When(
-  'the user waits for the current page to be loaded',
-  async function (this: CustomWorld) {
+  'the user waits for the element {string} to become visible',
+  async function (this: CustomWorld, elementName: SelectorName) {
+    const selector = await resolveLocator(this.page, elementName, {
+      validate: { requireVisible: false },
+    })
+    if (!selector) {
+      throw new Error(`Selector ${elementName} not found`)
+    }
+
     try {
-      await this.page.waitForLoadState('domcontentloaded');
+      await this.page.locator(selector).waitFor({ state: 'visible' })
     } catch (error) {
-      throw new Error(
-        `Failed to wait for the current page to be loaded: ${error}`
-      );
+      throw new Error(`Failed to wait for the element ${elementName} to become visible: ${error}`)
     }
-  }
-);
+  },
+)
 
 /**
- * @name wait for url route
- * @description Template step for waiting for a url route to be loaded
+ * @name wait for element to disappear
+ * @description Wait for an element to become hidden or detached
  * @icon WAIT
  */
 When(
-  'the user waits for the route {string} to be loaded',
-  async function (this: CustomWorld, routeName: string) {
+  'the user waits for the {string} element to disappear',
+  async function (this: CustomWorld, elementName: SelectorName) {
+    const selector = await resolveLocator(this.page, elementName, {
+      validate: { requireVisible: false },
+    })
+    if (!selector) {
+      throw new Error(`Selector ${elementName} not found`)
+    }
+
     try {
-      const baseUrl = getEnvironment(process.env.ENVIRONMENT as string).baseUrl;
-      const sanitizedBaseUrl = baseUrl.endsWith('/')
-        ? baseUrl.slice(0, -1)
-        : baseUrl;
-      const sanitizedRouteName = routeName.startsWith('/')
-        ? routeName.slice(1)
-        : routeName;
-      const fullRoute = `${sanitizedBaseUrl}/${sanitizedRouteName}`;
-      await this.page.waitForURL(fullRoute, { waitUntil: 'domcontentloaded' });
+      await this.page.locator(selector).waitFor({ state: 'hidden' })
     } catch (error) {
-      throw new Error(
-        `Failed to wait for the route ${routeName} to be loaded: ${error}`
-      );
+      throw new Error(`Failed to wait for the ${elementName} element to disappear: ${error}`)
     }
-  }
-);
+  },
+)
 
 /**
- * @name wait for element
- * @description Template step for waiting for element to become visible
+ * @name wait for page load
+ * @description Wait for the current page to finish loading
  * @icon WAIT
  */
-When(
-  'the user waits for the element {string} to become visible',
-  async function (this: CustomWorld, elementName: SelectorName) {
-    try {
-      const selector = await resolveLocator(this.page, elementName);
-      if (!selector) {
-        throw new Error(`Selector ${elementName} not found`);
-      }
-      await this.page.waitForSelector(selector, { state: 'visible' });
-    } catch (error) {
-      throw new Error(
-        `Failed to wait for the element ${elementName} to become visible: ${error}`
-      );
-    }
+When('the user waits for the current page to be loaded', async function (this: CustomWorld) {
+  try {
+    await this.page.waitForLoadState('domcontentloaded')
+  } catch (error) {
+    throw new Error(`Failed to wait for the current page to be loaded: ${error}`)
   }
-);
+})
 
 /**
- * @name wait for element to disappear
- * @description Template step for waiting for an element to disappear from viewport
+ * @name wait for specific amount of seconds
+ * @description Wait for a specific number of seconds
  * @icon WAIT
  */
-When(
-  'the user waits for the {string} element to disappear',
-  async function (this: CustomWorld, elementName: SelectorName) {
-    try {
-      const selector = await resolveLocator(this.page, elementName);
-      if (!selector) {
-        throw new Error(`Selector ${elementName} not found`);
-      }
-      await this.page.waitForSelector(selector, { state: 'hidden' });
-    } catch (error) {
-      throw new Error(
-        `Failed to wait for the ${elementName} element to disappear: ${error}`
-      );
-    }
+When('the user waits for {int} seconds', async function (this: CustomWorld, seconds: number) {
+  try {
+    await this.page.waitForTimeout(seconds * 1000)
+  } catch (error) {
+    throw new Error(`Failed to wait for ${seconds} seconds: ${error}`)
   }
-);
+})
 
 /**
- * @name wait for specific amount of seconds
- * @description Template step for waiting for for an specific amount of seconds before proceeding with next action
+ * @name wait for url route
+ * @description Wait for the current URL path to match a route
  * @icon WAIT
  */
-When(
-  'the user waits for {int} seconds',
-  async function (this: CustomWorld, waitTimeInSeconds: number) {
-    try {
-      await this.page.waitForTimeout(waitTimeInSeconds * 1000);
-    } catch (error) {
-      throw new Error(
-        `Failed to wait for ${waitTimeInSeconds} seconds: ${error}`
-      );
-    }
+When('the user waits for the route {string} to be loaded', async function (this: CustomWorld, route: string) {
+  try {
+    await this.page.waitForURL(url => url.pathname === route || url.pathname.endsWith(route))
+  } catch (error) {
+    throw new Error(`Failed to wait for the route ${route} to be loaded: ${error}`)
   }
-);
+})

package/templates/starter/automation/steps/validations/active_state_assertion.step.ts

@@ -5,8 +5,6 @@ import { When, Then, CustomWorld, expect, SelectorName, resolveLocator, getEnvir
  * @type VALIDATION
  */
 
-// This file is generated automatically. Add template steps to this group to generate content.
-
 /**
  * @name assert element active
  * @description Template step for validating whether an element is active or not

package/templates/starter/automation/steps/validations/navigation_assertion.step.ts

@@ -5,8 +5,6 @@ import { When, Then, CustomWorld, expect, SelectorName, resolveLocator, getEnvir
  * @type VALIDATION
  */
 
-// This file is generated automatically. Add template steps to this group to generate content.
-
 /**
  * @name assert url route equals
  * @description Template step for validating whether a url route equals the provided value or not

package/templates/starter/automation/steps/validations/text_assertion.step.ts

@@ -5,7 +5,15 @@ import { When, Then, CustomWorld, expect, SelectorName, resolveLocator, getEnvir
  * @type VALIDATION
  */
 
-// This file is generated automatically. Add template steps to this group to generate content.
+/**
+ * @name assert element contains stored variable text
+ * @description Template step to validate whether an element text contains the text inside a stored variable
+ * @icon VALIDATION
+ */
+Then(
+  'the element {string} should contain the text inside the stored variable {string}',
+  async function (this: CustomWorld, _elementName: SelectorName, _variableName: string) {},
+)
 
 /**
  * @name assert element contains text
@@ -14,42 +22,26 @@ import { When, Then, CustomWorld, expect, SelectorName, resolveLocator, getEnvir
  */
 Then(
   'the element {string} should {boolean} contain the text {string}',
-  async function (
-    this: CustomWorld,
-    elementName: SelectorName,
-    shouldContain: boolean,
-    elementText: string
-  ) {
+  async function (this: CustomWorld, elementName: SelectorName, shouldContain: boolean, elementText: string) {
     try {
-      const selector = await resolveLocator(this.page, elementName);
-      if (!selector) throw new Error(`Selector ${elementName} not found`);
-      const elementTextContent = await this.page
-        .locator(selector)
-        .textContent();
+      const selector = await resolveLocator(this.page, elementName)
+      if (!selector) throw new Error(`Selector ${elementName} not found`)
+      const elementTextContent = await this.page.locator(selector).textContent()
 
-      if (!elementTextContent)
-        throw new Error(
-          `Element ${elementName} does not have any text content`
-        );
+      if (!elementTextContent) throw new Error(`Element ${elementName} does not have any text content`)
 
       if (shouldContain) {
-        expect(
-          elementTextContent,
-          `Expected ${elementName} to contain "${elementText}"`
-        ).to.contain(elementText);
+        expect(elementTextContent, `Expected ${elementName} to contain "${elementText}"`).to.contain(elementText)
       } else {
-        expect(
-          elementTextContent,
-          `Expected ${elementName} NOT to contain "${elementText}"`
-        ).to.not.contain(elementText);
+        expect(elementTextContent, `Expected ${elementName} NOT to contain "${elementText}"`).to.not.contain(
+          elementText,
+        )
       }
     } catch (error) {
-      throw new Error(
-        `Failed to validate the containment of the text of the element ${elementName}: ${error}`
-      );
+      throw new Error(`Failed to validate the containment of the text of the element ${elementName}: ${error}`)
     }
-  }
-);
+  },
+)
 
 /**
  * @name assert element equals text
@@ -58,51 +50,19 @@ Then(
  */
 Then(
   'the element {string} should {boolean} equal the text {string}',
-  async function (
-    this: CustomWorld,
-    elementName: SelectorName,
-    shouldEqual: boolean,
-    elementText: string
-  ) {
+  async function (this: CustomWorld, elementName: SelectorName, shouldEqual: boolean, elementText: string) {
     try {
-      const selector = await resolveLocator(this.page, elementName);
-      if (!selector) throw new Error(`Selector ${elementName} not found`);
-      const elementTextContent = await this.page
-        .locator(selector)
-        .textContent();
-      if (!elementTextContent)
-        throw new Error(
-          `Element ${elementName} does not have any text content`
-        );
+      const selector = await resolveLocator(this.page, elementName)
+      if (!selector) throw new Error(`Selector ${elementName} not found`)
+      const elementTextContent = await this.page.locator(selector).textContent()
+      if (!elementTextContent) throw new Error(`Element ${elementName} does not have any text content`)
       if (shouldEqual) {
-        expect(
-          elementTextContent,
-          `Expected ${elementName} to equal "${elementText}"`
-        ).to.equal(elementText);
+        expect(elementTextContent, `Expected ${elementName} to equal "${elementText}"`).to.equal(elementText)
       } else {
-        expect(
-          elementTextContent,
-          `Expected ${elementName} NOT to equal "${elementText}"`
-        ).to.not.equal(elementText);
+        expect(elementTextContent, `Expected ${elementName} NOT to equal "${elementText}"`).to.not.equal(elementText)
       }
     } catch (error) {
-      throw new Error(
-        `Failed to validate the equality of the text of the element ${elementName}: ${error}`
-      );
+      throw new Error(`Failed to validate the equality of the text of the element ${elementName}: ${error}`)
     }
-  }
-);
-
-/**
- * @name assert element contains stored variable text
- * @description Template step to validate whether an element text contains the text inside a stored variable
- * @icon VALIDATION
- */
-Then(
-  'the element {string} should contain the text inside the stored variable {string}',
-  async function (
-    this: CustomWorld,
-    _elementName: SelectorName,
-    _variableName: string
-  ) {}
-);
+  },
+)

package/templates/starter/automation/steps/validations/visibility_assertion.step.ts

@@ -5,8 +5,6 @@ import { When, Then, CustomWorld, expect, SelectorName, resolveLocator, getEnvir
  * @type VALIDATION
  */
 
-// This file is generated automatically. Add template steps to this group to generate content.
-
 /**
  * @name assert element visible
  * @description Template step for validating whether an element should be visible or not

package/templates/starter/e2e/README.md

@@ -0,0 +1,56 @@
+# AppraiseJS E2E tests
+
+Playwright UI tests run against a local Next.js server with an isolated SQLite database. Data is reset and seeded before each test via Prisma helpers in `e2e/helpers/test-data.ts`.
+
+## Commands
+
+- `npm run validate:e2e` — full suite (used in CI)
+- `npm run validate:e2e:smoke` — smoke gate only (`@smoke` tag)
+- `E2E_GREP=@crud npx playwright test` — run a tagged subset locally
+
+## CI and parallelism
+
+GitHub Actions runs `npm run validate:e2e` after `npm run build` with `DATABASE_URL=file:./e2e.db`
+and `CI=true`. The Playwright web server starts via `e2e/start-server.mjs`, which recreates the
+E2E database and applies migrations before serving the production build.
+
+Keep `workers: 1` and `fullyParallel: false` in `playwright.config.ts` until each worker gets an
+isolated database. Spec files reset and seed the same SQLite file in `beforeEach`, so parallel
+workers cause unique-constraint and foreign-key failures in CI and locally.
+
+## Layout
+
+| File | Purpose |
+| --- | --- |
+| `appraise-smoke.spec.ts` | Fast regression gate |
+| `navigation.spec.ts` | Route matrix and dashboard attention links |
+| `crud-configuration.spec.ts` | Configuration entity CRUD |
+| `crud-tests.spec.ts` | Suites, cases, template-based create |
+| `authoring.spec.ts` | Inline dialogs, flow panel, authoring |
+| `runs-and-reports.spec.ts` | Seeded runs, reports, create form (no execution) |
+| `settings-sync.spec.ts` | Per-script sync buttons |
+
+Helpers live under `e2e/helpers/` (`ui`, `navigation`, `table`, `forms`, `test-data`).
+
+## Seed model
+
+`seedCoreData()` provisions modules, environments, tags, locators, template steps, a test case and suite, a completed run with report, and dashboard metric variants (failed, queued, running runs; attention metrics for drawer links).
+
+Seeded IDs are exported as `seededIds` for deep-link tests.
+
+## Scope boundaries
+
+**In scope:** UI flows with deterministic Prisma seed data.
+
+**Out of scope (covered elsewhere):**
+
+- Live `cucumber-js` execution and report JSON ingestion during E2E
+- Locator picker companion / external browser extension flows
+- Bidirectional feature sync CLI unless exposed in Settings UI
+
+## Debugging
+
+- Traces: `trace: 'on-first-retry'` in `playwright.config.ts`
+- Videos/screenshots retained on failure
+- Run a single file: `npx playwright test e2e/navigation.spec.ts`
+- UI mode: `npx playwright test --ui`

package/templates/starter/e2e/apply-migrations.mjs

@@ -0,0 +1,76 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { isAbsolute, join, resolve } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+
+function sqlitePathFromDatabaseUrl(value) {
+  if (!value?.startsWith('file:')) {
+    throw new Error(`E2E SQLite setup expects a file: DATABASE_URL, received ${value || '<empty>'}`)
+  }
+
+  const sqlitePath = value.replace(/^file:/, '')
+  return isAbsolute(sqlitePath) ? sqlitePath : resolve(process.cwd(), 'prisma', sqlitePath)
+}
+
+const databaseUrl = process.env.DATABASE_URL ?? 'file:./e2e.db'
+const databasePath = sqlitePathFromDatabaseUrl(databaseUrl)
+const migrationsDir = resolve(process.cwd(), 'prisma', 'migrations')
+const db = new DatabaseSync(databasePath)
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS "_prisma_migrations" (
+    "id"                    TEXT PRIMARY KEY NOT NULL,
+    "checksum"              TEXT NOT NULL,
+    "finished_at"           DATETIME,
+    "migration_name"        TEXT NOT NULL,
+    "logs"                  TEXT,
+    "rolled_back_at"        DATETIME,
+    "started_at"            DATETIME NOT NULL DEFAULT current_timestamp,
+    "applied_steps_count"   INTEGER UNSIGNED NOT NULL DEFAULT 0
+  );
+`)
+
+const appliedRows = db.prepare('SELECT migration_name FROM "_prisma_migrations"').all()
+const appliedMigrations = new Set(appliedRows.map(row => row.migration_name))
+const insertMigration = db.prepare(`
+  INSERT INTO "_prisma_migrations" (
+    id,
+    checksum,
+    finished_at,
+    migration_name,
+    logs,
+    rolled_back_at,
+    applied_steps_count
+  ) VALUES (?, ?, current_timestamp, ?, NULL, NULL, 1)
+`)
+
+const migrationNames = readdirSync(migrationsDir, { withFileTypes: true })
+  .filter(entry => entry.isDirectory())
+  .map(entry => entry.name)
+  .sort()
+
+for (const migrationName of migrationNames) {
+  if (appliedMigrations.has(migrationName)) {
+    continue
+  }
+
+  const migrationPath = join(migrationsDir, migrationName, 'migration.sql')
+  if (!existsSync(migrationPath)) {
+    continue
+  }
+
+  const sql = readFileSync(migrationPath, 'utf8')
+  const checksum = createHash('sha256').update(sql).digest('hex')
+
+  db.exec('BEGIN')
+  try {
+    db.exec(sql)
+    insertMigration.run(randomUUID(), checksum, migrationName)
+    db.exec('COMMIT')
+  } catch (error) {
+    db.exec('ROLLBACK')
+    throw error
+  }
+}
+
+db.close()

package/templates/starter/e2e/appraise-smoke.spec.ts

@@ -0,0 +1,78 @@
+import { test, expect } from '@playwright/test'
+
+import {
+  disconnectPrisma,
+  findModuleByName,
+  generateSeededFeature,
+  readGeneratedFeature,
+  resetE2eData,
+  seedCoreData,
+  seededIds,
+} from './helpers/test-data'
+import { createModule, expectPageHeading } from './helpers/ui'
+
+test.describe('Smoke @smoke', () => {
+  test.beforeEach(async () => {
+    await resetE2eData()
+    await seedCoreData()
+  })
+
+  test.afterAll(async () => {
+    await disconnectPrisma()
+  })
+
+  test('dashboard renders seeded entity metrics', async ({ page }) => {
+    await page.goto('/')
+    await expectPageHeading(page, 'Dashboard')
+    await expect(page.getByText('Test Cases')).toBeVisible()
+    await expect(page.getByText('Test Suites')).toBeVisible()
+    await expect(page.getByText('Template Steps')).toBeVisible()
+    await expect(page.getByText('Attention Needed')).toBeVisible()
+  })
+
+  test('module CRUD path creates edits and deletes a module', async ({ page }) => {
+    const moduleName = 'E2E Smoke Module'
+    const editedModuleName = 'E2E Smoke Module Edited'
+
+    await createModule(page, moduleName)
+    const createdModule = await findModuleByName(moduleName)
+    expect(createdModule).not.toBeNull()
+
+    await page.goto(`/modules/modify/${createdModule?.id}`)
+    await page.getByLabel('Name').fill(editedModuleName)
+    await page.getByRole('button', { name: /^Save$/ }).click()
+    await expect(page).toHaveURL(/\/modules$/)
+    await expect(page.getByText(editedModuleName, { exact: true }).first()).toBeVisible()
+  })
+
+  test('seeded completed run opens report summary', async ({ page }) => {
+    await page.goto(`/test-runs/${seededIds.testRun}`)
+    await expectPageHeading(page, 'Test Run Details')
+    await expect(page.getByText('E2E Completed Run')).toBeVisible()
+
+    await page.getByRole('link', { name: /View Report/ }).click()
+    await expectPageHeading(page, /Test Run Report:/)
+    await expect(page.getByText('E2E seeded login works')).toBeVisible()
+  })
+
+  test('settings sync all completes without a fatal error', async ({ page }) => {
+    test.setTimeout(120_000)
+
+    await page.goto('/settings')
+    await expectPageHeading(page, 'Settings')
+    await page.getByRole('button', { name: 'Sync All' }).click()
+    await expect(page.getByText(/Sync completed|Sync failed/).first()).toBeVisible({ timeout: 90_000 })
+    await expect(page.getByText(/fatal|uncaught/i)).toHaveCount(0)
+  })
+
+  test('feature generation writes suite-backed feature output', async () => {
+    const featurePath = await generateSeededFeature()
+    const featureContent = readGeneratedFeature()
+
+    expect(featurePath.replaceAll('\\', '/')).toContain('automation/features/E2E Auth/e2e-auth-suite.feature')
+    expect(featureContent).toContain('Feature: Seeded suite for E2E feature generation')
+    expect(featureContent).toContain('@e2e-smoke')
+    expect(featureContent).toContain('Scenario: [E2E seeded login works] Seeded login smoke case')
+    expect(featureContent).toContain('Given I open the seeded page')
+  })
+})