@toolstackhq/create-qa-patterns 1.0.6 → 1.0.8

package/README.md

@@ -20,15 +20,24 @@ Generate into a new directory:
 create-qa-patterns my-project
 ```
 
+The generated project is initialized with `git init` automatically and includes a default `.gitignore` for common local artifacts.
+
 Generate the Playwright template explicitly:
 
 ```bash
 create-qa-patterns playwright-template my-project
 ```
 
+Generate the Cypress template explicitly:
+
+```bash
+create-qa-patterns cypress-template my-project
+```
+
 ## Supported templates
 
 - `playwright-template`
+- `cypress-template`
 
 ## Interactive flow
 
@@ -39,16 +48,20 @@ When run in a terminal, the CLI shows:
 - scaffold progress while files are generated
 - optional post-generate actions for:
   - `npm install`
-  - `npx playwright install`
   - `npm test`
 
+For Playwright projects, the interactive flow also offers:
+
+- `npx playwright install`
+
 ## Prerequisite checks
 
 The CLI checks:
 
 - required Node.js version
 - `npm` availability for install and test actions
-- `npx` availability for Playwright browser installation
+- `npx` availability for template setup that depends on it
 - `docker` availability and warns if it is missing
+- `git` availability so the scaffold can start as a repository immediately
 
 If `npx playwright install` fails because the host is missing browser dependencies, the CLI keeps the generated project and prints the recovery steps instead of treating scaffold generation as failed.

package/index.js

@@ -18,7 +18,24 @@ const DEFAULT_GITIGNORE = `node_modules/
 .env.*
 !.env.example
 
+.DS_Store
+*.log
+*.tgz
+.idea/
+.vscode/
+.nyc_output/
+coverage/
+dist/
+build/
+tmp/
+temp/
+downloads/
+cypress.env.json
 reports/
+cypress/screenshots/
+cypress/videos/
+reports/screenshots/
+reports/videos/
 allure-results/
 allure-report/
 test-results/
@@ -30,7 +47,29 @@ const TEMPLATES = [
     id: DEFAULT_TEMPLATE,
     aliases: ["playwright", "pw"],
     label: "Playwright Template",
-    description: "TypeScript starter with page objects, fixtures, multi-environment config, reporting, linting, CI and Docker."
+    description: "TypeScript starter with page objects, fixtures, multi-environment config, reporting, linting, CI and Docker.",
+    defaultPackageName: "playwright-template",
+    demoAppsManagedByTemplate: true,
+    setup: {
+      availability: "npx",
+      prompt: "Run npx playwright install now?",
+      summaryLabel: "Playwright browser install",
+      nextStep: "npx playwright install",
+      run(targetDirectory) {
+        return runCommand("npx", ["playwright", "install"], targetDirectory);
+      },
+      recovery(targetDirectory) {
+        printPlaywrightInstallRecovery(targetDirectory);
+      }
+    }
+  },
+  {
+    id: "cypress-template",
+    aliases: ["cypress", "cy"],
+    label: "Cypress Template",
+    description: "TypeScript starter with Cypress e2e specs, custom commands, page modules, env-based config, CI, and a bundled demo app.",
+    defaultPackageName: "cypress-template",
+    demoAppsManagedByTemplate: true
   }
 ];
 
@@ -71,6 +110,8 @@ const colors = {
 };
 
 function printHelp() {
+  const supportedTemplates = TEMPLATES.map((template) => `  ${template.id}${template.aliases.length > 0 ? ` (${template.aliases.join(", ")})` : ""}`).join("\n");
+
   process.stdout.write(`${colors.bold("create-qa-patterns")}
 
 Usage:
@@ -82,9 +123,7 @@ Interactive mode:
   When run without an explicit template, the CLI shows an interactive template picker.
 
 Supported templates:
-  playwright-template
-  playwright
-  pw
+${supportedTemplates}
 `);
 }
 
@@ -145,7 +184,8 @@ function collectPrerequisites() {
   return {
     npm: commandExists("npm"),
     npx: commandExists("npx"),
-    docker: commandExists("docker")
+    docker: commandExists("docker"),
+    git: commandExists("git")
   };
 }
 
@@ -155,14 +195,18 @@ function printPrerequisiteWarnings(prerequisites) {
   }
 
   if (!prerequisites.npx) {
-    process.stdout.write(`${colors.yellow("Warning:")} npx was not found. Playwright browser installation will be unavailable.\n`);
+    process.stdout.write(`${colors.yellow("Warning:")} npx was not found. Template setup steps that depend on npx will be unavailable.\n`);
   }
 
   if (!prerequisites.docker) {
     process.stdout.write(`${colors.yellow("Warning:")} docker was not found. Docker-based template flows will not run until Docker is installed.\n`);
   }
 
-  if (!prerequisites.npm || !prerequisites.npx || !prerequisites.docker) {
+  if (!prerequisites.git) {
+    process.stdout.write(`${colors.yellow("Warning:")} git was not found. The generated project cannot be initialized as a repository automatically.\n`);
+  }
+
+  if (!prerequisites.npm || !prerequisites.npx || !prerequisites.docker || !prerequisites.git) {
     process.stdout.write("\n");
   }
 }
@@ -174,14 +218,15 @@ function createLineInterface() {
   });
 }
 
-function createSummary(templateName, targetDirectory, generatedInCurrentDirectory, demoAppsManagedByTemplate) {
+function createSummary(template, targetDirectory, generatedInCurrentDirectory) {
   return {
-    templateName,
+    template,
     targetDirectory,
     generatedInCurrentDirectory,
-    demoAppsManagedByTemplate,
+    demoAppsManagedByTemplate: Boolean(template.demoAppsManagedByTemplate),
+    gitInit: "not-run",
     npmInstall: "not-run",
-    playwrightInstall: "not-run",
+    extraSetup: template.setup ? "not-run" : null,
     testRun: "not-run"
   };
 }
@@ -333,7 +378,9 @@ function resolveNonInteractiveArgs(args) {
     const templateName = resolveTemplate(args[0]);
 
     if (!templateName) {
-      throw new Error(`Unsupported template "${args[0]}". Use "playwright-template".`);
+      throw new Error(
+        `Unsupported template "${args[0]}". Supported templates: ${TEMPLATES.map((template) => template.id).join(", ")}.`
+      );
     }
 
     return {
@@ -385,14 +432,14 @@ function ensureScaffoldTarget(targetDirectory) {
   }
 }
 
-function toPackageName(targetDirectory) {
+function toPackageName(targetDirectory, template) {
   const baseName = path.basename(targetDirectory).toLowerCase();
   const normalized = baseName
     .replace(/[^a-z0-9-_]+/g, "-")
     .replace(/^-+|-+$/g, "")
     .replace(/-{2,}/g, "-");
 
-  return normalized || "playwright-template";
+  return normalized || template.defaultPackageName || "qa-patterns-template";
 }
 
 function updateJsonFile(filePath, update) {
@@ -401,8 +448,8 @@ function updateJsonFile(filePath, update) {
   fs.writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
 }
 
-function customizeProject(targetDirectory) {
-  const packageName = toPackageName(targetDirectory);
+function customizeProject(targetDirectory, template) {
+  const packageName = toPackageName(targetDirectory, template);
   const packageJsonPath = path.join(targetDirectory, "package.json");
   const packageLockPath = path.join(targetDirectory, "package-lock.json");
   const gitignorePath = path.join(targetDirectory, ".gitignore");
@@ -435,6 +482,21 @@ function customizeProject(targetDirectory) {
   }
 }
 
+function initializeGitRepository(targetDirectory) {
+  if (fs.existsSync(path.join(targetDirectory, ".git"))) {
+    return;
+  }
+
+  const result = spawnSync(getCommandName("git"), ["init"], {
+    cwd: targetDirectory,
+    encoding: "utf8"
+  });
+
+  if (result.status !== 0) {
+    throw new Error(result.stderr || "git init failed.");
+  }
+}
+
 function renderProgress(completed, total, label) {
   const width = 24;
   const filled = Math.round((completed / total) * width);
@@ -444,7 +506,8 @@ function renderProgress(completed, total, label) {
   process.stdout.write(`\r[${bar}] ${percentage}% ${label}`);
 }
 
-async function scaffoldProject(templateName, targetDirectory) {
+async function scaffoldProject(template, targetDirectory, prerequisites) {
+  const templateName = template.id;
   const templateDirectory = path.resolve(__dirname, "templates", templateName);
 
   if (!fs.existsSync(templateDirectory)) {
@@ -469,10 +532,14 @@ async function scaffoldProject(templateName, targetDirectory) {
   renderProgress(2, steps.length, steps[1]);
   await sleep(80);
 
-  customizeProject(targetDirectory);
+  customizeProject(targetDirectory, template);
   renderProgress(3, steps.length, steps[2]);
   await sleep(80);
 
+  if (prerequisites.git) {
+    initializeGitRepository(targetDirectory);
+  }
+
   renderProgress(4, steps.length, steps[3]);
   await sleep(60);
   process.stdout.write("\n");
@@ -526,11 +593,9 @@ function runCommand(command, args, cwd) {
   });
 }
 
-function printSuccess(templateName, targetDirectory, generatedInCurrentDirectory) {
-  const template = getTemplate(templateName);
-
+function printSuccess(template, targetDirectory, generatedInCurrentDirectory) {
   process.stdout.write(`\n${colors.green(colors.bold("Success"))}
-Generated ${template ? template.label : templateName} in ${targetDirectory}
+Generated ${template ? template.label : template.id} in ${targetDirectory}
 \n`);
 
   if (!generatedInCurrentDirectory) {
@@ -549,8 +614,8 @@ function printNextSteps(summary) {
     steps.push("npm install");
   }
 
-  if (summary.playwrightInstall !== "completed") {
-    steps.push("npx playwright install");
+  if (summary.template.setup && summary.extraSetup !== "completed") {
+    steps.push(summary.template.setup.nextStep);
   }
 
   if (summary.testRun !== "completed") {
@@ -591,17 +656,20 @@ function formatStatus(status) {
 
 function printSummary(summary) {
   process.stdout.write(`\n${colors.bold("Summary")}\n`);
-  process.stdout.write(`  Template: ${summary.templateName}\n`);
+  process.stdout.write(`  Template: ${summary.template.id}\n`);
   process.stdout.write(`  Target: ${summary.targetDirectory}\n`);
+  process.stdout.write(`  Git repository: ${formatStatus(summary.gitInit)}\n`);
   process.stdout.write(
     `  Demo apps: ${summary.demoAppsManagedByTemplate ? "bundled and auto-started in dev when using default local URLs" : "external application required"}\n`
   );
   process.stdout.write(`  npm install: ${formatStatus(summary.npmInstall)}\n`);
-  process.stdout.write(`  Playwright browser install: ${formatStatus(summary.playwrightInstall)}\n`);
+  if (summary.template.setup) {
+    process.stdout.write(`  ${summary.template.setup.summaryLabel}: ${formatStatus(summary.extraSetup)}\n`);
+  }
   process.stdout.write(`  npm test: ${formatStatus(summary.testRun)}\n`);
 }
 
-async function runPostGenerateActions(targetDirectory, summary) {
+async function runPostGenerateActions(template, targetDirectory, summary) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     return;
   }
@@ -622,29 +690,35 @@ async function runPostGenerateActions(targetDirectory, summary) {
     summary.npmInstall = "unavailable";
   }
 
-  if (prerequisites.npx) {
-    const shouldInstallPlaywright = await askYesNo("Run npx playwright install now?", true);
+  if (template.setup) {
+    if (prerequisites[template.setup.availability]) {
+      const shouldRunExtraSetup = await askYesNo(template.setup.prompt, true);
 
-    if (shouldInstallPlaywright) {
-      try {
-        await runCommand("npx", ["playwright", "install"], targetDirectory);
-        summary.playwrightInstall = "completed";
-      } catch (error) {
-        summary.playwrightInstall = "manual-recovery";
-        printPlaywrightInstallRecovery(targetDirectory);
+      if (shouldRunExtraSetup) {
+        try {
+          await template.setup.run(targetDirectory);
+          summary.extraSetup = "completed";
+        } catch (error) {
+          summary.extraSetup = "manual-recovery";
+          if (typeof template.setup.recovery === "function") {
+            template.setup.recovery(targetDirectory);
+          }
 
-        const shouldContinue = await askYesNo("Continue without completing Playwright browser install?", true);
+          const shouldContinue = await askYesNo("Continue without completing setup?", true);
 
-        if (!shouldContinue) {
-          throw error;
+          if (!shouldContinue) {
+            throw error;
+          }
         }
+      } else {
+        summary.extraSetup = "skipped";
       }
     } else {
-      summary.playwrightInstall = "skipped";
+      process.stdout.write(
+        `${colors.yellow("Skipping")} ${template.setup.summaryLabel.toLowerCase()} prompt because ${template.setup.availability} is not available.\n`
+      );
+      summary.extraSetup = "unavailable";
     }
-  } else {
-    process.stdout.write(`${colors.yellow("Skipping")} Playwright browser install prompt because npx is not available.\n`);
-    summary.playwrightInstall = "unavailable";
   }
 
   if (prerequisites.npm) {
@@ -673,11 +747,19 @@ async function main() {
   }
 
   const { templateName, targetDirectory, generatedInCurrentDirectory } = await resolveScaffoldArgs(args);
-  const summary = createSummary(templateName, targetDirectory, generatedInCurrentDirectory, true);
-  printPrerequisiteWarnings(collectPrerequisites());
-  await scaffoldProject(templateName, targetDirectory);
-  printSuccess(templateName, targetDirectory, generatedInCurrentDirectory);
-  await runPostGenerateActions(targetDirectory, summary);
+  const template = getTemplate(templateName);
+
+  if (!template) {
+    throw new Error(`Unsupported template "${templateName}".`);
+  }
+
+  const prerequisites = collectPrerequisites();
+  const summary = createSummary(template, targetDirectory, generatedInCurrentDirectory);
+  printPrerequisiteWarnings(prerequisites);
+  await scaffoldProject(template, targetDirectory, prerequisites);
+  summary.gitInit = prerequisites.git ? "completed" : "unavailable";
+  printSuccess(template, targetDirectory, generatedInCurrentDirectory);
+  await runPostGenerateActions(template, targetDirectory, summary);
   printSummary(summary);
   printNextSteps(summary);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolstackhq/create-qa-patterns",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "CLI for generating QA framework templates.",
   "license": "MIT",
   "repository": {

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

@@ -0,0 +1,5 @@
+TEST_ENV=dev
+TEST_RUN_ID=local
+DEV_UI_BASE_URL=http://127.0.0.1:3000
+DEV_APP_USERNAME=tester
+DEV_APP_PASSWORD=Password123!

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

@@ -0,0 +1,47 @@
+name: Cypress Template Validation
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+
+jobs:
+  cypress-template:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install template dependencies
+        working-directory: templates/cypress-template
+        run: npm ci
+
+      - name: Run lint and typecheck
+        working-directory: templates/cypress-template
+        run: |
+          npm run lint
+          npm run typecheck
+
+      - name: Run Cypress tests
+        uses: cypress-io/github-action@v7
+        with:
+          working-directory: templates/cypress-template
+          install: false
+          start: npm run demo:ui
+          wait-on: "http://127.0.0.1:3000/health"
+          command: npm run cy:run
+
+      - name: Upload Cypress artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: cypress-template-artifacts
+          path: |
+            templates/cypress-template/reports

package/templates/cypress-template/README.md

@@ -0,0 +1,195 @@
+# Cypress Template
+
+This is a Cypress + TypeScript automation framework template for a small deterministic UI flow.
+
+## Table of contents
+
+- [Feature set](#feature-set)
+- [How it works](#how-it-works)
+- [Project structure](#project-structure)
+- [Quick start](#quick-start)
+- [Environment and secrets](#environment-and-secrets)
+- [Main commands](#main-commands)
+- [Reports and artifacts](#reports-and-artifacts)
+- [Add a new test](#add-a-new-test)
+- [Extend the framework](#extend-the-framework)
+- [CI](#ci)
+
+## Feature set
+
+- Cypress + TypeScript setup
+- Cypress-native custom commands for common user actions
+- page modules that own selectors and keep spec files focused on behavior
+- generic `DataFactory` helpers for repeatable UI data
+- multi-environment runtime config with `dev`, `staging`, and `prod`
+- env-based secret resolution with a replaceable `SecretProvider`
+- built-in screenshots and videos on failure
+- ESLint rules that keep selectors out of spec files
+- bundled deterministic UI demo app and GitHub Actions workflow
+
+## How it works
+
+- tests live in `cypress/e2e/`
+- shared Cypress commands live in `cypress/support/commands.ts`
+- selectors and page-level helpers live in `cypress/support/pages/`
+- runtime config is loaded from `config/runtime-config.ts`
+- bundled demo app auto-starts during `npm test` and `npm run open` in local `dev` when the default local URL is in use
+- screenshots and videos are written under `reports/`
+
+## Project structure
+
+```text
+cypress-template
+├── cypress
+│   ├── e2e
+│   └── support
+├── config
+├── demo-apps
+├── scripts
+├── .github
+├── cypress.config.ts
+└── package.json
+```
+
+## Quick start
+
+1. Install dependencies.
+
+```bash
+npm install
+```
+
+2. Run the example test.
+
+```bash
+npm test
+```
+
+In local `dev`, the template starts its bundled demo app automatically when the default local URL is still in use.
+
+If you want the interactive Cypress runner:
+
+```bash
+npm run open
+```
+
+If you want to run the demo app manually for debugging:
+
+```bash
+npm run demo:ui
+```
+
+Default local values:
+
+- UI base URL: `http://127.0.0.1:3000`
+- username: `tester`
+- password: `Password123!`
+
+## Environment and secrets
+
+The template supports:
+
+- `TEST_ENV=dev`
+- `TEST_ENV=staging`
+- `TEST_ENV=prod`
+
+Runtime values are resolved in this order:
+
+1. environment-specific variables such as `DEV_UI_BASE_URL`
+2. generic variables such as `UI_BASE_URL`
+3. built-in defaults from `config/environments.ts`
+
+Credentials resolve the same way:
+
+1. `DEV_APP_USERNAME` or `DEV_APP_PASSWORD`
+2. `APP_USERNAME` or `APP_PASSWORD`
+3. built-in defaults for the selected environment
+
+For local overrides, copy:
+
+```bash
+.env.example
+```
+
+to:
+
+```bash
+.env
+```
+
+If you want to disable the bundled local demo app even in `dev`, use:
+
+```bash
+CY_DISABLE_LOCAL_DEMO_APP=true npm test
+```
+
+If your team later uses a real secret system, replace the implementation behind `config/secret-manager.ts`.
+
+## Main commands
+
+```bash
+npm test
+npm run open
+npm run demo:ui
+npm run lint
+npm run typecheck
+npm run cy:run
+```
+
+## Reports and artifacts
+
+Outputs:
+
+- Cypress videos: `reports/videos`
+- Cypress screenshots: `reports/screenshots`
+
+The default Cypress terminal output is kept as the main reporting path.
+
+## Add a new test
+
+Create tests under `cypress/e2e/`.
+
+Keep the pattern simple:
+
+- create data with `DataFactory`
+- interact through custom commands or page modules
+- assert in the test
+
+Example shape:
+
+```ts
+it("does something", () => {
+  const dataFactory = new DataFactory("local");
+  const person = dataFactory.person();
+
+  cy.signIn("tester", "Password123!");
+  cy.addPerson(person);
+});
+```
+
+## Extend the framework
+
+Common extension points:
+
+- update or replace the bundled demo app under `demo-apps/`
+- add page modules under `cypress/support/pages/`
+- add shared custom commands in `cypress/support/commands.ts`
+- extend generic data builders in `cypress/support/data/`
+- add stronger lint rules in `eslint.config.mjs`
+
+Recommended rules:
+
+- keep selectors in support/page modules or custom commands
+- keep assertions in spec files
+- use Cypress commands for workflows, not giant helper classes
+- keep the data layer generic until the project really needs domain-specific factories
+
+## CI
+
+The included workflow lives at:
+
+```bash
+.github/workflows/cypress-tests.yml
+```
+
+It installs dependencies, starts the bundled demo app, runs Cypress tests, and uploads screenshots and videos as artifacts.

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

@@ -0,0 +1,37 @@
+import type { TestEnvironment } from "./test-env";
+
+type EnvironmentDefaults = {
+  uiBaseUrl: string;
+  credentials: {
+    username: string;
+    password: string;
+  };
+};
+
+const environmentDefaults: Record<TestEnvironment, EnvironmentDefaults> = {
+  dev: {
+    uiBaseUrl: "http://127.0.0.1:3000",
+    credentials: {
+      username: "tester",
+      password: "Password123!"
+    }
+  },
+  staging: {
+    uiBaseUrl: "https://staging-ui.example.internal",
+    credentials: {
+      username: "staging-user",
+      password: "staging-password"
+    }
+  },
+  prod: {
+    uiBaseUrl: "https://ui.example.internal",
+    credentials: {
+      username: "prod-user",
+      password: "prod-password"
+    }
+  }
+};
+
+export function getEnvironmentDefaults(environment: TestEnvironment): EnvironmentDefaults {
+  return environmentDefaults[environment];
+}