@toolstackhq/create-qa-patterns 1.0.14 → 1.0.15

package/templates/wdio-template/README.md

@@ -0,0 +1,241 @@
+# WebdriverIO Template
+
+This is a WebdriverIO + TypeScript automation framework template for UI 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)
+- [Template upgrades](#template-upgrades)
+- [CI](#ci)
+
+## Feature set
+
+- WebdriverIO + TypeScript setup
+- Mocha-based specs with page objects and step logging
+- generic data factory pattern with `DataFactory`
+- folder-level `README.md` guides and file-header comments for easier onboarding
+- multi-environment runtime config with `dev`, `staging`, and `prod`
+- env-based secret resolution with a replaceable `SecretProvider`
+- WebdriverIO spec reporter by default
+- optional Allure single-file report
+- screenshots and structured logs for debugging
+- ESLint rules that protect framework conventions
+- GitHub Actions workflow for the template
+
+## How it works
+
+- specs in `tests/` own the workflow and assertions
+- page objects in `pages/` own locators and browser actions
+- runtime config is loaded from `config/runtime-config.ts`
+- application URLs and credentials are resolved from `TEST_ENV`
+- the bundled demo app auto-starts during `npm test` in local `dev` mode when the default local URL is in use
+- reports and artifacts are written under `reports/`, `allure-results/`, and `test-results/`
+
+## Project structure
+
+```text
+wdio-template
+├── tests
+├── pages
+├── components
+├── data
+├── config
+├── reporters
+├── utils
+├── lint
+├── scripts
+├── wdio.conf.ts
+└── package.json
+```
+
+## Quick start
+
+1. Install dependencies.
+
+```bash
+npm install
+```
+
+2. Run tests.
+
+```bash
+npm test
+```
+
+In local `dev`, the template starts its bundled demo app automatically before the tests run.
+
+If you want to run the demo app manually for debugging:
+
+```bash
+npm run demo:ui
+```
+
+Default local values:
+
+- UI base URL: `http://127.0.0.1:3000`
+- credentials: generated into local `.env` on first run
+
+## 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 empty defaults for the selected environment
+
+For local overrides, copy:
+
+```bash
+.env.example
+```
+
+to:
+
+```bash
+.env
+```
+
+The template loads:
+
+- `.env`
+- `.env.<TEST_ENV>`
+
+On the first local run, the template also creates a `.env` file with random demo credentials if one does not already exist.
+
+Example:
+
+```bash
+TEST_ENV=staging \
+STAGING_UI_BASE_URL=https://staging-ui.example.internal \
+STAGING_APP_USERNAME=my-user \
+STAGING_APP_PASSWORD=my-password \
+npm test
+```
+
+If you want to disable the bundled local demo app even in `dev`, use:
+
+```bash
+WDIO_DISABLE_LOCAL_DEMO_APP=true npm 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 demo:ui
+npm run lint
+npm run typecheck
+npm run report:allure
+```
+
+## Reports and artifacts
+
+Optional Allure report:
+
+```bash
+npm run report:allure
+```
+
+Outputs:
+
+- Allure single file: `reports/allure/index.html`
+- structured event log: `reports/logs/wdio-events.jsonl`
+- raw Allure results: `allure-results`
+- failure screenshots: `test-results`
+
+If you only want WebdriverIO's built-in terminal reporting, remove the `allure` reporter entry in `wdio.conf.ts`.
+
+## Add a new test
+
+Create specs under `tests/`.
+
+Keep the pattern simple:
+
+- create data with `DataFactory`
+- interact through page objects
+- assert in the spec
+
+Example shape:
+
+```ts
+describe('do something @smoke', () => {
+  it('uses page objects and data factories', async () => {
+    // use page objects here
+  });
+});
+```
+
+## Extend the framework
+
+Common extension points:
+
+- update or replace the bundled demo app under `demo-apps/`
+- add page objects under `pages/`
+- add reusable UI pieces under `components/`
+- 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 spec files
+- prefer stable selectors such as labels, button text, and `data-testid`
+- keep the data layer generic until the project really needs domain-specific factories
+
+## Template upgrades
+
+This project includes a `.qa-patterns.json` metadata file so future CLI versions can compare the current project against the managed template baseline.
+
+Check for available safe updates:
+
+```bash
+npx -y @toolstackhq/create-qa-patterns upgrade check .
+```
+
+Apply only safe managed-file updates:
+
+```bash
+npx -y @toolstackhq/create-qa-patterns upgrade apply --safe .
+```
+
+The upgrade flow is conservative. It updates framework infrastructure such as config, scripts, workflows, and package metadata when those files are still unchanged from the generated baseline. If you changed a managed file yourself, the CLI reports a conflict instead of overwriting it.
+
+## CI
+
+The CI entrypoint is:
+
+```bash
+scripts/run-tests.sh
+```
+
+The bundled workflow lives in:
+
+```bash
+.github/workflows/wdio-tests.yml
+```

package/templates/wdio-template/allurerc.mjs

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

package/templates/wdio-template/components/README.md

@@ -0,0 +1,5 @@
+# Components
+
+This folder holds reusable UI fragments shared by multiple pages.
+
+- Use components for repeated widgets such as flash messages or shared panels.

package/templates/wdio-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/wdio-template/config/README.md

@@ -0,0 +1,5 @@
+# Config
+
+This folder resolves environment-specific runtime values.
+
+- Keep environment defaults, secret lookup, and runtime parsing here.

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

@@ -0,0 +1,40 @@
+// Defines the built-in environment defaults used when env vars are not provided.
+import type { TestEnvironment } from './test-env';
+
+type EnvironmentDefaults = {
+  uiBaseUrl: string;
+  credentials: {
+    username: string;
+    password: string;
+  };
+};
+
+const DEFAULTS: Record<TestEnvironment, EnvironmentDefaults> = {
+  dev: {
+    uiBaseUrl: 'http://127.0.0.1:3000',
+    credentials: {
+      username: '',
+      password: ''
+    }
+  },
+  staging: {
+    uiBaseUrl: 'https://staging-ui.example.internal',
+    credentials: {
+      username: '',
+      password: ''
+    }
+  },
+  prod: {
+    uiBaseUrl: 'https://ui.example.internal',
+    credentials: {
+      username: '',
+      password: ''
+    }
+  }
+};
+
+export function getEnvironmentDefaults(
+  testEnv: TestEnvironment
+): EnvironmentDefaults {
+  return DEFAULTS[testEnv];
+}

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

@@ -0,0 +1,53 @@
+// Builds the runtime configuration object that tests and fixtures consume.
+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/wdio-template/config/secret-manager.ts

@@ -0,0 +1,29 @@
+// Minimal secret abstraction so env-based secrets can later be replaced cleanly.
+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/wdio-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/wdio-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/wdio-template/data/factories/README.md

@@ -0,0 +1,6 @@
+# Factories
+
+This folder exposes small, readable builders for test data.
+
+- Start generic.
+- Add domain-specific builders only when the project needs them.

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

@@ -0,0 +1,36 @@
+// Generic data builders that keep tests readable and deterministic.
+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/wdio-template/data/generators/README.md

@@ -0,0 +1,5 @@
+# Generators
+
+This folder contains low-level helpers that factories build on.
+
+- Keep seeded randomness and id generation here.

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

@@ -0,0 +1,18 @@
+// Deterministic id generator for repeatable local and CI runs.
+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/wdio-template/data/generators/seeded-faker.ts

@@ -0,0 +1,14 @@
+// Seeded faker wrapper so generated values stay stable for a given run id.
+import { Faker, en } 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): Faker {
+  const instance = new Faker({ locale: [en] });
+  instance.seed(Math.abs(hashSeed(seedInput)));
+  return instance;
+}

package/templates/wdio-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%);
+}