@toolstackhq/create-qa-patterns 1.0.5 → 1.0.7

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

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

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

@@ -0,0 +1,46 @@
+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(),
+  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;
+
+  return runtimeConfigSchema.parse({
+    testEnv: environment,
+    testRunId: process.env.TEST_RUN_ID ?? "local",
+    uiBaseUrl,
+    credentials: {
+      username:
+        secretManager.getOptionalSecret("APP_USERNAME", environment) ?? defaults.credentials.username,
+      password:
+        secretManager.getOptionalSecret("APP_PASSWORD", environment) ?? defaults.credentials.password
+    }
+  });
+}

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

@@ -0,0 +1,19 @@
+import type { TestEnvironment } from "./test-env";
+
+export interface SecretProvider {
+  getOptionalSecret(secretName: string, environment: TestEnvironment): string | undefined;
+}
+
+export class EnvSecretProvider implements SecretProvider {
+  getOptionalSecret(secretName: string, environment: TestEnvironment): string | undefined {
+    return process.env[`${environment.toUpperCase()}_${secretName}`] ?? process.env[secretName];
+  }
+}
+
+export class SecretManager {
+  constructor(private readonly secretProvider: SecretProvider) {}
+
+  getOptionalSecret(secretName: string, environment: TestEnvironment): string | undefined {
+    return this.secretProvider.getOptionalSecret(secretName, environment);
+  }
+}

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

@@ -0,0 +1,13 @@
+export type TestEnvironment = "dev" | "staging" | "prod";
+
+const testEnvironmentValues = new Set<TestEnvironment>(["dev", "staging", "prod"]);
+
+export function loadTestEnvironment(): TestEnvironment {
+  const testEnv = process.env.TEST_ENV ?? "dev";
+
+  if (!testEnvironmentValues.has(testEnv as TestEnvironment)) {
+    throw new Error(`Unsupported TEST_ENV "${testEnv}". Expected one of: dev, staging, prod.`);
+  }
+
+  return testEnv as TestEnvironment;
+}

package/templates/cypress-template/cypress/e2e/ui-journey.cy.ts

@@ -0,0 +1,20 @@
+import { DataFactory } from "../support/data/data-factory";
+import { loadAppConfig } from "../support/app-config";
+import { peoplePage } from "../support/pages/people-page";
+
+describe("UI starter journey", () => {
+  it("signs in and adds one person", () => {
+    const appConfig = loadAppConfig();
+    const dataFactory = new DataFactory(appConfig.testRunId);
+    const person = dataFactory.person();
+
+    cy.signIn(appConfig.credentials.username, appConfig.credentials.password);
+    peoplePage.welcomeMessage().should("contain", appConfig.credentials.username);
+
+    cy.addPerson(person);
+    peoplePage.flashMessage().should("contain", "Person added");
+    peoplePage.nameCell(person.personId).should("have.text", person.name);
+    peoplePage.roleCell(person.personId).should("have.text", person.role);
+    peoplePage.emailCell(person.personId).should("have.text", person.email);
+  });
+});

package/templates/cypress-template/cypress/support/app-config.ts

@@ -0,0 +1,23 @@
+type Credentials = {
+  username: string;
+  password: string;
+};
+
+export type AppConfig = {
+  testEnv: string;
+  testRunId: string;
+  credentials: Credentials;
+};
+
+export function loadAppConfig(): AppConfig {
+  const credentials = Cypress.env("credentials") as Credentials | undefined;
+
+  return {
+    testEnv: String(Cypress.env("testEnv") ?? "dev"),
+    testRunId: String(Cypress.env("testRunId") ?? "local"),
+    credentials: {
+      username: credentials?.username ?? "tester",
+      password: credentials?.password ?? "Password123!"
+    }
+  };
+}

package/templates/cypress-template/cypress/support/commands.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="cypress" />
+
+import type { PersonRecord } from "./data/data-factory";
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      getByTestId(testId: string): Chainable<JQuery<HTMLElement>>;
+      signIn(username: string, password: string): Chainable<void>;
+      addPerson(person: PersonRecord): Chainable<void>;
+    }
+  }
+}
+
+export {};

package/templates/cypress-template/cypress/support/commands.ts

@@ -0,0 +1,17 @@
+import type { PersonRecord } from "./data/data-factory";
+import { loginPage } from "./pages/login-page";
+import { peoplePage } from "./pages/people-page";
+
+Cypress.Commands.add("getByTestId", (testId: string) => {
+  return cy.get(`[data-testid='${testId}']`);
+});
+
+Cypress.Commands.add("signIn", (username: string, password: string) => {
+  loginPage.visit();
+  loginPage.login(username, password);
+  peoplePage.heading().should("be.visible");
+});
+
+Cypress.Commands.add("addPerson", (person: PersonRecord) => {
+  peoplePage.addPerson(person);
+});

package/templates/cypress-template/cypress/support/data/data-factory.ts

@@ -0,0 +1,33 @@
+import { IdGenerator } from "./id-generator";
+import { createSeededFaker } from "./seeded-faker";
+
+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/cypress-template/cypress/support/data/id-generator.ts

@@ -0,0 +1,13 @@
+export class IdGenerator {
+  private readonly counters = new Map<string, number>();
+
+  constructor(private readonly testRunId: string) {}
+
+  next(prefix: string): string {
+    const currentCount = this.counters.get(prefix) ?? 0;
+    const nextCount = currentCount + 1;
+    this.counters.set(prefix, nextCount);
+
+    return `${prefix}-${this.testRunId}-${String(nextCount).padStart(4, "0")}`;
+  }
+}

package/templates/cypress-template/cypress/support/data/seeded-faker.ts

@@ -0,0 +1,11 @@
+import { Faker, en } from "@faker-js/faker";
+
+function toNumericSeed(seed: string): number {
+  return seed.split("").reduce((accumulator, character) => accumulator + character.charCodeAt(0), 0);
+}
+
+export function createSeededFaker(seed: string): Faker {
+  const faker = new Faker({ locale: [en] });
+  faker.seed(toNumericSeed(seed));
+  return faker;
+}

package/templates/cypress-template/cypress/support/e2e.ts

@@ -0,0 +1 @@
+import "./commands";

package/templates/cypress-template/cypress/support/pages/login-page.ts

@@ -0,0 +1,23 @@
+export const loginPage = {
+  visit(): Cypress.Chainable {
+    return cy.visit("/login");
+  },
+
+  usernameInput(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.get("#username");
+  },
+
+  passwordInput(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.get("#password");
+  },
+
+  submitButton(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.contains("button", "Sign in");
+  },
+
+  login(username: string, password: string): void {
+    this.usernameInput().clear().type(username);
+    this.passwordInput().clear().type(password, { log: false });
+    this.submitButton().click();
+  }
+};

package/templates/cypress-template/cypress/support/pages/people-page.ts

@@ -0,0 +1,59 @@
+import type { PersonRecord } from "../data/data-factory";
+
+export const peoplePage = {
+  heading(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.contains("h1", "People");
+  },
+
+  welcomeMessage(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.get("[data-testid='welcome-message']");
+  },
+
+  flashMessage(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.get("[data-testid='flash-message']");
+  },
+
+  personIdInput(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.get("#personId");
+  },
+
+  nameInput(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.get("#name");
+  },
+
+  roleInput(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.get("#role");
+  },
+
+  emailInput(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.get("#email");
+  },
+
+  submitButton(): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.contains("button", "Add person");
+  },
+
+  personRow(personId: string): Cypress.Chainable<JQuery<HTMLElement>> {
+    return cy.get(`[data-testid='person-row-${personId}']`);
+  },
+
+  nameCell(personId: string): Cypress.Chainable<JQuery<HTMLElement>> {
+    return this.personRow(personId).find("td").eq(0);
+  },
+
+  roleCell(personId: string): Cypress.Chainable<JQuery<HTMLElement>> {
+    return this.personRow(personId).find("td").eq(1);
+  },
+
+  emailCell(personId: string): Cypress.Chainable<JQuery<HTMLElement>> {
+    return this.personRow(personId).find("td").eq(2);
+  },
+
+  addPerson(person: PersonRecord): void {
+    this.personIdInput().clear().type(person.personId);
+    this.nameInput().clear().type(person.name);
+    this.roleInput().clear().type(person.role);
+    this.emailInput().clear().type(person.email);
+    this.submitButton().click();
+  }
+};

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

@@ -0,0 +1,32 @@
+import { defineConfig } from "cypress";
+
+import { loadRuntimeConfig } from "./config/runtime-config";
+
+const runtimeConfig = loadRuntimeConfig();
+
+export default defineConfig({
+  e2e: {
+    baseUrl: runtimeConfig.uiBaseUrl,
+    specPattern: "cypress/e2e/**/*.cy.ts",
+    supportFile: "cypress/support/e2e.ts",
+    setupNodeEvents(_on, config) {
+      config.env = {
+        ...config.env,
+        testEnv: runtimeConfig.testEnv,
+        testRunId: runtimeConfig.testRunId,
+        credentials: runtimeConfig.credentials
+      };
+
+      return config;
+    }
+  },
+  fixturesFolder: false,
+  retries: {
+    runMode: 1,
+    openMode: 0
+  },
+  screenshotOnRunFailure: true,
+  video: true,
+  videosFolder: "reports/videos",
+  screenshotsFolder: "reports/screenshots"
+});

package/templates/cypress-template/demo-apps/ui-demo-app/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@toolstackhq/ui-demo-app",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Deterministic two-page UI demo app for Playwright reference tests.",
+  "scripts": {
+    "dev": "node ./src/server.js",
+    "start": "node ./src/server.js"
+  }
+}

package/templates/cypress-template/demo-apps/ui-demo-app/public/styles.css

@@ -0,0 +1,120 @@
+body {
+  margin: 0;
+  font-family: "IBM Plex Sans", "Segoe UI", sans-serif;
+  background: linear-gradient(180deg, #f5f7fb 0%, #eef2f7 100%);
+  color: #102038;
+}
+
+.layout {
+  max-width: 1080px;
+  margin: 0 auto;
+  padding: 32px 24px 48px;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 24px;
+}
+
+.brand {
+  font-size: 1.5rem;
+  font-weight: 700;
+}
+
+.nav {
+  display: flex;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+
+.nav a {
+  text-decoration: none;
+  color: #102038;
+  background: #d8e6ff;
+  padding: 10px 14px;
+  border-radius: 999px;
+}
+
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 16px;
+  margin-bottom: 24px;
+}
+
+.card,
+.panel {
+  background: #ffffff;
+  border-radius: 18px;
+  padding: 20px;
+  box-shadow: 0 20px 40px rgba(16, 32, 56, 0.08);
+}
+
+.panel-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+  gap: 24px;
+}
+
+form {
+  display: grid;
+  gap: 14px;
+}
+
+label {
+  display: grid;
+  gap: 6px;
+  font-weight: 600;
+}
+
+input,
+select,
+button {
+  font: inherit;
+  padding: 10px 12px;
+  border-radius: 12px;
+  border: 1px solid #c4d3eb;
+}
+
+button {
+  background: #174ea6;
+  color: #ffffff;
+  border: none;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+th,
+td {
+  text-align: left;
+  padding: 12px 8px;
+  border-bottom: 1px solid #e1e9f5;
+}
+
+.flash-message {
+  background: #dff6e7;
+  border: 1px solid #9dd5ae;
+  color: #174f2c;
+  padding: 12px 14px;
+  border-radius: 14px;
+  margin-bottom: 16px;
+}
+
+.login-shell {
+  min-height: 100vh;
+  display: grid;
+  place-items: center;
+  padding: 24px;
+}
+
+.login-card {
+  width: min(420px, 100%);
+}

package/templates/cypress-template/demo-apps/ui-demo-app/src/server.js

@@ -0,0 +1,149 @@
+const fs = require("node:fs");
+const http = require("node:http");
+const path = require("node:path");
+const querystring = require("node:querystring");
+
+const { createPerson, getPeople, state } = require("./store");
+const { layout, loginPage, peoplePage } = require("./templates");
+
+const host = process.env.HOST || "0.0.0.0";
+const port = Number(process.env.PORT || "3000");
+
+function readBody(request) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    request.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+    request.on("end", () => resolve(querystring.parse(body)));
+    request.on("error", reject);
+  });
+}
+
+function parseCookies(request) {
+  const header = request.headers.cookie;
+  if (!header) {
+    return {};
+  }
+
+  return header.split(";").reduce((cookies, entry) => {
+    const [key, value] = entry.trim().split("=");
+    cookies[key] = value;
+    return cookies;
+  }, {});
+}
+
+function redirect(response, location) {
+  response.writeHead(302, { Location: location });
+  response.end();
+}
+
+function sendHtml(response, html) {
+  response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+  response.end(html);
+}
+
+function sendJson(response, payload) {
+  response.writeHead(200, { "Content-Type": "application/json" });
+  response.end(JSON.stringify(payload));
+}
+
+function isAuthenticated(request) {
+  return parseCookies(request).session === "authenticated";
+}
+
+function protectedRoute(request, response) {
+  if (!isAuthenticated(request)) {
+    redirect(response, "/login");
+    return false;
+  }
+
+  return true;
+}
+
+function pageMessage(url) {
+  return new URL(url, "http://127.0.0.1").searchParams.get("message") || "";
+}
+
+const server = http.createServer(async (request, response) => {
+  const url = new URL(request.url, "http://127.0.0.1");
+
+  if (request.method === "GET" && url.pathname === "/styles.css") {
+    const cssPath = path.join(__dirname, "..", "public", "styles.css");
+    response.writeHead(200, { "Content-Type": "text/css; charset=utf-8" });
+    response.end(fs.readFileSync(cssPath, "utf8"));
+    return;
+  }
+
+  if (request.method === "GET" && url.pathname === "/health") {
+    sendJson(response, { status: "ok", people: state.people.length });
+    return;
+  }
+
+  if (request.method === "GET" && url.pathname === "/") {
+    redirect(response, "/login");
+    return;
+  }
+
+  if (request.method === "GET" && url.pathname === "/login") {
+    sendHtml(response, loginPage());
+    return;
+  }
+
+  if (request.method === "POST" && url.pathname === "/login") {
+    const body = await readBody(request);
+    if (
+      body.username === state.credentials.username &&
+      body.password === state.credentials.password
+    ) {
+      response.writeHead(302, {
+        Location: "/people",
+        "Set-Cookie": "session=authenticated; HttpOnly; Path=/; SameSite=Lax"
+      });
+      response.end();
+      return;
+    }
+
+    sendHtml(response, loginPage("Invalid credentials"));
+    return;
+  }
+
+  if (request.method === "GET" && url.pathname === "/people") {
+    if (!protectedRoute(request, response)) {
+      return;
+    }
+
+    sendHtml(
+      response,
+      layout({
+        title: "People",
+        body: peoplePage(getPeople(url.searchParams.get("search") || "")),
+        flashMessage: pageMessage(request.url),
+        username: state.credentials.username
+      })
+    );
+    return;
+  }
+
+  if (request.method === "POST" && url.pathname === "/people") {
+    if (!protectedRoute(request, response)) {
+      return;
+    }
+
+    try {
+      const body = await readBody(request);
+      createPerson(body);
+      redirect(response, "/people?message=Person%20added");
+    } catch (error) {
+      redirect(response, `/people?message=${encodeURIComponent(error.message)}`);
+    }
+    return;
+  }
+
+  response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+  response.end("Not found");
+});
+
+server.listen(port, host, () => {
+  console.log(`UI demo app listening on http://${host}:${port}`);
+});