@toolstackhq/create-qa-patterns 1.0.12 → 1.0.14

package/templates/cypress-template/package.json

@@ -11,6 +11,8 @@
     "demo:ui": "node ./demo-apps/ui-demo-app/src/server.js",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
+    "report:allure": "node ./scripts/generate-allure-report.mjs",
+    "report:allure:open": "allure open reports/allure",
     "ci": "bash ./scripts/run-tests.sh"
   },
   "dependencies": {
@@ -24,6 +26,8 @@
     "@types/node": "^22.7.4",
     "@typescript-eslint/eslint-plugin": "^8.8.1",
     "@typescript-eslint/parser": "^8.8.1",
+    "allure": "^3.3.1",
+    "allure-cypress": "^3.3.3",
     "cypress": "^13.17.0",
     "eslint": "^9.12.0",
     "typescript": "^5.6.2"

package/templates/cypress-template/scripts/README.md

@@ -0,0 +1,5 @@
+# Scripts
+
+This folder contains local runner helpers for the Cypress template.
+
+- Keep automation entrypoints here so package scripts stay small.

package/templates/cypress-template/scripts/generate-allure-report.mjs

@@ -0,0 +1,66 @@
+// Builds a local Allure report from raw test results after a test run completes.
+import { AllureReport, readConfig } from "@allurereport/core";
+import { readdir, rm, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import process from "node:process";
+
+const cwd = process.cwd();
+const resultsDir = resolve(cwd, "allure-results");
+const outputDir = resolve(cwd, "reports/allure");
+
+const collectResultFiles = async () => {
+  const entries = (await readdir(resultsDir)).sort();
+  const files = [];
+
+  for (const entry of entries) {
+    const filePath = join(resultsDir, entry);
+    const entryStat = await stat(filePath);
+
+    if (entryStat.isFile()) {
+      files.push(filePath);
+    }
+  }
+
+  return files;
+};
+
+const generateReport = async () => {
+  try {
+    await stat(resultsDir);
+  } catch {
+    process.stdout.write("Skipping Allure report generation because allure-results does not exist.\n");
+    return;
+  }
+
+  const files = await collectResultFiles();
+
+  if (files.length === 0) {
+    process.stdout.write("Skipping Allure report generation because no result files were found.\n");
+    return;
+  }
+
+  await rm(outputDir, { force: true, recursive: true });
+
+  const config = await readConfig(cwd, "allurerc.mjs", { output: outputDir });
+  const report = new AllureReport(config);
+
+  await report.start();
+
+  for (const file of files) {
+    await report.readFile(file);
+  }
+
+  await report.done();
+
+  process.stdout.write("Allure report generated at reports/allure/index.html\n");
+};
+
+generateReport().catch((error) => {
+  if (error instanceof Error) {
+    process.stderr.write(`${error.message}\n`);
+  } else {
+    process.stderr.write(`${String(error)}\n`);
+  }
+
+  process.exit(1);
+});

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

@@ -1,5 +1,6 @@
 #!/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";

package/templates/cypress-template/tsconfig.json

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

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
@@ -21,6 +22,7 @@ This is a Playwright + TypeScript automation framework template for UI and API t
 - page object pattern with selectors kept out of tests
 - shared fixtures for config, logging, data, and page objects
 - generic data factory pattern with `DataFactory`
+- folder-level `README.md` guides and file-header comments for easier onboarding
 - multi-environment runtime config with `dev`, `staging`, and `prod`
 - env-based secret resolution with a replaceable `SecretProvider`
 - Playwright HTML report by default
@@ -227,6 +229,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/components/README.md

@@ -0,0 +1,5 @@
+# Components
+
+This folder holds reusable UI fragments shared by multiple pages.
+
+- Use components for repeated widgets such as flash messages or shared panels.

package/templates/playwright-template/config/README.md

@@ -0,0 +1,5 @@
+# Config
+
+This folder resolves environment-specific runtime values.
+
+- Keep environment defaults, secret lookup, and runtime parsing here.

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

@@ -1,3 +1,4 @@
+// Defines the built-in environment defaults used when env vars are not provided.
 import type { TestEnvironment } from "./test-env";
 
 type EnvironmentDefaults = {

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

@@ -1,3 +1,4 @@
+// Builds the runtime configuration object that tests and fixtures consume.
 import path from "node:path";
 
 import dotenv from "dotenv";

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

@@ -1,3 +1,4 @@
+// Minimal secret abstraction so env-based secrets can later be replaced cleanly.
 import type { TestEnvironment } from "./test-env";
 
 export interface SecretProvider {

package/templates/playwright-template/data/factories/README.md

@@ -0,0 +1,6 @@
+# Factories
+
+This folder exposes small, readable builders for test data.
+
+- Start generic.
+- Add domain-specific builders only when the project needs them.

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

@@ -1,3 +1,4 @@
+// Generic data builders that keep tests readable and deterministic.
 import { createSeededFaker } from "../generators/seeded-faker";
 import { IdGenerator } from "../generators/id-generator";
 

package/templates/playwright-template/data/generators/README.md

@@ -0,0 +1,5 @@
+# Generators
+
+This folder contains low-level helpers that factories build on.
+
+- Keep seeded randomness and id generation here.

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

@@ -1,3 +1,4 @@
+// Deterministic id generator for repeatable local and CI runs.
 export class IdGenerator {
   private readonly counters = new Map<string, number>();
 

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

@@ -1,3 +1,4 @@
+// Seeded faker wrapper so generated values stay stable for a given run id.
 import { Faker, en } from "@faker-js/faker";
 
 function hashSeed(value: string): number {

package/templates/playwright-template/fixtures/README.md

@@ -0,0 +1,5 @@
+# Fixtures
+
+This folder wires together the objects that tests consume.
+
+- Put shared setup, config loading, and page creation here.

package/templates/playwright-template/fixtures/test-fixtures.ts

@@ -1,3 +1,4 @@
+// Shared Playwright fixtures so tests can stay small and focus on behavior.
 import { test as base } from "@playwright/test";
 
 import { loadRuntimeConfig, type RuntimeConfig } from "../config/runtime-config";

package/templates/playwright-template/pages/README.md

@@ -0,0 +1,6 @@
+# Pages
+
+This folder holds Playwright page objects.
+
+- Page classes own locators and UI actions.
+- Tests should talk to these classes instead of raw selectors.

package/templates/playwright-template/pages/base-page.ts

@@ -1,3 +1,4 @@
+// Base page with shared helpers that concrete page objects can build on.
 import type { Page } from "@playwright/test";
 
 import { FlashMessage } from "../components/flash-message";

package/templates/playwright-template/pages/login-page.ts

@@ -1,3 +1,4 @@
+// Page object for the login screen and its user actions.
 import type { Page } from "@playwright/test";
 
 import type { Logger } from "../utils/logger";

package/templates/playwright-template/pages/people-page.ts

@@ -1,3 +1,4 @@
+// Page object for the people screen used in the starter UI workflow.
 import type { Page } from "@playwright/test";
 
 import type { PersonRecord } from "../data/factories/data-factory";

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

@@ -1,3 +1,4 @@
+// Central Playwright configuration for local runs, CI, reporters, and demo app startup.
 import { defineConfig, devices } from "@playwright/test";
 
 import { loadRuntimeConfig } from "./config/runtime-config";

package/templates/playwright-template/reporters/README.md

@@ -0,0 +1,5 @@
+# Reporters
+
+This folder contains custom Playwright reporters.
+
+- Use these when you need machine-readable output in addition to built-in reports.

package/templates/playwright-template/reporters/structured-reporter.ts

@@ -1,3 +1,4 @@
+// Custom reporter that writes machine-readable test lifecycle events to disk.
 import fs from "node:fs";
 import path from "node:path";
 

package/templates/playwright-template/scripts/README.md

@@ -0,0 +1,5 @@
+# Scripts
+
+This folder contains helper scripts used by local development and CI.
+
+- Keep shell and Node entrypoints here instead of inside workflow files.

package/templates/playwright-template/scripts/generate-allure-report.mjs

@@ -1,3 +1,4 @@
+// Builds a local Allure report from raw test results after a test run completes.
 import { AllureReport, readConfig } from "@allurereport/core";
 import { readdir, rm, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";

package/templates/playwright-template/tests/README.md

@@ -0,0 +1,7 @@
+# Tests
+
+This folder holds user-facing Playwright scenarios.
+
+- Keep tests focused on behavior and business flow.
+- Use fixtures from `../fixtures/test-fixtures`.
+- Keep selectors out of test files.

package/templates/playwright-template/tests/api-people.spec.ts

@@ -1,3 +1,4 @@
+// Starter API journey that pairs with the deterministic demo API server.
 import { expect, test } from "../fixtures/test-fixtures";
 
 test.describe("API starter flow", () => {

package/templates/playwright-template/tests/ui-journey.spec.ts

@@ -1,3 +1,4 @@
+// Starter UI journey that shows the preferred Playwright test style in this template.
 import { expect, test } from "../fixtures/test-fixtures";
 
 test.describe("UI starter journey", () => {

package/templates/playwright-template/utils/README.md

@@ -0,0 +1,5 @@
+# Utils
+
+This folder holds small framework helpers.
+
+- Put generic logging and step wrappers here.

package/templates/playwright-template/utils/logger.ts

@@ -1,3 +1,4 @@
+// Structured JSON logger used by tests, pages, and helper classes.
 import fs from "node:fs";
 import path from "node:path";
 

package/templates/playwright-template/utils/test-step.ts

@@ -1,3 +1,4 @@
+// Small wrapper that records named test steps in a consistent way.
 import { test } from "@playwright/test";
 
 import type { Logger } from "./logger";