@fixsense/cypress-plugin 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CopilotMe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @fixsense/cypress-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Cypress plugin that records what each test did, run after run.
+
+Cypress knows a test was retried inside the run it is executing and forgets it
+on exit. This plugin keeps that history, which is what makes a flaky test
+identifiable as flaky rather than as bad luck.
+
+Free and MIT licensed. It works on its own; FixSense's paid analysis and
+auto-fix build on the same data.
+
+## Install
+
+```bash
+npm install -D @fixsense/cypress-plugin
+```
+
+```ts
+// cypress.config.ts
+import { defineConfig } from 'cypress';
+import { registerFixSense } from '@fixsense/cypress-plugin';
+
+export default defineConfig({
+  // Retries are what let Cypress distinguish a flaky test from a failing one.
+  retries: { runMode: 2, openMode: 0 },
+  e2e: {
+    setupNodeEvents(on, config) {
+      registerFixSense(on);
+      return config;
+    },
+  },
+});
+```
+
+Set `FIXSENSE_API_KEY` in CI. Without it the plugin does nothing, so local
+runs are unaffected.
+
+## Options
+
+```ts
+registerFixSense(on, {
+  apiKey: process.env.FIXSENSE_API_KEY, // default: FIXSENSE_API_KEY
+  apiUrl: 'https://fix-sense.com',      // self-hosted installations
+  enabled: true,
+  timeoutMs: 10000,
+  repoFullName: 'acme/web',             // when CI variables are absent
+});
+```
+
+GitHub Actions, GitLab CI, Bitbucket Pipelines and Azure Pipelines are
+detected automatically.
+
+## What it sends
+
+Per test: the describe/it title chain, the spec file, the outcome, the retry
+count, the duration, and the error message truncated to 2000 characters.
+
+It does not send source code, screenshots, videos or environment variables.
+
+## What it will not do
+
+It will never fail your run. If the upload fails for any reason, it prints one
+line to stderr and the run's own exit code is untouched.

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fixsense/cypress-plugin
+ *
+ * Records what each Cypress test did, run after run, so a flaky test can be
+ * recognised as flaky rather than as bad luck.
+ *
+ * Same two rules as the Playwright reporter, for the same reasons: it never
+ * fails a run, and it sends outcomes rather than content.
+ */
+import { type TestRecord } from "./payload";
+export interface FixSenseCypressOptions {
+    /** Defaults to the FIXSENSE_API_KEY environment variable. */
+    apiKey?: string;
+    /** Override for self-hosted installations. */
+    apiUrl?: string;
+    /** Set false to turn the plugin off without editing the config. */
+    enabled?: boolean;
+    timeoutMs?: number;
+    /** Override repo detection when CI variables are absent or wrong. */
+    repoFullName?: string;
+}
+/** The subset of Cypress's plugin event registrar we use. */
+type On = (event: string, handler: (...args: never[]) => void | Promise<void>) => void;
+/**
+ * Register the plugin from `setupNodeEvents`.
+ *
+ * Results are collected per spec and sent once at the end of the run, so one
+ * request covers the whole suite rather than one per spec file.
+ */
+export declare function registerFixSense(on: On, options?: FixSenseCypressOptions): void;
+export declare function sendRun(tests: TestRecord[], startedAt: Date, options: FixSenseCypressOptions): Promise<void>;
+export default registerFixSense;
+export * from "./payload";

package/dist/index.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * @fixsense/cypress-plugin
+ *
+ * Records what each Cypress test did, run after run, so a flaky test can be
+ * recognised as flaky rather than as bad luck.
+ *
+ * Same two rules as the Playwright reporter, for the same reasons: it never
+ * fails a run, and it sends outcomes rather than content.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFixSense = registerFixSense;
+exports.sendRun = sendRun;
+const payload_1 = require("./payload");
+const DEFAULT_API_URL = "https://fix-sense.com";
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * Register the plugin from `setupNodeEvents`.
+ *
+ * Results are collected per spec and sent once at the end of the run, so one
+ * request covers the whole suite rather than one per spec file.
+ */
+function registerFixSense(on, options = {}) {
+    const tests = [];
+    const startedAt = new Date();
+    on("after:spec", ((spec, results) => {
+        try {
+            for (const test of results?.tests ?? []) {
+                tests.push((0, payload_1.toTestRecord)(test, spec));
+            }
+        }
+        catch {
+            // One unreadable spec is not a reason to lose the rest of the run.
+        }
+    }));
+    on("after:run", (async () => {
+        await sendRun(tests, startedAt, options);
+    }));
+}
+async function sendRun(tests, startedAt, options) {
+    if (options.enabled === false)
+        return;
+    const apiKey = options.apiKey ?? process.env.FIXSENSE_API_KEY;
+    // Silent without a key: a developer running Cypress locally has none and
+    // does not need telling on every run.
+    if (!apiKey)
+        return;
+    if (tests.length === 0)
+        return;
+    const context = (0, payload_1.detectContext)(process.env);
+    const payload = {
+        schemaVersion: 1,
+        ...context,
+        repoFullName: options.repoFullName ?? context.repoFullName,
+        startedAt: startedAt.toISOString(),
+        durationMs: Date.now() - startedAt.getTime(),
+        totals: (0, payload_1.summarise)(tests),
+        tests,
+    };
+    const base = options.apiUrl ?? process.env.FIXSENSE_API_URL ?? DEFAULT_API_URL;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const res = await fetch(`${base.replace(/\/$/, "")}/api/v1/runs`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            console.error(`[fixsense] Run not recorded: ${res.status} ${res.statusText}`);
+        }
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        console.error(`[fixsense] Run not recorded: ${reason}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+exports.default = registerFixSense;
+__exportStar(require("./payload"), exports);

package/dist/payload.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Building the run payload from Cypress results.
+ *
+ * The CI detection and truncation below are deliberately a copy of what
+ * @fixsense/playwright-reporter does, not a shared dependency. Each package
+ * installs on its own with no FixSense runtime dependency, which is the whole
+ * reason a team will add it. `tests/unit/reporter-parity.test.ts` asserts both
+ * copies answer identically for the same environment, so the duplication
+ * cannot drift silently.
+ */
+/** Cypress calls a test's state one of these. */
+export type CypressState = "passed" | "failed" | "pending" | "skipped";
+/** The parts of a Cypress `after:spec` result we read. Structural on purpose. */
+export interface CypressTestLike {
+    title: string[];
+    state: CypressState;
+    duration?: number;
+    attempts?: Array<{
+        state?: string;
+    }>;
+    displayError?: string | null;
+}
+export interface CypressSpecLike {
+    relative?: string;
+    absolute?: string;
+}
+/** The same four words the Playwright reporter sends. */
+export type Outcome = "expected" | "unexpected" | "flaky" | "skipped";
+export interface TestRecord {
+    title: string;
+    file: string | null;
+    outcome: Outcome;
+    status: string;
+    retries: number;
+    durationMs: number;
+    errorMessage: string | null;
+}
+export declare const MAX_ERROR_CHARS = 2000;
+export declare function truncateError(message: string | undefined | null): string | null;
+/**
+ * Cypress has no "flaky" state, so it has to be derived.
+ *
+ * With `retries` configured, a test that failed an attempt and passed a later
+ * one is exactly what Playwright calls flaky. Without retries configured
+ * Cypress cannot produce the signal at all, and such a run contributes only
+ * pass/fail — which the cross-run history still scores, just more slowly.
+ */
+export declare function deriveOutcome(test: CypressTestLike): Outcome;
+export declare function toTestRecord(test: CypressTestLike, spec: CypressSpecLike): TestRecord;
+export declare function summarise(tests: TestRecord[]): {
+    total: number;
+    passed: number;
+    failed: number;
+    flaky: number;
+    skipped: number;
+};
+export declare function detectContext(env: Record<string, string | undefined>): {
+    provider: string;
+    repoFullName: string | null;
+    commitSha: string | null;
+    branch: string | null;
+    ciRunId: string | null;
+    ciRunUrl: string | null;
+} | {
+    provider: null;
+    repoFullName: null;
+    commitSha: null;
+    branch: null;
+    ciRunId: null;
+    ciRunUrl: null;
+};

package/dist/payload.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Building the run payload from Cypress results.
+ *
+ * The CI detection and truncation below are deliberately a copy of what
+ * @fixsense/playwright-reporter does, not a shared dependency. Each package
+ * installs on its own with no FixSense runtime dependency, which is the whole
+ * reason a team will add it. `tests/unit/reporter-parity.test.ts` asserts both
+ * copies answer identically for the same environment, so the duplication
+ * cannot drift silently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ERROR_CHARS = void 0;
+exports.truncateError = truncateError;
+exports.deriveOutcome = deriveOutcome;
+exports.toTestRecord = toTestRecord;
+exports.summarise = summarise;
+exports.detectContext = detectContext;
+exports.MAX_ERROR_CHARS = 2000;
+function truncateError(message) {
+    if (!message)
+        return null;
+    const clean = message.replace(/\u001b\[[0-9;]*m/g, "").trim();
+    if (!clean)
+        return null;
+    return clean.length > exports.MAX_ERROR_CHARS
+        ? `${clean.slice(0, exports.MAX_ERROR_CHARS)}… [truncated]`
+        : clean;
+}
+/**
+ * Cypress has no "flaky" state, so it has to be derived.
+ *
+ * With `retries` configured, a test that failed an attempt and passed a later
+ * one is exactly what Playwright calls flaky. Without retries configured
+ * Cypress cannot produce the signal at all, and such a run contributes only
+ * pass/fail — which the cross-run history still scores, just more slowly.
+ */
+function deriveOutcome(test) {
+    if (test.state === "pending" || test.state === "skipped")
+        return "skipped";
+    if (test.state === "failed")
+        return "unexpected";
+    const attempts = test.attempts ?? [];
+    const failedEarlier = attempts
+        .slice(0, -1)
+        .some((attempt) => attempt.state === "failed");
+    return failedEarlier ? "flaky" : "expected";
+}
+function toTestRecord(test, spec) {
+    return {
+        // Cypress gives the describe/it chain as an array; the separator matches
+        // the Playwright reporter so one history reads the same from both.
+        title: test.title.filter(Boolean).join(" › "),
+        file: spec.relative ?? spec.absolute ?? null,
+        outcome: deriveOutcome(test),
+        status: test.state,
+        retries: Math.max(0, (test.attempts?.length ?? 1) - 1),
+        durationMs: test.duration ?? 0,
+        errorMessage: truncateError(test.displayError),
+    };
+}
+function summarise(tests) {
+    return {
+        total: tests.length,
+        passed: tests.filter((t) => t.outcome === "expected").length,
+        failed: tests.filter((t) => t.outcome === "unexpected").length,
+        flaky: tests.filter((t) => t.outcome === "flaky").length,
+        skipped: tests.filter((t) => t.outcome === "skipped").length,
+    };
+}
+function detectContext(env) {
+    if (env.GITHUB_ACTIONS === "true" || env.GITHUB_REPOSITORY) {
+        const repo = env.GITHUB_REPOSITORY ?? null;
+        return {
+            provider: "github",
+            repoFullName: repo,
+            commitSha: env.GITHUB_SHA ?? null,
+            branch: env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME || null,
+            ciRunId: env.GITHUB_RUN_ID ?? null,
+            ciRunUrl: repo && env.GITHUB_RUN_ID
+                ? `${env.GITHUB_SERVER_URL ?? "https://github.com"}/${repo}/actions/runs/${env.GITHUB_RUN_ID}`
+                : null,
+        };
+    }
+    if (env.GITLAB_CI === "true" || env.CI_PROJECT_PATH) {
+        return {
+            provider: "gitlab",
+            repoFullName: env.CI_PROJECT_PATH ?? null,
+            commitSha: env.CI_COMMIT_SHA ?? null,
+            branch: env.CI_COMMIT_REF_NAME ?? null,
+            ciRunId: env.CI_PIPELINE_ID ?? null,
+            ciRunUrl: env.CI_PIPELINE_URL ?? null,
+        };
+    }
+    if (env.BITBUCKET_REPO_FULL_NAME) {
+        return {
+            provider: "bitbucket",
+            repoFullName: env.BITBUCKET_REPO_FULL_NAME,
+            commitSha: env.BITBUCKET_COMMIT ?? null,
+            branch: env.BITBUCKET_BRANCH ?? null,
+            ciRunId: env.BITBUCKET_BUILD_NUMBER ?? null,
+            ciRunUrl: null,
+        };
+    }
+    if (env.BUILD_REPOSITORY_NAME || env.TF_BUILD === "True") {
+        return {
+            provider: "azure",
+            repoFullName: env.BUILD_REPOSITORY_NAME ?? null,
+            commitSha: env.BUILD_SOURCEVERSION ?? null,
+            branch: (env.BUILD_SOURCEBRANCHNAME || env.BUILD_SOURCEBRANCH) ?? null,
+            ciRunId: env.BUILD_BUILDID ?? null,
+            ciRunUrl: null,
+        };
+    }
+    return {
+        provider: null,
+        repoFullName: null,
+        commitSha: null,
+        branch: null,
+        ciRunId: null,
+        ciRunUrl: null,
+    };
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@fixsense/cypress-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cypress plugin that records test outcomes across runs so flaky tests can be identified over time.",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cypress",
+    "cypress-plugin",
+    "flaky-tests",
+    "ci",
+    "test-reporting"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CopilotMe/fix-sense.git",
+    "directory": "packages/cypress-plugin"
+  },
+  "homepage": "https://fix-sense.com",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "cypress": ">=12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}