@kaizenreport/kensho-cypress 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Ordoñez
+
+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

@@ -0,0 +1,52 @@
+# @kaizenreport/kensho-cypress
+
+A Cypress reporter that emits the canonical [Kensho v1](../schema) JSON format. Cypress uses Mocha under the hood, so this reporter plugs in via the standard Mocha reporter API.
+
+## Install
+
+```bash
+pnpm add -D @kaizenreport/kensho-cypress
+# or
+npm i -D @kaizenreport/kensho-cypress
+```
+
+## Configure
+
+```js
+// cypress.config.js
+const { defineConfig } = require('cypress');
+
+module.exports = defineConfig({
+  reporter: '@kaizenreport/kensho-cypress',
+  reporterOptions: {
+    output: 'kensho-results',
+    project: { name: 'Acme Web', slug: 'acme-web' },
+    severityFromTag: true,
+  },
+});
+```
+
+## Run
+
+```bash
+npx cypress run
+# => kensho-results/ populated with cases/*.json and run.json
+
+npx kensho generate   # → kensho-report/
+npx kensho open
+```
+
+## What it produces
+
+- `kensho-results/run.json` — run manifest (project, env, totals, timing)
+- `kensho-results/cases/<stableId>.json` — one per test case
+- `kensho-results/attachments/` — empty by default (Cypress screenshots/videos
+  are handled per-spec; wire a `cy.task()` hook if you want to copy them in).
+
+Each test gets a **stable id** hashed from its fullName + file path, so the
+same test correlates across runs for history and flakiness tracking.
+
+## Environment auto-detected
+
+GitHub Actions, CircleCI, GitLab CI, Jenkins, Buildkite — CI provider, branch,
+commit, run URL, OS, architecture, Node version.

package/index.js

@@ -0,0 +1,152 @@
+// @kaizenreport/kensho-cypress — Cypress reporter (built on Mocha's reporter API).
+// Collects pass/fail/pending events from the Mocha runner, then writes
+// kensho-results/run.json + cases/<id>.json on the runner 'end' event.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { emptyRun, computeTotals, stableCaseId, validateRun, envInfo } from '@kaizenreport/kensho-schema';
+
+// envInfo() is imported from @kaizenreport/kensho-schema below.
+
+function suiteChainOf(test) {
+  const chain = [];
+  for (let s = test.parent; s; s = s.parent) {
+    if (s.title) chain.unshift(s.title);
+  }
+  return chain;
+}
+
+function mapMochaStatus(state) {
+  if (state === 'passed') return 'pass';
+  if (state === 'failed') return 'fail';
+  if (state === 'pending') return 'skip';
+  return 'broken';
+}
+
+function extractInlineTags(title) {
+  const tags = [];
+  const re = /@([\w-]+)/g;
+  let m;
+  while ((m = re.exec(title || ''))) tags.push(m[1]);
+  return tags;
+}
+
+function severityFromTags(tags) {
+  for (const t of tags || []) {
+    const m = /^@?(blocker|critical|normal|minor|trivial)$/i.exec(t);
+    if (m) return m[1].toLowerCase();
+  }
+  return undefined;
+}
+
+export default class KenshoCypressReporter {
+  /**
+   * Mocha-style reporter constructor.
+   * @param {*} runner - Mocha Runner
+   * @param {{ reporterOptions?: any }} opts
+   */
+  constructor(runner, opts = {}) {
+    const options = (opts && opts.reporterOptions) || {};
+    this.outputDir = resolve(process.cwd(), options.output || 'kensho-results');
+    this.casesDir = resolve(this.outputDir, 'cases');
+    this.attachmentsDir = resolve(this.outputDir, 'attachments');
+    this.project = options.project || {};
+    this.severityFromTag = options.severityFromTag !== false;
+    this.runId = options.runId || ('run_' + new Date().toISOString().replace(/[^0-9]/g, '').slice(0, 14));
+    this.startedAt = new Date().toISOString();
+    this.casesById = new Map();
+
+    mkdirSync(this.outputDir, { recursive: true });
+    mkdirSync(this.casesDir, { recursive: true });
+    mkdirSync(this.attachmentsDir, { recursive: true });
+
+    if (!runner) return; // allow instantiation for tests without a runner
+
+    runner.on('pass', (test) => this._record(test, 'pass'));
+    runner.on('fail', (test, err) => this._record(test, 'fail', err));
+    runner.on('pending', (test) => this._record(test, 'skip'));
+    runner.on('end', () => this._finalize(runner));
+  }
+
+  _record(test, statusLabel, err) {
+    try {
+      const caseObj = this._toKenshoCase(test, statusLabel, err);
+      writeFileSync(
+        resolve(this.casesDir, caseObj.id + '.json'),
+        JSON.stringify(caseObj, null, 2),
+      );
+      this.casesById.set(caseObj.id, caseObj);
+    } catch (e) {
+      console.error('[kensho] failed to write case:', e && e.message);
+    }
+  }
+
+  _toKenshoCase(test, statusLabel, err) {
+    const suite = suiteChainOf(test);
+    const fullName = suite.concat(test.title || '').join(' › ');
+    const filePath = test.file ? relative(process.cwd(), test.file) : undefined;
+    let id = stableCaseId(fullName, filePath);
+    if (this.casesById.has(id)) {
+      let i = 2;
+      while (this.casesById.has(id + '_' + i)) i++;
+      id = id + '_' + i;
+    }
+    const tags = extractInlineTags(test.title);
+    const duration = Math.max(0, Math.round(test.duration || 0));
+    const startedAt = new Date().toISOString();
+
+    const errors = err ? [{
+      message: String(err.message || err),
+      stack: err.stack,
+      type: err.name,
+    }] : undefined;
+
+    return {
+      id,
+      name: test.title || 'unnamed',
+      fullName,
+      filePath,
+      suite,
+      tags,
+      severity: this.severityFromTag ? severityFromTags(tags) : undefined,
+      status: mapMochaStatus(statusLabel === 'pass' ? 'passed' : statusLabel === 'fail' ? 'failed' : 'pending'),
+      startedAt,
+      finishedAt: new Date(Date.parse(startedAt) + duration).toISOString(),
+      duration,
+      retries: (test.currentRetry && test.currentRetry()) || 0,
+      platform: process.platform,
+      steps: [],
+      errors,
+      attachments: [],
+      logs: [],
+    };
+  }
+
+  _finalize() {
+    const cases = [...this.casesById.values()];
+    const finishedAt = new Date().toISOString();
+    const run = emptyRun({
+      id: this.runId,
+      project: {
+        name: this.project.name || 'Unknown project',
+        slug: this.project.slug || 'unknown',
+        url: this.project.url,
+      },
+      framework: { name: 'cypress', version: process.env.CYPRESS_VERSION || 'unknown' },
+      env: envInfo(),
+      startedAt: this.startedAt,
+    });
+    run.finishedAt = finishedAt;
+    run.durationMs = Math.max(0, Date.parse(finishedAt) - Date.parse(this.startedAt));
+    run.testCases = cases;
+    run.totals = computeTotals(cases);
+
+    writeFileSync(resolve(this.outputDir, 'run.json'), JSON.stringify(run, null, 2));
+    const { ok, errors } = validateRun(run);
+    if (!ok) {
+      console.warn('[kensho] run.json failed validation:');
+      for (const e of errors.slice(0, 8)) console.warn('  -', e);
+    }
+    console.log(`[kensho] wrote ${cases.length} cases + run.json to ${this.outputDir}`);
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kaizenreport/kensho-cypress",
+  "version": "0.1.0",
+  "description": "Kensho reporter for Cypress (Mocha runner) — writes kensho-results/ so the Kensho CLI can generate a rich HTML report.",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "cypress": ">=12.0.0",
+    "mocha": ">=10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "cypress": {
+      "optional": true
+    },
+    "mocha": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@kaizenreport/kensho-schema": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brandon1794/kensho.git",
+    "directory": "packages/cypress"
+  },
+  "homepage": "https://github.com/brandon1794/kensho/tree/main/packages/cypress#readme",
+  "bugs": {
+    "url": "https://github.com/brandon1794/kensho/issues"
+  }
+}