@toolstackhq/create-qa-patterns 1.0.0 → 1.0.1

package/README.md

@@ -1,24 +1,31 @@
 # @toolstackhq/create-qa-patterns
 
-This package is the future scaffolding entrypoint for the `qa-patterns` repository.
+CLI for generating QA framework templates from `qa-patterns`.
 
-## Current status
+## Install
 
-The package is intentionally minimal today. It exists so the repository can reserve the CLI name and publish a stable install target while the scaffold commands evolve.
+```bash
+npm install -g @toolstackhq/create-qa-patterns
+```
 
 ## Usage
 
 ```bash
-npm install -g @toolstackhq/create-qa-patterns
 create-qa-patterns
 ```
 
-Current output:
+Generate into a new directory:
+
+```bash
+create-qa-patterns my-project
+```
+
+Generate the Playwright template explicitly:
 
-- prints a placeholder message
+```bash
+create-qa-patterns playwright-template my-project
+```
 
-Planned direction:
+## Supported templates
 
-- scaffold a Playwright automation framework
-- scaffold reference demo applications
-- generate standardized config, lint, CI, and reporting assets
+- `playwright-template`

package/index.js

@@ -1,3 +1,199 @@
 #!/usr/bin/env node
 
-console.log("create-qa-patterns is reserved for future repository scaffolding workflows.");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const DEFAULT_TEMPLATE = "playwright-template";
+const DEFAULT_GITIGNORE = `node_modules/
+
+.env
+.env.*
+!.env.example
+
+reports/
+allure-results/
+allure-report/
+test-results/
+playwright-report/
+`;
+const TEMPLATE_ALIASES = new Map([
+  ["playwright", DEFAULT_TEMPLATE],
+  ["pw", DEFAULT_TEMPLATE],
+  [DEFAULT_TEMPLATE, DEFAULT_TEMPLATE]
+]);
+
+function printHelp() {
+  process.stdout.write(`create-qa-patterns
+
+Usage:
+  create-qa-patterns
+  create-qa-patterns <target-directory>
+  create-qa-patterns <template> [target-directory]
+
+Supported templates:
+  playwright-template
+  playwright
+  pw
+`);
+}
+
+function resolveTemplate(value) {
+  return TEMPLATE_ALIASES.get(value);
+}
+
+function resolveScaffoldArgs(args) {
+  if (args.length === 0) {
+    return {
+      templateName: DEFAULT_TEMPLATE,
+      targetDirectory: process.cwd(),
+      generatedInCurrentDirectory: true
+    };
+  }
+
+  if (args.length === 1) {
+    const templateName = resolveTemplate(args[0]);
+    if (templateName) {
+      return {
+        templateName,
+        targetDirectory: process.cwd(),
+        generatedInCurrentDirectory: true
+      };
+    }
+
+    return {
+      templateName: DEFAULT_TEMPLATE,
+      targetDirectory: path.resolve(process.cwd(), args[0]),
+      generatedInCurrentDirectory: false
+    };
+  }
+
+  if (args.length === 2) {
+    const templateName = resolveTemplate(args[0]);
+    if (!templateName) {
+      throw new Error(`Unsupported template "${args[0]}". Use "playwright-template".`);
+    }
+
+    return {
+      templateName,
+      targetDirectory: path.resolve(process.cwd(), args[1]),
+      generatedInCurrentDirectory: false
+    };
+  }
+
+  throw new Error("Too many arguments. Run `create-qa-patterns --help` for usage.");
+}
+
+function ensureScaffoldTarget(targetDirectory) {
+  if (!fs.existsSync(targetDirectory)) {
+    fs.mkdirSync(targetDirectory, { recursive: true });
+    return;
+  }
+
+  const entries = fs
+    .readdirSync(targetDirectory)
+    .filter((entry) => ![".git", ".DS_Store"].includes(entry));
+
+  if (entries.length > 0) {
+    throw new Error(`Target directory is not empty: ${targetDirectory}`);
+  }
+}
+
+function toPackageName(targetDirectory) {
+  const baseName = path.basename(targetDirectory).toLowerCase();
+  const normalized = baseName
+    .replace(/[^a-z0-9-_]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+
+  return normalized || "playwright-template";
+}
+
+function updateJsonFile(filePath, update) {
+  const current = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  const next = update(current);
+  fs.writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+}
+
+function customizeProject(targetDirectory) {
+  const packageName = toPackageName(targetDirectory);
+  const packageJsonPath = path.join(targetDirectory, "package.json");
+  const packageLockPath = path.join(targetDirectory, "package-lock.json");
+  const gitignorePath = path.join(targetDirectory, ".gitignore");
+
+  if (fs.existsSync(packageJsonPath)) {
+    updateJsonFile(packageJsonPath, (pkg) => ({
+      ...pkg,
+      name: packageName
+    }));
+  }
+
+  if (fs.existsSync(packageLockPath)) {
+    updateJsonFile(packageLockPath, (lock) => ({
+      ...lock,
+      name: packageName,
+      packages: lock.packages
+        ? {
+            ...lock.packages,
+            "": {
+              ...lock.packages[""],
+              name: packageName
+            }
+          }
+        : lock.packages
+    }));
+  }
+
+  if (!fs.existsSync(gitignorePath)) {
+    fs.writeFileSync(gitignorePath, DEFAULT_GITIGNORE, "utf8");
+  }
+}
+
+function scaffoldProject(templateName, targetDirectory) {
+  const templateDirectory = path.resolve(__dirname, "templates", templateName);
+
+  if (!fs.existsSync(templateDirectory)) {
+    throw new Error(`Template files are missing for "${templateName}".`);
+  }
+
+  ensureScaffoldTarget(targetDirectory);
+  fs.cpSync(templateDirectory, targetDirectory, { recursive: true });
+  customizeProject(targetDirectory);
+}
+
+function printNextSteps(targetDirectory, generatedInCurrentDirectory) {
+  process.stdout.write(`Generated ${DEFAULT_TEMPLATE} in ${targetDirectory}
+
+Next steps:
+`);
+
+  if (!generatedInCurrentDirectory) {
+    process.stdout.write(`  cd ${path.relative(process.cwd(), targetDirectory) || "."}
+`);
+  }
+
+  process.stdout.write(`  npm install
+  npx playwright install
+  npm test
+`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  const { templateName, targetDirectory, generatedInCurrentDirectory } = resolveScaffoldArgs(args);
+  scaffoldProject(templateName, targetDirectory);
+  printNextSteps(targetDirectory, generatedInCurrentDirectory);
+}
+
+try {
+  main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@toolstackhq/create-qa-patterns",
-  "version": "1.0.0",
-  "description": "Placeholder CLI for future test framework scaffolding.",
+  "version": "1.0.1",
+  "description": "CLI for generating QA framework templates.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
   },
   "files": [
     "index.js",
+    "templates",
     "README.md",
     "LICENSE"
   ],
@@ -24,6 +25,6 @@
   },
   "scripts": {
     "start": "node ./index.js",
-    "test": "node ./index.js"
+    "test": "node ./index.js --help"
   }
 }

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

@@ -0,0 +1,17 @@
+TEST_ENV=dev
+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!
+
+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
+
+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

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

@@ -0,0 +1,126 @@
+name: Playwright Template Validation
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - "templates/playwright-template/**"
+      - "test-apps/**"
+      - "package.json"
+
+jobs:
+  playwright:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install workspace dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        working-directory: templates/playwright-template
+        run: npx playwright install --with-deps chromium
+
+      - name: Start API demo server
+        run: npm run dev --workspace @toolstackhq/api-demo-server &
+
+      - name: Start UI demo app
+        run: npm run dev --workspace @toolstackhq/ui-demo-app &
+
+      - name: Wait for demo services
+        run: |
+          for target in http://127.0.0.1:3000/health http://127.0.0.1:3001/health; do
+            until curl --silent --fail "$target" >/dev/null; do
+              sleep 1
+            done
+          done
+
+      - name: Run Playwright validation
+        working-directory: templates/playwright-template
+        env:
+          TEST_ENV: dev
+          TEST_RUN_ID: ci
+        run: bash ./scripts/run-tests.sh
+
+      - name: Generate Allure report
+        if: always()
+        working-directory: templates/playwright-template
+        run: npm run report:allure
+
+      - name: Upload Playwright artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-template-artifacts
+          path: |
+            templates/playwright-template/reports
+            templates/playwright-template/allure-results
+            templates/playwright-template/test-results
+
+  playwright-docker:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install workspace dependencies
+        run: npm ci
+
+      - name: Start API demo server
+        run: npm run dev --workspace @toolstackhq/api-demo-server &
+
+      - name: Start UI demo app
+        run: npm run dev --workspace @toolstackhq/ui-demo-app &
+
+      - name: Wait for demo services
+        run: |
+          for target in http://127.0.0.1:3000/health http://127.0.0.1:3001/health; do
+            until curl --silent --fail "$target" >/dev/null; do
+              sleep 1
+            done
+          done
+
+      - name: Prepare Docker artifacts directories
+        run: |
+          rm -rf templates/playwright-template/reports templates/playwright-template/test-results templates/playwright-template/allure-results
+          mkdir -p templates/playwright-template/reports templates/playwright-template/test-results templates/playwright-template/allure-results
+
+      - name: Build Playwright template Docker image
+        run: docker build -t qa-patterns-playwright-template:ci -f templates/playwright-template/docker/Dockerfile templates/playwright-template
+
+      - name: Run Playwright template inside Docker
+        run: |
+          docker run --rm \
+            --add-host=host.docker.internal:host-gateway \
+            -e TEST_ENV=dev \
+            -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 \
+            -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" \
+            qa-patterns-playwright-template:ci
+
+      - name: Generate Allure report
+        if: always()
+        working-directory: templates/playwright-template
+        run: npm run report:allure
+
+      - name: Upload Docker Playwright artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-template-docker-artifacts
+          path: |
+            templates/playwright-template/reports
+            templates/playwright-template/allure-results
+            templates/playwright-template/test-results

package/templates/playwright-template/README.md

@@ -0,0 +1,234 @@
+# Playwright Template
+
+This is a Playwright + TypeScript automation framework template for UI and API tests.
+
+## 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 and Docker](#ci-and-docker)
+
+## Feature set
+
+- Playwright + TypeScript setup
+- page object pattern with selectors kept out of tests
+- shared fixtures for config, logging, data, and page objects
+- generic data factory pattern with `DataFactory`
+- multi-environment runtime config with `dev`, `staging`, and `prod`
+- env-based secret resolution with a replaceable `SecretProvider`
+- Playwright HTML report by default
+- optional Allure single-file report
+- traces, screenshots, videos, and structured logs for debugging
+- ESLint rules that protect framework conventions
+- GitHub Actions workflow and Docker support
+
+## How it works
+
+- tests import shared fixtures from `fixtures/test-fixtures.ts`
+- page objects in `pages/` own locators and user actions
+- runtime config is loaded from `config/runtime-config.ts`
+- application URLs and credentials are resolved from `TEST_ENV`
+- reports and artifacts are written under `reports/`, `allure-results/`, and `test-results/`
+
+## Project structure
+
+```text
+playwright-template
+├── tests
+├── pages
+├── components
+├── fixtures
+├── data
+├── config
+├── reporters
+├── utils
+├── lint
+├── scripts
+├── docker
+├── playwright.config.ts
+└── package.json
+```
+
+## Quick start
+
+1. Install dependencies.
+
+```bash
+npm install
+```
+
+2. Start the target apps you want the tests to hit.
+
+For the local demo apps from the root repo:
+
+```bash
+npm run dev:ui
+```
+
+```bash
+npm run dev:api
+```
+
+3. Run tests.
+
+```bash
+npm test
+```
+
+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!`
+
+## 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`
+
+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
+
+For local overrides, copy:
+
+```bash
+.env.example
+```
+
+to:
+
+```bash
+.env
+```
+
+The template loads:
+
+- `.env`
+- `.env.<TEST_ENV>`
+
+Example:
+
+```bash
+TEST_ENV=staging \
+STAGING_UI_BASE_URL=https://staging-ui.example.internal \
+STAGING_API_BASE_URL=https://staging-api.example.internal \
+STAGING_APP_USERNAME=my-user \
+STAGING_APP_PASSWORD=my-password \
+npx playwright test
+```
+
+If your team uses a real secret system later, replace the implementation behind `config/secret-manager.ts`.
+
+## Main commands
+
+```bash
+npm test
+npm run test:smoke
+npm run test:regression
+npm run test:critical
+npm run lint
+npm run typecheck
+npm run report:playwright
+npm run report:allure
+```
+
+## Reports and artifacts
+
+Default Playwright HTML report:
+
+```bash
+npm run report:playwright
+```
+
+Optional Allure report:
+
+```bash
+npm run report:allure
+```
+
+Outputs:
+
+- Playwright HTML: `reports/html`
+- Allure single file: `reports/allure/index.html`
+- structured event log: `reports/logs/playwright-events.jsonl`
+- raw Allure results: `allure-results`
+- traces, screenshots, videos: `test-results`
+
+If you only want Playwright reporting, remove the `allure-playwright` reporter entry in `playwright.config.ts`.
+
+## Add a new test
+
+Create tests under `tests/` and import the shared fixtures:
+
+```ts
+import { expect, test } from "../fixtures/test-fixtures";
+```
+
+Keep the pattern simple:
+
+- create data with `dataFactory`
+- interact through page objects
+- assert in the test
+
+Example shape:
+
+```ts
+test("do something @smoke", async ({ dataFactory, loginPage }) => {
+  const person = dataFactory.person();
+  // use page objects here
+});
+```
+
+## Extend the framework
+
+Common extension points:
+
+- add page objects under `pages/`
+- add reusable UI pieces under `components/`
+- extend fixtures in `fixtures/test-fixtures.ts`
+- add more generic builders under `data/factories/`
+- add stronger custom lint rules in `lint/architecture-plugin.cjs`
+- add custom reporters under `reporters/`
+
+Recommended rules:
+
+- keep selectors in page objects
+- keep assertions in test files
+- prefer semantic selectors such as `getByRole`, `getByLabel`, and `data-testid`
+- keep the data layer generic until the project really needs domain-specific factories
+
+## CI and Docker
+
+The CI entrypoint is:
+
+```bash
+scripts/run-tests.sh
+```
+
+Docker support is included in:
+
+```bash
+docker/Dockerfile
+```
+
+The included GitHub Actions workflow installs dependencies, runs tests, and uploads artifacts. The Docker path is also validated in CI so the container setup does not drift from the normal runner path.

package/templates/playwright-template/allurerc.mjs

@@ -0,0 +1,10 @@
+export default {
+  name: "qa-patterns Playwright Template",
+  plugins: {
+    awesome: {
+      options: {
+        singleFile: true
+      }
+    }
+  }
+};

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

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