@pwtap/create 0.1.0

package/template/fixtures/auth.ts

@@ -0,0 +1,150 @@
+import fs from 'fs';
+import path from 'path';
+
+import type { Browser, Page } from '@playwright/test';
+
+import { LoginPage } from '@pages/LoginPage';
+
+/** Directory where per-session storage-state files are cached. */
+export const AUTH_DIR = '.auth';
+
+/** A single login session's credentials, as declared in testData/users.json. */
+export interface UserCredentials {
+  username: string;
+  password: string;
+}
+
+/** Resolve a session key (e.g. `'admin'`) to its storage-state file path (`.auth/admin.json`). */
+export function authState(key: string): string {
+  return path.join(AUTH_DIR, `${key}.json`);
+}
+
+/**
+ * Read the named login sessions from testData/users.json (gitignored). Returns `{}` when the file
+ * is absent, so a fresh scaffold with no users configured simply has no sessions.
+ */
+export function readUsers(): Record<string, UserCredentials> {
+  const file = path.join(process.cwd(), 'testData', 'users.json');
+  if (!fs.existsSync(file)) {
+    return {};
+  }
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8')) as {
+    users?: Record<string, UserCredentials>;
+  };
+
+  return parsed.users ?? {};
+}
+
+/** A storage-state file counts as valid once it actually carries cookies or localStorage. */
+function isValidState(file: string): boolean {
+  if (!fs.existsSync(file)) {
+    return false;
+  }
+  try {
+    const state = JSON.parse(fs.readFileSync(file, 'utf8')) as {
+      cookies?: unknown[];
+      origins?: Array<{ localStorage?: unknown[] }>;
+    };
+    return (state.cookies?.length ?? 0) > 0 || (state.origins?.[0]?.localStorage?.length ?? 0) > 0;
+  } catch {
+    return false;
+  }
+}
+
+const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Run `fn` under a cross-process lock keyed by `file` (atomic mkdir). Only one worker performs the
+ * login; the others wait for the resulting file to appear and reuse it — so a session is created
+ * exactly once even under parallel workers.
+ */
+async function withLock(file: string, fn: () => Promise<void>): Promise<void> {
+  if (!fs.existsSync(AUTH_DIR)) {
+    fs.mkdirSync(AUTH_DIR, { recursive: true });
+  }
+  const lockDir = `${file}.lock`;
+
+  let acquired = false;
+  try {
+    fs.mkdirSync(lockDir);
+    acquired = true;
+  } catch {
+    acquired = false;
+  }
+
+  if (acquired) {
+    try {
+      await fn();
+    } finally {
+      try {
+        fs.rmdirSync(lockDir);
+      } catch {
+        // already removed
+      }
+    }
+    return;
+  }
+
+  // Another worker holds the lock — wait for it to produce the file.
+  const maxWaitMs = 60_000;
+  const intervalMs = 300;
+  for (let waited = 0; waited < maxWaitMs; waited += intervalMs) {
+    if (!fs.existsSync(lockDir) && isValidState(file)) {
+      return;
+    }
+    await sleep(intervalMs);
+  }
+  throw new Error(`[auth] timed out waiting for another worker to create session file: ${file}`);
+}
+
+/** The minimal contract the auth flow needs from a login page object. */
+export interface SessionLogin {
+  /** Navigate to the login page, authenticate, and wait until signed in. */
+  signIn(username: string, password: string): Promise<void>;
+}
+
+/** Maps a session key to the login page object that authenticates it. */
+export type CreateLoginPage = (page: Page, key: string) => SessionLogin;
+
+/**
+ * Default factory: every session logs in through the one LoginPage. Override the `createLoginPage`
+ * fixture only if different sessions need different login page objects.
+ */
+export const defaultCreateLoginPage: CreateLoginPage = page => new LoginPage(page);
+
+/**
+ * Ensure `.auth/<key>.json` exists: reuse it if already cached, otherwise log in once (worker-safe)
+ * and save it. Credentials come from testData/users.json; the login page object is built by
+ * `createLoginPage` (the fixture-provided factory). Called lazily by the `session` fixture, and
+ * directly for multi-role tests that open their own contexts.
+ */
+export async function ensureSession(
+  browser: Browser,
+  key: string,
+  createLoginPage: CreateLoginPage = defaultCreateLoginPage,
+): Promise<void> {
+  const file = authState(key);
+  if (isValidState(file)) {
+    return;
+  }
+
+  await withLock(file, async () => {
+    if (isValidState(file)) {
+      return; // produced by another worker while we waited for the lock
+    }
+    const creds = readUsers()[key];
+    if (creds === undefined) {
+      throw new Error(
+        `[auth] no credentials for session '${key}' — add it to testData/users.json.`,
+      );
+    }
+    const context = await browser.newContext({ baseURL: process.env.BASE_URL });
+    try {
+      const page = await context.newPage();
+      await createLoginPage(page, key).signIn(creds.username, creds.password);
+      await context.storageState({ path: file });
+    } finally {
+      await context.close();
+    }
+  });
+}

package/template/fixtures/index.ts

@@ -0,0 +1,38 @@
+import { mergeExpects, mergeTests } from '@playwright/test';
+
+import { test as apiTest } from './api';
+import { expect as uiExpect, test as uiTest, withSessionAuth } from './ui';
+
+/**
+ * The single, editable test object for this project — core UI + API fixtures, plus any installed
+ * plugin fixtures merged in below. Import `test` and `expect` from `@fixtures` everywhere. Auth works
+ * at suite level (`test.use({ session })`) or per test (`test.as('session')('title', fn)`).
+ *
+ * The regions between the `pwtap:` markers are maintained by `create-pwtap add|remove`. Edit outside
+ * the markers freely; the tool only rewrites between them.
+ *
+ * @example
+ * import { test, expect } from '@fixtures';
+ * test.as('adminUser')('reaches the app', async ({ page }) => {
+ *   await page.goto('/');
+ *   await expect(page).toHaveURL(/\//);
+ * });
+ */
+
+// pwtap:plugins:imports
+// pwtap:plugins:imports:end
+
+export const test = withSessionAuth(
+  mergeTests(
+    uiTest,
+    apiTest,
+    // pwtap:plugins:tests
+    // pwtap:plugins:tests:end
+  ),
+);
+
+export const expect = mergeExpects(
+  uiExpect,
+  // pwtap:plugins:expects
+  // pwtap:plugins:expects:end
+);

package/template/fixtures/ui.ts

@@ -0,0 +1,112 @@
+import { test as base, expect, type TestInfo, type TestType } from '@playwright/test';
+
+import { loadEnv } from '@config/loadEnv';
+
+import { authState, defaultCreateLoginPage, ensureSession, type CreateLoginPage } from './auth';
+
+// Load the selected environment (TEST_ENV → BASE_URL → baseURL) before any test runs.
+loadEnv();
+
+/** Annotation type carrying a per-test session key, set by `test.as(session)` and read by storageState. */
+const SESSION_ANNOTATION = 'pwtap:session';
+
+/** Options this test object adds on top of the built-in Playwright fixtures. */
+export interface AuthOptions {
+  /**
+   * Suite-level session key: `test.use({ session })` at file/describe scope authenticates every test
+   * in that scope. On first use its `.auth/<session>.json` is created by logging in (once,
+   * worker-safe) and reused later. Leave unset for an unauthenticated context. For per-test auth use
+   * `test.as(session)` instead.
+   */
+  session: string | undefined;
+}
+
+/** Non-option fixtures this test object adds. */
+interface AuthFixtures {
+  /**
+   * Factory mapping a session key to its login page object. Init'd here so the auth flow logs in
+   * through a page object (never constructing one inline). Override to wire your app's page objects.
+   */
+  createLoginPage: CreateLoginPage;
+}
+
+/**
+ * Core UI test object. Adds a `session` option for suite-level auth and overrides `storageState` so
+ * the authenticated state is applied lazily and cached. Per-test auth is layered on separately by
+ * `withSessionAuth` (the `test.as(session)` API), which sets an annotation this fixture reads.
+ */
+export const test = base.extend<AuthOptions & AuthFixtures>({
+  session: [undefined, { option: true }],
+
+  // The login page-object factory, provided as a fixture so the auth flow doesn't `new` one inline.
+  createLoginPage: async ({}, use) => {
+    await use(defaultCreateLoginPage);
+  },
+
+  // Effective session = per-test annotation (test.as) > suite-level option (test.use) > none.
+  // When set, ensure the cached state exists (log in on a miss) and apply it as storageState.
+  storageState: async ({ browser, session, storageState, createLoginPage }, use, testInfo) => {
+    const perTest = testInfo.annotations.find(a => a.type === SESSION_ANNOTATION)?.description;
+    const effective = perTest ?? session;
+    if (effective === undefined) {
+      await use(storageState);
+      return;
+    }
+    await ensureSession(browser, effective, createLoginPage);
+    await use(authState(effective));
+  },
+});
+
+export { expect };
+
+/** A test object of any fixture shape — the constraint for the session-auth helpers below. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyTest = TestType<any, any>;
+
+/** Fixtures + worker args of a test type, as passed to its test body. */
+type TestArgsOf<T> = T extends TestType<infer A, infer W> ? A & W : never;
+type SessionTestBody<T> = (args: TestArgsOf<T>, testInfo: TestInfo) => void | Promise<void>;
+
+/** A session-bound test declarator: callable like `test`, with the standard declaration modifiers. */
+export interface SessionBoundTest<T extends AnyTest> {
+  (title: string, body: SessionTestBody<T>): void;
+  skip(title: string, body: SessionTestBody<T>): void;
+  only(title: string, body: SessionTestBody<T>): void;
+  fixme(title: string, body: SessionTestBody<T>): void;
+  fail(title: string, body: SessionTestBody<T>): void;
+}
+
+/**
+ * Attach `.as(session)` to a test object for test-level auth. `test.as('admin')('title', fn)` runs
+ * that single test authenticated as `admin` (its `page`/`storageState` carry the cached session), and
+ * `.skip`/`.only`/`.fixme`/`.fail` work the same. It sets a declaration-time annotation the
+ * `storageState` fixture reads, so it composes with suite-level `test.use({ session })`.
+ *
+ * @example
+ * export const test = withSessionAuth(mergeTests(uiTest, apiTest));
+ * test.as('adminUser')('sees dashboard', async ({ page }) => { await page.goto('/dashboard'); });
+ * test.as('customerUser').fixme('broken flow', async ({ page }) => { await page.goto('/x'); });
+ */
+export function withSessionAuth<T extends AnyTest>(
+  testObj: T,
+): T & { as: (session: string) => SessionBoundTest<T> } {
+  const as = (session: string): SessionBoundTest<T> => {
+    const details = { annotation: { type: SESSION_ANNOTATION, description: session } };
+    // Playwright's declaration forms accept (title, details, body); cast to reach them generically.
+    const decl = testObj as unknown as {
+      (title: string, details: unknown, body: unknown): void;
+      skip(title: string, details: unknown, body: unknown): void;
+      only(title: string, details: unknown, body: unknown): void;
+      fixme(title: string, details: unknown, body: unknown): void;
+      fail(title: string, details: unknown, body: unknown): void;
+    };
+    const bound = ((title: string, body: SessionTestBody<T>) =>
+      decl(title, details, body)) as SessionBoundTest<T>;
+    bound.skip = (title, body) => decl.skip(title, details, body);
+    bound.only = (title, body) => decl.only(title, details, body);
+    bound.fixme = (title, body) => decl.fixme(title, details, body);
+    bound.fail = (title, body) => decl.fail(title, details, body);
+    return bound;
+  };
+  return Object.assign(testObj, { as });
+}

package/template/pages/BasePage.ts

@@ -0,0 +1,225 @@
+import type { Locator, Page } from '@playwright/test';
+
+/**
+ * Base Page Object class with common functionality.
+ * Extend this class for all page objects.
+ *
+ * @example
+ * export class LoginPage extends BasePage {
+ *   readonly usernameInput: Locator;
+ *   readonly passwordInput: Locator;
+ *
+ *   constructor(page: Page) {
+ *     super(page, '/login');
+ *     this.usernameInput = page.getByPlaceholder('Email');
+ *     this.passwordInput = page.getByPlaceholder('Password');
+ *   }
+ *
+ *   async login(username: string, password: string) {
+ *     await this.usernameInput.fill(username);
+ *     await this.passwordInput.fill(password);
+ *     await this.clickButton('Sign In');
+ *   }
+ * }
+ */
+export class BasePage {
+  readonly page: Page;
+  readonly pageUrl: string;
+
+  constructor(page: Page, pageUrl: string = '/') {
+    this.page = page;
+    this.pageUrl = pageUrl;
+  }
+
+  /**
+   * Navigate to the page URL
+   */
+  async goto(options?: { waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' }): Promise<void> {
+    await this.page.goto(this.pageUrl, options);
+  }
+
+  /**
+   * Navigate to a custom path (relative to baseURL)
+   */
+  async navigateTo(path: string): Promise<void> {
+    await this.page.goto(path);
+  }
+
+  /**
+   * Wait for page to fully load
+   */
+  async waitForLoad(state: 'load' | 'domcontentloaded' | 'networkidle' = 'load'): Promise<void> {
+    await this.page.waitForLoadState(state);
+  }
+
+  /**
+   * Get current URL
+   */
+  getCurrentUrl(): string {
+    return this.page.url();
+  }
+
+  /**
+   * Get page title
+   */
+  async getTitle(): Promise<string> {
+    return await this.page.title();
+  }
+
+  /**
+   * Click a button by its accessible name
+   */
+  async clickButton(name: string | RegExp): Promise<void> {
+    await this.page.getByRole('button', { name }).click();
+  }
+
+  /**
+   * Click a link by its accessible name
+   */
+  async clickLink(name: string | RegExp): Promise<void> {
+    await this.page.getByRole('link', { name }).click();
+  }
+
+  /**
+   * Fill a text field by label
+   */
+  async fillByLabel(label: string | RegExp, value: string): Promise<void> {
+    await this.page.getByLabel(label).fill(value);
+  }
+
+  /**
+   * Fill a text field by placeholder
+   */
+  async fillByPlaceholder(placeholder: string | RegExp, value: string): Promise<void> {
+    await this.page.getByPlaceholder(placeholder).fill(value);
+  }
+
+  /**
+   * Select an option from a dropdown by label
+   */
+  async selectByLabel(label: string | RegExp, value: string): Promise<void> {
+    await this.page.getByLabel(label).selectOption(value);
+  }
+
+  /**
+   * Check a checkbox by label
+   */
+  async checkByLabel(label: string | RegExp): Promise<void> {
+    await this.page.getByLabel(label).check();
+  }
+
+  /**
+   * Uncheck a checkbox by label
+   */
+  async uncheckByLabel(label: string | RegExp): Promise<void> {
+    await this.page.getByLabel(label).uncheck();
+  }
+
+  /**
+   * Get text content of an element
+   */
+  async getText(locator: Locator): Promise<string> {
+    return (await locator.textContent()) ?? '';
+  }
+
+  /**
+   * Get input value
+   */
+  async getValue(locator: Locator): Promise<string> {
+    return await locator.inputValue();
+  }
+
+  /**
+   * Check if element is visible
+   */
+  async isVisible(locator: Locator): Promise<boolean> {
+    return await locator.isVisible();
+  }
+
+  /**
+   * Check if element is enabled
+   */
+  async isEnabled(locator: Locator): Promise<boolean> {
+    return await locator.isEnabled();
+  }
+
+  /**
+   * Wait for element to be visible
+   */
+  async waitForVisible(locator: Locator, timeout?: number): Promise<void> {
+    await locator.waitFor({ state: 'visible', timeout });
+  }
+
+  /**
+   * Wait for element to be hidden
+   */
+  async waitForHidden(locator: Locator, timeout?: number): Promise<void> {
+    await locator.waitFor({ state: 'hidden', timeout });
+  }
+
+  /**
+   * Wait for URL to match pattern
+   */
+  async waitForUrl(url: string | RegExp, timeout?: number): Promise<void> {
+    await this.page.waitForURL(url, { timeout });
+  }
+
+  /**
+   * Take a screenshot
+   */
+  async screenshot(path: string): Promise<Buffer> {
+    return await this.page.screenshot({ path, fullPage: true });
+  }
+
+  /**
+   * Press keyboard key
+   */
+  async pressKey(key: string): Promise<void> {
+    await this.page.keyboard.press(key);
+  }
+
+  /**
+   * Scroll to bottom of page
+   */
+  async scrollToBottom(): Promise<void> {
+    await this.page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+  }
+
+  /**
+   * Scroll to top of page
+   */
+  async scrollToTop(): Promise<void> {
+    await this.page.evaluate(() => window.scrollTo(0, 0));
+  }
+
+  /**
+   * Get element by test id
+   */
+  getByTestId(testId: string): Locator {
+    return this.page.getByTestId(testId);
+  }
+
+  /**
+   * Get element by role
+   */
+  getByRole(
+    role: Parameters<Page['getByRole']>[0],
+    options?: Parameters<Page['getByRole']>[1],
+  ): Locator {
+    return this.page.getByRole(role, options);
+  }
+
+  /**
+   * Get element by text
+   */
+  getByText(text: string | RegExp, options?: { exact?: boolean }): Locator {
+    return this.page.getByText(text, options);
+  }
+
+  /**
+   * Locator shorthand
+   */
+  locator(selector: string): Locator {
+    return this.page.locator(selector);
+  }
+}

package/template/pages/LoginPage.ts

@@ -0,0 +1,50 @@
+import type { Locator, Page } from '@playwright/test';
+
+import { BasePage } from './BasePage';
+
+/**
+ * Login page object — a basic POM. Selectors, the login URL, and the post-login URL below are wired
+ * to the saucedemo.com example app (the scaffold's placeholder, set as BASE_URL in
+ * env/environments.json). For your own app, point BASE_URL at it and swap the four selectors +
+ * success URL here — the rest of the framework (lazy session auth, fixtures) stays the same.
+ *
+ * @example
+ * const login = new LoginPage(page);
+ * await login.signIn('standard_user', 'secret_sauce');
+ */
+export class LoginPage extends BasePage {
+  readonly usernameInput: Locator;
+  readonly passwordInput: Locator;
+  readonly loginButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    super(page, '/'); // saucedemo serves the login form at the site root
+    this.usernameInput = page.locator('#user-name');
+    this.passwordInput = page.locator('#password');
+    this.loginButton = page.locator('#login-button');
+    this.errorMessage = page.locator('[data-test="error"]');
+  }
+
+  /** Whether the login form is visible. */
+  async isFormVisible(): Promise<boolean> {
+    return this.usernameInput.isVisible();
+  }
+
+  /** Fill the credentials and submit (without waiting for navigation). */
+  async login(username: string, password: string): Promise<void> {
+    await this.usernameInput.fill(username);
+    await this.passwordInput.fill(password);
+    await this.loginButton.click();
+  }
+
+  /**
+   * Navigate to the login page, sign in, and wait for the post-login page. This is the single entry
+   * point the lazy auth flow (fixtures/auth.ts) calls to establish a session.
+   */
+  async signIn(username: string, password: string): Promise<void> {
+    await this.goto();
+    await this.login(username, password);
+    await this.page.waitForURL(/\/inventory\.html/);
+  }
+}

package/template/pages/index.ts

@@ -0,0 +1,2 @@
+export { BasePage } from './BasePage';
+export { LoginPage } from './LoginPage';

package/template/playwright.config.ts

@@ -0,0 +1,71 @@
+import { defineConfig, devices } from '@playwright/test';
+
+import { loadEnv } from '@config/loadEnv';
+
+// Load env/environments.json (TEST_ENV → BASE_URL/API_BASE_URL → process.env) before defining config.
+loadEnv();
+
+// Plugin gates (e.g. `const maestroEnabled = process.env.MAESTRO === '1';`) are spliced in below by
+// `create-pwtap add|remove`. Keep these markers — the tool rewrites only between them.
+// pwtap:plugins:gates
+// pwtap:plugins:gates:end
+
+/**
+ * Playwright configuration. Core ships two projects — `chromium` (UI) and `api`. Each opt-in plugin
+ * registers its own env-gated project between the markers, so a bare `npm test` stays UI + API only.
+ *
+ * @example
+ *   npx playwright test                      # chromium + api
+ *   npx playwright test --project=chromium   # UI only
+ *   TEST_ENV=staging npx playwright test     # against the staging env block
+ */
+export default defineConfig({
+  testDir: './tests',
+  testMatch: ['**/*.spec.ts', '**/*.test.ts'],
+  testIgnore: ['**/setup/**', '**/helpers/**', '**/*.helper.ts'],
+
+  fullyParallel: true,
+  workers: process.env.CI ? 2 : undefined,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  timeout: 60 * 1000,
+  expect: { timeout: 10 * 1000 },
+
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['json', { outputFile: 'test-results/results.json' }],
+    ['allure-playwright', { detail: true, outputFolder: 'allure-results', suiteTitle: false }],
+    ['list'],
+  ],
+  outputDir: 'test-results/',
+
+  use: {
+    baseURL: process.env.BASE_URL,
+    headless: false,
+    viewport: { width: 1280, height: 720 },
+    ignoreHTTPSErrors: true,
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    trace: 'retain-on-failure',
+    navigationTimeout: 30 * 1000,
+    actionTimeout: 15 * 1000,
+    locale: 'en-US',
+    timezoneId: 'UTC',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      // Pure API project — baseURL/headers live in the layered client (api/core/ApiClient.ts,
+      // wired via fixtures/api.ts from API_BASE_URL), so there is nothing to configure here.
+      name: 'api',
+      testDir: './tests/api',
+      testMatch: /.*\.api\.ts$/,
+    },
+    // pwtap:plugins:projects
+    // pwtap:plugins:projects:end
+  ],
+});

package/template/templates/gitignore

@@ -0,0 +1,19 @@
+node_modules/
+dist/
+
+# Playwright / reports
+playwright-report/
+test-results/
+allure-results/
+allure-report/
+playwright/.cache/
+
+# Cached auth sessions (per-session storage state)
+.auth/
+
+# Secrets — only the *.example.json files are tracked
+env/environments.json
+testData/users.json
+
+*.log
+.DS_Store

package/template/testData/users.example.json

@@ -0,0 +1,17 @@
+{
+  "_note": "Named login sessions. Copy to testData/users.json (gitignored). Sessions are logged in lazily on first use (via pages/LoginPage) and cached to .auth/<key>.json; select one in a test with test.use({ session: '<key>' }). Values below are the public saucedemo.com placeholder creds so the examples run out of the box — replace with your app's users.",
+  "users": {
+    "demoUser": {
+      "username": "visual_user",
+      "password": "secret_sauce"
+    },
+    "adminUser": {
+      "username": "performance_glitch_user",
+      "password": "secret_sauce"
+    },
+    "customerUser": {
+      "username": "standard_user",
+      "password": "secret_sauce"
+    }
+  }
+}