@esimplicitylabs/katalyst-xspec 0.6.0

package/dist/index.js

@@ -0,0 +1,1091 @@
+import {
+  assertMasked,
+  clearFetchIntercept,
+  defaultBearerConfig,
+  defaultBypassConfig,
+  interpolate,
+  isFlagEnabled,
+  parseExpected,
+  registerAllSteps,
+  registerApiAssertionSteps,
+  registerApiAuthSteps,
+  registerApiHttpSteps,
+  registerApiSteps,
+  registerCleanup,
+  registerDebugSteps,
+  registerFlagSteps,
+  registerFormSteps,
+  registerHybridSteps,
+  registerHybridSuite,
+  registerLayoutSteps,
+  registerSharedCleanupSteps,
+  registerSharedSteps,
+  registerSharedVarSteps,
+  registerTuiBasicSteps,
+  registerTuiSteps,
+  registerTuiWizardSteps,
+  registerUiAuthSteps,
+  registerUiBasicSteps,
+  registerUiSteps,
+  registerWizardSteps,
+  selectPath,
+  setFlag,
+  setupBearerAuth,
+  setupBypassAuth,
+  setupFetchIntercept,
+  tryParseJson
+} from "./chunk-ACAXOGKZ.js";
+
+// src/fixtures.ts
+import { test as base } from "playwright-bdd";
+import { expect as expect2 } from "@playwright/test";
+
+// src/world.ts
+function initWorld() {
+  return {
+    vars: {},
+    headers: {},
+    cleanup: []
+  };
+}
+
+// src/network.ts
+function resolveApiRequestTarget(baseURL, env = process.env) {
+  const flag = (env.KATALYST_XSPEC_FORCE_IPV4 ?? env.STACK_TESTS_FORCE_IPV4)?.trim().toLowerCase();
+  if (flag === "false" || flag === "0") return { baseURL };
+  let parsed;
+  try {
+    parsed = new URL(baseURL);
+  } catch {
+    return { baseURL };
+  }
+  if (parsed.protocol !== "http:" || !parsed.hostname.endsWith(".localhost")) {
+    return { baseURL };
+  }
+  const host = parsed.host;
+  parsed.hostname = "127.0.0.1";
+  let rewritten = parsed.toString();
+  if (!baseURL.endsWith("/") && rewritten.endsWith("/")) rewritten = rewritten.slice(0, -1);
+  return { baseURL: rewritten, extraHTTPHeaders: { Host: host } };
+}
+
+// src/adapters/api/playwright-api.adapter.ts
+var PlaywrightApiAdapter = class {
+  constructor(request) {
+    this.request = request;
+  }
+  async sendJson(method, path, body, headers) {
+    const opts = {
+      headers: { Accept: "application/json", ...headers || {} }
+    };
+    if (body !== void 0) {
+      opts.data = body;
+      opts.headers["Content-Type"] = "application/json";
+    }
+    const resp = await this.request.fetch(path, { method, ...opts });
+    const text = await resp.text();
+    const respHeaders = resp.headers();
+    const contentType = respHeaders["content-type"] || "";
+    const json = contentType.includes("application/json") ? tryParseJson(text) : tryParseJson(text);
+    return {
+      status: resp.status(),
+      text,
+      json,
+      headers: respHeaders,
+      contentType,
+      response: resp
+    };
+  }
+  async sendForm(method, path, form, headers) {
+    const body = new URLSearchParams(form).toString();
+    const resp = await this.request.fetch(path, {
+      method,
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/x-www-form-urlencoded",
+        ...headers || {}
+      },
+      data: body
+    });
+    const text = await resp.text();
+    const respHeaders = resp.headers();
+    const contentType = respHeaders["content-type"] || "";
+    const json = contentType.includes("application/json") ? tryParseJson(text) : tryParseJson(text);
+    return {
+      status: resp.status(),
+      text,
+      json,
+      headers: respHeaders,
+      contentType,
+      response: resp
+    };
+  }
+};
+
+// src/adapters/ui/playwright-ui.adapter.ts
+import { expect } from "@playwright/test";
+var PlaywrightUiAdapter = class {
+  constructor(page) {
+    this.page = page;
+  }
+  async goto(path) {
+    await this.page.goto(path);
+    await this.page.waitForLoadState("domcontentloaded");
+  }
+  async clickButton(name) {
+    await this.page.getByRole("button", { name }).first().click();
+  }
+  async clickLink(name) {
+    await this.page.getByRole("link", { name }).first().click();
+  }
+  async fillPlaceholder(placeholder, value) {
+    await this.page.getByPlaceholder(placeholder).first().fill(value);
+  }
+  async fillLabel(label, value) {
+    await this.page.getByLabel(label).first().fill(value);
+  }
+  async expectText(text) {
+    await expect(this.page.getByText(text).first()).toBeVisible();
+  }
+  async expectUrlContains(part) {
+    await expect(this.page).toHaveURL(new RegExp(part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+  }
+  async goBack() {
+    await this.page.goBack();
+  }
+  async reload() {
+    await this.page.reload();
+  }
+  async waitSeconds(seconds) {
+    await this.page.waitForTimeout(seconds * 1e3);
+  }
+  async waitForPageLoad() {
+    await this.page.waitForLoadState("domcontentloaded");
+    await this.page.waitForLoadState("load");
+    try {
+      await this.page.waitForLoadState("networkidle", { timeout: 5e3 });
+    } catch {
+    }
+  }
+  async getCurrentUrl() {
+    return this.page.url();
+  }
+  async zoomTo(scale) {
+    await this.page.evaluate((z) => {
+      document.documentElement.style.zoom = String(z);
+    }, scale);
+  }
+  async typeText(text) {
+    await this.page.keyboard.type(text);
+  }
+  async pressKey(key) {
+    await this.page.keyboard.press(key);
+  }
+  async clickElementThatContains(clickMode, elementType, text) {
+    const locator = this.page.locator(elementType).filter({ hasText: text }).first();
+    await this.performClick(locator, clickMode);
+  }
+  async clickElementWith(clickMode, ordinal, text, method) {
+    const idx = this.parseOrdinal(ordinal);
+    const locator = this.locatorBy(method, text).nth(idx);
+    await this.performClick(locator, clickMode);
+  }
+  async fillDropdown(value, dropdownLabel) {
+    const select = this.page.getByLabel(dropdownLabel).first();
+    try {
+      await select.selectOption({ label: value });
+    } catch {
+      await select.selectOption(value);
+    }
+  }
+  async inputInElement(action, value, ordinal, text, method) {
+    const idx = this.parseOrdinal(ordinal);
+    const locator = this.locatorBy(method, text).nth(idx);
+    if (action === "type") {
+      await locator.type(value);
+      return;
+    }
+    if (action === "fill") {
+      await locator.fill(value);
+      return;
+    }
+    try {
+      await locator.selectOption({ label: value });
+    } catch {
+      await locator.click({ force: true }).catch(() => {
+      });
+      await this.page.getByRole("option", { name: value }).first().click().catch(() => {
+      });
+      await this.page.getByText(value).first().click();
+    }
+  }
+  async expectUrl(mode, expected) {
+    this.assertUrlAgainst(this.page.url(), mode, expected);
+  }
+  async expectNewTabUrl(mode, expected) {
+    const context = this.page.context();
+    const alreadyOpen = context.pages().filter((p) => p !== this.page);
+    const newPage = alreadyOpen.length > 0 ? alreadyOpen[alreadyOpen.length - 1] : await context.waitForEvent("page", {
+      timeout: 1e4
+    });
+    await newPage.waitForLoadState("domcontentloaded");
+    this.assertUrlAgainst(newPage.url(), mode, expected);
+  }
+  async expectElementWithTextVisible(elementType, text, shouldBeVisible) {
+    const locator = this.page.locator(elementType).filter({ hasText: text });
+    if (shouldBeVisible) {
+      await expect(locator.first()).toBeVisible();
+      return;
+    }
+    if (await locator.count() === 0) {
+      await expect(locator).toHaveCount(0);
+      return;
+    }
+    await expect(locator.first()).toBeHidden();
+  }
+  async expectElementState(ordinal, text, method, state) {
+    const idx = this.parseOrdinal(ordinal);
+    const locator = this.locatorBy(method, text).nth(idx);
+    await this.expectState(locator, state);
+  }
+  async expectElementStateWithin(ordinal, text, method, state, seconds) {
+    const idx = this.parseOrdinal(ordinal);
+    const locator = this.locatorBy(method, text).nth(idx);
+    await this.expectState(locator, state, { timeout: seconds * 1e3 });
+  }
+  parseOrdinal(ordinal) {
+    const n = Number.parseInt(String(ordinal), 10);
+    if (!Number.isFinite(n) || n < 1) {
+      throw new Error(`Invalid element ordinal '${ordinal}'. Expected 1,2,3...`);
+    }
+    return n - 1;
+  }
+  locatorBy(method, text) {
+    switch (method) {
+      case "text":
+        return this.page.getByText(text);
+      case "label":
+        return this.page.getByLabel(text);
+      case "placeholder":
+        return this.page.getByPlaceholder(text);
+      case "role":
+        return this.page.getByRole(text);
+      case "test ID":
+        return this.page.getByTestId(text);
+      case "alternative text":
+        return this.page.getByAltText(text);
+      case "title":
+        return this.page.getByTitle(text);
+      case "locator":
+        return this.page.locator(text);
+      default: {
+        const neverMethod = method;
+        throw new Error(`Unsupported locator method: ${neverMethod}`);
+      }
+    }
+  }
+  async performClick(locator, clickMode) {
+    if (clickMode === "dispatch click") {
+      await locator.dispatchEvent("click");
+      return;
+    }
+    if (clickMode === "force click") {
+      await locator.click({ force: true });
+      return;
+    }
+    if (clickMode === "force dispatch click") {
+      await locator.dispatchEvent("click");
+      return;
+    }
+    await locator.click();
+  }
+  async expectState(locator, state, options) {
+    if (state === "visible") {
+      await expect(locator).toBeVisible(options);
+      return;
+    }
+    if (state === "hidden") {
+      await expect(locator).toBeHidden(options);
+      return;
+    }
+    if (state === "editable") {
+      await expect(locator).toBeEditable(options);
+      return;
+    }
+    if (state === "disabled") {
+      await expect(locator).toBeDisabled(options);
+      return;
+    }
+    if (state === "enabled") {
+      await expect(locator).toBeEnabled(options);
+      return;
+    }
+    if (state === "read-only") {
+      await expect(locator).toHaveJSProperty("readOnly", true, options);
+      return;
+    }
+    const neverState = state;
+    throw new Error(`Unsupported expected state: ${neverState}`);
+  }
+  assertUrlAgainst(actualUrl, mode, expected) {
+    const expectedStr = String(expected);
+    const assertFor = (actual) => {
+      if (mode === "contains") {
+        expect(actual).toContain(expectedStr);
+        return;
+      }
+      if (mode === "doesntContain") {
+        expect(actual).not.toContain(expectedStr);
+        return;
+      }
+      if (mode === "equals") {
+        expect(actual).toBe(expectedStr);
+        return;
+      }
+      const neverMode = mode;
+      throw new Error(`Unsupported URL assertion mode: ${neverMode}`);
+    };
+    if (expectedStr.startsWith("/")) {
+      const u = new URL(actualUrl);
+      const actualPath = `${u.pathname}${u.search}${u.hash}`;
+      assertFor(actualPath);
+      return;
+    }
+    assertFor(actualUrl);
+  }
+};
+
+// src/adapters/auth/universal-auth.adapter.ts
+var UniversalAuthAdapter = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  apiSetBearer(world, token) {
+    world.headers = { ...world.headers || {}, Authorization: `Bearer ${token}` };
+  }
+  async apiLoginAsAdmin(world) {
+    const username = process.env.DEFAULT_ADMIN_USERNAME || process.env.DEFAULT_ADMIN_EMAIL;
+    const password = process.env.DEFAULT_ADMIN_PASSWORD;
+    if (!username || !password) {
+      console.warn("apiLoginAsAdmin skipped: DEFAULT_ADMIN_USERNAME and DEFAULT_ADMIN_PASSWORD are not set");
+      return;
+    }
+    await this.apiLogin(world, username, password);
+  }
+  async apiLoginAsUser(world) {
+    const username = process.env.DEFAULT_USER_USERNAME || process.env.NON_ADMIN_USERNAME;
+    const password = process.env.DEFAULT_USER_PASSWORD || process.env.NON_ADMIN_PASSWORD;
+    if (!username || !password) {
+      console.warn("apiLoginAsUser skipped: DEFAULT_USER_USERNAME and DEFAULT_USER_PASSWORD are not set");
+      return;
+    }
+    await this.apiLogin(world, username, password);
+  }
+  async apiLogin(world, username, password) {
+    const loginPath = process.env.API_AUTH_LOGIN_PATH || "/auth/login";
+    const result = await this.deps.api.sendForm("POST", loginPath, { username, password });
+    world.lastStatus = result.status;
+    world.lastText = result.text;
+    world.lastJson = result.json;
+    world.lastHeaders = result.headers;
+    const json = result.json || {};
+    const token = json?.access_token;
+    if (typeof token !== "string" || !token) {
+      throw new Error(`API login failed for ${username}: ${result.status} ${result.text}`);
+    }
+    this.apiSetBearer(world, token);
+  }
+  async uiLoginAsAdmin(world) {
+    const username = process.env.DEFAULT_ADMIN_USERNAME || process.env.DEFAULT_ADMIN_EMAIL;
+    const password = process.env.DEFAULT_ADMIN_PASSWORD;
+    if (!username || !password) {
+      console.warn("uiLoginAsAdmin skipped: DEFAULT_ADMIN_USERNAME and DEFAULT_ADMIN_PASSWORD are not set");
+      return;
+    }
+    await this.uiLogin(world, username, password);
+  }
+  async uiLoginAsUser(world) {
+    const username = process.env.DEFAULT_USER_USERNAME || process.env.NON_ADMIN_USERNAME;
+    const password = process.env.DEFAULT_USER_PASSWORD || process.env.NON_ADMIN_PASSWORD;
+    if (!username || !password) {
+      console.warn("uiLoginAsUser skipped: DEFAULT_USER_USERNAME and DEFAULT_USER_PASSWORD are not set");
+      return;
+    }
+    await this.uiLogin(world, username, password);
+  }
+  async uiLogin(_world, username, password) {
+    const loginPath = process.env.UI_LOGIN_PATH || "/login";
+    const usernameField = process.env.UI_USERNAME_FIELD || "Username";
+    const passwordField = process.env.UI_PASSWORD_FIELD || "Password";
+    const loginButton = process.env.UI_LOGIN_BUTTON || "Login";
+    await this.deps.ui.goto(loginPath);
+    await this.deps.ui.fillPlaceholder(usernameField, username);
+    await this.deps.ui.fillPlaceholder(passwordField, password);
+    await this.deps.ui.clickButton(loginButton);
+  }
+};
+
+// src/adapters/cleanup/default-cleanup.adapter.ts
+function looksTesty(meta) {
+  const s = typeof meta === "string" ? meta : JSON.stringify(meta ?? "");
+  return /__|test/i.test(s);
+}
+function isIdLike(value) {
+  const uuidPattern = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+  const prefixedIdPattern = /^[a-z]+_[a-zA-Z0-9_-]+$/;
+  const numericPattern = /^\d+$/;
+  const objectIdPattern = /^[0-9a-fA-F]{24}$/;
+  const cuidPattern = /^c[a-z0-9]{24,}$/;
+  const ulidPattern = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+  return uuidPattern.test(value) || prefixedIdPattern.test(value) || numericPattern.test(value) || objectIdPattern.test(value) || cuidPattern.test(value) || ulidPattern.test(value);
+}
+function matchVar(rule, varNameLower) {
+  const m = rule.varMatch;
+  if (m.startsWith("/") && m.endsWith("/") && m.length > 2) {
+    const re = new RegExp(m.slice(1, -1));
+    return re.test(varNameLower);
+  }
+  return varNameLower.includes(m.toLowerCase());
+}
+function loadRulesFromEnv() {
+  const raw = process.env.CLEANUP_RULES?.trim();
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+      return parsed.filter((x) => x && typeof x === "object").map((x) => ({
+        varMatch: String(x.varMatch ?? ""),
+        method: x.method ? String(x.method).toUpperCase() : void 0,
+        path: String(x.path ?? ""),
+        body: x.body
+      })).filter((r) => r.varMatch && r.path);
+    }
+  } catch {
+  }
+  return [];
+}
+var defaultRules = [];
+var DefaultCleanupAdapter = class {
+  constructor(input) {
+    const fromEnv = loadRulesFromEnv();
+    this.rules = input?.rules && input.rules.length ? input.rules : [...fromEnv, ...defaultRules];
+    this.allowHeuristic = input?.allowHeuristic ?? /^(1|true|yes|on)$/i.test(process.env.CLEANUP_ALLOW_ALL || "");
+  }
+  registerFromVar(world, varName, id, meta) {
+    if (!id) return;
+    const idStr = String(id);
+    if (!isIdLike(idStr)) return;
+    if (!this.allowHeuristic) {
+      if (!looksTesty(meta) && !looksTesty(varName)) return;
+    }
+    const name = (varName || "").toLowerCase();
+    const rule = this.rules.find((r) => matchVar(r, name));
+    if (!rule) return;
+    const path = rule.path.replace(/\{id\}/g, idStr);
+    registerCleanup(world, { method: rule.method ?? "DELETE", path, body: rule.body });
+  }
+};
+
+// src/fixtures.ts
+var cachedAdminToken;
+async function defaultGetAdminHeaders(request) {
+  if (cachedAdminToken) {
+    return { Authorization: `Bearer ${cachedAdminToken}` };
+  }
+  const staticToken = process.env.CLEANUP_AUTH_TOKEN;
+  if (staticToken) {
+    cachedAdminToken = staticToken;
+    return { Authorization: `Bearer ${staticToken}` };
+  }
+  const username = process.env.DEFAULT_ADMIN_USERNAME || process.env.DEFAULT_ADMIN_EMAIL;
+  const password = process.env.DEFAULT_ADMIN_PASSWORD;
+  if (!username || !password) {
+    return {};
+  }
+  const loginPath = process.env.API_AUTH_LOGIN_PATH || "/auth/login";
+  const body = new URLSearchParams({ username, password }).toString();
+  const resp = await request.post(loginPath, {
+    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+    data: body
+  });
+  if (!resp.ok()) {
+    console.warn(`cleanup auth failed: ${resp.status()} ${resp.statusText()}`);
+    cachedAdminToken = void 0;
+    return {};
+  }
+  const json = await resp.json();
+  const token = json?.access_token;
+  if (typeof token === "string" && token) {
+    cachedAdminToken = token;
+    return { Authorization: `Bearer ${token}` };
+  }
+  console.warn("cleanup auth: no access_token in response");
+  cachedAdminToken = void 0;
+  return {};
+}
+function createBddTest(options = {}) {
+  const {
+    createApi = ({ apiRequest }) => new PlaywrightApiAdapter(apiRequest),
+    createUi = ({ page }) => new PlaywrightUiAdapter(page),
+    createAuth = ({ api, ui }) => new UniversalAuthAdapter({ api, ui }),
+    createCleanup = () => new DefaultCleanupAdapter(),
+    getCleanupAuth = defaultGetAdminHeaders,
+    createTui,
+    worldFactory = initWorld
+  } = options;
+  const test = base.extend({
+    world: async ({ apiRequest }, use) => {
+      const w = worldFactory();
+      await use(w);
+      if (w.skipCleanup) return;
+      if (!w.cleanup.length) return;
+      for (const item of [...w.cleanup].reverse()) {
+        const adminHeaders = await getCleanupAuth(apiRequest);
+        const headers = { ...adminHeaders, ...item.headers || {} };
+        if (item.body !== void 0) {
+          headers["Content-Type"] = "application/json";
+        }
+        try {
+          const resp = await apiRequest.fetch(item.path, {
+            method: item.method,
+            headers,
+            data: item.body
+          });
+          const status = resp.status();
+          if (status === 401 || status === 403) {
+            cachedAdminToken = void 0;
+            console.warn(`cleanup auth expired (${status}) for ${item.method} ${item.path}`);
+            continue;
+          }
+          if (status >= 400 && status !== 404) {
+            console.warn(`cleanup ${item.method} ${item.path} failed`, status);
+          }
+        } catch (err) {
+          console.warn("cleanup error", item.method, item.path, err);
+        }
+      }
+    },
+    apiRequest: async ({ playwright }, use, testInfo) => {
+      const projectName = String(testInfo.project.name || "");
+      const baseURLFromProject = testInfo.project.use?.baseURL;
+      const baseURL = process.env.API_BASE_URL || process.env.TARGET_BASE_URL || (projectName.includes("api") ? baseURLFromProject : void 0) || (process.env.TARGET_PORT ? `http://localhost:${process.env.TARGET_PORT}` : void 0) || "http://localhost:3000";
+      const ctx = await playwright.request.newContext(resolveApiRequestTarget(baseURL));
+      try {
+        await use(ctx);
+      } finally {
+        await ctx.dispose();
+      }
+    },
+    api: async ({ apiRequest }, use) => {
+      await use(createApi({ apiRequest }));
+    },
+    cleanup: async ({ apiRequest }, use) => {
+      await use(createCleanup({ apiRequest }));
+    },
+    ui: async ({ page }, use) => {
+      await use(createUi({ page }));
+    },
+    auth: async ({ api, ui }, use) => {
+      await use(createAuth({ api, ui }));
+    },
+    /**
+     * TUI fixture for terminal user interface testing.
+     * Automatically stops the TUI application after the test completes.
+     */
+    tui: async ({}, use) => {
+      const tuiAdapter = createTui?.();
+      await use(tuiAdapter);
+      if (tuiAdapter?.isRunning?.()) {
+        try {
+          await tuiAdapter.stop();
+        } catch (error) {
+          console.warn("Error stopping TUI adapter:", error);
+        }
+      }
+    }
+  });
+  return { test, expect: expect2 };
+}
+
+// src/adapters/tui/tui-tester.adapter.ts
+var DEFAULT_WAIT_OPTIONS = {
+  timeout: 3e4,
+  interval: 100
+};
+var KEY_MAP = {
+  enter: "enter",
+  return: "enter",
+  tab: "tab",
+  escape: "escape",
+  esc: "escape",
+  backspace: "backspace",
+  delete: "delete",
+  up: "up",
+  down: "down",
+  left: "left",
+  right: "right",
+  home: "home",
+  end: "end",
+  pageup: "pageup",
+  pagedown: "pagedown",
+  space: "space",
+  f1: "f1",
+  f2: "f2",
+  f3: "f3",
+  f4: "f4",
+  f5: "f5",
+  f6: "f6",
+  f7: "f7",
+  f8: "f8",
+  f9: "f9",
+  f10: "f10",
+  f11: "f11",
+  f12: "f12"
+};
+var TuiTesterAdapter = class {
+  constructor(config) {
+    this.tester = null;
+    this.running = false;
+    this.tuiTesterModule = null;
+    this.config = {
+      size: { cols: 80, rows: 24 },
+      ...config
+    };
+  }
+  /**
+   * Lazily load the tui-tester module to support optional dependency
+   */
+  async loadTuiTester() {
+    if (this.tuiTesterModule) {
+      return this.tuiTesterModule;
+    }
+    try {
+      const module = await import("tui-tester");
+      this.tuiTesterModule = module;
+      return module;
+    } catch (error) {
+      throw new Error(
+        "tui-tester is not installed. Please install it with: npm install tui-tester\nAlso ensure tmux is installed on your system."
+      );
+    }
+  }
+  /**
+   * Get the tester instance, throwing if not started
+   */
+  getTester() {
+    if (!this.tester) {
+      throw new Error("TUI tester not started. Call start() first.");
+    }
+    return this.tester;
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Lifecycle Methods
+  // ═══════════════════════════════════════════════════════════════════════════
+  async start() {
+    if (this.running) {
+      return;
+    }
+    const { TmuxTester } = await this.loadTuiTester();
+    this.tester = new TmuxTester({
+      command: this.config.command,
+      size: this.config.size,
+      cwd: this.config.cwd,
+      env: this.config.env,
+      debug: this.config.debug,
+      shell: this.config.shell,
+      snapshotDir: this.config.snapshotDir
+    });
+    await this.tester.start();
+    this.running = true;
+  }
+  async stop() {
+    if (!this.running || !this.tester) {
+      return;
+    }
+    try {
+      await this.tester.stop();
+    } finally {
+      this.running = false;
+      this.tester = null;
+    }
+  }
+  async restart() {
+    await this.stop();
+    await this.start();
+  }
+  isRunning() {
+    return this.running && this.tester !== null;
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Input Methods
+  // ═══════════════════════════════════════════════════════════════════════════
+  async typeText(text, options) {
+    const tester = this.getTester();
+    await tester.typeText(text, options?.delay);
+  }
+  async pressKey(key, modifiers) {
+    const tester = this.getTester();
+    const normalizedKey = KEY_MAP[key.toLowerCase()] || key.toLowerCase();
+    await tester.sendKey(normalizedKey, {
+      ctrl: modifiers?.ctrl,
+      alt: modifiers?.alt,
+      shift: modifiers?.shift
+    });
+  }
+  async sendText(text) {
+    const tester = this.getTester();
+    await tester.sendText(text);
+  }
+  async fillField(fieldLabel, value) {
+    const tester = this.getTester();
+    await tester.waitForText(fieldLabel, { timeout: DEFAULT_WAIT_OPTIONS.timeout });
+    await tester.typeText(value);
+  }
+  async selectOption(option) {
+    const tester = this.getTester();
+    await tester.waitForText(option, { timeout: DEFAULT_WAIT_OPTIONS.timeout });
+    await tester.sendKey("enter");
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Mouse Methods
+  // ═══════════════════════════════════════════════════════════════════════════
+  async sendMouse(event) {
+    const tester = this.getTester();
+    await tester.sendMouse({
+      type: event.type,
+      position: event.position,
+      button: event.button
+    });
+  }
+  async click(x, y, button = "left") {
+    await this.sendMouse({
+      type: "click",
+      position: { x, y },
+      button
+    });
+  }
+  async clickOnText(text) {
+    const tester = this.getTester();
+    const lines = await tester.getScreenLines();
+    let found = false;
+    for (let y = 0; y < lines.length; y++) {
+      const x = lines[y].indexOf(text);
+      if (x !== -1) {
+        await this.click(x, y);
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      throw new Error(`Text "${text}" not found on screen`);
+    }
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Assertion Methods
+  // ═══════════════════════════════════════════════════════════════════════════
+  async expectText(text, options) {
+    const tester = this.getTester();
+    const opts = { ...DEFAULT_WAIT_OPTIONS, ...options };
+    await tester.waitForText(text, { timeout: opts.timeout });
+  }
+  async expectPattern(pattern, options) {
+    const tester = this.getTester();
+    const opts = { ...DEFAULT_WAIT_OPTIONS, ...options };
+    await tester.waitForPattern(pattern, { timeout: opts.timeout });
+  }
+  async expectNotText(text) {
+    const screenText = await this.getScreenText();
+    if (screenText.includes(text)) {
+      throw new Error(`Expected text "${text}" to NOT be present on screen, but it was found.`);
+    }
+  }
+  async assertScreenContains(text) {
+    const tester = this.getTester();
+    await tester.assertScreenContains(text);
+  }
+  async assertScreenMatches(pattern) {
+    const screenText = await this.getScreenText();
+    if (!pattern.test(screenText)) {
+      throw new Error(`Screen content does not match pattern: ${pattern}
+Screen content:
+${screenText}`);
+    }
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Wait Methods
+  // ═══════════════════════════════════════════════════════════════════════════
+  async waitForText(text, options) {
+    await this.expectText(text, options);
+  }
+  async waitForPattern(pattern, options) {
+    await this.expectPattern(pattern, options);
+  }
+  async waitForReady() {
+    const tester = this.getTester();
+    await tester.sleep(500);
+  }
+  async waitSeconds(seconds) {
+    const tester = this.getTester();
+    await tester.sleep(seconds * 1e3);
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Screen Capture Methods
+  // ═══════════════════════════════════════════════════════════════════════════
+  async captureScreen() {
+    const tester = this.getTester();
+    const capture = await tester.captureScreen();
+    const lines = capture.lines || await tester.getScreenLines();
+    return {
+      text: capture.text,
+      lines,
+      timestamp: Date.now(),
+      size: this.getSize()
+    };
+  }
+  async getScreenText() {
+    const tester = this.getTester();
+    return tester.getScreenText();
+  }
+  async getScreenLines() {
+    const tester = this.getTester();
+    return tester.getScreenLines();
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Snapshot Methods
+  // ═══════════════════════════════════════════════════════════════════════════
+  async takeSnapshot(name) {
+    const tester = this.getTester();
+    await tester.takeSnapshot(name);
+  }
+  async matchSnapshot(name) {
+    const tester = this.getTester();
+    try {
+      const result = await tester.compareSnapshot(name);
+      return {
+        pass: result.pass,
+        diff: result.diff
+      };
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("not found")) {
+        await this.takeSnapshot(name);
+        return { pass: true };
+      }
+      throw error;
+    }
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Utility Methods
+  // ═══════════════════════════════════════════════════════════════════════════
+  async clear() {
+    const tester = this.getTester();
+    await tester.clear();
+  }
+  async resize(size) {
+    const tester = this.getTester();
+    await tester.resize(size);
+    this.config.size = size;
+  }
+  getSize() {
+    if (this.tester) {
+      return this.tester.getSize();
+    }
+    return this.config.size || { cols: 80, rows: 24 };
+  }
+  getConfig() {
+    return { ...this.config };
+  }
+};
+
+// src/helpers/oidc-cleanup-auth.ts
+var cachedOidcToken;
+var cachedOidcHeaders;
+function createOidcCleanupAuth(config = {}) {
+  return async (_request) => {
+    if (cachedOidcToken && cachedOidcHeaders) {
+      return cachedOidcHeaders;
+    }
+    const tokenUrl = config.tokenUrl || process.env.OIDC_TOKEN_URL;
+    const clientId = config.clientId || process.env.OIDC_CLIENT_ID;
+    const clientSecret = config.clientSecret || process.env.OIDC_CLIENT_SECRET;
+    const grantType = config.grantType || process.env.OIDC_GRANT_TYPE || "client_credentials";
+    const scope = config.scope || process.env.OIDC_SCOPE;
+    const username = config.username || process.env.OIDC_USERNAME;
+    const password = config.password || process.env.OIDC_PASSWORD;
+    if (!tokenUrl || !clientId) {
+      console.warn("OIDC cleanup auth skipped: OIDC_TOKEN_URL and OIDC_CLIENT_ID are required");
+      return {};
+    }
+    const params = {
+      client_id: clientId,
+      grant_type: grantType
+    };
+    if (clientSecret) params.client_secret = clientSecret;
+    if (scope) params.scope = scope;
+    if (username) params.username = username;
+    if (password) params.password = password;
+    try {
+      const resp = await fetch(tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(params)
+      });
+      if (!resp.ok) {
+        console.warn(`OIDC cleanup auth failed: ${resp.status} ${resp.statusText}`);
+        cachedOidcToken = void 0;
+        cachedOidcHeaders = void 0;
+        return {};
+      }
+      const json = await resp.json();
+      const token = json?.access_token;
+      if (typeof token === "string" && token) {
+        cachedOidcToken = token;
+        const headers = {
+          Authorization: `Bearer ${token}`
+        };
+        if (config.extraHeaders) {
+          Object.assign(headers, config.extraHeaders);
+        }
+        const envHeaders = process.env.OIDC_EXTRA_HEADERS;
+        if (envHeaders) {
+          try {
+            const parsed = JSON.parse(envHeaders);
+            if (parsed && typeof parsed === "object") {
+              Object.assign(headers, parsed);
+            }
+          } catch {
+          }
+        }
+        cachedOidcHeaders = headers;
+        return headers;
+      }
+    } catch (err) {
+      console.warn("OIDC cleanup auth error:", err);
+    }
+    cachedOidcToken = void 0;
+    cachedOidcHeaders = void 0;
+    return {};
+  };
+}
+function resetOidcCleanupAuth() {
+  cachedOidcToken = void 0;
+  cachedOidcHeaders = void 0;
+}
+
+// src/config.ts
+function tagsForProject({ projectTag, extraTags, defaultExcludes = "not @Skip and not @ignore" }) {
+  if (extraTags) return `${defaultExcludes} and ${projectTag} and (${extraTags})`;
+  return `${defaultExcludes} and ${projectTag}`;
+}
+function resolveExtraTags(raw) {
+  const tagFilterRaw = raw?.trim();
+  if (!tagFilterRaw) return void 0;
+  const looksLikeExpression = /\s|@|\bnot\b|\band\b|\bor\b/.test(tagFilterRaw);
+  if (looksLikeExpression) return tagFilterRaw;
+  const parts = tagFilterRaw.split(",").map((s) => s.trim()).filter(Boolean).map((t) => t.startsWith("@") ? t : `@${t}`);
+  if (!parts.length) return void 0;
+  return parts.join(" or ");
+}
+
+// src/workers.ts
+import os from "os";
+function resolveWorkers(options = {}) {
+  const { testType, ciWorkers = 1, defaultWorkers } = options;
+  if (testType === "tui") {
+    return 1;
+  }
+  const workersEnv = process.env.WORKERS?.trim();
+  if (workersEnv && workersEnv.toLowerCase() !== "auto") {
+    const parsed = parseInt(workersEnv, 10);
+    if (!isNaN(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  if (process.env.CI) {
+    return ciWorkers;
+  }
+  return defaultWorkers;
+}
+function getCpuCount() {
+  return os.cpus().length;
+}
+
+// src/paths.ts
+function resolveFeatures(options = {}) {
+  const { defaultDir = "features" } = options;
+  const envValue = process.env.FEATURES_DIR?.trim();
+  if (envValue) {
+    return envValue;
+  }
+  return defaultDir;
+}
+function resolveSteps(options = {}) {
+  const { defaultDir = "features/steps" } = options;
+  const envValue = process.env.CUSTOM_STEPS_DIR?.trim();
+  if (envValue) {
+    return envValue;
+  }
+  return defaultDir;
+}
+function resolveBddPaths(options = {}) {
+  const { tag, featuresOptions, stepsOptions } = options;
+  const featuresDir = resolveFeatures(featuresOptions);
+  const stepsDir = resolveSteps(stepsOptions);
+  const features = tag ? `${featuresDir}/${tag}/**/*.feature` : `${featuresDir}/**/*.feature`;
+  const steps = `${stepsDir}/**/*.ts`;
+  return { features, steps };
+}
+export {
+  DefaultCleanupAdapter,
+  PlaywrightApiAdapter,
+  PlaywrightUiAdapter,
+  TuiTesterAdapter,
+  UniversalAuthAdapter,
+  assertMasked,
+  base as baseTest,
+  clearFetchIntercept,
+  createBddTest,
+  createOidcCleanupAuth,
+  defaultBearerConfig,
+  defaultBypassConfig,
+  getCpuCount,
+  initWorld,
+  interpolate,
+  isFlagEnabled,
+  parseExpected,
+  registerAllSteps,
+  registerApiAssertionSteps,
+  registerApiAuthSteps,
+  registerApiHttpSteps,
+  registerApiSteps,
+  registerCleanup,
+  registerDebugSteps,
+  registerFlagSteps,
+  registerFormSteps,
+  registerHybridSteps,
+  registerHybridSuite,
+  registerLayoutSteps,
+  registerSharedCleanupSteps,
+  registerSharedSteps,
+  registerSharedVarSteps,
+  registerTuiBasicSteps,
+  registerTuiSteps,
+  registerTuiWizardSteps,
+  registerUiAuthSteps,
+  registerUiBasicSteps,
+  registerUiSteps,
+  registerWizardSteps,
+  resetOidcCleanupAuth,
+  resolveApiRequestTarget,
+  resolveBddPaths,
+  resolveExtraTags,
+  resolveFeatures,
+  resolveSteps,
+  resolveWorkers,
+  selectPath,
+  setFlag,
+  setupBearerAuth,
+  setupBypassAuth,
+  setupFetchIntercept,
+  tagsForProject,
+  tryParseJson
+};