@qualflare/cypress 0.1.0

package/dist/index.cjs

@@ -0,0 +1,931 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  qualflare: () => qualflare
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/browser/browser-integration-guard.ts
+function initializeBrowserIntegration(register) {
+  const target = typeof Cypress === "undefined" ? void 0 : Cypress;
+  if (target?.__qualflareBrowserRegistered) {
+    return;
+  }
+  if (target) {
+    target.__qualflareBrowserRegistered = true;
+  }
+  register();
+}
+
+// src/shared/constants.ts
+var TASK_REPORT_CASE = "qualflareReportCase";
+var TASK_MARK_TEST_PHASE_STARTED = "qualflareMarkTestPhaseStarted";
+var MAX_PARAMETERS_PER_STEP = 50;
+var MAX_ATTACHMENTS_PER_CASE = 50;
+var MAX_LABELS_PER_CASE = 100;
+var MAX_LINKS_PER_CASE = 20;
+var MAX_TAGS_PER_CASE = 64;
+var MAX_TAG_LENGTH = 255;
+var MAX_STEPS_PER_TEST_ATTEMPT = 300;
+
+// src/shared/duration.ts
+var NS_PER_MS = 1e6;
+function msToNs(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) {
+    return 0;
+  }
+  return Math.round(ms * NS_PER_MS);
+}
+
+// src/shared/logger.ts
+var PREFIX = "[qualflare-cypress]";
+var logger = {
+  debug(...args) {
+    console.debug(PREFIX, ...args);
+  },
+  info(...args) {
+    console.log(PREFIX, ...args);
+  },
+  warn(...args) {
+    console.warn(PREFIX, ...args);
+  },
+  error(...args) {
+    console.error(PREFIX, ...args);
+  }
+};
+
+// src/browser/console-props.ts
+var MAX_VALUE_CHARS = 500;
+var MAX_STRINGIFY_DEPTH = 3;
+function safeStringify(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  const type = typeof value;
+  if (type === "string") {
+    return truncate(value);
+  }
+  if (type === "number" || type === "boolean" || type === "bigint") {
+    return truncate(String(value));
+  }
+  if (type === "function") {
+    return "[function]";
+  }
+  if (type === "symbol") {
+    return value.toString();
+  }
+  const obj = value;
+  if (seen.has(obj)) {
+    return "[circular]";
+  }
+  seen.add(obj);
+  try {
+    if (isDomElementLike(obj)) {
+      return describeDomElementLike(obj);
+    }
+    if (depth >= MAX_STRINGIFY_DEPTH) {
+      return Array.isArray(obj) ? "[array]" : "[object]";
+    }
+    if (Array.isArray(obj)) {
+      const items = obj.slice(0, 20).map((item) => safeStringify(item, depth + 1, seen));
+      const suffix = obj.length > 20 ? `, \u2026(${obj.length - 20} more)` : "";
+      return truncate(`[${items.join(", ")}${suffix}]`);
+    }
+    if (obj instanceof Error) {
+      return truncate(obj.message ? `${obj.name}: ${obj.message}` : obj.name);
+    }
+    const entries = Object.entries(obj).slice(0, 20);
+    const rendered = entries.map(([key, val]) => `${key}: ${safeStringify(val, depth + 1, seen)}`);
+    return truncate(`{${rendered.join(", ")}}`);
+  } catch {
+    return "[unserializable]";
+  } finally {
+    seen.delete(obj);
+  }
+}
+function truncate(text) {
+  return text.length > MAX_VALUE_CHARS ? `${text.slice(0, MAX_VALUE_CHARS)}\u2026` : text;
+}
+function isDomElementLike(obj) {
+  return typeof obj.tagName === "string";
+}
+function describeDomElementLike(el) {
+  const tag = el.tagName.toLowerCase();
+  const id = el.id ? `#${el.id}` : "";
+  const cls = typeof el.className === "string" && el.className ? `.${el.className.split(/\s+/).join(".")}` : "";
+  return `<${tag}${id}${cls}>`;
+}
+function buildParametersFromConsoleProps(consoleProps) {
+  let resolved = consoleProps;
+  if (typeof resolved === "function") {
+    try {
+      resolved = resolved();
+    } catch {
+      return [];
+    }
+  }
+  if (resolved === null || typeof resolved !== "object") {
+    return [];
+  }
+  const outer = resolved;
+  const nestedProps = outer.props;
+  const source = nestedProps !== null && typeof nestedProps === "object" && !Array.isArray(nestedProps) ? nestedProps : outer;
+  const parameters = [];
+  for (const [name, value] of Object.entries(source)) {
+    if (typeof value === "function") {
+      continue;
+    }
+    parameters.push({ name, value: safeStringify(value) });
+    if (parameters.length >= MAX_PARAMETERS_PER_STEP) {
+      break;
+    }
+  }
+  return parameters;
+}
+
+// src/browser/command-log-listener.ts
+var MAX_STEP_MESSAGE_CHARS = 200;
+function describeMessage(message) {
+  if (typeof message !== "string") {
+    return void 0;
+  }
+  const trimmed = message.trim();
+  if (trimmed.length === 0) {
+    return void 0;
+  }
+  return trimmed.length > MAX_STEP_MESSAGE_CHARS ? `${trimmed.slice(0, MAX_STEP_MESSAGE_CHARS)}\u2026` : trimmed;
+}
+function formatLogError(err) {
+  if (err === void 0 || err === null) {
+    return void 0;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  if (err instanceof Error) {
+    return err.stack ? `${err.message}
+${err.stack}` : err.message;
+  }
+  return err.stack ? `${err.message ?? ""}
+${err.stack}`.trim() : err.message;
+}
+function mapLogState(state) {
+  if (state === "failed") return "failed";
+  if (state === "passed") return "passed";
+  return "pending";
+}
+var CommandLogBuffer = class {
+  records = [];
+  indexById = /* @__PURE__ */ new Map();
+  lastParentIndex;
+  capWarned = false;
+  handleAdded(attrs, now = Date.now()) {
+    if (!attrs.name) {
+      return;
+    }
+    if (this.records.length >= MAX_STEPS_PER_TEST_ATTEMPT) {
+      if (!this.capWarned) {
+        this.capWarned = true;
+        logger.warn(
+          `reached the ${MAX_STEPS_PER_TEST_ATTEMPT}-step-per-test soft cap \u2014 further command-log entries for this test attempt will not be recorded.`
+        );
+      }
+      return;
+    }
+    const index = this.records.length;
+    const parentIndex = attrs.type === "child" ? this.lastParentIndex : void 0;
+    if (attrs.type === "parent") {
+      this.lastParentIndex = index;
+    }
+    const message = describeMessage(attrs.message);
+    const name = message ? `${attrs.name} ${message}` : attrs.name;
+    this.records.push({
+      name,
+      keyword: attrs.displayName && attrs.displayName !== attrs.name ? attrs.displayName : void 0,
+      status: mapLogState(attrs.state),
+      error: formatLogError(attrs.err),
+      parentIndex,
+      startedAt: now,
+      lastSeenAt: now,
+      consoleProps: attrs.consoleProps
+    });
+    if (attrs.id) {
+      this.indexById.set(attrs.id, index);
+    }
+  }
+  handleChanged(attrs, now = Date.now()) {
+    const index = attrs.id ? this.indexById.get(attrs.id) : void 0;
+    if (index === void 0) {
+      return;
+    }
+    const record = this.records[index];
+    if (!record) {
+      return;
+    }
+    record.lastSeenAt = now;
+    if (attrs.state !== void 0) {
+      record.status = mapLogState(attrs.state);
+    }
+    if (attrs.err !== void 0) {
+      record.error = formatLogError(attrs.err);
+    }
+    if (attrs.consoleProps !== void 0) {
+      record.consoleProps = attrs.consoleProps;
+    }
+  }
+  /** Returns this attempt's steps as wire-shaped `Step[]` (durations already
+   * converted to nanoseconds — unlike `Case`-level duration, which stays in
+   * milliseconds until `queue.ts`, `Step` has no separate internal/ms-shaped
+   * representation elsewhere in this codebase, so there's no benefit to
+   * threading one through here only to convert it later) and clears the
+   * buffer for the next attempt. */
+  drain() {
+    const steps = this.records.map((record) => {
+      const step = {
+        name: record.name,
+        status: record.status,
+        duration: msToNs(Math.max(0, record.lastSeenAt - record.startedAt))
+      };
+      if (record.keyword) step.keyword = record.keyword;
+      if (record.error) step.error = record.error;
+      if (record.location) step.location = record.location;
+      if (record.parentIndex !== void 0) step.parentIndex = record.parentIndex;
+      const parameters = buildParametersFromConsoleProps(record.consoleProps);
+      if (parameters.length > 0) step.parameters = parameters;
+      return step;
+    });
+    this.reset();
+    return steps;
+  }
+  /** Starts a fresh attempt: clears all recorded steps and nesting state.
+   * Steps from an abandoned (retried) attempt are discarded, never merged
+   * into the next attempt's buffer — see `mocha-listener.ts`, which calls
+   * this on every `runner.on('test', ...)` (fired once per attempt,
+   * including retries) so only the FINAL attempt's steps ever reach
+   * `drain()`. */
+  reset() {
+    this.records = [];
+    this.indexById.clear();
+    this.lastParentIndex = void 0;
+    this.capWarned = false;
+  }
+};
+function registerCommandLogListener(buffer) {
+  Cypress.on("log:added", (attributes) => {
+    buffer.handleAdded(attributes);
+  });
+  Cypress.on("log:changed", (attributes) => {
+    buffer.handleChanged(attributes);
+  });
+}
+
+// src/browser/case-builder.ts
+function combineSteps(autoSteps, manualSteps) {
+  const auto = autoSteps ?? [];
+  const manual = manualSteps ?? [];
+  if (auto.length === 0 && manual.length === 0) {
+    return void 0;
+  }
+  const offsetManual = manual.map((record) => {
+    const step = { name: record.name, status: record.status, duration: msToNs(record.durationMs ?? 0) };
+    if (record.error) step.error = record.error;
+    if (record.parentIndex !== void 0) step.parentIndex = record.parentIndex + auto.length;
+    if (record.parameters && record.parameters.length > 0) step.parameters = record.parameters;
+    return step;
+  });
+  return [...auto, ...offsetManual];
+}
+function collapseAttempts(attempts) {
+  if (attempts.length === 0) {
+    throw new Error("collapseAttempts: at least one attempt is required");
+  }
+  const final = attempts[attempts.length - 1];
+  const retryCount = attempts.length - 1;
+  const isFlaky = retryCount > 0 && final.status === "passed" && attempts.some((a) => a.status !== "passed");
+  const duration = attempts.reduce((sum, a) => sum + a.duration, 0);
+  return {
+    status: final.status,
+    duration,
+    retryCount,
+    isFlaky,
+    error: final.status === "passed" ? void 0 : final.error,
+    steps: combineSteps(final.steps, final.manualSteps),
+    labels: final.labels,
+    links: final.links,
+    tags: final.tags,
+    description: final.description,
+    priority: final.priority,
+    properties: final.properties,
+    attachments: final.attachments
+  };
+}
+
+// src/browser/queue.ts
+function flushCase(test, attempts) {
+  if (attempts.length === 0) {
+    return;
+  }
+  const collapsed = collapseAttempts(attempts);
+  const testCase = {
+    id: test.fullTitle(),
+    name: test.title,
+    className: test.parent?.fullTitle() || void 0,
+    status: collapsed.status,
+    duration: msToNs(collapsed.duration),
+    retryCount: collapsed.retryCount,
+    isFlaky: collapsed.isFlaky,
+    error: collapsed.error,
+    steps: collapsed.steps,
+    // qualflare.* author-facing metadata API calls (labels/links/tags/
+    // description/priority/properties from qualflare.label()/link()/tag()/
+    // description()/priority()/parameter(); attachments from
+    // qualflare.attachment()/attachmentFromFile() — the latter carry only
+    // a `path`, resolved into inline content Node-side by the existing
+    // screenshot-attachment pipeline, see tasks.ts/attachment-reader.ts)
+    // from the FINAL attempt only, same "abandoned attempts are discarded"
+    // rule as `steps`.
+    labels: collapsed.labels,
+    links: collapsed.links,
+    tags: collapsed.tags,
+    description: collapsed.description,
+    priority: collapsed.priority,
+    properties: collapsed.properties,
+    attachments: collapsed.attachments
+  };
+  cy.task(TASK_REPORT_CASE, testCase, { log: false });
+}
+
+// src/browser/test-metadata-buffer.ts
+var TestMetadataBuffer = class {
+  active = false;
+  labels = [];
+  links = [];
+  tags = [];
+  descriptionText;
+  priorityValue;
+  properties = {};
+  attachments = [];
+  manualSteps = [];
+  manualStepStack = [];
+  cappedWarnings = /* @__PURE__ */ new Set();
+  isActive() {
+    return this.active;
+  }
+  /** Starts a fresh attempt: clears all accumulated data and marks the
+   * buffer active. Called from `mocha-listener.ts`'s `runner.on('test', ...)`
+   * — fired once per attempt, including retries. */
+  reset() {
+    this.active = true;
+    this.labels = [];
+    this.links = [];
+    this.tags = [];
+    this.descriptionText = void 0;
+    this.priorityValue = void 0;
+    this.properties = {};
+    this.attachments = [];
+    this.manualSteps = [];
+    this.manualStepStack = [];
+    this.cappedWarnings.clear();
+  }
+  /** Ends the current attempt: returns everything accumulated (undefined for
+   * any field with nothing recorded, matching this codebase's
+   * omit-rather-than-empty-array convention elsewhere), marks the buffer
+   * inactive, and clears state. */
+  drain() {
+    const snapshot = {
+      labels: this.labels.length > 0 ? this.labels : void 0,
+      links: this.links.length > 0 ? this.links : void 0,
+      tags: this.tags.length > 0 ? this.tags : void 0,
+      description: this.descriptionText,
+      priority: this.priorityValue,
+      properties: Object.keys(this.properties).length > 0 ? this.properties : void 0,
+      attachments: this.attachments.length > 0 ? this.attachments : void 0,
+      manualSteps: this.manualSteps.length > 0 ? this.manualSteps : void 0
+    };
+    this.active = false;
+    this.labels = [];
+    this.links = [];
+    this.tags = [];
+    this.descriptionText = void 0;
+    this.priorityValue = void 0;
+    this.properties = {};
+    this.attachments = [];
+    this.manualSteps = [];
+    this.manualStepStack = [];
+    return snapshot;
+  }
+  warnInactive(fnName) {
+    logger.warn(
+      `qualflare.${fnName}() was called while no test is currently running (e.g. from a before/after hook, or at module-load time) \u2014 this call has no effect.`
+    );
+  }
+  /** Warns at most once per (buffer lifetime, cap-name) pair, so a loop that
+   * blows through a cap doesn't spam the log once per iteration. */
+  warnCappedOnce(capName, message) {
+    if (this.cappedWarnings.has(capName)) return;
+    this.cappedWarnings.add(capName);
+    logger.warn(message);
+  }
+  label(name, value) {
+    if (!this.active) return this.warnInactive("label");
+    if (this.labels.length >= MAX_LABELS_PER_CASE) {
+      return this.warnCappedOnce(
+        "labels",
+        `reached the ${MAX_LABELS_PER_CASE}-label-per-case cap \u2014 further qualflare.label() calls this test will be dropped.`
+      );
+    }
+    this.labels.push({ name, value });
+  }
+  link(url, opts) {
+    if (!this.active) return this.warnInactive("link");
+    if (this.links.length >= MAX_LINKS_PER_CASE) {
+      return this.warnCappedOnce(
+        "links",
+        `reached the ${MAX_LINKS_PER_CASE}-link-per-case cap \u2014 further qualflare.link() calls this test will be dropped.`
+      );
+    }
+    const link = { type: opts?.type ?? "custom", url };
+    if (opts?.name) link.name = opts.name;
+    this.links.push(link);
+  }
+  /** `Case.tags` is a REJECT-not-truncate field server-side (`max=64` items,
+   * `max=255` chars each) — unlike most other caps in this file, exceeding
+   * it 400s the whole launch, not just this one test's tags. Count is
+   * enforced the same warn-and-drop-excess way as `label()`/`link()`; an
+   * individual over-length tag is truncated (not dropped) instead, since a
+   * single long string is a shortenable formatting issue, not a structural
+   * one — matching how other length-only limits elsewhere in this codebase
+   * (e.g. `console-props.ts`'s `truncate()`) are handled. */
+  tag(...tags) {
+    if (!this.active) return this.warnInactive("tag");
+    for (const rawTag of tags) {
+      if (this.tags.length >= MAX_TAGS_PER_CASE) {
+        this.warnCappedOnce(
+          "tags",
+          `reached the ${MAX_TAGS_PER_CASE}-tag-per-case cap \u2014 further qualflare.tag() calls this test will be dropped.`
+        );
+        return;
+      }
+      let tag = rawTag;
+      if (tag.length > MAX_TAG_LENGTH) {
+        this.warnCappedOnce("tag-length", `a tag exceeded ${MAX_TAG_LENGTH} characters and was truncated.`);
+        tag = tag.slice(0, MAX_TAG_LENGTH);
+      }
+      this.tags.push(tag);
+    }
+  }
+  /** Last-write-wins if called more than once in one test — simpler than
+   * concatenation, and matches how most comparable metadata APIs (a single
+   * "set the description" call, not an accumulating log) behave. */
+  description(text) {
+    if (!this.active) return this.warnInactive("description");
+    this.descriptionText = text;
+  }
+  /** Last-write-wins if called more than once in one test, same as
+   * `description()`. Server-side, an unrecognized value is normalized/
+   * dropped rather than rejecting the request (`shared/types.ts`), so —
+   * like `link()`'s `type` option — this does no runtime validation of
+   * its own and simply takes the caller's word for it. */
+  priority(value) {
+    if (!this.active) return this.warnInactive("priority");
+    this.priorityValue = value;
+  }
+  /**
+   * Placement decision (the wire contract has no top-level `Parameter[]` on
+   * `Case` — only `Step.parameters` exists, see `shared/types.ts`): a call
+   * made while a `qualflare.step()` is currently open attaches to that
+   * step's `parameters[]` (capped at `MAX_PARAMETERS_PER_STEP`, shared with
+   * whatever `consoleProps`-derived parameters that step might separately
+   * accumulate — no, actually a manual step never has consoleProps, only
+   * auto-captured command-log steps do, so no sharing/collision is possible
+   * here). A call made OUTSIDE any step becomes a `Case.properties` entry
+   * instead, since that's the only test-level key/value bag the wire
+   * contract offers. `opts.masked` has no analog on `properties` (a plain
+   * `Record<string,string>`) and is silently ignored in that branch — real,
+   * documented limitation, not a bug: masking only has meaning for a
+   * step-level `Parameter`.
+   */
+  parameter(name, value, opts) {
+    if (!this.active) return this.warnInactive("parameter");
+    const openStepIndex = this.manualStepStack[this.manualStepStack.length - 1];
+    if (openStepIndex !== void 0) {
+      const step = this.manualSteps[openStepIndex];
+      if (!step) return;
+      step.parameters ??= [];
+      if (step.parameters.length >= MAX_PARAMETERS_PER_STEP) {
+        return this.warnCappedOnce(
+          "step-parameters",
+          `reached the ${MAX_PARAMETERS_PER_STEP}-parameter-per-step cap \u2014 further qualflare.parameter() calls within this step will be dropped.`
+        );
+      }
+      const parameter = { name };
+      if (value !== void 0) parameter.value = value;
+      if (opts?.masked) parameter.masked = true;
+      step.parameters.push(parameter);
+      return;
+    }
+    this.properties[name] = value ?? "";
+  }
+  /** `encoding` defaults to `'utf8'`: `content` is treated as plain text and
+   * base64-encoded before being placed into the wire format's
+   * always-base64 `Attachment.content` (see `shared/types.ts`). `'base64'`
+   * means the caller already has base64 text and it's passed through
+   * unencoded. Uses `TextEncoder`/`btoa` rather than Node's `Buffer` — this
+   * module runs in the browser (Cypress's actual browser context, not
+   * Node), where `Buffer` does not exist; both are standard Web APIs
+   * available in every browser Cypress supports. */
+  attachment(name, content, opts) {
+    if (!this.active) return this.warnInactive("attachment");
+    if (this.attachments.length >= MAX_ATTACHMENTS_PER_CASE) {
+      return this.warnCappedOnce(
+        "attachments",
+        `reached the ${MAX_ATTACHMENTS_PER_CASE}-attachment-per-case cap \u2014 further qualflare.attachment()/attachmentFromFile() calls this test will be dropped. Note this cap is enforced independently of any screenshots captured during the same test, which are merged in Node-side \u2014 the combined total is not currently capped.`
+      );
+    }
+    const base64 = opts?.encoding === "base64" ? content : utf8ToBase64(content);
+    const attachment = { name, content: base64 };
+    if (opts?.mimeType) attachment.mimeType = opts.mimeType;
+    this.attachments.push(attachment);
+  }
+  /** Mirrors the screenshot flow (`plugin/attachment-reader.ts`): the file's
+   * bytes are never read here (this runs browser-side, with no filesystem
+   * access) — a path-only `Attachment{name, path, mimeType}` is queued, and
+   * the EXISTING Node-side `resolveAttachments()` pipeline (already
+   * generic — it reads and size-guards any attachment that has a `path` but
+   * no `content`) resolves it once this test's `Case` reaches
+   * `TASK_REPORT_CASE`. No new Node-side code needed for this to work. */
+  attachmentFromFile(name, path, opts) {
+    if (!this.active) return this.warnInactive("attachmentFromFile");
+    if (this.attachments.length >= MAX_ATTACHMENTS_PER_CASE) {
+      return this.warnCappedOnce(
+        "attachments",
+        `reached the ${MAX_ATTACHMENTS_PER_CASE}-attachment-per-case cap \u2014 further qualflare.attachment()/attachmentFromFile() calls this test will be dropped.`
+      );
+    }
+    const attachment = { name, path };
+    if (opts?.mimeType) attachment.mimeType = opts.mimeType;
+    this.attachments.push(attachment);
+  }
+  /** Starts a manually-declared step, nested under whatever manual step (if
+   * any) is currently open — an independent nesting stack from
+   * `CommandLogBuffer`'s command-log-derived parent/child tracking (see this
+   * file's header comment for why the two aren't unified). Returns an index
+   * to pass back to `endStep()`. Soft-capped at `MAX_STEPS_PER_TEST_ATTEMPT`,
+   * same limit `CommandLogBuffer` uses (the two counts aren't combined
+   * against a single shared budget — a deliberate, documented simplification;
+   * either buffer alone can reach its own cap independently). Returns
+   * `undefined` if inactive or capped — `endStep(undefined, ...)` is a
+   * documented no-op, so callers don't need to branch on this themselves. */
+  beginStep(name, now = Date.now()) {
+    if (!this.active) {
+      this.warnInactive("step");
+      return void 0;
+    }
+    if (this.manualSteps.length >= MAX_STEPS_PER_TEST_ATTEMPT) {
+      this.warnCappedOnce(
+        "manual-steps",
+        `reached the ${MAX_STEPS_PER_TEST_ATTEMPT}-step-per-test soft cap \u2014 further qualflare.step() calls this test attempt will still run their wrapped commands, but will not be recorded as steps.`
+      );
+      return void 0;
+    }
+    const index = this.manualSteps.length;
+    const parentIndex = this.manualStepStack[this.manualStepStack.length - 1];
+    const record = { name, status: "pending", startedAt: now };
+    if (parentIndex !== void 0) record.parentIndex = parentIndex;
+    this.manualSteps.push(record);
+    this.manualStepStack.push(index);
+    return index;
+  }
+  /** Finalizes a step started by `beginStep()`, recording its real
+   * wall-clock duration. A no-op if `index` is `undefined` (the documented
+   * signal from `beginStep()` that nothing was actually recorded —
+   * inactive buffer or step-count cap reached). If a step's wrapped
+   * commands fail/throw, this never runs — see `metadata-api.ts`'s
+   * `step()` doc comment — so `durationMs` stays `undefined` and
+   * `combineSteps` (`case-builder.ts`) falls back to 0 for that step. */
+  endStep(index, status, error, now = Date.now()) {
+    if (index === void 0) return;
+    const record = this.manualSteps[index];
+    if (record) {
+      record.status = status;
+      if (error) record.error = error;
+      record.durationMs = Math.max(0, now - record.startedAt);
+    }
+    const stackPos = this.manualStepStack.lastIndexOf(index);
+    if (stackPos !== -1) {
+      this.manualStepStack.splice(stackPos, 1);
+    }
+  }
+};
+function utf8ToBase64(text) {
+  const bytes = new TextEncoder().encode(text);
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+var fallbackBuffer;
+function getDefaultMetadataBuffer() {
+  if (typeof Cypress === "undefined") {
+    fallbackBuffer ??= new TestMetadataBuffer();
+    return fallbackBuffer;
+  }
+  const target = Cypress;
+  target.__qualflareMetadataBuffer ??= new TestMetadataBuffer();
+  return target.__qualflareMetadataBuffer;
+}
+
+// src/browser/mocha-listener.ts
+function retryIndex(test) {
+  return test._currentRetry ?? 0;
+}
+function formatError(err) {
+  if (err === void 0 || err === null) {
+    return void 0;
+  }
+  if (err instanceof Error) {
+    return err.stack ? `${err.message}
+${err.stack}` : err.message;
+  }
+  return String(err);
+}
+var MochaAttemptTracker = class {
+  entries = /* @__PURE__ */ new Map();
+  entryFor(key, test) {
+    let entry = this.entries.get(key);
+    if (!entry) {
+      entry = { test, attempts: [], willRetry: false };
+      this.entries.set(key, entry);
+    }
+    return entry;
+  }
+  /** Records one attempt, deduped against only the immediately-preceding
+   * record for THIS test (never against any other test's history). More
+   * than one Mocha/Cypress event can legitimately fire for the same
+   * physical attempt (verified empirically: `runner.on('fail', ...)` AND
+   * `runner.on('retry', ...)` both fire for one failing-and-retried
+   * attempt) — a second call with the same `retryIndex` for the same key
+   * is a no-op rather than double-recording. */
+  record(key, retryIdx, test, snapshot) {
+    const entry = this.entryFor(key, test);
+    if (entry.lastRecordedRetryIndex === retryIdx) {
+      return;
+    }
+    entry.lastRecordedRetryIndex = retryIdx;
+    entry.attempts.push(snapshot);
+  }
+  /** Marks this test's most-recently-recorded attempt as non-final — more
+   * attempts are coming, so `takeIfFinal`/`drainOrphaned` must not flush
+   * yet. Only meaningful immediately after a `record()` call for the same
+   * attempt (Cypress's retry mechanism always records the failing attempt
+   * before emitting `'retry'`). A no-op if no entry exists yet for `key`. */
+  markWillRetry(key) {
+    const entry = this.entries.get(key);
+    if (entry) {
+      entry.willRetry = true;
+    }
+  }
+  /** The `afterEach`-driven path for the CURRENTLY-ending test: returns its
+   * attempts and forgets them — UNLESS `markWillRetry` was called for the
+   * attempt just recorded, in which case this consumes that flag and
+   * returns `undefined`, leaving the entry in place so the next attempt
+   * appends to the same array instead of starting fresh. Returns
+   * `undefined` (nothing to do) if no entry exists for `key` at all. */
+  takeIfFinal(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return void 0;
+    }
+    if (entry.willRetry) {
+      entry.willRetry = false;
+      return void 0;
+    }
+    this.entries.delete(key);
+    return entry.attempts;
+  }
+  /**
+   * Sweeps every OTHER finalized-but-never-collected entry (excluding
+   * `excludeKey`, the test this `afterEach` firing is already handling via
+   * `takeIfFinal`), skipping anything still mid-retry. This exists for
+   * exactly one real scenario: a statically-skipped test (`it.skip(...)` or
+   * an inherited `.skip`) fires `'pending'` and gets `record()`ed, but
+   * Mocha's skip path never runs `afterEach` for it at all — so nothing
+   * else will ever collect it.
+   *
+   * The obvious-looking alternative — flush a skipped test immediately,
+   * right in the `'pending'` handler — was tried and is UNSAFE: verified
+   * empirically (a real `cypress run` against a fixture spec containing
+   * `it.skip(...)`) that calling `cy.task()` synchronously from that
+   * handler doesn't just silently no-op, it HANGS the entire run
+   * indefinitely (Cypress's command-queue machinery for a test whose body
+   * never executes at all appears to never reach a state where a
+   * newly-enqueued command can be processed). `drainOrphaned` instead waits
+   * until the NEXT real `afterEach` fires (a call site independently
+   * proven safe for `cy.task()`, both here and by every other flush in this
+   * file) and sweeps anything left over at that point.
+   *
+   * Residual, honestly-documented limitation: if EVERY test in a spec file
+   * is statically skipped, no real `afterEach` ever fires at all in that
+   * spec, so a lingering skip entry is never swept — the same outcome as
+   * before this fix, for that one narrower sub-case. The common case (at
+   * least one non-skipped test in the spec) is fully fixed.
+   */
+  drainOrphaned(excludeKey) {
+    const drained = [];
+    for (const [key, entry] of this.entries) {
+      if (key === excludeKey || entry.willRetry) {
+        continue;
+      }
+      drained.push({ test: entry.test, attempts: entry.attempts });
+      this.entries.delete(key);
+    }
+    return drained;
+  }
+};
+function registerMochaListener() {
+  const runner = Cypress.mocha.getRunner();
+  const tracker = new MochaAttemptTracker();
+  const stepBuffer = new CommandLogBuffer();
+  registerCommandLogListener(stepBuffer);
+  function buildSnapshot(test, status, err) {
+    const steps = stepBuffer.drain();
+    const metadata = getDefaultMetadataBuffer().drain();
+    return {
+      status,
+      duration: test.duration ?? 0,
+      error: formatError(err),
+      steps: steps.length > 0 ? steps : void 0,
+      ...metadata
+    };
+  }
+  runner.on("test", () => {
+    stepBuffer.reset();
+    getDefaultMetadataBuffer().reset();
+  });
+  runner.on("pass", (test) => {
+    tracker.record(test.fullTitle(), retryIndex(test), test, buildSnapshot(test, "passed"));
+  });
+  runner.on("fail", (test, err) => {
+    const runnable = test;
+    if (runnable.type === "test") {
+      tracker.record(test.fullTitle(), retryIndex(test), test, buildSnapshot(test, "failed", err));
+      return;
+    }
+    const guardedTest = runnable.ctx?.currentTest;
+    const isBeforeEachHook = (runnable.originalTitle ?? runnable.title ?? "").startsWith('"before each" hook');
+    if (guardedTest && isBeforeEachHook) {
+      tracker.record(guardedTest.fullTitle(), retryIndex(guardedTest), guardedTest, buildSnapshot(guardedTest, "failed", err));
+    }
+  });
+  runner.on("retry", (test, err) => {
+    const status = err ? "failed" : "passed";
+    tracker.record(test.fullTitle(), retryIndex(test), test, buildSnapshot(test, status, err));
+    tracker.markWillRetry(test.fullTitle());
+  });
+  runner.on("pending", (test) => {
+    tracker.record(test.fullTitle(), retryIndex(test), test, buildSnapshot(test, "skipped"));
+  });
+  Cypress.on("fail", (err, runnable) => {
+    if (runnable.type !== "test") {
+      throw err;
+    }
+    const test = runnable;
+    tracker.record(test.fullTitle(), retryIndex(test), test, buildSnapshot(test, "failed", err));
+    throw err;
+  });
+  afterEach(function flushCurrentTest() {
+    const test = this.currentTest;
+    if (!test) {
+      return;
+    }
+    const key = test.fullTitle();
+    const attempts = tracker.takeIfFinal(key);
+    if (attempts) {
+      flushCase(test, attempts);
+    }
+    for (const orphan of tracker.drainOrphaned(key)) {
+      flushCase(orphan.test, orphan.attempts);
+    }
+  });
+}
+
+// src/browser/test-phase-signal.ts
+function registerTestPhaseSignal() {
+  let signaled = false;
+  beforeEach(function qualflareMarkTestPhaseStarted() {
+    if (signaled) {
+      return;
+    }
+    signaled = true;
+    cy.task(TASK_MARK_TEST_PHASE_STARTED, null, { log: false });
+  });
+}
+
+// src/browser/index.ts
+initializeBrowserIntegration(() => {
+  registerMochaListener();
+  registerTestPhaseSignal();
+});
+
+// src/browser/metadata-api.ts
+var qualflare = {
+  label(name, value) {
+    getDefaultMetadataBuffer().label(name, value);
+  },
+  link(url, opts) {
+    getDefaultMetadataBuffer().link(url, opts);
+  },
+  tag(...tags) {
+    getDefaultMetadataBuffer().tag(...tags);
+  },
+  description(text) {
+    getDefaultMetadataBuffer().description(text);
+  },
+  priority(value) {
+    getDefaultMetadataBuffer().priority(value);
+  },
+  parameter(name, value, opts) {
+    getDefaultMetadataBuffer().parameter(name, value, opts);
+  },
+  attachment(name, content, opts) {
+    getDefaultMetadataBuffer().attachment(name, content, opts);
+  },
+  attachmentFromFile(name, path, opts) {
+    getDefaultMetadataBuffer().attachmentFromFile(name, path, opts);
+  },
+  /**
+   * Wraps `fn` as a named, reportable step. Unlike every other function on
+   * this object, a step's start/end only has meaning relative to when its
+   * wrapped `cy.*()` commands actually EXECUTE — not when `step()` is
+   * textually called, which happens synchronously, before any queued
+   * command has run. So this interleaves `beginStep`/`endStep` INTO the
+   * command queue itself via `cy.then()`, at the exact point the wrapped
+   * commands run, rather than calling them eagerly.
+   *
+   * Verified directly against `node_modules/cypress/types/cypress.d.ts`
+   * (Cypress 14.5.4) before relying on any of this, rather than assumed:
+   *  - `Cypress.isCy(obj: any): obj is Chainable` exists exactly as the
+   *    plan's sketch expected.
+   *  - `cy.wrap<S>(object: S, options?: Partial<Loggable & Timeoutable>)`
+   *    accepts `{ log: false }` — this is properly typed.
+   *  - `cy.then<S>(options: Partial<Timeoutable>, fn): ...` does NOT accept
+   *    `Loggable` in its options type (only `wrap()` does) — passing
+   *    `{ log: false }` to `.then()` is a genuine type error under this
+   *    version's declarations. Cypress's own runtime DOES honor `log: false`
+   *    on `.then()` in practice (a long-documented, widely-relied-upon
+   *    behavior across the Cypress plugin ecosystem — every reporter that
+   *    injects bookkeeping commands into the queue uses this), so `.then()`
+   *    calls below pass it via a narrow, explicitly-commented type
+   *    assertion rather than omitting it and cluttering every test's
+   *    Command Log with reporter-internal entries.
+   */
+  step(name, fn) {
+    const stepIndex = getDefaultMetadataBuffer().beginStep(name);
+    let result;
+    try {
+      result = fn();
+    } catch (err) {
+      getDefaultMetadataBuffer().endStep(stepIndex, "failed", formatSyncStepError(err));
+      throw err;
+    }
+    const chained = Cypress.isCy(result) ? result : cy.wrap(result, { log: false });
+    return chained.then(withoutLog(), (value) => {
+      getDefaultMetadataBuffer().endStep(stepIndex, "passed");
+      return value;
+    });
+  }
+};
+function formatSyncStepError(err) {
+  if (err instanceof Error) {
+    return err.stack ? `${err.message}
+${err.stack}` : err.message;
+  }
+  return String(err);
+}
+function withoutLog() {
+  return { log: false };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  qualflare
+});
+//# sourceMappingURL=index.cjs.map