mocha-multiple-sessions-detailed-runner/readme.md

High-level API for multi-session Mocha tests with detailed reporting

# 📦 MultiSessionDetailedRunner – High-Level API for Multi-Session Mocha Tests

`MultiSessionDetailedRunner` is a minimal, opinionated abstraction on top of `mocha-multiple-sessions-ts` and `mocha-detailed-json-reporter`, designed to make **multi-session test management and reporting painless** in the browser.

---


## ✅ Features

* ⚙️ Automatically sets up `testSessionSetup()` for JSON reporting
* 🔖 Define multiple labeled test sessions
* ▶️ Run sessions individually or all together
* 📊 Get session-specific or combined test reports
* 🧼 No more `windowVariableName` boilerplate

---


## 🚀 Getting Started

### 1. Load dependencies in browser (via CDN)

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/mocha/10.2.0/mocha.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/chai/4.3.10/chai.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/mocha-detailed-json-reporter@1.0.0/build/iife/mocha-detailed-json-reporter.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/mocha-multiple-sessions-ts@1.0.0/build/iife/mocha-multiple-sessions.min.js"></script>
```

### 2. Create the runner

```ts
const runner = createMultiSessionDetailedRunner();
runner.init();
```

### 3. Define sessions

```ts
runner.define('unit-tests', () => {
  describe('Unit Math', () => {
    it('adds correctly', () => {
      expect(2 + 2).to.equal(4);
    });
  });
});
```

### 4. Run sessions

```ts
await runner.run('unit-tests');
// or
await runner.runAll();
```

### 5. Get reports

```ts
const unitReport = runner.getReport('unit-tests');
const combined = runner.getCombinedReport();

console.log(combined.sessions['unit-tests'].stats);
```

---


## 📚 API Reference

### `init(): void`

Sets up `testSessionSetup()` using a default `createMochaInstance()` function.
This ensures standardized reporter integration with window-based keys like `mochaSession__unit_tests`.

---


### `define(label: string, setupFn: () => void): void`

Registers a new test session. The label is automatically converted into a window-safe variable name.

---


### `run(label: string): Promise<SessionResult>`

Runs one session and tracks status, timing, and stats. Automatically extracts the report JSON from the window object.

---


### `runAll(): Promise<Record<string, SessionResult>>`

Runs all registered sessions in order and returns their individual results.

---


### `getReport(label: string): DetailedReport | null`

Returns the parsed JSON report for a given session label from the associated window variable.

---


### `getSessionStates(): Record<string, SessionState>`

Returns internal status for all defined sessions.

---


### `getCombinedReport(): CombinedReport`

Returns a complete merged report across all sessions.
Automatically:

* Retrieves all reports from their corresponding window variables
* Aggregates test counts
* Stores all raw reports under `sessions[label]`

---


## 🧠 Internal Mechanics

* Result keys are standardized as:

  ```ts
  const resultKey = `mochaSession__${label.replace(/\s+/g, '_')}`;
  ```
* The `init()` call internally invokes:

  ```ts
  testSessionSetup({
    createMochaInstance(label) => new Mocha({...}),
    injectGlobals(mocha) => mocha.suite.emit(...)
  });
  ```
* All session metadata and status are tracked internally in `Map<string, SessionMeta>`.

---


## 📦 Type Summary

```ts
interface SessionState {
  label: string;
  status: 'ready' | 'running' | 'passed' | 'failed';
  stats?: { tests: number; passes: number; failures: number; pending: number };
  timestamp?: Date;
}

interface SessionResult extends SessionState {
  success: boolean;
}

interface DetailedReport {
  data: any; // Full raw detailed report from mocha-detailed-json-reporter
  stats: {
    tests: number;
    passes: number;
    failures: number;
    pending: number;
  };
  timestamp: Date;
}

interface CombinedReport {
  generatedAt: string;
  summary: {
    totalTests: number;
    totalPasses: number;
    totalFailures: number;
    totalPending: number;
  };
  sessions: Record<string, DetailedReport>; // Each session is a full detailed report
}
```

---


## 🧩 Example: getCombinedReport()

```ts
function getCombinedReport(): CombinedReport {
  const combined: CombinedReport = {
    generatedAt: new Date().toISOString(),
    summary: {
      totalTests: 0,
      totalPasses: 0,
      totalFailures: 0,
      totalPending: 0,
    },
    sessions: {},
  };

  for (const label of Object.keys(sessionMeta)) {
    const resultKey = sessionMeta[label].resultKey;
    const report = (window as any)[resultKey];
    if (!report) continue;

    const stats = report.stats || { tests: 0, passes: 0, failures: 0, pending: 0 };
    combined.sessions[label] = {
      data: report,
      stats,
      timestamp: new Date(), // Or use report.timestamp if available
    };

    combined.summary.totalTests += stats.tests;
    combined.summary.totalPasses += stats.passes;
    combined.summary.totalFailures += stats.failures;
    combined.summary.totalPending += stats.pending;
  }

  return combined;
}
```