# lironer/cypress-mochawesome-reporter architecture

> Architecture diagram of the GitHub repository lironer/cypress-mochawesome-reporter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lironer/cypress-mochawesome-reporter
- Repository: https://github.com/lironer/cypress-mochawesome-reporter

## Overview

##### Project type and purpose
- This is an open-source plugin / reporter tool for Cypress tests. It integrates with the Cypress test runner, listens to test lifecycle events, and produces Mochawesome HTML reports with embedded screenshots.

##### File structure
- Top-level “plugin.js”, “register.js”, “cli.js” and “cucumberSupport.js” are your integration entry points.
- The “lib/” folder holds the core modules:
- config.js / consts.js – default settings and constants
- logger.js – logging support
- reporter.js – event listener that collects test results and screenshots
- enhanceReport.js – post-processing of raw JSON results
- generateReport.js – invokes the Mochawesome report generator CLI
- “examples/” and “docs/” show usage patterns but are not part of the runtime.
- “cypress.config.js”, “cypress/support/e2e.js” are how users wire up your plugin.

##### Extract architectural insights from the README
- The plugin hooks into Cypress’s Node event API via `setupNodeEvents(on, config)` in “plugin.js”.
- On test events (“before:run”, “after:spec”, “after:run”), it collects data, writes intermediate JSON, then generates a final HTML report.
- A browser-side “register.js” file injects commands (`cy.addTestContext()`) into Cypress’s client for attaching metadata to tests.
- Optional “cucumberSupport.js” integrates with Cypress-Cucumber preprocessors.

##### Main components and interactions (
a. Cypress Test Runner (Node.js process)
b. Plugin entry point (plugin.js)
c. Reporter module (lib/reporter.js)
d. Report enhancer & generator (lib/enhanceReport.js + lib/generateReport.js)
e. Browser-side commands (register.js)
f. Optional cucumber adapter (cucumberSupport.js)
g. File System (JSON & Screenshots output, final HTML report)
h. External Reporter Tool (Mochawesome Report Generator CLI)

##### Relationships and data flows
1. User “npm install” & “require(‘cypress-mochawesome-reporter/plugin’)” ➔ Cypress config
2. On `before:run` ➔ plugin.js calls beforeRunHook (initializes artifacts folder)
3. During each spec: on `after:spec` ➔ reporter.js collects spec results + screenshots, writes JSON
4. On `after:run` ➔ plugin.js calls afterRunHook which chains:
- enhanceReport.js reads all JSON, augments them
- generateReport.js spawns Mochawesome CLI to produce final HTML
5. Browser tests: register.js injects `cy.addTestContext()` to add per-test metadata
6. If user has Cucumber: cucumberSupport.js maps Cucumber hooks to reporter events

##### Architectural patterns and principles
- Event-driven: relies on Cypress’s hook API (`on(…, handler)`).
- Separation of concerns:
- plugin.js = wiring and lifecycle hooks
- reporter.js = data capture
- enhanceReport.js & generateReport.js = post-processing and report generation
- register.js = UI-side commands injection
- Extensibility: cucumberSupport.js is a pluggable adapter for Cucumber users.
- CLI abstraction: cli.js allows standalone invocation if needed.

##### Essential details to capture
- The lifecycle hook sequence and where each module intercedes
- The transition from raw test data → enhanced JSON → final HTML
- Configuration flow: user’s Cypress config ➔ plugin initialization
- Extensibility points: reporterOptions and cucumberSupport

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Setup"
        Config["cypress.config.js"]:::cypress
        E2E["cypress/support/e2e.js"]:::cypress
        Cmds["cypress/support/commands.js"]:::cypress
    end

    Runner["Cypress Test Runner"]:::cypress

    subgraph "Node Context"
        Plugin["plugin.js"]:::plugin
        Index["lib/index.js"]:::lib
        ConfigMod["lib/config.js"]:::lib
        Consts["lib/consts.js"]:::lib
        Logger["lib/logger.js"]:::lib
        Reporter["lib/reporter.js"]:::lib
        Hooks["after:run Hook"]:::plugin
        Enhancer["lib/enhanceReport.js"]:::lib
        Generator["lib/generateReport.js"]:::lib
        CLI_Node["cli.js"]:::plugin
    end

    subgraph "Browser Context"
        Browser["register.js"]:::browser
        Cucumber["cucumberSupport.js"]:::browser
    end

    subgraph "File System & External"
        FS_JSON["JSON Outputs"]:::external
        CLI["Mochawesome CLI"]:::external
        FS_HTML["HTML Report"]:::external
    end

    Config --> Runner
    E2E --> Runner
    Cmds --> Runner

    Runner -->|setupNodeEvents| Plugin
    Plugin --> Index
    Index --> ConfigMod
    Index --> Consts
    Index --> Logger

    Plugin --> Reporter
    Reporter -->|write JSON| FS_JSON

    Runner -->|inject cy.addTestContext| Browser
    Runner -->|optional Cucumber hooks| Cucumber

    Plugin -->|after:run| Hooks
    Hooks --> Enhancer
    Enhancer -->|augment JSON| FS_JSON
    Enhancer --> Generator
    CLI_Node --> Generator
    Generator -->|spawn CLI| CLI
    CLI -->|produce| FS_HTML

    click Config "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/cypress.config.js"
    click E2E "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/cypress/support/e2e.js"
    click Cmds "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/cypress/support/commands.js"
    click Plugin "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/plugin.js"
    click Index "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/lib/index.js"
    click ConfigMod "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/lib/config.js"
    click Consts "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/lib/consts.js"
    click Logger "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/lib/logger.js"
    click Reporter "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/lib/reporter.js"
    click Enhancer "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/lib/enhanceReport.js"
    click Generator "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/lib/generateReport.js"
    click Cucumber "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/cucumberSupport.js"
    click Browser "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/register.js"
    click CLI_Node "https://github.com/lironer/cypress-mochawesome-reporter/blob/master/cli.js"

    classDef cypress fill:#bae3ff,stroke:#1f77b4,color:#000;
    classDef plugin fill:#d4f4dd,stroke:#2ca02c,color:#000;
    classDef lib fill:#e2f0d9,stroke:#2ca02c,color:#000;
    classDef browser fill:#ffe5b4,stroke:#ff7f0e,color:#000;
    classDef external fill:#f0f0f0,stroke:#7f7f7f,color:#000;
```
