📦 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)

<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/[email protected]/build/iife/mocha-detailed-json-reporter.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/build/iife/mocha-multiple-sessions.min.js"></script>

2. Create the runner

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

3. Define sessions

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

4. Run sessions

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

5. Get reports

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:

  const resultKey = `mochaSession__${label.replace(/\s+/g, '_')}`;

• The init() call internally invokes:

  testSessionSetup({
    createMochaInstance(label) => new Mocha({...}),
    injectGlobals(mocha) => mocha.suite.emit(...)
  });

• All session metadata and status are tracked internally in Map<string, SessionMeta>.

📦 Type Summary

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()

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;
}