@desplega.ai/qa-use 2.16.0 → 2.18.0

package/lib/env/force-headless.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { assertHeadlessAllowed, isForceHeadless, resolveForcedHeadless } from './force-headless.js';
+import { clearConfigCache } from './index.js';
+
+const ENV_KEY = 'QA_USE_FORCE_HEADLESS';
+
+let saved: string | undefined;
+
+beforeEach(() => {
+  saved = process.env[ENV_KEY];
+  delete process.env[ENV_KEY];
+  clearConfigCache();
+});
+
+afterEach(() => {
+  if (saved === undefined) {
+    delete process.env[ENV_KEY];
+  } else {
+    process.env[ENV_KEY] = saved;
+  }
+  clearConfigCache();
+});
+
+describe('isForceHeadless', () => {
+  test('false when unset', () => {
+    expect(isForceHeadless()).toBe(false);
+  });
+
+  test('true for truthy values (case/whitespace insensitive)', () => {
+    for (const v of ['1', 'true', 'TRUE', ' yes ', 'on', 'On']) {
+      process.env[ENV_KEY] = v;
+      expect(isForceHeadless()).toBe(true);
+    }
+  });
+
+  test('false for falsy / empty values', () => {
+    for (const v of ['0', 'false', 'no', 'off', '']) {
+      process.env[ENV_KEY] = v;
+      expect(isForceHeadless()).toBe(false);
+    }
+  });
+});
+
+describe('assertHeadlessAllowed', () => {
+  test('no-op when force is off', () => {
+    expect(() => assertHeadlessAllowed(false, '--no-headless flag')).not.toThrow();
+  });
+
+  test('no-op when requested is true or undefined', () => {
+    process.env[ENV_KEY] = '1';
+    expect(() => assertHeadlessAllowed(true, 'src')).not.toThrow();
+    expect(() => assertHeadlessAllowed(undefined, 'src')).not.toThrow();
+  });
+
+  test('throws when force is on and requested is false', () => {
+    process.env[ENV_KEY] = '1';
+    expect(() => assertHeadlessAllowed(false, '--no-headless flag')).toThrow(
+      /QA_USE_FORCE_HEADLESS/
+    );
+    expect(() => assertHeadlessAllowed(false, '--no-headless flag')).toThrow(/--no-headless flag/);
+  });
+});
+
+describe('resolveForcedHeadless', () => {
+  test('passthrough when force is off', () => {
+    expect(resolveForcedHeadless(false)).toBe(false);
+    expect(resolveForcedHeadless(true)).toBe(true);
+    expect(resolveForcedHeadless(undefined)).toBeUndefined();
+  });
+
+  test('coerces undefined to true when force is on', () => {
+    process.env[ENV_KEY] = 'true';
+    expect(resolveForcedHeadless(undefined)).toBe(true);
+    expect(resolveForcedHeadless(true)).toBe(true);
+  });
+
+  test('throws on explicit false when force is on', () => {
+    process.env[ENV_KEY] = '1';
+    expect(() => resolveForcedHeadless(false, 'startBrowser options')).toThrow(
+      /startBrowser options/
+    );
+  });
+});

package/lib/env/force-headless.ts

@@ -0,0 +1,61 @@
+/**
+ * Operator-level "force headless" override.
+ *
+ * When `QA_USE_FORCE_HEADLESS` is set to a truthy value, qa-use refuses
+ * to launch a visible (headful) browser. Any explicit headful request
+ * — `--no-headless`, `--headful`, `defaults.headless: false`, or an MCP
+ * client passing `headless: false` — fails with a clear error.
+ *
+ * This is a hard policy switch for environments that must guarantee no
+ * visible browser ever opens (CI, locked-down hosts, security policy).
+ *
+ * The env var is read via `getEnv` so it also resolves through the
+ * `~/.qa-use.json` env block, consistent with other `QA_USE_*` vars.
+ */
+
+import { getEnv } from './index.js';
+
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+
+/**
+ * Returns `true` when force-headless is active.
+ */
+export function isForceHeadless(): boolean {
+  const raw = getEnv('QA_USE_FORCE_HEADLESS');
+  if (!raw) return false;
+  return TRUTHY.has(raw.trim().toLowerCase());
+}
+
+/**
+ * Throw if force-headless is on AND the caller explicitly asked for
+ * headful (`requested === false`). `undefined` and `true` pass through.
+ *
+ * `source` is interpolated into the error so the user can see which
+ * input triggered it (e.g. `"--no-headless flag"`).
+ */
+export function assertHeadlessAllowed(requested: boolean | undefined, source: string): void {
+  if (requested !== false) return;
+  if (!isForceHeadless()) return;
+  throw new Error(
+    `Headful browser mode is disabled by QA_USE_FORCE_HEADLESS.\n` +
+      `Triggered by: ${source}.\n` +
+      `Unset the env var or remove the headful request to proceed.`
+  );
+}
+
+/**
+ * Resolve the effective headless value at a launch site.
+ *
+ * - Asserts that an explicit `false` is not silently overridden.
+ * - When force-headless is on, coerces `undefined` to `true`.
+ * - Otherwise returns the requested value unchanged (callers keep
+ *   their existing `?? true` defaulting downstream).
+ */
+export function resolveForcedHeadless(
+  requested: boolean | undefined,
+  source = 'browser launch options'
+): boolean | undefined {
+  assertHeadlessAllowed(requested, source);
+  if (isForceHeadless()) return true;
+  return requested;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/qa-use",
-  "version": "2.16.0",
+  "version": "2.18.0",
   "packageManager": "bun@^1.3.4",
   "description": "QA automation tool for browser testing with MCP server support",
   "type": "module",