@pwtap/create 0.1.0

package/dist/util/run.js

@@ -0,0 +1,27 @@
+import { spawn } from 'node:child_process';
+/** Strip inherited `npm_*` lifecycle env so a nested `npm install` uses a clean config. */
+function cleanEnv() {
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+        if (key.startsWith('npm_')) {
+            delete env[key];
+        }
+    }
+    return env;
+}
+/** Run a command to completion; rejects on non-zero exit or spawn error. */
+export function run(cmd, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd,
+            env: cleanEnv(),
+            stdio: opts.silent ? 'ignore' : 'inherit',
+            shell: false,
+        });
+        child.on('error', reject);
+        child.on('close', code => code === 0
+            ? resolve()
+            : reject(new Error(`\`${cmd} ${args.join(' ')}\` exited with code ${code}`)));
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/util/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/util/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,2FAA2F;AAC3F,SAAS,QAAQ;IACf,MAAM,GAAG,GAAsB,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAClD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAQD,4EAA4E;AAC5E,MAAM,UAAU,GAAG,CAAC,GAAW,EAAE,IAAc,EAAE,OAAmB,EAAE;IACpE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE;YAC7B,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,GAAG,EAAE,QAAQ,EAAE;YACf,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;YACzC,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CACvB,IAAI,KAAK,CAAC;YACR,CAAC,CAAC,OAAO,EAAE;YACX,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC,CAC/E,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@pwtap/create",
+  "version": "0.1.0",
+  "description": "Scaffold a Playwright Test Automation Platform project — UI + API core with opt-in plugins (npm init @pwtap)",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caslanqa/playwright-ai-distro.git",
+    "directory": "packages/create"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "bin": {
+    "create-pwtap": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "core-manifest.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "bundle:template": "rm -rf template core-manifest.json && cp -R ../core-template/files template && cp ../core-template/manifest.json core-manifest.json",
+    "prepack": "npm run build && npm run bundle:template"
+  }
+}

package/template/.commitlintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@commitlint/config-conventional"]
+}

package/template/.prettierrc

@@ -0,0 +1,17 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "avoid",
+  "bracketSpacing": true,
+  "endOfLine": "auto",
+  "proseWrap": "preserve",
+  "quoteProps": "as-needed",
+  "bracketSameLine": false,
+  "jsxSingleQuote": false,
+  "embeddedLanguageFormatting": "auto",
+  "plugins": ["prettier-plugin-organize-imports"]
+}

package/template/api/core/ApiClient.ts

@@ -0,0 +1,99 @@
+import type { APIRequestContext, APIResponse } from '@playwright/test';
+
+import type { ApiResponse, HttpMethod, RequestOptions } from './types';
+
+/**
+ * Layer 1 — the base HTTP client. A thin, typed wrapper over Playwright's APIRequestContext that
+ * exposes get/post/put/patch/delete, resolves paths against an optional basePath, and normalizes
+ * every response into an {@link ApiResponse} (status + parsed body). Service classes (layer 2) build
+ * on this; tests (layer 3) never touch the raw request context.
+ *
+ * @example
+ * const client = new ApiClient(request); // `request` is the Playwright fixture
+ * const res = await client.get<Pet[]>('/pet/findByStatus', { params: { status: 'available' } });
+ * expect(res.ok).toBeTruthy();
+ */
+export class ApiClient {
+  private readonly request: APIRequestContext;
+  private readonly basePath: string;
+  private readonly defaultHeaders: Record<string, string>;
+
+  /**
+   * @param request        Playwright's APIRequestContext (the built-in `request` fixture).
+   * @param basePath       Absolute API root prepended to every URL (e.g. 'https://host/api/v3').
+   *                       URLs are built by concatenation, so service paths keep their leading slash.
+   * @param defaultHeaders Headers sent on every request; a per-request `headers` value overrides
+   *                       them. Defaults to `Accept: application/json` — extend for auth tokens, etc.
+   */
+  constructor(
+    request: APIRequestContext,
+    basePath = '',
+    defaultHeaders: Record<string, string> = { Accept: 'application/json' },
+  ) {
+    this.request = request;
+    this.basePath = basePath;
+    this.defaultHeaders = defaultHeaders;
+  }
+
+  async get<T>(url: string, options?: RequestOptions): Promise<ApiResponse<T>> {
+    return this.send<T>('GET', url, options);
+  }
+
+  async post<T>(url: string, options?: RequestOptions): Promise<ApiResponse<T>> {
+    return this.send<T>('POST', url, options);
+  }
+
+  async put<T>(url: string, options?: RequestOptions): Promise<ApiResponse<T>> {
+    return this.send<T>('PUT', url, options);
+  }
+
+  async patch<T>(url: string, options?: RequestOptions): Promise<ApiResponse<T>> {
+    return this.send<T>('PATCH', url, options);
+  }
+
+  async delete<T>(url: string, options?: RequestOptions): Promise<ApiResponse<T>> {
+    return this.send<T>('DELETE', url, options);
+  }
+
+  /** Single code path for every verb: issue the request and normalize the response. */
+  private async send<T>(
+    method: HttpMethod,
+    url: string,
+    options: RequestOptions = {},
+  ): Promise<ApiResponse<T>> {
+    const response = await this.request.fetch(`${this.basePath}${url}`, {
+      method,
+      params: options.params,
+      headers: { ...this.defaultHeaders, ...options.headers },
+      data: options.data,
+    });
+
+    return {
+      status: response.status(),
+      ok: response.ok(),
+      headers: response.headers(),
+      data: await this.parseBody<T>(response),
+    };
+  }
+
+  /**
+   * Parse the body without throwing: JSON when the response advertises JSON, otherwise raw text;
+   * `undefined` for an empty body (e.g. a 204 or a bare-text DELETE). Reading via text() first
+   * avoids APIResponse.json() throwing on non-JSON payloads (Petstore's DELETE returns "Pet deleted").
+   */
+  private async parseBody<T>(response: APIResponse): Promise<T> {
+    const body = await response.text();
+    if (body.length === 0) {
+      return undefined as T;
+    }
+    const contentType = response.headers()['content-type'] ?? '';
+    if (contentType.includes('application/json')) {
+      try {
+        return JSON.parse(body) as T;
+      } catch {
+        return body as unknown as T;
+      }
+    }
+    return body as unknown as T;
+  }
+}

package/template/api/core/types.ts

@@ -0,0 +1,29 @@
+import type { APIRequestContext } from '@playwright/test';
+
+/** HTTP verbs supported by the base client. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/** The options accepted by Playwright's APIRequestContext.fetch — reused so our types never drift. */
+type FetchOptions = NonNullable<Parameters<APIRequestContext['fetch']>[1]>;
+
+/** Per-request options passed to the base client methods. */
+export interface RequestOptions {
+  /** Query-string parameters appended to the URL. */
+  params?: FetchOptions['params'];
+  /** Extra headers merged over the client/project defaults. */
+  headers?: FetchOptions['headers'];
+  /** Request body. A plain object is serialized as JSON (Content-Type set automatically). */
+  data?: FetchOptions['data'];
+}
+
+/** A parsed HTTP response: status + typed body, decoupled from Playwright's APIResponse. */
+export interface ApiResponse<T> {
+  /** HTTP status code (e.g. 200, 404). */
+  status: number;
+  /** True for 2xx responses. */
+  ok: boolean;
+  /** Parsed body: JSON when the response is JSON, else the raw text; undefined when the body is empty. */
+  data: T;
+  /** Response headers (lower-cased keys). */
+  headers: Record<string, string>;
+}

package/template/api/index.ts

@@ -0,0 +1,4 @@
+export { ApiClient } from './core/ApiClient';
+export type { ApiResponse, HttpMethod, RequestOptions } from './core/types';
+export type { Category, Pet, PetStatus, Tag } from './models/pet';
+export { PetService } from './services/PetService';

package/template/api/models/pet.ts

@@ -0,0 +1,24 @@
+/** Petstore domain models — the subset of the OpenAPI v3 schema these examples exercise. */
+
+/** A pet's lifecycle status in the store. */
+export type PetStatus = 'available' | 'pending' | 'sold';
+
+export interface Category {
+  id?: number;
+  name?: string;
+}
+
+export interface Tag {
+  id?: number;
+  name?: string;
+}
+
+export interface Pet {
+  /** Server-assigned id; must stay within JS safe-integer range when set by a test. */
+  id?: number;
+  name: string;
+  category?: Category;
+  photoUrls: string[];
+  tags?: Tag[];
+  status?: PetStatus;
+}

package/template/api/services/PetService.ts

@@ -0,0 +1,67 @@
+import type { ApiClient } from '../core/ApiClient';
+import type { Pet, PetStatus } from '../models/pet';
+
+/**
+ * Layer 2 — the business/service layer for Petstore's /pet resource. It calls the base
+ * {@link ApiClient} (layer 1) and turns raw HTTP into business operations: fetch by status, CRUD,
+ * and — the point of this layer — results the API does not offer directly, e.g. "available pets in
+ * a given category", by reading a list and filtering on a property HERE rather than in the test.
+ *
+ * @example
+ * const pets = await petService.findAvailableByCategory('Dogs');
+ */
+export class PetService {
+  private readonly client: ApiClient;
+
+  constructor(client: ApiClient) {
+    this.client = client;
+  }
+
+  /** GET /pet/findByStatus — every pet with the given status. */
+  async findByStatus(status: PetStatus): Promise<Pet[]> {
+    const res = await this.client.get<Pet[]>('/pet/findByStatus', { params: { status } });
+    if (!res.ok) {
+      throw new Error(`[PetService] findByStatus(${status}) failed: HTTP ${res.status}`);
+    }
+    return res.data ?? [];
+  }
+
+  /** Convenience wrapper: all currently available pets. */
+  async findAvailable(): Promise<Pet[]> {
+    return this.findByStatus('available');
+  }
+
+  /**
+   * Business rule (read-then-filter): fetch available pets, then keep only those carrying the given
+   * category name. The endpoint has no category filter, so the logic lives in this layer — the test
+   * just asks for "available Dogs" and asserts on the result.
+   */
+  async findAvailableByCategory(categoryName: string): Promise<Pet[]> {
+    const available = await this.findAvailable();
+    return available.filter(pet => pet.category?.name === categoryName);
+  }
+
+  /** GET /pet/{id} — a single pet. */
+  async getById(id: number): Promise<Pet> {
+    const res = await this.client.get<Pet>(`/pet/${id}`);
+    if (!res.ok) {
+      throw new Error(`[PetService] getById(${id}) failed: HTTP ${res.status}`);
+    }
+    return res.data;
+  }
+
+  /** POST /pet — create a pet, returning the created record. */
+  async create(pet: Pet): Promise<Pet> {
+    const res = await this.client.post<Pet>('/pet', { data: pet });
+    if (!res.ok) {
+      throw new Error(`[PetService] create('${pet.name}') failed: HTTP ${res.status}`);
+    }
+    return res.data;
+  }
+
+  /** DELETE /pet/{id} — remove a pet; returns the HTTP status so tests can assert on it. */
+  async deleteById(id: number): Promise<number> {
+    const res = await this.client.delete(`/pet/${id}`);
+    return res.status;
+  }
+}

package/template/config/envUtils.ts

@@ -0,0 +1,70 @@
+import { loadEnv } from './loadEnv';
+
+// Load the selected environment (TEST_ENV, default from environments.json)
+// before any getEnv call. Centralized so every consumer switches envs via one variable.
+loadEnv();
+
+/**
+ * Get environment variable value with optional default
+ * Removes surrounding quotes if present
+ * @param key - The environment variable key
+ * @param defaultValue - Optional default value if key is not found
+ * @returns The environment variable value or default value
+ * @throws Error if key is not found and no default value is provided
+ */
+export const getEnv = (key: string, defaultValue?: string): string => {
+  const value = process.env[key];
+
+  if (value === undefined) {
+    if (defaultValue !== undefined) {
+      return defaultValue;
+    }
+    throw new Error(`Environment variable "${key}" is not defined`);
+  }
+
+  // Remove surrounding quotes (both single and double) if present
+  // This handles cases where .env values are quoted
+  return value.replace(/^["']|["']$/g, '');
+};
+
+/**
+ * Get environment variable as a number
+ * @param key - The environment variable key
+ * @param defaultValue - Optional default value
+ * @returns The environment variable value as a number
+ */
+export const getEnvNumber = (key: string, defaultValue?: number): number => {
+  const value = getEnv(key, defaultValue?.toString());
+  const num = Number(value);
+
+  if (isNaN(num)) {
+    throw new Error(`Environment variable "${key}" must be a valid number, got "${value}"`);
+  }
+
+  return num;
+};
+
+/**
+ * Get environment variable as a boolean
+ * @param key - The environment variable key
+ * @param defaultValue - Optional default value
+ * @returns The environment variable value as a boolean
+ */
+export const getEnvBoolean = (key: string, defaultValue?: boolean): boolean => {
+  const value = getEnv(key, defaultValue?.toString());
+  return value.toLowerCase() === 'true' || value === '1' || value === 'yes';
+};
+
+/**
+ * Check if environment variable exists
+ * @param key - The environment variable key
+ * @returns true if the environment variable exists, false otherwise
+ */
+export const hasEnv = (key: string): boolean => process.env[key] !== undefined;
+
+/**
+ * Get all environment variables as an object
+ * @returns An object containing all environment variables
+ */
+export const getAllEnv = (): Record<string, string> =>
+  ({ ...process.env }) as Record<string, string>;

package/template/config/index.ts

@@ -0,0 +1,2 @@
+export { getAllEnv, getEnv, getEnvBoolean, getEnvNumber, hasEnv } from './envUtils';
+export { loadEnv } from './loadEnv';

package/template/config/loadEnv.ts

@@ -0,0 +1,110 @@
+import fs from 'fs';
+import path from 'path';
+
+// Single source of truth for environment loading. Every consumer (envUtils, the fixtures,
+// playwright.config) goes through loadEnv() so switching environments is a single variable change.
+//
+// All config lives in env/environments.json with two blocks:
+//   {
+//     "common":       { ...shared string keys, may contain ${TEST_ENV.X} tokens... },
+//     "environments": { "<env>": { "BASE_URL": "...", ...other per-env scalars... } }
+//   }
+// The environment is selected via TEST_ENV (falls back to common.DEFAULT_TEST_ENV). loadEnv flattens
+// every string scalar (from `common` and the selected environment block) into process.env, e.g.
+// common.DEFAULT_TEST_ENV and environments.dev.BASE_URL both become process.env keys.
+//
+// Login credentials do NOT live here — named sessions are in testData/users.json and consumed
+// directly by the auth fixtures (fixtures/auth.ts) when a session is first used.
+
+const ENV_FILE = 'environments.json';
+
+// Matches ${TEST_ENV.SOME_KEY} placeholders inside common string values; the key is resolved
+// against the selected environment block (e.g. ${TEST_ENV.BASE_URL}).
+const TEST_ENV_TOKEN = /\$\{TEST_ENV\.([A-Za-z0-9_]+)\}/g;
+
+let loaded = false;
+let resolvedEnv = '';
+
+interface EnvConfig {
+  common?: Record<string, unknown>;
+  environments?: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * Convert a config key to its flat env-var form: camelCase becomes SCREAMING_SNAKE_CASE
+ * (e.g. "supabaseUrl" -> "SUPABASE_URL"); an already upper/snake key is left unchanged.
+ */
+function toEnvKey(key: string): string {
+  return key.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+}
+
+/**
+ * Set a process.env key unless it is a documentation key (leading "_"/"$") or was already defined
+ * explicitly (e.g. an exported CI secret), so an explicit value always wins over the file.
+ */
+function setEnv(key: string, value: string): void {
+  if (key.startsWith('_') || key.startsWith('$')) {
+    return;
+  }
+  if (process.env[key] === undefined) {
+    process.env[key] = value;
+  }
+}
+
+/**
+ * Replace ${TEST_ENV.X} tokens in a string with the matching scalar from the selected environment
+ * block. An unknown/missing key resolves to an empty string so a malformed template degrades
+ * visibly rather than crashing the run.
+ */
+function resolveTokens(value: string, envBlock: Record<string, unknown>): string {
+  return value.replace(TEST_ENV_TOKEN, (_match, key: string) => {
+    const resolved = envBlock[key];
+    return typeof resolved === 'string' ? resolved : '';
+  });
+}
+
+/**
+ * Load env/environments.json, flattening string scalars into process.env keys. Idempotent — safe to
+ * call multiple times.
+ *
+ * Environment selection: TEST_ENV env var > common.DEFAULT_TEST_ENV fallback.
+ *
+ * @returns The name of the selected environment for logging/debugging.
+ */
+export function loadEnv(): string {
+  if (loaded) {
+    return resolvedEnv;
+  }
+  loaded = true;
+
+  const file = path.join(process.cwd(), 'env', ENV_FILE);
+  if (!fs.existsSync(file)) {
+    console.warn(`[loadEnv] ${file} not found — skipping.`);
+    return '';
+  }
+
+  const config = JSON.parse(fs.readFileSync(file, 'utf8')) as EnvConfig;
+  const common = config.common ?? {};
+
+  // Determine environment: explicit TEST_ENV wins, else fallback from common.
+  resolvedEnv = process.env.TEST_ENV ?? (common.DEFAULT_TEST_ENV as string) ?? '';
+
+  const envBlock = config.environments?.[resolvedEnv] ?? {};
+
+  // 1. Flatten common string scalars (resolve ${TEST_ENV.X} tokens against the env block).
+  for (const [key, val] of Object.entries(common)) {
+    if (typeof val === 'string') {
+      setEnv(toEnvKey(key), resolveTokens(val, envBlock));
+    }
+  }
+
+  // 2. Flatten the selected environment block's string scalars (BASE_URL, etc.).
+  for (const [key, val] of Object.entries(envBlock)) {
+    if (typeof val === 'string') {
+      setEnv(toEnvKey(key), val);
+    }
+  }
+
+  console.info(`[loadEnv] Loaded environment: ${resolvedEnv}`);
+  return resolvedEnv;
+}

package/template/env/environments.example.json

@@ -0,0 +1,20 @@
+{
+  "_note": "Per-environment test config. Select with TEST_ENV (default = common.DEFAULT_TEST_ENV). 'common' is merged into every env (with ${TEST_ENV.X} resolved from the selected env block). 'environments' holds per-env scalars: BASE_URL (UI, the Playwright baseURL) and API_BASE_URL (the api project's baseURL, kept separate so the two never collide). Every string scalar is flattened to a process.env key by loadEnv. Login sessions live in testData/users.json (not here). Plugins add their own keys under 'common' when installed.",
+  "common": {
+    "DEFAULT_TEST_ENV": "dev"
+  },
+  "environments": {
+    "dev": {
+      "BASE_URL": "https://www.saucedemo.com/",
+      "API_BASE_URL": "https://petstore3.swagger.io/api/v3"
+    },
+    "staging": {
+      "BASE_URL": "https://www.saucedemo.com/",
+      "API_BASE_URL": "https://petstore3.swagger.io/api/v3"
+    },
+    "production": {
+      "BASE_URL": "https://www.saucedemo.com/",
+      "API_BASE_URL": "https://petstore3.swagger.io/api/v3"
+    }
+  }
+}

package/template/eslint.config.js

@@ -0,0 +1,74 @@
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsparser from '@typescript-eslint/parser';
+import prettierConfig from 'eslint-config-prettier';
+import playwright from 'eslint-plugin-playwright';
+import prettier from 'eslint-plugin-prettier';
+
+export default [
+  {
+    ignores: [
+      'node_modules/**',
+      'dist/**',
+      'playwright-report/**',
+      'test-results/**',
+      'allure-results/**',
+      'allure-report/**',
+      '*.log',
+    ],
+  },
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+        projectService: true,
+      },
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+      playwright: playwright,
+      prettier: prettier,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      ...prettierConfig.rules,
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      '@typescript-eslint/no-namespace': 'off',
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
+      'no-console': ['warn', { allow: ['warn', 'error', 'info'] }],
+      'prefer-const': 'warn',
+      'no-var': 'error',
+      'prettier/prettier': ['error', { endOfLine: 'auto' }],
+    },
+  },
+  {
+    files: ['**/*.spec.ts', '**/*.test.ts', 'tests/**/*.ts'],
+    plugins: { playwright: playwright },
+    rules: {
+      ...playwright.configs['flat/recommended'].rules,
+      '@typescript-eslint/no-explicit-any': 'off',
+      // `test.as(session)('title', fn)` is a valid test block the plugin can't statically detect.
+      'playwright/no-standalone-expect': 'off',
+      'playwright/no-conditional-in-test': 'off',
+      'playwright/no-networkidle': 'off',
+    },
+  },
+];

package/template/fixtures/api.ts

@@ -0,0 +1,46 @@
+import { test as base, expect } from '@playwright/test';
+
+import { ApiClient } from '@api/core/ApiClient';
+import { PetService } from '@api/services/PetService';
+import { loadEnv } from '@config/loadEnv';
+
+// Load the selected environment (API_BASE_URL → the api project's baseURL) before any test runs.
+loadEnv();
+
+/** API-layer fixtures: the base client (layer 1) and the services (layer 2) built on top of it. */
+export interface ApiFixtures {
+  /** Layer 1 — base HTTP client bound to this test's APIRequestContext (baseURL = API_BASE_URL). */
+  apiClient: ApiClient;
+  /** Layer 2 — Petstore /pet business service. */
+  petService: PetService;
+}
+
+/**
+ * Test object for API tests. It extends the plain Playwright base (no browser/auth — API tests need
+ * neither) with an `apiClient` wrapping the built-in `request` fixture, so the client inherits the
+ * api project's baseURL/headers, plus the service objects. Import this in tests/api/*.api.ts.
+ *
+ * @example
+ * import { test, expect } from '@fixtures/apiFixtures';
+ * test('available pets', async ({ petService }) => {
+ *   const pets = await petService.findAvailable();
+ *   expect(pets.length).toBeGreaterThan(0);
+ * });
+ */
+export const test = base.extend<ApiFixtures>({
+  apiClient: async ({ request }, use) => {
+    // API_BASE_URL (env/environments.json) includes a path (/api/v3), so we pass it as the client's
+    // basePath and build URLs by absolute concatenation — a leading-slash path against a context
+    // baseURL would drop that path (WHATWG URL join) and hit the wrong host root.
+    const baseUrl = process.env.API_BASE_URL;
+    if (baseUrl === undefined || baseUrl.length === 0) {
+      throw new Error('[api] API_BASE_URL is not set (env/environments.json)');
+    }
+    await use(new ApiClient(request, baseUrl));
+  },
+  petService: async ({ apiClient }, use) => {
+    await use(new PetService(apiClient));
+  },
+});
+
+export { expect };