@toolstackhq/create-qa-patterns 1.0.14 → 1.0.15

package/templates/wdio-template/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@toolstackhq/wdio-template",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Production-ready WebdriverIO automation framework template with deterministic test patterns.",
+  "scripts": {
+    "ensure:env": "node ./scripts/ensure-local-env.mjs",
+    "test": "node ./scripts/ensure-local-env.mjs && node ./scripts/run-wdio.mjs",
+    "test:smoke": "node ./scripts/ensure-local-env.mjs && node ./scripts/run-wdio.mjs --mochaOpts.grep @smoke",
+    "test:regression": "node ./scripts/ensure-local-env.mjs && node ./scripts/run-wdio.mjs --mochaOpts.grep @regression",
+    "test:critical": "node ./scripts/ensure-local-env.mjs && node ./scripts/run-wdio.mjs --mochaOpts.grep @critical",
+    "demo:ui": "node ./scripts/ensure-local-env.mjs && node ./demo-apps/ui-demo-app/src/server.js",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "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",
+    "express": "^4.21.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.12.0",
+    "@types/node": "^22.7.4",
+    "@typescript-eslint/eslint-plugin": "^8.8.1",
+    "@typescript-eslint/parser": "^8.8.1",
+    "@wdio/allure-reporter": "^9.0.0",
+    "@wdio/cli": "^9.0.0",
+    "@wdio/globals": "^9.0.0",
+    "@wdio/local-runner": "^9.0.0",
+    "@wdio/mocha-framework": "^9.0.0",
+    "@wdio/reporter": "^9.0.0",
+    "@wdio/spec-reporter": "^9.0.0",
+    "@wdio/types": "^9.0.0",
+    "allure": "^3.3.1",
+    "expect-webdriverio": "^5.4.3",
+    "eslint": "^9.12.0",
+    "typescript": "^5.6.2",
+    "webdriverio": "^9.0.0"
+  }
+}

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

@@ -0,0 +1,6 @@
+# Pages
+
+This folder holds Playwright page objects.
+
+- Page classes own locators and UI actions.
+- Tests should talk to these classes instead of raw selectors.

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

@@ -0,0 +1,15 @@
+// Base page object for WebdriverIO pages.
+import { browser } from '@wdio/globals';
+
+import type { Logger } from '../utils/logger';
+
+export class BasePage {
+  constructor(
+    protected readonly baseUrl: string,
+    protected readonly logger: Logger
+  ) {}
+
+  async open(pathname: string): Promise<void> {
+    await browser.url(new globalThis.URL(pathname, this.baseUrl).toString());
+  }
+}

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

@@ -0,0 +1,27 @@
+// Page object for the login screen and its user actions.
+import { $ } from '@wdio/globals';
+
+import type { Logger } from '../utils/logger';
+
+import { BasePage } from './base-page';
+
+export class LoginPage extends BasePage {
+  constructor(baseUrl: string, logger: Logger) {
+    super(baseUrl, logger);
+  }
+
+  async goto(): Promise<void> {
+    this.logger.info('page.goto', { pageObject: 'LoginPage', page: 'login' });
+    await this.open('/login');
+  }
+
+  async login(username: string, password: string): Promise<void> {
+    this.logger.info('login.submit', {
+      pageObject: 'LoginPage',
+      username
+    });
+    await $('#username').setValue(username);
+    await $('#password').setValue(password);
+    await $('button=Sign in').click();
+  }
+}

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

@@ -0,0 +1,54 @@
+// Page object for the people screen used in the starter WDIO workflow.
+import { $ } from '@wdio/globals';
+
+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(baseUrl: string, logger: Logger) {
+    super(baseUrl, logger);
+  }
+
+  async waitForReady(): Promise<void> {
+    await $('h1=People').waitForDisplayed();
+  }
+
+  async getWelcomeMessage(): Promise<string> {
+    return $('[data-testid="welcome-message"]').getText();
+  }
+
+  async addPerson(person: PersonRecord): Promise<void> {
+    this.logger.info('person.create', {
+      pageObject: 'PeoplePage',
+      personId: person.personId
+    });
+    await $('#personId').setValue(person.personId);
+    await $('#name').setValue(person.name);
+    await $('#role').setValue(person.role);
+    await $('#email').setValue(person.email);
+    await $('button=Add person').click();
+    await $('[data-testid="flash-message"]').waitForDisplayed();
+  }
+
+  async getFlashMessage(): Promise<string> {
+    return $('[data-testid="flash-message"]').getText();
+  }
+
+  async getPersonSummary(
+    personId: string
+  ): Promise<{ name: string; role: string; email: string } | null> {
+    const row = await $(`[data-testid="person-row-${personId}"]`);
+    if (!(await row.isExisting())) {
+      return null;
+    }
+
+    const cells = await row.$$('td');
+    return {
+      name: await cells[0].getText(),
+      role: await cells[1].getText(),
+      email: await cells[2].getText()
+    };
+  }
+}

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

@@ -0,0 +1,5 @@
+# Reporters
+
+This folder contains custom Playwright reporters.
+
+- Use these when you need machine-readable output in addition to built-in reports.

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

@@ -0,0 +1,78 @@
+// Custom reporter that writes machine-readable WebdriverIO lifecycle events to disk.
+import fs from 'node:fs';
+import path from 'node:path';
+
+import reporter from '@wdio/reporter';
+
+type ReporterOptions = {
+  outputFile?: string;
+};
+
+export default class StructuredReporter extends reporter {
+  private readonly outputFile: string;
+
+  constructor(options: ReporterOptions = {}) {
+    super({ ...options, stdout: false });
+    this.outputFile = path.resolve(
+      process.cwd(),
+      options.outputFile ?? 'reports/logs/wdio-events.jsonl'
+    );
+    fs.mkdirSync(path.dirname(this.outputFile), { recursive: true });
+  }
+
+  onRunnerStart(runnerStats: { cid?: string; specs?: string[] }): void {
+    this.writeEvent({
+      event: 'run.started',
+      cid: runnerStats.cid ?? 'unknown',
+      specCount: runnerStats.specs?.length ?? 0
+    });
+  }
+
+  onTestPass(testStats: { title: string; duration?: number }): void {
+    this.writeTestEvent('passed', testStats);
+  }
+
+  onTestFail(testStats: {
+    title: string;
+    duration?: number;
+    errors?: Array<{ message?: string }>;
+  }): void {
+    this.writeTestEvent('failed', testStats, {
+      error: testStats.errors?.[0]?.message
+    });
+  }
+
+  onTestSkip(testStats: { title: string; duration?: number }): void {
+    this.writeTestEvent('skipped', testStats);
+  }
+
+  onRunnerEnd(runnerStats: { failures?: number }): void {
+    this.writeEvent({
+      event: 'run.finished',
+      status: runnerStats.failures ? 'failed' : 'passed'
+    });
+  }
+
+  private writeTestEvent(
+    status: string,
+    testStats: { title: string; duration?: number },
+    extra: Record<string, unknown> = {}
+  ): void {
+    this.writeEvent({
+      event: 'test.finished',
+      title: testStats.title,
+      tags: testStats.title.match(/@\w+/g) ?? [],
+      status,
+      durationMs: testStats.duration ?? 0,
+      ...extra
+    });
+  }
+
+  private writeEvent(payload: Record<string, unknown>): void {
+    fs.appendFileSync(
+      this.outputFile,
+      `${JSON.stringify({ timestamp: new Date().toISOString(), ...payload })}\n`,
+      'utf8'
+    );
+  }
+}

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

@@ -0,0 +1,5 @@
+# Scripts
+
+This folder contains helper scripts used by local development and CI.
+
+- Keep shell and Node entrypoints here instead of inside workflow files.

package/templates/wdio-template/scripts/ensure-local-env.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const currentProcess = globalThis.process;
+const envPath = path.resolve(currentProcess.cwd(), '.env');
+
+if (fs.existsSync(envPath)) {
+  currentProcess.exit(0);
+}
+
+const projectSlug = path
+  .basename(currentProcess.cwd())
+  .toLowerCase()
+  .replace(/[^a-z0-9]+/g, '-')
+  .replace(/^-+|-+$/g, '')
+  .slice(0, 12);
+const username = `${projectSlug || 'local'}-${crypto.randomBytes(3).toString('hex')}`;
+const password = `${crypto.randomBytes(9).toString('base64url')}A1!`;
+
+const envContents = [
+  'TEST_ENV=dev',
+  'TEST_RUN_ID=local',
+  'DEV_UI_BASE_URL=http://127.0.0.1:3000',
+  `DEV_APP_USERNAME=${username}`,
+  `DEV_APP_PASSWORD=${password}`,
+  `UI_DEMO_USERNAME=${username}`,
+  `UI_DEMO_PASSWORD=${password}`
+].join('\n');
+
+fs.writeFileSync(envPath, `${envContents}\n`, 'utf8');
+currentProcess.stdout.write(
+  `Generated local .env with demo credentials for ${username}\n`
+);

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

@@ -0,0 +1,72 @@
+// Builds a local Allure report from raw test results after a test run completes.
+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 () => {
+  try {
+    await stat(resultsDir);
+  } catch {
+    process.stdout.write(
+      'Skipping Allure report generation because allure-results does not exist.\n'
+    );
+    return;
+  }
+
+  const files = await collectResultFiles();
+
+  if (files.length === 0) {
+    process.stdout.write(
+      'Skipping Allure report generation because no result files were found.\n'
+    );
+    return;
+  }
+
+  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/wdio-template/scripts/run-tests.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+node ./scripts/ensure-local-env.mjs
+npm run lint
+npm run typecheck
+npm test -- "$@"

package/templates/wdio-template/scripts/run-wdio.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+// Starts the local demo app when needed, then launches the WebdriverIO runner.
+import process from 'node:process';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+import dotenv from 'dotenv';
+
+const args = process.argv.slice(2);
+const cwd = process.cwd();
+const healthUrl = 'http://127.0.0.1:3000/health';
+const environment = process.env.TEST_ENV ?? 'dev';
+const environmentDefaults = {
+  dev: 'http://127.0.0.1:3000',
+  staging: 'https://staging-ui.example.internal',
+  prod: 'https://ui.example.internal'
+};
+
+dotenv.config({ path: path.resolve(cwd, '.env') });
+dotenv.config({
+  path: path.resolve(cwd, `.env.${environment}`),
+  override: true
+});
+
+const uiBaseUrl =
+  process.env[`${environment.toUpperCase()}_UI_BASE_URL`] ??
+  process.env.UI_BASE_URL ??
+  environmentDefaults[environment] ??
+  environmentDefaults.dev;
+
+const shouldAutoStartDemoApp =
+  environment === 'dev' &&
+  uiBaseUrl === environmentDefaults.dev &&
+  process.env.WDIO_DISABLE_LOCAL_DEMO_APP !== 'true';
+
+function getCommandName(command) {
+  return process.platform === 'win32' ? `${command}.cmd` : command;
+}
+
+function spawnCommand(command, commandArgs, options = {}) {
+  return spawn(getCommandName(command), commandArgs, {
+    cwd,
+    stdio: 'inherit',
+    ...options
+  });
+}
+
+async function waitForHealthcheck(url, timeoutMs = 30_000) {
+  const start = Date.now();
+
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const response = await globalThis.fetch(url);
+      if (response.ok) {
+        return;
+      }
+    } catch {
+      // Service is not ready yet.
+    }
+
+    await new Promise((resolve) => globalThis.setTimeout(resolve, 500));
+  }
+
+  throw new Error(`Timed out waiting for ${url}`);
+}
+
+function killChild(child) {
+  if (!child || child.killed) {
+    return;
+  }
+
+  child.kill('SIGTERM');
+}
+
+async function run() {
+  let demoAppProcess;
+
+  try {
+    if (shouldAutoStartDemoApp) {
+      demoAppProcess = spawnCommand('npm', ['run', 'demo:ui']);
+      await waitForHealthcheck(healthUrl);
+    }
+
+    const wdioProcess = spawnCommand('npx', [
+      'wdio',
+      'run',
+      './wdio.conf.ts',
+      ...args
+    ]);
+
+    const exitCode = await new Promise((resolve) => {
+      wdioProcess.on('close', resolve);
+      wdioProcess.on('error', () => resolve(1));
+    });
+
+    if (exitCode !== 0) {
+      process.exit(Number(exitCode) || 1);
+    }
+  } finally {
+    killChild(demoAppProcess);
+  }
+}
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => process.exit(1));
+}
+
+run().catch((error) => {
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`
+  );
+  process.exit(1);
+});

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

@@ -0,0 +1,7 @@
+# Tests
+
+This folder holds user-facing Playwright scenarios.
+
+- Keep tests focused on behavior and business flow.
+- Use fixtures from `../fixtures/test-fixtures`.
+- Keep selectors out of test files.

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

@@ -0,0 +1,52 @@
+// Starter WDIO scenario that demonstrates the preferred spec style for this template.
+import assert from 'node:assert/strict';
+
+import { loadRuntimeConfig } 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 } from '../utils/logger';
+import { StepLogger } from '../utils/test-step';
+
+describe('UI starter journey', () => {
+  it('login and add one person @smoke @critical', async () => {
+    const appConfig = loadRuntimeConfig();
+    const logger = createLogger({
+      test: 'ui-journey.spec.ts > UI starter journey > login and add one person @smoke @critical'
+    });
+    const stepLogger = new StepLogger(logger.child({ scope: 'steps' }));
+    const dataFactory = new DataFactory(appConfig.testRunId);
+    const loginPage = new LoginPage(
+      appConfig.uiBaseUrl,
+      logger.child({ pageObject: 'LoginPage' })
+    );
+    const peoplePage = new PeoplePage(
+      appConfig.uiBaseUrl,
+      logger.child({ pageObject: 'PeoplePage' })
+    );
+    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();
+      assert.match(
+        await peoplePage.getWelcomeMessage(),
+        new RegExp(appConfig.credentials.username)
+      );
+    });
+
+    await stepLogger.run('Add one person and verify the list', async () => {
+      await peoplePage.addPerson(person);
+      assert.match(await peoplePage.getFlashMessage(), /Person added/);
+      assert.deepEqual(await peoplePage.getPersonSummary(person.personId), {
+        name: person.name,
+        role: person.role,
+        email: person.email
+      });
+    });
+  });
+});

package/templates/wdio-template/tsconfig.json

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

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

@@ -0,0 +1,5 @@
+# Utils
+
+This folder holds small framework helpers.
+
+- Put generic logging and step wrappers here.

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

@@ -0,0 +1,60 @@
+// Structured JSON logger used by tests, pages, and helper classes.
+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/wdio-template/utils/test-step.ts

@@ -0,0 +1,20 @@
+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 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;
+    }
+  }
+}