@postxl/generators 0.2.2

package/dist/e2e/template/e2e/.env.example

@@ -0,0 +1,11 @@
+# Set the base url for the web app
+BASE_URL='http://host.docker.internal:3000'
+
+# Set the base url for the api
+API_URL='http://host.docker.internal:3001'
+
+# Set to true to enable video recording
+ENABLE_VIDEO=false
+
+# Enable shutdown of the backend after tests to generate coverage reports
+ENABLE_BACKEND_SHUTDOWN=false

package/dist/e2e/template/e2e/Dockerfile

@@ -0,0 +1,8 @@
+FROM mcr.microsoft.com/playwright:v1.56.1
+
+# Install pnpm
+# Note: Without specifying a version, the installation defaults to pnpm v8.
+RUN npm i -g --ignore-scripts pnpm@9.11.0
+
+# Don't run tests as root
+USER pwuser

package/dist/e2e/template/e2e/README.md

@@ -0,0 +1,87 @@
+# E2E Tests
+
+We use end-to-end (E2E) tests to ensure that the application works as expected from the user's perspective.
+
+E2E tests should _not_ test every possible edge case or error condition. Instead, they should test main user flows and ensure that the application works as expected in the most common scenarios. As a rule of thumb:
+
+- develop E2E tests alongside the development of new features, and
+
+- run the tests during any development/bugfixes to avoid regressions.
+
+> The CI is configured to run the E2E tests on every push to a branch.
+
+## Stateful vs. Stateless
+
+The E2E tests are configured to run in two modes:
+
+- **Stateful**: These tests can change the data. Each test should run a data reset before it runs. Hence, these tests are slower and should work with limited seed data.
+- **Stateless**: The tests should not alter any data on the server - but rather tests the views. This allows for larger/more complex seed data.
+
+## Quick start
+
+#### Start Backend in E2E mode
+
+```sh
+# Start backend in E2E stateful mode
+cd backend
+pnpm e2e:stateful
+
+# Start backend in E2E stateless mode
+cd backend
+pnpm e2e:stateless
+```
+
+#### Start Frontend in E2E mode
+
+```sh
+# Start frontend in E2E mode
+cd frontend
+# Builds and starts in production mode with test-specific settings. Use this to test the production build locally and ensure it behaves as expected, similar to the CI environment
+pnpm e2e:build
+```
+
+#### Run E2E tests
+
+> Tests need to be executed in a Docker Linux container so that the environment matches the one used in CI.
+
+```sh
+# Start a shell in Docker
+pnpm docker
+
+# Run E2E tests
+pnpm e2e
+
+# Test using Playwright UI
+pnpm e2e:ui
+
+# Run E2E tests and update snapshots
+pnpm e2e:update-snapshots
+```
+
+## Writing tests
+
+When writing tests, you can think of the AAA pattern: Arrange, Act, Assert:
+
+- **Arrange**: Set up the test data and the environment
+- **Act**: Perform the action that you want to test
+- **Assert**: Check that the action had the expected effect
+
+See the example tests provided in `e2e/specs/` for inspiration.
+
+> When running `pnpm e2e`, the detailed test results are saved in `test-results/` directory!
+
+## CI/CD
+
+The `e2e` GitHub Action runs the E2E tests on every push to GitHub.
+
+In case the tests fail, the GitHub Action will fail and the error messages will be displayed in the GitHub Actions tab. The _playwright-report_ can be downloaded from GitHub's Artifacts section and be consumed by running `pnpm playwright show-report`. In the [report](http://localhost:9323/) you can also analyze the [trace](https://playwright.dev/docs/trace-viewer).
+
+## F.A.Q
+
+### How to resolve Error: No Tests Found?
+
+Playwright recognizes test files with patterns like `*.spec.ts`, `*.test.ts`, `test-*.ts`. Make sure that you are using the same naming convention in your test files.
+
+### I start Playwright in UI mode. It says `Listening on http://0.0.0.0:3030`, what do I do next?
+
+You can now navigate to http://127.0.0.1:3030 for the Playwright dashboard.

package/dist/e2e/template/e2e/fixtures/global-setup.ts

@@ -0,0 +1,3 @@
+export default function globalSetup() {
+  // You can add global setup code here if needed in the future.
+}

package/dist/e2e/template/e2e/fixtures/global-teardown.ts

@@ -0,0 +1,21 @@
+import { TEST_CONFIG } from 'playwright.config'
+
+export default async function globalTeardown() {
+  if (!TEST_CONFIG.enableBackendShutdown) {
+    console.log('Backend shutdown disabled')
+    return
+  }
+  // Use the shutdown endpoint to stop the backend
+  if (!TEST_CONFIG.apiURL) {
+    throw new Error('API_URL environment variable not set')
+  }
+  try {
+    const response = await fetch(`${TEST_CONFIG.apiURL}/shutdown`, { method: 'POST' })
+    if (!response.ok) {
+      throw new Error(`Backend shutdown failed: ${response.statusText}`)
+    }
+    console.log('Backend shutdown successfully')
+  } catch (error) {
+    console.error('Error shutting down backend:', error)
+  }
+}

package/dist/e2e/template/e2e/fixtures/handle-backend.ts

@@ -0,0 +1,35 @@
+import { TestInfo } from '@playwright/test'
+
+import { TEST_CONFIG } from 'playwright.config'
+
+export type BackendScope = 'global' | 'file'
+export async function startBackend(scope: BackendScope, testInfo: TestInfo): Promise<void> {
+  if (scope === 'global') {
+    return
+  }
+  console.log(`Starting backend for scope ${scope} in test ${testInfo.title} in file ${testInfo.file}`)
+  try {
+    await fetch(`${TEST_CONFIG.apiURL}/startBackend`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json', ...getTestHeaders(testInfo) },
+    })
+  } catch (e) {
+    console.error(`Failed to start backend on ${TEST_CONFIG.apiURL}`, e)
+    throw e
+  }
+}
+
+export async function stopBackend(scope: BackendScope, testInfo: TestInfo): Promise<void> {
+  console.log(`Stopping backend for scope ${scope} in test ${testInfo.title} in file ${testInfo.file}`)
+  await fetch(`${TEST_CONFIG.apiURL}/stopBackend`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json', ...getTestHeaders(testInfo) },
+  })
+}
+
+export function getTestHeaders(testInfo: TestInfo): Record<string, string> {
+  return {
+    'x-test-spec-file': testInfo.file,
+    'x-test-test-title': testInfo.title,
+  }
+}

package/dist/e2e/template/e2e/fixtures/set-date-script.js

@@ -0,0 +1,28 @@
+// Any Playwright test page that uses the current date normally leads to changes in the test results and hence failing tests.
+// With this script and other files in `e2e/fixtures` we address this by fixing the `now` date to a hardcoded value.
+//
+// The solution is inspired by:
+// * GitHub issue and comment: https://github.com/microsoft/playwright/issues/6347#issuecomment-1085850728
+//   where we can set the date for the test pages.
+// * GitHub issue and comment: https://github.com/microsoft/playwright/issues/6347#issuecomment-1884463948
+//   where we extend the test fixtures to set the date for the test pages.
+
+// Pick the new/fake 'now' for the test pages.
+const fakeNow = new Date('November 25 2000 13:37:11').valueOf()
+
+// Extend Date constructor to default to fakeNow
+// eslint-disable-next-line no-global-assign
+Date = class extends Date {
+  constructor(...args) {
+    if (args.length === 0) {
+      super(fakeNow)
+    } else {
+      super(...args)
+    }
+  }
+}
+
+// Override Date.now() to start from fakeNow
+const __DateNowOffset = fakeNow - Date.now()
+const __DateNow = Date.now
+Date.now = () => __DateNow() + __DateNowOffset

package/dist/e2e/template/e2e/fixtures/set-fixed-date.ts

@@ -0,0 +1,12 @@
+import { Page } from '@playwright/test'
+
+/**
+ * Override the Date/Time in a browser environment for Playwright tests.
+ */
+export async function setFixedDate(page: Page): Promise<void> {
+  // See https://playwright.dev/docs/api/class-page#pageadinitscriptscript-arg
+  await page.addInitScript({
+    // Update the Date/Time in test pages.
+    path: './fixtures/set-date-script.js',
+  })
+}

package/dist/e2e/template/e2e/fixtures/test-fixtures.ts

@@ -0,0 +1,132 @@
+import { BrowserContext, test as baseTest } from '@playwright/test'
+
+import { getTestHeaders } from 'fixtures/handle-backend'
+import { addCoverageReport } from 'monocart-reporter'
+import { TEST_CONFIG } from 'playwright.config'
+import { registerContextForStability } from 'support/page-stability'
+
+import { setFixedDate } from './set-fixed-date'
+
+// Re-exporting the default expect as well so that on the tests we can have
+// a single import for expect and test, but the test will be the extended test below.
+export { expect } from '@playwright/test'
+
+// See https://playwright.dev/docs/test-fixtures for more information about fixtures.
+// Declare the types for the fixtures.
+type TestFixtures = {
+  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+  setFixedDate: void
+  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+  setAutoCoverage: void
+
+  context: BrowserContext
+}
+
+// Extend base test by providing `setFixedDate`.
+// This new `test` can be used in multiple test files, and each of them will get the fixtures.
+export const test = baseTest.extend<TestFixtures>({
+  setFixedDate: [
+    async ({ page }, use): Promise<void> => {
+      // Set up the fixture.
+      await setFixedDate(page)
+      // Use the fixture value in the test.
+      await use()
+    },
+    {
+      // Automatic fixtures are set up for each test/worker, even when the test does not list them directly.
+      auto: true,
+    },
+  ],
+  // automatically create test coverage reports
+  setAutoCoverage: [
+    async ({ page }, use) => {
+      // coverage API is chromium only, make sure to setup the project correctly
+      await Promise.all([
+        page.coverage.startJSCoverage({
+          resetOnNavigation: false,
+        }),
+        page.coverage.startCSSCoverage({
+          resetOnNavigation: false,
+        }),
+      ])
+
+      await use()
+
+      const [jsCoverage, cssCoverage] = await Promise.all([
+        page.coverage.stopJSCoverage(),
+        page.coverage.stopCSSCoverage(),
+      ])
+      const coverageList = [...jsCoverage, ...cssCoverage]
+      await addCoverageReport(coverageList, test.info())
+    },
+    {
+      scope: 'test',
+      auto: true,
+    },
+  ],
+
+  /**
+   * This modifies the context so that all backend requests add testinfo as custom headers
+   */
+  context: async ({ browser }, use, testInfo) => {
+    const context = await browser.newContext()
+
+    await context.addInitScript(() => {
+      const disableAnimations = () => {
+        const style = document.createElement('style')
+        style.dataset.testid = 'disable-animations'
+        style.textContent = `
+          *,
+          *::before,
+          *::after {
+            animation-delay: 0s !important;
+            animation-duration: 0s !important;
+            transition-delay: 0s !important;
+            transition-duration: 0s !important;
+            scroll-behavior: auto !important;
+          }
+
+          html {
+            scroll-behavior: auto !important;
+          }
+        `
+
+        document.head?.append(style)
+      }
+
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', disableAnimations, { once: true })
+      } else {
+        disableAnimations()
+      }
+    })
+
+    registerContextForStability(context, new URL(TEST_CONFIG.apiURL))
+
+    await context.route('**/*', async (route) => {
+      const request = route.request()
+      let handled = false
+
+      try {
+        const url = new URL(request.url())
+        if (url.port == TEST_CONFIG.apiPort) {
+          const headers = {
+            ...request.headers(),
+            ...getTestHeaders(testInfo),
+          }
+          handled = true //NOSONAR
+          await route.continue({ headers })
+          return
+        }
+      } catch {
+        // ignore malformed URLs and just continue with default handling
+      }
+
+      if (!handled) {
+        await route.continue()
+      }
+    })
+    await use(context)
+    await context.close()
+  },
+})

package/dist/e2e/template/e2e/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "<%schema.slug%>-e2e",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "e2e": "dotenvx run -- pnpm pw test",
+    "e2e:ui": "dotenvx run -- pnpm pw test --ui-host=0.0.0.0 --ui-port=3030",
+    "e2e:update-snapshots": "MAX_DIFF_PIXELS=50 dotenvx run -- pnpm pw test --update-snapshots",
+    "pw": "npx playwright",
+    "test:types": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint ."
+  },
+  "devDependencies": {
+    "@dotenvx/dotenvx": "0.40.0",
+    "@playwright/test": "1.56.1",
+    "@types/node": "20.5.0",
+    "playwright": "1.56.1",
+    "typescript": "5.9.2",
+    "monocart-reporter": "^2.6.3",
+    "zod": "3.25.76"
+  }
+}

package/dist/e2e/template/e2e/playwright.config.ts

@@ -0,0 +1,161 @@
+import { defineConfig, devices } from '@playwright/test'
+
+import { CoverageReportOptions } from 'monocart-reporter'
+
+// Directories that should not be covered by the coverage report
+const dirsToNotCover = ['node_modules', 'backend']
+
+const coverageReportOptions: CoverageReportOptions = {
+  // logging: 'debug',
+  name: 'Vite.js V8 Coverage Report',
+
+  // Vite serves assets from /assets/ and source files from /src/
+  entryFilter: (entry) => {
+    // Filter for Vite client-side chunks (adjust as needed for your build output)
+    return entry.url.includes('/assets/') || entry.url.includes('/src/')
+  },
+
+  sourceFilter: (sourcePath) => {
+    if (dirsToNotCover.some((dir) => sourcePath.includes(dir))) {
+      return false
+    }
+    // Vite source files are typically under /src
+    return sourcePath.includes('src')
+  },
+
+  sourcePath: (fileSource) => {
+    return fileSource
+  },
+
+  reports: ['v8', 'html', 'lcov'],
+}
+
+import z from 'zod'
+
+// We use zod to read and validate the configuration from environment variables.
+const TEST_CONFIG_SCHEMA = z
+  .object({
+    apiURL: z.string(),
+    baseURL: z.string(),
+    enableVideo: z.boolean().optional().default(false),
+    isCI: z.boolean().optional().default(false),
+    workers: z.number().optional(),
+    maxDiffPixels: z.number().optional().default(100),
+    enableBackendShutdown: z.boolean().optional().default(false),
+    // stateful: z.boolean().optional().default(false),
+  })
+  .transform((config) => ({
+    ...config,
+    apiPort: new URL(config.apiURL).port || 3001,
+  }))
+
+export const TEST_CONFIG = TEST_CONFIG_SCHEMA.parse({
+  apiURL: nextenv(process.env.API_URL),
+  baseURL: nextenv(process.env.BASE_URL),
+  enableVideo: nextenv(process.env.ENABLE_VIDEO),
+  isCI: nextenv(process.env.CI),
+  workers: nextenv(process.env.PLAYWRIGHT_WORKERS),
+  maxDiffPixels: nextenv(process.env.MAX_DIFF_PIXELS),
+  enableBackendShutdown: nextenv(process.env.ENABLE_BACKEND_SHUTDOWN),
+  // stateful: nextenv(process.env.STATEFUL),
+})
+
+function nextenv(value?: string | null): string | boolean | number | null | undefined {
+  if (value == null) {
+    return value
+  }
+
+  try {
+    return JSON.parse(value) as string | boolean | number | null | undefined
+  } catch {
+    // If we can't parse the value as JSON, just return the original value as string.
+    return value
+  }
+}
+
+// Zod validation is done in the `TEST_CONFIG` object.
+// We can access the values from the `TEST_CONFIG` object.
+
+const isVideoEnabled = TEST_CONFIG.enableVideo ? 'on' : 'off'
+
+export default defineConfig({
+  globalSetup: require.resolve('./fixtures/global-setup'),
+
+  // If running in "stateful" mode, run tests that are not marked as stateless.
+  // Otherwise, run tests that are not marked as stateful.
+  // testMatch: TEST_CONFIG.stateful ? '**/!(*.stateless).+(test|spec).ts' : '**/!(*.stateful).+(test|spec).ts',
+
+  // We enable test retries. When `retries` option is used, failing tests will be retried until they pass or up to the specified number of times.
+  // Here we retry twice.
+  retries: 2,
+
+  use: {
+    // Traces are run on CI on the first retry of a failed test. This is done by setting the `trace` option to 'on-first-retry'.
+    // This will produce a trace directory in test result artifacts.
+    // This will also produce a `trace.zip` file for each test that was retried, they are saved in `test-results` directory.
+    trace: 'on-first-retry',
+    baseURL: TEST_CONFIG.baseURL,
+    testIdAttribute: 'data-test-id',
+    viewport: { width: 1920, height: 1080 },
+    video: {
+      mode: isVideoEnabled,
+      size: { width: 1920, height: 1080 },
+    },
+  },
+
+  expect: {
+    toHaveScreenshot: {
+      // Default maxDiffPixels is set to 100 for regular test runs to allow for minor rendering differences
+      // across different environments, browsers, or system configurations. However, when updating snapshots
+      // via the e2e:update-snapshots script, we use a stricter threshold of 50 pixels to ensure new
+      // snapshots are more precise and catch smaller visual regressions in future test runs.
+      maxDiffPixels: TEST_CONFIG.maxDiffPixels,
+      threshold: 0.15,
+    },
+  },
+
+  // Dynamically set the number of workers based on the test configuration.
+  // In "stateful" mode, limit the workers to 1 to avoid concurrency issues.
+  // Otherwise, use the value from TEST_CONFIG.workers, or default to half the available CPU cores if not specified.
+  // Note: Playwright calculates the default number of workers as (# CPU cores) / 2.
+  workers: TEST_CONFIG.workers,
+
+  //  We can generate a report in different formats, use the following:
+  // 'github' for GitHub Actions CI to generate annotations,
+  // 'html' to produce a report in HTML format,
+  // 'list' to print a line for each test being run and a summary is saved at the end of the run.
+  //  Here we use 'github', 'html' and monocart-reporter for CI,
+  //  'list' and the monocart-reporter (test coverage generator) for local run.
+  reporter: TEST_CONFIG.isCI
+    ? [
+        ['github'],
+        ['html', { open: 'never' }],
+        [
+          'monocart-reporter',
+          {
+            coverage: coverageReportOptions,
+          },
+        ],
+      ]
+    : [
+        ['list'],
+        [
+          'monocart-reporter',
+          {
+            coverage: coverageReportOptions,
+          },
+        ],
+      ],
+
+  projects: [
+    // use chromium to allow coverage reports
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        viewport: { width: 1920, height: 1080 },
+      },
+    },
+  ],
+  globalTeardown: require.resolve('./fixtures/global-teardown'),
+})

package/dist/e2e/template/e2e/specs/example-backend-isolation.spec.ts

@@ -0,0 +1,59 @@
+/**
+ * 🔒 Backend Isolation Test Example
+ *
+ * This test file demonstrates the backend isolation pattern where each test file
+ * can have its own dedicated backend instance. This provides:
+ *
+ * - Complete test isolation between different test files
+ * - Independent backend state for each test suite
+ * - Ability to run tests in parallel without interference
+ * - Custom backend configuration per test file
+ *
+ * When backend isolation is specified, the test runner will:
+ * 1. Launch a dedicated backend instance before running tests in this file
+ * 2. Keep the backend running for the duration of all tests in this file
+ * 3. Clean up and stop the backend after all tests complete
+ */
+
+import { startBackend, stopBackend } from 'fixtures/handle-backend'
+
+import { expect, test } from '../fixtures/test-fixtures'
+
+/**
+ * Configure tests to run in serial mode to ensure proper backend lifecycle management.
+ * If one test fails, we restart the backend and run all tests again for consistency.
+ */
+test.describe.configure({ mode: 'serial' })
+
+/**
+ * Backend Lifecycle: Startup
+ *
+ * Starts a dedicated backend instance for this test file before any tests run.
+ * The 'file' parameter indicates this backend is scoped to this specific test file.
+ */
+// eslint-disable-next-line no-empty-pattern
+test.beforeAll(async ({}, testInfo) => {
+  await startBackend('file', testInfo)
+})
+
+/**
+ * Backend Lifecycle: Cleanup
+ *
+ * Stops the dedicated backend instance after all tests in this file complete.
+ * This ensures proper cleanup and prevents resource leaks between test runs.
+ */
+// eslint-disable-next-line no-empty-pattern
+test.afterAll(async ({}, testInfo) => {
+  await stopBackend('file', testInfo)
+})
+
+/**
+ * Example test using the isolated backend instance.
+ * This test runs against the dedicated backend started in beforeAll(),
+ * ensuring it has a clean, isolated environment.
+ */
+test('Dashboard page is accessible ', async ({ page }) => {
+  await page.goto('/dashboard')
+
+  await expect(page).toHaveURL(/.*\/dashboard$/)
+})

package/dist/e2e/template/e2e/specs/example.spec.ts

@@ -0,0 +1,77 @@
+import { DataMocker } from '@mock-data/dataMocker.class'
+
+import { setData } from 'support/set-data'
+
+import { expect, test } from '../fixtures/test-fixtures'
+
+// ------------------------------------------------------------
+// 🧭 Visual Regression Test
+// ------------------------------------------------------------
+// Purpose: Capture a baseline screenshot of the homepage.
+// Expectation: Screenshot is stored and compared against future changes.
+// ------------------------------------------------------------
+test('Navigate to homepage and take snapshot', async ({ page }) => {
+  await page.goto('/')
+
+  await expect(page).toHaveScreenshot()
+})
+
+// ------------------------------------------------------------
+// 📊 Navigation Test — Dashboard Accessibility
+// ------------------------------------------------------------
+// Purpose: Ensure that the dashboard page can be accessed directly.
+// Expectation: The browser navigates to /dashboard successfully.
+// ------------------------------------------------------------
+test('Dashboard page is accessible ', async ({ page }) => {
+  await page.goto('/dashboard')
+
+  await expect(page).toHaveURL(/.*\/dashboard$/)
+})
+
+// ------------------------------------------------------------
+// 🙋‍♂️ Dashboard Content Test — User Greeting
+// ------------------------------------------------------------
+// Purpose: Verify that a logged-in user sees a personalized greeting.
+// Expectation: The greeting text “Hi Test User!” is visible on the page.
+// ------------------------------------------------------------
+test('Dashboard displays user greeting message', async ({ page }) => {
+  await page.goto('/dashboard')
+
+  await expect(page.getByText('Hi Test User!')).toBeVisible()
+})
+
+// ------------------------------------------------------------
+// 🌙 UI Theme Toggle Test
+// ------------------------------------------------------------
+// Purpose: Validate that the theme toggle switches to dark mode.
+// Steps:
+//   1. Navigate to /dashboard
+//   2. Click the theme toggle button (data-test-id)
+// Expectation: A toast confirms “As you may see now it's dark theme”.
+// ------------------------------------------------------------
+test('Theme toggle switches to dark mode successfully', async ({ page }) => {
+  await page.goto('/dashboard')
+
+  await page.getByTestId('button-toggle-theme').click()
+
+  await expect(page.getByText("As you may see now it's dark theme")).toBeVisible()
+})
+
+/**
+ * 🧪 Backend Data Reset Test
+ *
+ * This test demonstrates how to use the DataMocker class for backend data manipulation
+ * in E2E tests. It shows the pattern for:
+ * - Creating test data using DataMocker
+ * - Sending data to the backend for test setup
+ * - Ensuring clean state between test runs
+ *
+ * Keep this test for reference during further development.
+ */
+test.skip('Should reset data with data mocker', async () => {
+  const data = new DataMocker()
+
+  data.addUser({ id: 'user1' })
+
+  await expect(setData(data)).resolves.not.toThrow()
+})