# wmaarts/pitest-mutation-testing-elements-plugin architecture

> Architecture diagram of the GitHub repository wmaarts/pitest-mutation-testing-elements-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wmaarts/pitest-mutation-testing-elements-plugin
- Repository: https://github.com/wmaarts/pitest-mutation-testing-elements-plugin

## Overview

##### Project type and purpose
- This is a Java-based Pitest plugin that converts Pitest mutation testing results into Stryker’s Mutation Testing Elements format (JSON or HTML).
- It plugs into the Pitest ecosystem via Java’s Service Provider Interface (SPI) and generates reports adhering to the Stryker report schema.

##### File structure
- Top-level:
- pom.xml – Maven build definition (declares plugin packaging, dependencies).
- src/main/java/org/pitest/elements – core plugin code organized into:
– MutationReportListener.java (SPI listener entry point)
– ReportFactory classes (JSON & HTML2 factories)
– models (domain objects mapping Pitest results to Stryker schema)
– utils (parsing & helper functions)
- src/main/resources/META-INF/services – SPI descriptor registering MutationResultListenerFactory
- src/test – unit tests for all key code paths
- No frontend/backend split; it’s a single JVM plugin with clear sub‐packages following a plugin+factory pattern.

##### Key README insights
- This plugin must be added as a Pitest dependency and configured for outputFormats = [ HTML2, JSON ].
- It implements two output formats mapping to Stryker’s report schema.

##### Main components
A. Pitest Test Runner (External)
- Discovers and runs user tests.
- Loads all MutationResultListenerFactory implementations via SPI.
B. pitest-mutation-testing-elements-plugin (JAR)
1. Service Loader / SPI Layer (META-INF/services)
2. MutationReportListener (implements Pitest’s MutationResultListener)
3. Report Factories:
– MutationTestingElementsJsonReportFactory
– MutationTestingElementsReportFactory (HTML2)
4. Domain Model Layer (org.pitest.elements.models + .json)
5. Utility Layer (JSON parsing, line iteration, ID counters, comparators)
C. Stryker Mutation Testing Elements Schema (External JSON spec)
D. Output Artifacts
- JSON report file following schema
- HTML2 report

##### Relationships and data flows
1. Pitest runner ← loads → plugin via SPI
2. Pitest executes mutation tests → emits MutationResult events → delivered to MutationReportListener
3. Listener collects results → passes to appropriate ReportFactory
4. ReportFactory uses Utility Layer & Domain Models to transform data → writes output file(s)
5. Output files viewed by downstream tools or users

##### Architectural patterns & design principles
- SPI / Service Locator: Plugin registered in META-INF/services for automatic discovery
- Factory Pattern: Separate JSON vs HTML2 factories behind a common listener interface
- Layered Structure:
- Listener layer (entry point)
- Business logic layer (models + factories)
- Utility layer (parsing & helpers)
- Single responsibility per package/class

##### Technologies, frameworks, libraries
- Java 8+
- Maven (pom.xml) for build & dependency management
- Pitest plugin API (org.pitest.mutationtest.MutationResultListener)
- Jackson or custom JSON utilities for JSON serialization
- Stryker mutation-testing-elements report schema (external JSON spec)

- Package/group boundaries to show code organization

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Systems
    PitestRunner["Pitest Test Runner"]:::external
    StrykerSchema["Stryker Mutation Testing Elements Schema"]:::external

    %% Plugin Subsystem
    subgraph "pitest-mutation-testing-elements-plugin"
        direction TB
        SPI["Service Loader / SPI Layer"]:::internal
        Listener["MutationReportListener"]:::internal
        subgraph "Report Factories"
            direction TB
            JsonFactory["MutationTestingElementsJsonReportFactory"]:::internal
            HtmlFactory["MutationTestingElementsReportFactory"]:::internal
        end
        subgraph "Domain Model Layer"
            direction TB
            CoreModels["Core Models"]:::internal
            JsonModels["JSON-specific Models"]:::internal
        end
        Utils["Utility Layer"]:::internal
    end

    %% Output Artifacts
    JsonReport["JSON Report File"]:::output
    HtmlReport["HTML2 Report File"]:::output

    %% Build Definition
    Pom["Maven Build Definition (pom.xml)"]:::internal

    %% Connections
    PitestRunner -->|"loads plugin via SPI"| SPI
    PitestRunner -->|"MutationResult events"| Listener
    SPI -->|"registers listener"| Listener
    Listener -->|"delegates to"| JsonFactory
    Listener -->|"delegates to"| HtmlFactory
    JsonFactory -->|"uses"| CoreModels
    JsonFactory -->|"uses"| JsonModels
    JsonFactory -->|"uses"| Utils
    JsonFactory -->|"writes JSON report"| JsonReport
    HtmlFactory -->|"uses"| CoreModels
    HtmlFactory -->|"uses"| JsonModels
    HtmlFactory -->|"uses"| Utils
    HtmlFactory -->|"writes HTML report"| HtmlReport
    StrykerSchema -->|"schema guidelines"| JsonFactory
    StrykerSchema -->|"schema guidelines"| HtmlFactory
    Pom -->|"build & dependencies"| SPI

    %% Click Events
    click SPI "https://github.com/wmaarts/pitest-mutation-testing-elements-plugin/blob/master/src/main/resources/META-INF/services/org.pitest.mutationtest.MutationResultListenerFactory"
    click Listener "https://github.com/wmaarts/pitest-mutation-testing-elements-plugin/blob/master/src/main/java/org/pitest/elements/MutationReportListener.java"
    click JsonFactory "https://github.com/wmaarts/pitest-mutation-testing-elements-plugin/blob/master/src/main/java/org/pitest/elements/MutationTestingElementsJsonReportFactory.java"
    click HtmlFactory "https://github.com/wmaarts/pitest-mutation-testing-elements-plugin/blob/master/src/main/java/org/pitest/elements/MutationTestingElementsReportFactory.java"
    click CoreModels "https://github.com/wmaarts/pitest-mutation-testing-elements-plugin/tree/master/src/main/java/org/pitest/elements/models"
    click JsonModels "https://github.com/wmaarts/pitest-mutation-testing-elements-plugin/tree/master/src/main/java/org/pitest/elements/models/json"
    click Utils "https://github.com/wmaarts/pitest-mutation-testing-elements-plugin/tree/master/src/main/java/org/pitest/elements/utils"
    click Pom "https://github.com/wmaarts/pitest-mutation-testing-elements-plugin/blob/master/pom.xml"

    %% Styles
    classDef internal fill:#D0E1FF,stroke:#3B70A1,stroke-width:2px
    classDef external fill:#DFFFC0,stroke:#6DA800,stroke-width:2px
    classDef output fill:#FFE0B2,stroke:#E38D00,stroke-width:2px
```
