# mockk/mockk architecture

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

- Interactive diagram: https://gitdiagram.com/mockk/mockk
- Repository: https://github.com/mockk/mockk

## Overview

##### Project type and purpose
- This is a multi-module Kotlin/Java library (MockK) for mocking in unit and integration tests.
- It provides a user-facing DSL, a core engine, and platform-specific “agent” modules (JVM, Android, JS) that perform bytecode/native instrumentation or proxying.

##### File-structure overview
- Top-level: CI (`.github`, `.travis.yml`, `circle.yml`), docs/web (`doc`, `_layouts`, `_includes`, assets), build helpers (`build.gradle.kts`, `settings.gradle.kts`, `buildSrc`), and the `modules` folder.
- `buildSrc`: Kotlin code that centralizes dependency versions, publishing and convention plugins.
- `modules/`: one subdirectory per component:
- mockk-dsl – the Kotlin DSL API, multiplatform (common, JVM, JS)
- mockk-core – core mock-engine (recording, stubbing, verification), common and JVM sources
- mockk-agent-api – interface for instrumentation requests (common, JVM)
- mockk-agent – JVM agent implementation (java.lang.instrument + ASM/Byte Buddy)
- mockk-agent-android & mockk-agent-android-dispatcher – Android instrumentation via JNI/C++ slicer & dispatcher
- mockk-android – Android test integration (Instrumented & unit tests)
- mockk – top-level multiplatform wrapper (pulled in by consumers)
- `test-modules/`: sample projects for client, logger and performance tests demonstrating integration.

##### Key insights from README
- Describes features (mocking styles, coroutines, static/constructor mocks, matchers) but omits architecture.
- Technology stack: Kotlin Multiplatform, Gradle, Java agent (JVMTI), JNI/C++ slicer for Android, web docs via Jekyll.

a. Main components
- DSL Layer (mockk-dsl) – user entry point
- Core Engine (mockk-core) – recording calls, answers, verification
- Agent API (mockk-agent-api) – abstraction for class transformation or proxy dispatch
- JVM Agent (mockk-agent) – implements Agent API using java.lang.instrument + ASM/Byte Buddy
- Android Agent (mockk-agent-android & dispatcher) – JNI + C++ slicer modules for Dalvik/ART instrumentation
- JS Adapter (part of mockk-dsl/jsMain) – proxies using JS reflection
- Build & Publishing (buildSrc + Gradle) – orchestrates compilation, test, artifact publication
- Docs/Web (Jekyll assets) – website generation
b. Relationships & data flow
1. Gradle build → applies conventions (buildSrc) → compiles each module → runs module tests
2. Consumer code imports `mockk` artifact → at test compile time links mockk-dsl + mockk-core
3. At runtime → DSL calls core engine → core engine delegates instrumentation calls to Agent API
4. Agent API binds to platform plugin:
- JVM: transformer installed by `-javaagent` or Gradle plugin → uses ASM to weave mocks
- Android: instrumentation APK loads JNI library (C++ slicer) → injects proxies at runtime
- JS: uses JS engine’s dynamic proxy facilities
5. Verification & reporting cycle returns to DSL layer → user assertions
c. Architectural patterns & principles
- Modular multilayer design: separation of API/DSL, core logic, platform adapters
- Dependency inversion: core logic depends on an abstract Agent API, not on platform details
- Convention-over-configuration: centralized build conventions in `buildSrc`
- Native integration: JNI/C++ for Android; java.lang.instrument for JVM
- Multiplatform support: commonMain for business logic, jvmMain/jsMain for platform specifics
d. Key technologies & libraries
- Kotlin Multiplatform (commonMain, jvmMain, jsMain)
- Gradle Kotlin DSL + `buildSrc` conventions
- Java agent (JVMTI, ASM or Byte Buddy)
- JNI/C++ slicer for Android instrumentation
- Jekyll for documentation site

##### Detail & thoroughness
- Every module and its primary dependencies
- Call out build conventions in `buildSrc` as part of the CI/publishing pipeline
- Both compile-time (Gradle → module graph) and runtime (DSL → core → agent) interactions
- Avoid clutter by grouping similar modules (e.g., all `mockk-agent-*` under a “Platform Adapters” cluster)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI
    subgraph "Build & CI"
        BS["buildSrc"]:::infra
        GR["build.gradle.kts\nsettings.gradle.kts"]:::infra
        CI[".github/\n.travis.yml\ncircle.yml"]:::infra
    end

    %% Documentation & Website
    subgraph "Documentation & Website"
        DOCS["doc/\n_layouts/\n_includes/\nassets/css/style.scss"]:::infra
        CFG["_config.yml\nCNAME"]:::infra
    end

    %% Modules Cluster
    subgraph "Modules"
        subgraph "API & DSL" 
            DSL["mockk-dsl"]:::api
            WRAP["mockk\n(multiplatform wrapper)"]:::api
        end
        subgraph "Core Modules"
            CORE["mockk-core"]:::core
            API["mockk-agent-api"]:::core
        end
        subgraph "Platform Adapters"
            JVM["mockk-agent\n(JVM Agent)"]:::adapter
            ANDDISP["mockk-agent-android-dispatcher\n(Android Dispatcher)"]:::adapter
            ANDAG["mockk-agent-android\n(Android JNI/C++ slicer)"]:::adapter
            JS["JS Adapter"]:::adapter
        end
        ANDTEST["mockk-android\n(Android Test Integration)"]:::adapter
    end

    %% Build Flow
    BS -->|provides conventions| GR
    GR -->|compiles & tests| DSL
    GR --> CORE
    GR --> API
    GR --> JVM
    GR --> ANDDISP
    GR --> ANDAG
    GR --> ANDTEST
    GR --> WRAP
    GR --> JS

    %% Runtime Flow
    WRAP -->|imports| DSL
    DSL -->|calls| CORE
    CORE -->|delegates| API
    API -->|JVM binding| JVM
    API -->|Android binding| ANDAG
    API -->|Android dispatcher| ANDDISP
    API -->|JS proxy| JS
    JS -->|uses dynamic proxy| CORE
    JVM -->|instrumentation via ASM/Byte Buddy| CORE
    ANDAG -->|native injection| CORE
    ANDDISP -->|dispatch JNI calls| ANDAG
    DSL -->|verification results| WRAP

    %% Click Events
    click DSL "https://github.com/mockk/mockk/tree/master/modules/mockk-dsl"
    click CORE "https://github.com/mockk/mockk/tree/master/modules/mockk-core"
    click API "https://github.com/mockk/mockk/tree/master/modules/mockk-agent-api"
    click JVM "https://github.com/mockk/mockk/tree/master/modules/mockk-agent"
    click ANDDISP "https://github.com/mockk/mockk/tree/master/modules/mockk-agent-android-dispatcher"
    click ANDAG "https://github.com/mockk/mockk/tree/master/modules/mockk-agent-android"
    click ANDTEST "https://github.com/mockk/mockk/tree/master/modules/mockk-android"
    click WRAP "https://github.com/mockk/mockk/tree/master/modules/mockk"
    click JS "https://github.com/mockk/mockk/blob/master/modules/mockk-dsl/src/jsMain/kotlin/io/mockk/InternalPlatformDsl.kt"
    click BS "https://github.com/mockk/mockk/tree/master/buildSrc/"
    click GR "https://github.com/mockk/mockk/blob/master/build.gradle.kts"
    click GR "https://github.com/mockk/mockk/blob/master/settings.gradle.kts"
    click BS "https://github.com/mockk/mockk/tree/master/buildSrc/"
    click DOCS "https://github.com/mockk/mockk/tree/master/doc/"
    click DOCS "https://github.com/mockk/mockk/tree/master/_layouts/"
    click DOCS "https://github.com/mockk/mockk/tree/master/_includes/"
    click DOCS "https://github.com/mockk/mockk/blob/master/assets/css/style.scss"
    click CFG "https://github.com/mockk/mockk/blob/master/_config.yml"
    click CFG "https://github.com/mockk/mockk/tree/master/CNAME"
    click CI "https://github.com/mockk/mockk/tree/master/.github/"
    click CI "https://github.com/mockk/mockk/blob/master/.travis.yml"
    click CI "https://github.com/mockk/mockk/blob/master/circle.yml"

    %% Styles
    classDef api fill:#AEDFFD,stroke:#027BDB,color:#000
    classDef core fill:#DFFFAE,stroke:#7DBC02,color:#000
    classDef adapter fill:#FFDFAE,stroke:#DB7B02,color:#000
    classDef infra fill:#E0E0E0,stroke:#888888,color:#000
    class DSL,WRAP api
    class CORE,API core
    class JVM,ANDDISP,ANDAG,ANDTEST,JS adapter
    class BS,GR,CI,DOCS,CFG infra
```
