@toolstackhq/create-qa-patterns 1.0.0 → 1.0.1

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";

package/templates/playwright-template/lint/architecture-plugin.cjs

@@ -0,0 +1,118 @@
+const TEST_FILE_PATTERN = /[/\\]tests[/\\].+\.ts$/;
+const PAGE_OBJECT_PATTERN = /[/\\](pages|components)[/\\].+\.ts$/;
+
+const locatorMethods = new Set([
+  "locator",
+  "getByRole",
+  "getByLabel",
+  "getByTestId",
+  "getByText",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "$",
+  "$$"
+]);
+
+function isIdentifierProperty(node, name) {
+  return (
+    node &&
+    node.type === "MemberExpression" &&
+    !node.computed &&
+    node.property &&
+    node.property.type === "Identifier" &&
+    node.property.name === name
+  );
+}
+
+module.exports = {
+  rules: {
+    "no-raw-locators-in-tests": {
+      meta: {
+        type: "problem",
+        docs: {
+          description: "Disallow selectors inside test files"
+        },
+        schema: [],
+        messages: {
+          noRawLocators:
+            "Raw locators are not allowed in tests. Move selector logic into a page object or component."
+        }
+      },
+      create(context) {
+        if (!TEST_FILE_PATTERN.test(context.getFilename())) {
+          return {};
+        }
+
+        return {
+          CallExpression(node) {
+            if (
+              node.callee.type === "MemberExpression" &&
+              !node.callee.computed &&
+              node.callee.property.type === "Identifier" &&
+              locatorMethods.has(node.callee.property.name)
+            ) {
+              context.report({
+                node,
+                messageId: "noRawLocators"
+              });
+            }
+          }
+        };
+      }
+    },
+    "no-wait-for-timeout": {
+      meta: {
+        type: "problem",
+        docs: {
+          description: "Disallow waitForTimeout"
+        },
+        schema: [],
+        messages: {
+          noWaitForTimeout: "waitForTimeout is not allowed. Synchronize with user-visible events instead."
+        }
+      },
+      create(context) {
+        return {
+          CallExpression(node) {
+            if (isIdentifierProperty(node.callee, "waitForTimeout")) {
+              context.report({
+                node,
+                messageId: "noWaitForTimeout"
+              });
+            }
+          }
+        };
+      }
+    },
+    "no-expect-in-page-objects": {
+      meta: {
+        type: "problem",
+        docs: {
+          description: "Disallow assertions inside page objects and UI components"
+        },
+        schema: [],
+        messages: {
+          noExpect:
+            "Assertions are not allowed inside page objects or components. Return state and assert from the test."
+        }
+      },
+      create(context) {
+        if (!PAGE_OBJECT_PATTERN.test(context.getFilename())) {
+          return {};
+        }
+
+        return {
+          CallExpression(node) {
+            if (node.callee.type === "Identifier" && node.callee.name === "expect") {
+              context.report({
+                node,
+                messageId: "noExpect"
+              });
+            }
+          }
+        };
+      }
+    }
+  }
+};