@toolstackhq/create-qa-patterns 1.0.0 → 1.0.2

package/templates/playwright-template/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@toolstackhq/playwright-template",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Production-ready Playwright automation framework template with deterministic test patterns.",
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep @smoke",
+    "test:regression": "playwright test --grep @regression",
+    "test:critical": "playwright test --grep @critical",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "report:playwright": "playwright show-report reports/html",
+    "report:allure": "node ./scripts/generate-allure-report.mjs",
+    "report:allure:open": "allure open reports/allure",
+    "ci": "bash ./scripts/run-tests.sh"
+  },
+  "dependencies": {
+    "@faker-js/faker": "^8.4.1",
+    "dotenv": "^16.4.5",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.53.0",
+    "@types/node": "^22.7.4",
+    "@typescript-eslint/eslint-plugin": "^8.8.1",
+    "@typescript-eslint/parser": "^8.8.1",
+    "@eslint/js": "^9.12.0",
+    "allure": "^3.3.1",
+    "allure-playwright": "^3.6.0",
+    "eslint": "^9.12.0",
+    "typescript": "^5.6.2"
+  }
+}

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

@@ -0,0 +1,24 @@
+import type { Page } from "@playwright/test";
+
+import { FlashMessage } from "../components/flash-message";
+import type { Logger } from "../utils/logger";
+
+export abstract class BasePage {
+  readonly flashMessage: FlashMessage;
+
+  constructor(
+    protected readonly page: Page,
+    private readonly baseUrl: string,
+    protected readonly logger: Logger
+  ) {
+    this.flashMessage = new FlashMessage(page);
+  }
+
+  protected buildUrl(pathname: string): string {
+    return new URL(pathname, this.baseUrl).toString();
+  }
+
+  async getWelcomeMessage(): Promise<string> {
+    return (await this.page.getByTestId("welcome-message").textContent()) ?? "";
+  }
+}

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

@@ -0,0 +1,22 @@
+import type { Page } from "@playwright/test";
+
+import type { Logger } from "../utils/logger";
+import { BasePage } from "./base-page";
+
+export class LoginPage extends BasePage {
+  constructor(page: Page, baseUrl: string, logger: Logger) {
+    super(page, baseUrl, logger);
+  }
+
+  async goto(): Promise<void> {
+    this.logger.info("page.goto", { page: "login" });
+    await this.page.goto(this.buildUrl("/login"));
+  }
+
+  async login(username: string, password: string): Promise<void> {
+    this.logger.info("login.submit", { username });
+    await this.page.getByLabel("Username").fill(username);
+    await this.page.getByLabel("Password").fill(password);
+    await this.page.getByRole("button", { name: "Sign in" }).click();
+  }
+}

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

@@ -0,0 +1,39 @@
+import type { Page } from "@playwright/test";
+
+import type { PersonRecord } from "../data/factories/data-factory";
+import type { Logger } from "../utils/logger";
+import { BasePage } from "./base-page";
+
+export class PeoplePage extends BasePage {
+  constructor(page: Page, baseUrl: string, logger: Logger) {
+    super(page, baseUrl, logger);
+  }
+
+  async waitForReady(): Promise<void> {
+    await this.page.getByRole("heading", { level: 1, name: "People", exact: true }).waitFor();
+  }
+
+  async addPerson(person: PersonRecord): Promise<void> {
+    this.logger.info("person.create", { personId: person.personId });
+    await this.page.getByLabel("Person ID").fill(person.personId);
+    await this.page.getByLabel("Name").fill(person.name);
+    await this.page.getByLabel("Role").fill(person.role);
+    await this.page.getByLabel("Email").fill(person.email);
+    await this.page.getByRole("button", { name: "Add person" }).click();
+    await this.page.waitForLoadState("networkidle");
+  }
+
+  async getPersonSummary(personId: string): Promise<{ name: string; role: string; email: string } | null> {
+    const row = this.page.getByTestId(`person-row-${personId}`);
+    if (!(await row.count())) {
+      return null;
+    }
+
+    const cells = row.getByRole("cell");
+    return {
+      name: (await cells.nth(0).textContent()) ?? "",
+      role: (await cells.nth(1).textContent()) ?? "",
+      email: (await cells.nth(2).textContent()) ?? ""
+    };
+  }
+}

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

@@ -0,0 +1,46 @@
+import { defineConfig, devices } from "@playwright/test";
+
+import { loadRuntimeConfig } from "./config/runtime-config";
+
+const runtimeConfig = loadRuntimeConfig();
+
+export default defineConfig({
+  testDir: "./tests",
+  fullyParallel: false,
+  forbidOnly: Boolean(process.env.CI),
+  retries: process.env.CI ? 1 : 0,
+  workers: process.env.CI ? 2 : undefined,
+  timeout: 45_000,
+  expect: {
+    timeout: 10_000
+  },
+  outputDir: "test-results",
+  reporter: [
+    ["list"],
+    ["html", { open: "never", outputFolder: "reports/html" }],
+    // Keep the HTML reporter as the default path most users expect.
+    // Remove the Allure line below if you prefer to stay with Playwright's built-in reporters only.
+    ["allure-playwright", { resultsDir: "allure-results" }],
+    ["./reporters/structured-reporter.ts", { outputFile: "reports/logs/playwright-events.jsonl" }]
+  ],
+  use: {
+    baseURL: runtimeConfig.uiBaseUrl,
+    trace: "retain-on-failure",
+    screenshot: "only-on-failure",
+    video: "retain-on-failure",
+    headless: !process.env.PWDEBUG
+  },
+  metadata: {
+    environment: runtimeConfig.testEnv,
+    testRunId: runtimeConfig.testRunId,
+    apiBaseUrl: runtimeConfig.apiBaseUrl
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: {
+        ...devices["Desktop Chrome"]
+      }
+    }
+  ]
+});

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

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type {
+  FullConfig,
+  FullResult,
+  Reporter,
+  Suite,
+  TestCase,
+  TestResult
+} from "@playwright/test/reporter";
+
+type ReporterOptions = {
+  outputFile?: string;
+};
+
+class StructuredReporter implements Reporter {
+  private outputFile = path.resolve(process.cwd(), "reports/logs/playwright-events.jsonl");
+
+  constructor(options?: ReporterOptions) {
+    if (options?.outputFile) {
+      this.outputFile = path.resolve(process.cwd(), options.outputFile);
+    }
+    fs.mkdirSync(path.dirname(this.outputFile), { recursive: true });
+  }
+
+  onBegin(config: FullConfig, suite: Suite): void {
+    this.write({
+      event: "run.started",
+      projectCount: config.projects.length,
+      testCount: suite.allTests().length
+    });
+  }
+
+  onTestEnd(test: TestCase, result: TestResult): void {
+    this.write({
+      event: "test.finished",
+      title: test.title,
+      tags: test.title.match(/@\w+/g) ?? [],
+      status: result.status,
+      durationMs: result.duration
+    });
+  }
+
+  onEnd(result: FullResult): void {
+    this.write({
+      event: "run.finished",
+      status: result.status
+    });
+  }
+
+  private write(payload: Record<string, unknown>): void {
+    fs.appendFileSync(
+      this.outputFile,
+      `${JSON.stringify({ timestamp: new Date().toISOString(), ...payload })}\n`,
+      "utf8"
+    );
+  }
+}
+
+export default StructuredReporter;

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

@@ -0,0 +1,57 @@
+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 () => {
+  const files = await collectResultFiles();
+
+  if (files.length === 0) {
+    throw new Error("No Allure result files found in allure-results. Run the tests before generating a report.");
+  }
+
+  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/playwright-template/scripts/run-tests.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm run lint
+npm run typecheck
+npx playwright test "$@"

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

@@ -0,0 +1,28 @@
+import { expect, test } from "../fixtures/test-fixtures";
+
+test.describe("API starter flow", () => {
+  test("create and list one person @regression", async ({
+    appConfig,
+    dataFactory,
+    request,
+    stepLogger
+  }) => {
+    const person = dataFactory.person();
+
+    await stepLogger.run("Create one person through the API", async () => {
+      const response = await request.post(`${appConfig.apiBaseUrl}/people`, {
+        data: person
+      });
+      expect(response.ok()).toBeTruthy();
+      expect(await response.json()).toMatchObject(person);
+    });
+
+    await stepLogger.run("List people and verify the new record", async () => {
+      const response = await request.get(`${appConfig.apiBaseUrl}/people`);
+      expect(response.ok()).toBeTruthy();
+
+      const people = await response.json();
+      expect(people).toContainEqual(expect.objectContaining({ personId: person.personId }));
+    });
+  });
+});

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

@@ -0,0 +1,30 @@
+import { expect, test } from "../fixtures/test-fixtures";
+
+test.describe("UI starter journey", () => {
+  test("login and add one person @smoke @critical", async ({
+    appConfig,
+    loginPage,
+    peoplePage,
+    dataFactory,
+    stepLogger
+  }) => {
+    const person = dataFactory.person();
+
+    await stepLogger.run("Sign in to the demo app", async () => {
+      await loginPage.goto();
+      await loginPage.login(appConfig.credentials.username, appConfig.credentials.password);
+      await peoplePage.waitForReady();
+      expect(await peoplePage.getWelcomeMessage()).toContain(appConfig.credentials.username);
+    });
+
+    await stepLogger.run("Add one person and verify the list", async () => {
+      await peoplePage.addPerson(person);
+      expect(await peoplePage.flashMessage.getText()).toContain("Person added");
+      expect(await peoplePage.getPersonSummary(person.personId)).toEqual({
+        name: person.name,
+        role: person.role,
+        email: person.email
+      });
+    });
+  });
+});

package/templates/playwright-template/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "types": [
+      "node",
+      "@playwright/test"
+    ],
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "baseUrl": "."
+  },
+  "include": [
+    "**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "reports",
+    "allure-results",
+    "allure-report",
+    "test-results",
+    "playwright-report"
+  ]
+}

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

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+
+type LogLevel = "info" | "error";
+
+type LogContext = Record<string, string | number | boolean | null | undefined>;
+
+const LOG_FILE = path.resolve(process.cwd(), "reports/logs/execution.log");
+
+function ensureLogDirectory(): void {
+  fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
+}
+
+function serialize(level: LogLevel, message: string, context?: LogContext): string {
+  return JSON.stringify({
+    timestamp: new Date().toISOString(),
+    level,
+    message,
+    ...context
+  });
+}
+
+export class Logger {
+  constructor(private readonly context: LogContext = {}) {
+    ensureLogDirectory();
+  }
+
+  child(context: LogContext): Logger {
+    return new Logger({
+      ...this.context,
+      ...context
+    });
+  }
+
+  info(message: string, context?: LogContext): void {
+    this.write("info", message, context);
+  }
+
+  error(message: string, context?: LogContext): void {
+    this.write("error", message, context);
+  }
+
+  private write(level: LogLevel, message: string, context?: LogContext): void {
+    const line = serialize(level, message, {
+      ...this.context,
+      ...context
+    });
+    fs.appendFileSync(LOG_FILE, `${line}\n`, "utf8");
+    console.log(line);
+  }
+}
+
+export function createLogger(context: LogContext = {}): Logger {
+  return new Logger(context);
+}

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

@@ -0,0 +1,22 @@
+import { test } from "@playwright/test";
+
+import type { Logger } from "./logger";
+
+export class StepLogger {
+  constructor(private readonly logger: Logger) {}
+
+  async run<T>(message: string, callback: () => Promise<T>): Promise<T> {
+    this.logger.info("step.started", { step: message });
+    try {
+      const result = await test.step(message, callback);
+      this.logger.info("step.passed", { step: message });
+      return result;
+    } catch (error) {
+      this.logger.error("step.failed", {
+        step: message,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+}