# williamfzc/randunit architecture

> Architecture diagram of the GitHub repository williamfzc/randunit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/williamfzc/randunit
- Repository: https://github.com/williamfzc/randunit

## Overview

##### Main Components
- Core Library (randunit): This is the main engine. It contains the modules for scanning (to collect candidate classes/methods), generating statements (test cases) and executing them. Sub-packages like “env”, “operations”, “models”, “rules”, “exceptions”, “mock”, “extensions”, “scanner” indicate distinct responsibilities.
- Android-Specific Extension (randunit-android): This module adapts the core functionality (the scanning, generation, and execution processes) to work optimally in Android environments, integrating with tools like Robolectric.
- Demo/Example Applications (randunit-demo, randunit-android-demo): These projects demonstrate how to integrate and run the tests produced by the framework using JUnit (and its Android alterations such as ParameterizedRobolectricTestRunner). They show how to import the library, configure a test environment, and run the generated test cases.
- Build/CI Infrastructure: The presence of Gradle files, GitHub workflows (in .github/workflows), and additional scripts (under scripts/) show that the project is built with CI/CD in mind.

##### Relationships and Interactions
- The “Scanner” component (located in the “scanner” package) is responsible for traversing the provided package or class names to collect all candidate classes.
- The “Generator” uses the information collected (and represented by “StatementModel” and related artifacts in “models”) to produce a set of executable test cases.
- The “Runner” (or “env” package) provides the execution environment. It includes sandboxing (e.g., the “sandbox” packages), strategies, and rule systems which decide how to handle exceptions or filter test outcomes.
- The Android module adapts these components (for example, substituting RandUnit with RandUnitAndroid and integrating with robolectric-specific runners and configurations).
- The demo modules (randunit-demo and randunit-android-demo) show the integration flow where the developer simply copies a test template (as shown in the README) into their project, pointing it to the correct package to allow all previous components to be invoked and tie together.

##### Architectural Patterns and Design Principles
- Modularity: The separation between core functionality, Android-specific behavior, and demonstration projects is clear. Each module encapsulates a specific concern.
- Extensibility: The architecture is built around extensibility: rules (for handling exceptions), strategies (for test case generation), and a clear separation of scanning, generating, and running test cases. This allows developers or algorithm engineers to extend any part without affecting the others.
- Plugin/Adapter Pattern: The Android module acts as an adapter that tweaks the basic test process to use Android’s testing tools (like Robolectric), thereby showcasing a “plug-in” style extension of the core behavior.

##### And Note Relevant Technologies and Frameworks
- Gradle for build and dependency management.
- JUnit (both version 4 and 5) as the test running framework.
- Robolectric for Android testing.
- Kotlin and Java as the primary programming languages.
- Github Actions for CI, as indicated in the .github/workflows files.
- Additional libraries for scanning (e.g., reflections) and for easing mocking and sandboxing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Subgraph
    subgraph "Core Library"
        S["Scanner"]:::core
        G["Generator (Operations)"]:::core
        R["Runner (Env)"]:::core
        M["Models"]:::core
        L["Rules"]:::core
        X["Exceptions"]:::core
        MK["Mocks"]:::core
        EX["Extensions"]:::core
    end

    %% Relationships within Core Library
    S -->|"collects"| G
    G -->|"generates_tests"| R
    R -->|"invokes"| M
    R -->|"applies"| L
    R -->|"handles"| X
    R -->|"uses"| MK
    R -->|"uses"| EX

    %% Android Extension Subgraph
    subgraph "Android Extension"
        RA["RandUnitAndroid Entry"]:::android
        AEnv["Android Test Env"]:::android
        AR["Android Builtin Rule"]:::android
        AS["Android Sandbox"]:::android
        AM["Android Mocker"]:::android
        AEX["Android Exception Extension"]:::android
    end

    %% Relationships within Android Extension
    RA -->|"wraps"| AEnv
    AEnv -->|"integrates_with"| AR
    AEnv -->|"integrates_with"| AS
    AEnv -->|"uses"| AM
    AEnv -->|"uses"| AEX

    %% Demo Projects Subgraph
    subgraph "Demo Projects"
        D1["Standard Demo"]:::demo
        D2["Android Demo"]:::demo
    end

    %% Build/CI Infrastructure Subgraph
    subgraph "Build/CI Infrastructure"
        BI["Build & CI Pipelines"]:::build
    end

    %% Interactions between Demo Projects and Core/Android Extension
    D1 -->|"invokes"| S
    D1 -->|"invokes"| G
    D1 -->|"invokes"| R
    D2 -->|"invokes"| RA
    D2 -->|"invokes"| AEnv

    %% Build/CI interacting with other modules
    BI -->|"builds"| S
    BI -->|"builds"| RA
    BI -->|"builds"| D1
    BI -->|"builds"| D2

    %% Click Events for Core Library Components
    click S "https://github.com/williamfzc/randunit/tree/main/randunit/src/main/kotlin/com/williamfzc/randunit/scanner"
    click G "https://github.com/williamfzc/randunit/tree/main/randunit/src/main/kotlin/com/williamfzc/randunit/operations"
    click R "https://github.com/williamfzc/randunit/tree/main/randunit/src/main/kotlin/com/williamfzc/randunit/env"
    click M "https://github.com/williamfzc/randunit/tree/main/randunit/src/main/kotlin/com/williamfzc/randunit/models"
    click L "https://github.com/williamfzc/randunit/tree/main/randunit/src/main/kotlin/com/williamfzc/randunit/env/rules"
    click X "https://github.com/williamfzc/randunit/tree/main/randunit/src/main/kotlin/com/williamfzc/randunit/exceptions"
    click MK "https://github.com/williamfzc/randunit/tree/main/randunit/src/main/kotlin/com/williamfzc/randunit/mock"
    click EX "https://github.com/williamfzc/randunit/tree/main/randunit/src/main/kotlin/com/williamfzc/randunit/extensions"

    %% Click Events for Android Extension Components
    click RA "https://github.com/williamfzc/randunit/blob/main/randunit-android/src/main/java/com/williamfzc/randunit/RandUnitAndroid.kt"
    click AEnv "https://github.com/williamfzc/randunit/tree/main/randunit-android/src/main/java/com/williamfzc/randunit/env"
    click AR "https://github.com/williamfzc/randunit/blob/main/randunit-android/src/main/java/com/williamfzc/randunit/env/rules/AndroidBuiltinRule.kt"
    click AS "https://github.com/williamfzc/randunit/blob/main/randunit-android/src/main/java/com/williamfzc/randunit/env/sandbox/AndroidSandbox.kt"
    click AM "https://github.com/williamfzc/randunit/blob/main/randunit-android/src/main/java/com/williamfzc/randunit/mock/AndroidMocker.kt"
    click AEX "https://github.com/williamfzc/randunit/blob/main/randunit-android/src/main/java/com/williamfzc/randunit/extensions/AndroidExceptionExt.kt"

    %% Click Events for Demo Projects
    click D1 "https://github.com/williamfzc/randunit/tree/main/randunit-demo/"
    click D2 "https://github.com/williamfzc/randunit/tree/main/randunit-android-demo/"

    %% Click Events for Build/CI Infrastructure (multiple mappings)
    click BI "https://github.com/williamfzc/randunit/blob/main/build.gradle"
    click BI "https://github.com/williamfzc/randunit/tree/main/gradlew"
    click BI "https://github.com/williamfzc/randunit/tree/main/.github/workflows/"
    click BI "https://github.com/williamfzc/randunit/tree/main/scripts/"

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef android fill:#bbf,stroke:#333,stroke-width:2px;
    classDef demo fill:#bfb,stroke:#333,stroke-width:2px;
    classDef build fill:#ff9,stroke:#333,stroke-width:2px;
```
