@toolstackhq/create-qa-patterns 1.0.13 → 1.0.15

package/templates/cypress-template/scripts/run-cypress.mjs

@@ -1,25 +1,28 @@
 #!/usr/bin/env node
 
 // Starts the local demo app when needed, then launches Cypress in run or open mode.
-import process from "node:process";
-import path from "node:path";
-import { spawn } from "node:child_process";
+import process from 'node:process';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
 
-import dotenv from "dotenv";
+import dotenv from 'dotenv';
 
-const mode = process.argv[2] ?? "run";
+const mode = process.argv[2] ?? 'run';
 const args = process.argv.slice(3);
 const cwd = process.cwd();
-const healthUrl = "http://127.0.0.1:3000/health";
-const environment = process.env.TEST_ENV ?? "dev";
+const healthUrl = 'http://127.0.0.1:3000/health';
+const environment = process.env.TEST_ENV ?? 'dev';
 const environmentDefaults = {
-  dev: "http://127.0.0.1:3000",
-  staging: "https://staging-ui.example.internal",
-  prod: "https://ui.example.internal"
+  dev: 'http://127.0.0.1:3000',
+  staging: 'https://staging-ui.example.internal',
+  prod: 'https://ui.example.internal'
 };
 
-dotenv.config({ path: path.resolve(cwd, ".env") });
-dotenv.config({ path: path.resolve(cwd, `.env.${environment}`), override: true });
+dotenv.config({ path: path.resolve(cwd, '.env') });
+dotenv.config({
+  path: path.resolve(cwd, `.env.${environment}`),
+  override: true
+});
 
 const uiBaseUrl =
   process.env[`${environment.toUpperCase()}_UI_BASE_URL`] ??
@@ -28,18 +31,18 @@ const uiBaseUrl =
   environmentDefaults.dev;
 
 const shouldAutoStartDemoApp =
-  environment === "dev" &&
+  environment === 'dev' &&
   uiBaseUrl === environmentDefaults.dev &&
-  process.env.CY_DISABLE_LOCAL_DEMO_APP !== "true";
+  process.env.CY_DISABLE_LOCAL_DEMO_APP !== 'true';
 
 function getCommandName(command) {
-  return process.platform === "win32" ? `${command}.cmd` : command;
+  return process.platform === 'win32' ? `${command}.cmd` : command;
 }
 
 function spawnCommand(command, commandArgs, options = {}) {
   return spawn(getCommandName(command), commandArgs, {
     cwd,
-    stdio: "inherit",
+    stdio: 'inherit',
     ...options
   });
 }
@@ -68,7 +71,7 @@ function killChild(child) {
     return;
   }
 
-  child.kill("SIGTERM");
+  child.kill('SIGTERM');
 }
 
 async function run() {
@@ -76,16 +79,20 @@ async function run() {
 
   try {
     if (shouldAutoStartDemoApp) {
-      demoAppProcess = spawnCommand("npm", ["run", "demo:ui"]);
+      demoAppProcess = spawnCommand('npm', ['run', 'demo:ui']);
       await waitForHealthcheck(healthUrl);
     }
 
-    const cypressCommand = mode === "open" ? "open" : "run";
-    const cypressProcess = spawnCommand("npx", ["cypress", cypressCommand, ...args]);
+    const cypressCommand = mode === 'open' ? 'open' : 'run';
+    const cypressProcess = spawnCommand('npx', [
+      'cypress',
+      cypressCommand,
+      ...args
+    ]);
 
     const exitCode = await new Promise((resolve) => {
-      cypressProcess.on("close", resolve);
-      cypressProcess.on("error", () => resolve(1));
+      cypressProcess.on('close', resolve);
+      cypressProcess.on('error', () => resolve(1));
     });
 
     if (exitCode !== 0) {
@@ -96,11 +103,13 @@ async function run() {
   }
 }
 
-for (const signal of ["SIGINT", "SIGTERM"]) {
+for (const signal of ['SIGINT', 'SIGTERM']) {
   process.on(signal, () => process.exit(1));
 }
 
 run().catch((error) => {
-  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`
+  );
   process.exit(1);
 });

package/templates/cypress-template/scripts/run-tests.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+node ./scripts/ensure-local-env.mjs
 npm run lint
 npm run typecheck
 npx cypress run "$@"

package/templates/cypress-template/tsconfig.json

@@ -11,5 +11,11 @@
     "noEmit": true,
     "types": ["cypress", "node"]
   },
-  "include": ["cypress/**/*.ts", "cypress/**/*.d.ts", "config/**/*.ts", "cypress.config.ts", "allurerc.mjs"]
+  "include": [
+    "cypress/**/*.ts",
+    "cypress/**/*.d.ts",
+    "config/**/*.ts",
+    "cypress.config.ts",
+    "allurerc.mjs"
+  ]
 }

package/templates/playwright-template/.env.example

@@ -3,15 +3,15 @@ TEST_RUN_ID=local
 
 DEV_UI_BASE_URL=http://127.0.0.1:3000
 DEV_API_BASE_URL=http://127.0.0.1:3001
-DEV_APP_USERNAME=tester
-DEV_APP_PASSWORD=Password123!
+DEV_APP_USERNAME=generate-a-local-username
+DEV_APP_PASSWORD=generate-a-local-password
 
 STAGING_UI_BASE_URL=https://staging-ui.example.internal
 STAGING_API_BASE_URL=https://staging-api.example.internal
-STAGING_APP_USERNAME=staging-user
-STAGING_APP_PASSWORD=replace-me
+STAGING_APP_USERNAME=your-staging-username
+STAGING_APP_PASSWORD=your-staging-password
 
 PROD_UI_BASE_URL=https://ui.example.internal
 PROD_API_BASE_URL=https://api.example.internal
-PROD_APP_USERNAME=prod-user
-PROD_APP_PASSWORD=replace-me
+PROD_APP_USERNAME=your-prod-username
+PROD_APP_PASSWORD=your-prod-password

package/templates/playwright-template/.github/workflows/playwright-tests.yml

@@ -4,9 +4,9 @@ on:
   workflow_dispatch:
   push:
     paths:
-      - "templates/playwright-template/**"
-      - "test-apps/**"
-      - "package.json"
+      - 'templates/playwright-template/**'
+      - 'test-apps/**'
+      - 'package.json'
 
 jobs:
   playwright:
@@ -17,7 +17,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: '20'
 
       - name: Install workspace dependencies
         run: npm ci
@@ -50,13 +50,18 @@ jobs:
 
   playwright-docker:
     runs-on: ubuntu-latest
+    env:
+      DEV_APP_USERNAME: ci-docker-user
+      DEV_APP_PASSWORD: ci-docker-password-A1!
+      UI_DEMO_USERNAME: ci-docker-user
+      UI_DEMO_PASSWORD: ci-docker-password-A1!
 
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: '20'
 
       - name: Install workspace dependencies
         run: npm ci
@@ -91,6 +96,10 @@ jobs:
             -e TEST_RUN_ID=ci-docker \
             -e DEV_UI_BASE_URL=http://host.docker.internal:3000 \
             -e DEV_API_BASE_URL=http://host.docker.internal:3001 \
+            -e DEV_APP_USERNAME=${DEV_APP_USERNAME} \
+            -e DEV_APP_PASSWORD=${DEV_APP_PASSWORD} \
+            -e UI_DEMO_USERNAME=${UI_DEMO_USERNAME} \
+            -e UI_DEMO_PASSWORD=${UI_DEMO_PASSWORD} \
             -v "${GITHUB_WORKSPACE}/templates/playwright-template/reports:/workspace/reports" \
             -v "${GITHUB_WORKSPACE}/templates/playwright-template/allure-results:/workspace/allure-results" \
             -v "${GITHUB_WORKSPACE}/templates/playwright-template/test-results:/workspace/test-results" \

package/templates/playwright-template/README.md

@@ -13,6 +13,7 @@ This is a Playwright + TypeScript automation framework template for UI and API t
 - [Reports and artifacts](#reports-and-artifacts)
 - [Add a new test](#add-a-new-test)
 - [Extend the framework](#extend-the-framework)
+- [Template upgrades](#template-upgrades)
 - [CI and Docker](#ci-and-docker)
 
 ## Feature set
@@ -88,8 +89,7 @@ Default local values:
 
 - UI base URL: `http://127.0.0.1:3000`
 - API base URL: `http://127.0.0.1:3001`
-- username: `tester`
-- password: `Password123!`
+- credentials: generated into local `.env` on first run
 
 ## Environment and secrets
 
@@ -109,7 +109,7 @@ The same pattern is used for credentials:
 
 1. `DEV_APP_USERNAME` or `DEV_APP_PASSWORD`
 2. `APP_USERNAME` or `APP_PASSWORD`
-3. built-in defaults for the selected environment
+3. built-in empty defaults for the selected environment
 
 For local overrides, copy:
 
@@ -128,6 +128,8 @@ The template loads:
 - `.env`
 - `.env.<TEST_ENV>`
 
+On the first local run, the template also creates a `.env` file with random demo credentials if one does not already exist.
+
 Example:
 
 ```bash
@@ -191,7 +193,7 @@ If you only want Playwright reporting, remove the `allure-playwright` reporter e
 Create tests under `tests/` and import the shared fixtures:
 
 ```ts
-import { expect, test } from "../fixtures/test-fixtures";
+import { expect, test } from '../fixtures/test-fixtures';
 ```
 
 Keep the pattern simple:
@@ -203,7 +205,7 @@ Keep the pattern simple:
 Example shape:
 
 ```ts
-test("do something @smoke", async ({ dataFactory, loginPage }) => {
+test('do something @smoke', async ({ dataFactory, loginPage }) => {
   const person = dataFactory.person();
   // use page objects here
 });
@@ -228,6 +230,24 @@ Recommended rules:
 - prefer semantic selectors such as `getByRole`, `getByLabel`, and `data-testid`
 - keep the data layer generic until the project really needs domain-specific factories
 
+## Template upgrades
+
+This project includes a `.qa-patterns.json` metadata file so future CLI versions can compare the current project against the managed template baseline.
+
+Check for available safe updates:
+
+```bash
+npx -y @toolstackhq/create-qa-patterns upgrade check .
+```
+
+Apply only safe managed-file updates:
+
+```bash
+npx -y @toolstackhq/create-qa-patterns upgrade apply --safe .
+```
+
+The upgrade flow is conservative. It updates framework infrastructure such as config, scripts, workflows, and package metadata when those files are still unchanged from the generated baseline. If you changed a managed file yourself, the CLI reports a conflict instead of overwriting it.
+
 ## CI and Docker
 
 The CI entrypoint is:

package/templates/playwright-template/allurerc.mjs

@@ -1,5 +1,5 @@
 export default {
-  name: "qa-patterns Playwright Template",
+  name: 'qa-patterns Playwright Template',
   plugins: {
     awesome: {
       options: {

package/templates/playwright-template/components/flash-message.ts

@@ -1,10 +1,10 @@
-import type { Locator, Page } from "@playwright/test";
+import type { Locator, Page } from '@playwright/test';
 
 export class FlashMessage {
   private readonly message: Locator;
 
   constructor(page: Page) {
-    this.message = page.getByTestId("flash-message");
+    this.message = page.getByTestId('flash-message');
   }
 
   async getText(): Promise<string | null> {

package/templates/playwright-template/config/environments.ts

@@ -1,5 +1,5 @@
 // Defines the built-in environment defaults used when env vars are not provided.
-import type { TestEnvironment } from "./test-env";
+import type { TestEnvironment } from './test-env';
 
 type EnvironmentDefaults = {
   uiBaseUrl: string;
@@ -12,31 +12,33 @@ type EnvironmentDefaults = {
 
 const DEFAULTS: Record<TestEnvironment, EnvironmentDefaults> = {
   dev: {
-    uiBaseUrl: "http://127.0.0.1:3000",
-    apiBaseUrl: "http://127.0.0.1:3001",
+    uiBaseUrl: 'http://127.0.0.1:3000',
+    apiBaseUrl: 'http://127.0.0.1:3001',
     credentials: {
-      username: "tester",
-      password: "Password123!"
+      username: '',
+      password: ''
     }
   },
   staging: {
-    uiBaseUrl: "https://staging-ui.example.internal",
-    apiBaseUrl: "https://staging-api.example.internal",
+    uiBaseUrl: 'https://staging-ui.example.internal',
+    apiBaseUrl: 'https://staging-api.example.internal',
     credentials: {
-      username: "staging-user",
-      password: "replace-me"
+      username: '',
+      password: ''
     }
   },
   prod: {
-    uiBaseUrl: "https://ui.example.internal",
-    apiBaseUrl: "https://api.example.internal",
+    uiBaseUrl: 'https://ui.example.internal',
+    apiBaseUrl: 'https://api.example.internal',
     credentials: {
-      username: "prod-user",
-      password: "replace-me"
+      username: '',
+      password: ''
     }
   }
 };
 
-export function getEnvironmentDefaults(testEnv: TestEnvironment): EnvironmentDefaults {
+export function getEnvironmentDefaults(
+  testEnv: TestEnvironment
+): EnvironmentDefaults {
   return DEFAULTS[testEnv];
 }

package/templates/playwright-template/config/runtime-config.ts

@@ -1,20 +1,23 @@
 // Builds the runtime configuration object that tests and fixtures consume.
-import path from "node:path";
+import path from 'node:path';
 
-import dotenv from "dotenv";
-import { z } from "zod";
+import dotenv from 'dotenv';
+import { z } from 'zod';
 
-import { getEnvironmentDefaults } from "./environments";
-import { EnvSecretProvider, SecretManager } from "./secret-manager";
-import { loadTestEnvironment } from "./test-env";
+import { getEnvironmentDefaults } from './environments';
+import { EnvSecretProvider, SecretManager } from './secret-manager';
+import { loadTestEnvironment } from './test-env';
 
 const environment = loadTestEnvironment();
 
-dotenv.config({ path: path.resolve(process.cwd(), ".env") });
-dotenv.config({ path: path.resolve(process.cwd(), `.env.${environment}`), override: true });
+dotenv.config({ path: path.resolve(process.cwd(), '.env') });
+dotenv.config({
+  path: path.resolve(process.cwd(), `.env.${environment}`),
+  override: true
+});
 
 const runtimeConfigSchema = z.object({
-  testEnv: z.enum(["dev", "staging", "prod"]),
+  testEnv: z.enum(['dev', 'staging', 'prod']),
   testRunId: z.string().min(1),
   uiBaseUrl: z.string().url(),
   apiBaseUrl: z.string().url(),
@@ -41,14 +44,16 @@ export function loadRuntimeConfig(): RuntimeConfig {
 
   return runtimeConfigSchema.parse({
     testEnv: environment,
-    testRunId: process.env.TEST_RUN_ID ?? "local",
+    testRunId: process.env.TEST_RUN_ID ?? 'local',
     uiBaseUrl,
     apiBaseUrl,
     credentials: {
       username:
-        secretManager.getOptionalSecret("APP_USERNAME", environment) ?? defaults.credentials.username,
+        secretManager.getOptionalSecret('APP_USERNAME', environment) ??
+        defaults.credentials.username,
       password:
-        secretManager.getOptionalSecret("APP_PASSWORD", environment) ?? defaults.credentials.password
+        secretManager.getOptionalSecret('APP_PASSWORD', environment) ??
+        defaults.credentials.password
     }
   });
 }

package/templates/playwright-template/config/secret-manager.ts

@@ -1,5 +1,5 @@
 // Minimal secret abstraction so env-based secrets can later be replaced cleanly.
-import type { TestEnvironment } from "./test-env";
+import type { TestEnvironment } from './test-env';
 
 export interface SecretProvider {
   getSecret(key: string, testEnv: TestEnvironment): string | undefined;

package/templates/playwright-template/config/test-env.ts

@@ -1,9 +1,9 @@
-import { z } from "zod";
+import { z } from 'zod';
 
-export const testEnvironmentSchema = z.enum(["dev", "staging", "prod"]);
+export const testEnvironmentSchema = z.enum(['dev', 'staging', 'prod']);
 
 export type TestEnvironment = z.infer<typeof testEnvironmentSchema>;
 
 export function loadTestEnvironment(): TestEnvironment {
-  return testEnvironmentSchema.parse(process.env.TEST_ENV ?? "dev");
+  return testEnvironmentSchema.parse(process.env.TEST_ENV ?? 'dev');
 }

package/templates/playwright-template/data/factories/data-factory.ts

@@ -1,6 +1,6 @@
 // Generic data builders that keep tests readable and deterministic.
-import { createSeededFaker } from "../generators/seeded-faker";
-import { IdGenerator } from "../generators/id-generator";
+import { createSeededFaker } from '../generators/seeded-faker';
+import { IdGenerator } from '../generators/id-generator';
 
 export type PersonRecord = {
   personId: string;
@@ -17,7 +17,7 @@ export class DataFactory {
   }
 
   person(overrides?: Partial<PersonRecord>): PersonRecord {
-    const personId = overrides?.personId ?? this.idGenerator.next("person");
+    const personId = overrides?.personId ?? this.idGenerator.next('person');
     const seededFaker = createSeededFaker(`${this.testRunId}:${personId}`);
     const firstName = seededFaker.person.firstName();
     const lastName = seededFaker.person.lastName();
@@ -27,7 +27,9 @@ export class DataFactory {
       personId,
       name,
       role: overrides?.role ?? seededFaker.person.jobTitle(),
-      email: overrides?.email ?? `${firstName}.${lastName}.${personId}@example.test`.toLowerCase(),
+      email:
+        overrides?.email ??
+        `${firstName}.${lastName}.${personId}@example.test`.toLowerCase(),
       ...overrides
     };
   }

package/templates/playwright-template/data/generators/id-generator.ts

@@ -7,7 +7,7 @@ export class IdGenerator {
   next(prefix: string): string {
     const counter = (this.counters.get(prefix) ?? 0) + 1;
     this.counters.set(prefix, counter);
-    return `${prefix}-${this.runId}-${String(counter).padStart(4, "0")}`;
+    return `${prefix}-${this.runId}-${String(counter).padStart(4, '0')}`;
   }
 
   nextSequence(prefix: string): number {

package/templates/playwright-template/data/generators/seeded-faker.ts

@@ -1,8 +1,8 @@
 // Seeded faker wrapper so generated values stay stable for a given run id.
-import { Faker, en } from "@faker-js/faker";
+import { Faker, en } from '@faker-js/faker';
 
 function hashSeed(value: string): number {
-  return value.split("").reduce((seed, character) => {
+  return value.split('').reduce((seed, character) => {
     return ((seed << 5) - seed + character.charCodeAt(0)) | 0;
   }, 0);
 }

package/templates/playwright-template/demo-apps/api-demo-server/src/server.js

@@ -1,25 +1,25 @@
-const express = require("express");
+const express = require('express');
 
-const { createPerson, state } = require("./store");
+const { createPerson, state } = require('./store');
 
 const app = express();
-const host = process.env.HOST || "0.0.0.0";
-const port = Number(process.env.PORT || "3001");
+const host = process.env.HOST || '0.0.0.0';
+const port = Number(process.env.PORT || '3001');
 
 app.use(express.json());
 
-app.get("/health", (_request, response) => {
-  response.json({ status: "ok" });
+app.get('/health', (_request, response) => {
+  response.json({ status: 'ok' });
 });
 
-app.get("/people", (_request, response) => {
+app.get('/people', (_request, response) => {
   response.json(state.people);
 });
 
-app.post("/people", (request, response) => {
+app.post('/people', (request, response) => {
   const { name, role, email } = request.body;
   if (!name || !role || !email) {
-    response.status(400).json({ error: "name, role, and email are required" });
+    response.status(400).json({ error: 'name, role, and email are required' });
     return;
   }
 

package/templates/playwright-template/demo-apps/api-demo-server/src/store.js

@@ -7,7 +7,7 @@ const state = {
 
 function nextId() {
   state.counters.person += 1;
-  return `person-${String(state.counters.person).padStart(4, "0")}`;
+  return `person-${String(state.counters.person).padStart(4, '0')}`;
 }
 
 function getPerson(personId) {

package/templates/playwright-template/demo-apps/ui-demo-app/public/styles.css

@@ -1,6 +1,6 @@
 body {
   margin: 0;
-  font-family: "IBM Plex Sans", "Segoe UI", sans-serif;
+  font-family: 'IBM Plex Sans', 'Segoe UI', sans-serif;
   background: linear-gradient(180deg, #f5f7fb 0%, #eef2f7 100%);
   color: #102038;
 }