@toolstackhq/create-qa-patterns 1.0.0 → 1.0.2

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();
+  }
+}

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

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

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

@@ -0,0 +1,53 @@
+import path from "node:path";
+
+import dotenv from "dotenv";
+import { z } from "zod";
+
+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 });
+
+const runtimeConfigSchema = z.object({
+  testEnv: z.enum(["dev", "staging", "prod"]),
+  testRunId: z.string().min(1),
+  uiBaseUrl: z.string().url(),
+  apiBaseUrl: z.string().url(),
+  credentials: z.object({
+    username: z.string().min(1),
+    password: z.string().min(1)
+  })
+});
+
+export type RuntimeConfig = z.infer<typeof runtimeConfigSchema>;
+
+export function loadRuntimeConfig(): RuntimeConfig {
+  const defaults = getEnvironmentDefaults(environment);
+  const secretManager = new SecretManager(new EnvSecretProvider());
+
+  const uiBaseUrl =
+    process.env[`${environment.toUpperCase()}_UI_BASE_URL`] ??
+    process.env.UI_BASE_URL ??
+    defaults.uiBaseUrl;
+  const apiBaseUrl =
+    process.env[`${environment.toUpperCase()}_API_BASE_URL`] ??
+    process.env.API_BASE_URL ??
+    defaults.apiBaseUrl;
+
+  return runtimeConfigSchema.parse({
+    testEnv: environment,
+    testRunId: process.env.TEST_RUN_ID ?? "local",
+    uiBaseUrl,
+    apiBaseUrl,
+    credentials: {
+      username:
+        secretManager.getOptionalSecret("APP_USERNAME", environment) ?? defaults.credentials.username,
+      password:
+        secretManager.getOptionalSecret("APP_PASSWORD", environment) ?? defaults.credentials.password
+    }
+  });
+}

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

@@ -0,0 +1,28 @@
+import type { TestEnvironment } from "./test-env";
+
+export interface SecretProvider {
+  getSecret(key: string, testEnv: TestEnvironment): string | undefined;
+}
+
+export class EnvSecretProvider implements SecretProvider {
+  getSecret(key: string, testEnv: TestEnvironment): string | undefined {
+    const envPrefix = testEnv.toUpperCase();
+    return process.env[`${envPrefix}_${key}`] ?? process.env[key];
+  }
+}
+
+export class SecretManager {
+  constructor(private readonly provider: SecretProvider) {}
+
+  getRequiredSecret(key: string, testEnv: TestEnvironment): string {
+    const value = this.provider.getSecret(key, testEnv);
+    if (!value) {
+      throw new Error(`Missing secret "${key}" for TEST_ENV=${testEnv}`);
+    }
+    return value;
+  }
+
+  getOptionalSecret(key: string, testEnv: TestEnvironment): string | undefined {
+    return this.provider.getSecret(key, testEnv);
+  }
+}

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

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+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");
+}

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

@@ -0,0 +1,9 @@
+# Data Layer
+
+Keep the starter data layer generic.
+
+- Start with `DataFactory.person()` or similarly small builders.
+- Add domain-specific factories only when the project actually needs them.
+- Introduce stricter validation later only if your team actually needs it.
+
+The template should feel approachable before it feels comprehensive.

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

@@ -0,0 +1,33 @@
+import { createSeededFaker } from "../generators/seeded-faker";
+import { IdGenerator } from "../generators/id-generator";
+
+export type PersonRecord = {
+  personId: string;
+  name: string;
+  role: string;
+  email: string;
+};
+
+export class DataFactory {
+  private readonly idGenerator: IdGenerator;
+
+  constructor(private readonly testRunId: string) {
+    this.idGenerator = new IdGenerator(testRunId);
+  }
+
+  person(overrides?: Partial<PersonRecord>): PersonRecord {
+    const personId = overrides?.personId ?? this.idGenerator.next("person");
+    const seededFaker = createSeededFaker(`${this.testRunId}:${personId}`);
+    const firstName = seededFaker.person.firstName();
+    const lastName = seededFaker.person.lastName();
+    const name = `${firstName} ${lastName}`;
+
+    return {
+      personId,
+      name,
+      role: overrides?.role ?? seededFaker.person.jobTitle(),
+      email: overrides?.email ?? `${firstName}.${lastName}.${personId}@example.test`.toLowerCase(),
+      ...overrides
+    };
+  }
+}

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

@@ -0,0 +1,17 @@
+export class IdGenerator {
+  private readonly counters = new Map<string, number>();
+
+  constructor(private readonly runId: string) {}
+
+  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")}`;
+  }
+
+  nextSequence(prefix: string): number {
+    const counter = (this.counters.get(prefix) ?? 0) + 1;
+    this.counters.set(prefix, counter);
+    return counter;
+  }
+}

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

@@ -0,0 +1,13 @@
+import { faker } from "@faker-js/faker";
+
+function hashSeed(value: string): number {
+  return value.split("").reduce((seed, character) => {
+    return ((seed << 5) - seed + character.charCodeAt(0)) | 0;
+  }, 0);
+}
+
+export function createSeededFaker(seedInput: string) {
+  const instance = faker;
+  instance.seed(Math.abs(hashSeed(seedInput)));
+  return instance;
+}

package/templates/playwright-template/docker/Dockerfile

@@ -0,0 +1,21 @@
+FROM node:20-bookworm-slim
+
+WORKDIR /workspace
+
+COPY package.json package-lock.json tsconfig.json playwright.config.ts eslint.config.mjs allurerc.mjs ./
+COPY config ./config
+COPY components ./components
+COPY data ./data
+COPY fixtures ./fixtures
+COPY lint ./lint
+COPY pages ./pages
+COPY reporters ./reporters
+COPY scripts ./scripts
+COPY tests ./tests
+COPY utils ./utils
+COPY .env.example ./.env.example
+
+RUN npm ci
+RUN npx playwright install --with-deps chromium
+
+CMD ["bash", "./scripts/run-tests.sh"]

package/templates/playwright-template/eslint.config.mjs

@@ -0,0 +1,66 @@
+import js from "@eslint/js";
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsParser from "@typescript-eslint/parser";
+import { fileURLToPath } from "node:url";
+
+import architecturePlugin from "./lint/architecture-plugin.cjs";
+
+const configDirectory = fileURLToPath(new globalThis.URL(".", import.meta.url));
+
+export default [
+  {
+    ignores: [
+      "node_modules/**",
+      "reports/**",
+      "allure-results/**",
+      "allure-report/**",
+      "test-results/**",
+      "playwright-report/**"
+    ]
+  },
+  js.configs.recommended,
+  {
+    files: ["**/*.ts"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: "./tsconfig.json",
+        tsconfigRootDir: configDirectory
+      },
+      globals: {
+        console: "readonly",
+        process: "readonly",
+        URL: "readonly"
+      }
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+      architecture: architecturePlugin
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      "@typescript-eslint/naming-convention": [
+        "error",
+        {
+          selector: "default",
+          format: ["camelCase"],
+          leadingUnderscore: "allow"
+        },
+        {
+          selector: "typeLike",
+          format: ["PascalCase"]
+        },
+        {
+          selector: "variable",
+          modifiers: ["const"],
+          format: ["camelCase", "UPPER_CASE", "PascalCase"]
+        }
+      ],
+      "@typescript-eslint/no-explicit-any": "off",
+      "no-empty-pattern": "off",
+      "architecture/no-raw-locators-in-tests": "error",
+      "architecture/no-wait-for-timeout": "error",
+      "architecture/no-expect-in-page-objects": "error"
+    }
+  }
+];

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

@@ -0,0 +1,43 @@
+import { test as base } from "@playwright/test";
+
+import { loadRuntimeConfig, type RuntimeConfig } from "../config/runtime-config";
+import { DataFactory } from "../data/factories/data-factory";
+import { LoginPage } from "../pages/login-page";
+import { PeoplePage } from "../pages/people-page";
+import { createLogger, type Logger } from "../utils/logger";
+import { StepLogger } from "../utils/test-step";
+
+type FrameworkFixtures = {
+  appConfig: RuntimeConfig;
+  logger: Logger;
+  stepLogger: StepLogger;
+  dataFactory: DataFactory;
+  loginPage: LoginPage;
+  peoplePage: PeoplePage;
+};
+
+export const test = base.extend<FrameworkFixtures>({
+  appConfig: async ({}, use) => {
+    await use(loadRuntimeConfig());
+  },
+  logger: async ({}, use, testInfo) => {
+    const logger = createLogger({
+      test: testInfo.titlePath.join(" > ")
+    });
+    await use(logger);
+  },
+  stepLogger: async ({ logger }, use) => {
+    await use(new StepLogger(logger.child({ scope: "steps" })));
+  },
+  dataFactory: async ({ appConfig }, use) => {
+    await use(new DataFactory(appConfig.testRunId));
+  },
+  loginPage: async ({ page, appConfig, logger }, use) => {
+    await use(new LoginPage(page, appConfig.uiBaseUrl, logger.child({ pageObject: "LoginPage" })));
+  },
+  peoplePage: async ({ page, appConfig, logger }, use) => {
+    await use(new PeoplePage(page, appConfig.uiBaseUrl, logger.child({ pageObject: "PeoplePage" })));
+  }
+});
+
+export { expect } from "@playwright/test";