How mockk/mockk works
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)