# junit-team/junit-framework architecture

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

- Interactive diagram: https://gitdiagram.com/junit-team/junit-framework
- Repository: https://github.com/junit-team/junit-framework

## Overview

1. This is a monorepo for the JUnit ecosystem, split into three major product lines: JUnit Platform, JUnit Jupiter, and JUnit Vintage. The codebase is organized as many Gradle subprojects, with modules published independently and tied together by a shared build, BOM, docs, and compatibility test suites.

2. The lowest architectural layer is `junit-platform-commons`. It contains shared utilities used everywhere else: reflection and classpath scanning, annotation handling, conversion helpers, resource access, logging, string utilities, and precondition/error types. This module is the common dependency boundary for most other modules.

3. The Platform execution kernel lives in `junit-platform-engine`. It defines the engine SPI and core model: `TestEngine`, `TestDescriptor`, `UniqueId`, selectors, discovery filters, execution results, reporting types, and the hierarchical execution support used by engines. Engines build descriptor trees during discovery and execute them through the hierarchical executor infrastructure.

4. `junit-platform-launcher` is the orchestration layer above engines. It aggregates discovery requests, applies filters and listeners, coordinates engine discovery/execution, manages launcher sessions, handles tag expressions and method filters, and adapts engine events into `TestExecutionListener` callbacks. This is the main entry point used by IDEs, build tools, and command-line tools.

5. `junit-platform-console` is a CLI and `ToolProvider` wrapper around the launcher. It translates command-line options into discovery/execution requests, loads test engines via service discovery, and renders results in different output styles. The console layer is how the platform is exposed as a standalone executable tool.

6. `junit-platform-reporting` sits on the listener side of the launcher and turns execution events into reports. It contains both legacy XML reporting and the newer Open Test Reporting implementation, with service-loader registrations so it can be attached automatically during execution. This module is a post-processing boundary: it does not run tests, it consumes launcher events.

7. `junit-platform-suite-api` and `junit-platform-suite-engine` provide test-suite composition. The API defines annotations such as suite selectors, inclusion/exclusion filters, and lifecycle hooks; the suite engine interprets those annotations, creates discovery selectors, and delegates actual test execution to other engines. This is the bridge between “suite definition” and “engine execution.”

8. `junit-platform-testkit` is a verification tool for engines and launcher behavior. It provides in-process assertions over discovery results, execution events, event statistics, and termination state, and is used heavily by the repo’s own tests to validate engine and launcher behavior.

9. `junit-jupiter-api` is the user-facing programming model for writing tests. It includes assertions, assumptions, lifecycle annotations, display names, dynamic/repeated/parameterized test support, conditions, extensions, temp directory and parallel-execution APIs, plus Kotlin support in `src/main/kotlin`. It is the contract that test classes and extensions program against.

10. `junit-jupiter-engine` is the runtime that discovers and executes Jupiter tests. It translates Jupiter annotations into engine descriptors, applies extension registration and parameter resolution, manages test instances and lifecycle callbacks, and handles features like nested tests, test templates, repeated tests, timeouts, and dynamic tests. This module is the core implementation behind the Jupiter programming model.

11. `junit-jupiter-params` is a specialized Jupiter extension module for parameterized tests and parameterized classes. It adds argument providers, converters, aggregators, invocation name formatting, and the resolver pipeline that injects argument values into test methods and class templates. It depends on the Jupiter engine infrastructure but adds its own discovery/execution extension points.

12. `junit-jupiter-migrationsupport` is a compatibility bridge for JUnit 4-era constructs. It adapts selected JUnit 4 rules and ignored conditions into Jupiter extensions, helping legacy tests move forward without rewriting everything at once.

13. `junit-vintage-engine` is the adapter for running JUnit 3 and JUnit 4 tests on the JUnit Platform. It discovers legacy test classes, wraps runners/descriptions into platform descriptors, and executes them through the platform engine contract so Vintage tests appear alongside Jupiter tests in the same launcher flow.

14. `junit-jupiter` and `junit-start` are umbrella/entry modules. `junit-jupiter` is the aggregate dependency for the Jupiter stack, while `junit-start` provides a minimal bootstrapping entry point for users who want a simple runtime start class rather than the full platform API surface.

15. The repository is heavily self-tested through dedicated integration suites: `jupiter-tests`, `platform-tests`, and `platform-tooling-support-tests`. These projects exercise cross-module behavior, Kotlin/Groovy interoperability, console output snapshots, build-tool integrations, reporting formats, and launch/execution edge cases. They are as important to the architecture as the production modules because they validate the contracts between modules.

16. Build and packaging are first-class architectural concerns. The project uses Gradle Kotlin DSL, Java modules (`module-info.java`), service-loader registrations under `META-INF/services`, JMH benchmarks in selected modules, and generated sources/templates in a few places. Documentation is also a structured subsystem via Antora, with examples and executable snippets that mirror the API/engine split.

Main entry points: [`platform-tests/platform-tests.gradle.kts`](https://github.com/junit-team/junit-framework/blob/main/platform-tests/platform-tests.gradle.kts) (Platform tests), [`junit-platform-launcher/src/main/java/org/junit/platform/launcher/package-info.java`](https://github.com/junit-team/junit-framework/blob/main/junit-platform-launcher/src/main/java/org/junit/platform/launcher/package-info.java) (Launcher), [`junit-platform-engine/src/main/java/org/junit/platform/engine/package-info.java`](https://github.com/junit-team/junit-framework/blob/main/junit-platform-engine/src/main/java/org/junit/platform/engine/package-info.java) (Platform engine), [`platform-tooling-support-tests/platform-tooling-support-tests.gradle.kts`](https://github.com/junit-team/junit-framework/blob/main/platform-tooling-support-tests/platform-tooling-support-tests.gradle.kts) (Tooling tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["JUnit Platform"]
  node_commons["Platform commons<br/>shared utilities<br/>[package-info.java]"]
  node_engine["Platform engine<br/>engine SPI<br/>[package-info.java]"]
  node_launcher["Launcher<br/>orchestration<br/>[package-info.java]"]
  node_console["Console<br/>CLI tool"]
  node_reporting["Reporting<br/>listeners<br/>[package-info.java]"]
  node_suite_api["Suite API<br/>suite annotations<br/>[package-info.java]"]
  node_suite_engine["Suite engine<br/>suite runtime"]
  node_testkit["TestKit<br/>verification toolkit<br/>[EngineTestKit.java]"]
end

subgraph group_jupiter["JUnit Jupiter"]
  node_jupiter_api["Jupiter API<br/>user API<br/>[package-info.java]"]
  node_jupiter_engine["Jupiter engine<br/>runtime engine"]
  node_jupiter_params["Params<br/>parameterized extension<br/>[package-info.java]"]
  node_jupiter_migration["Migration support<br/>compatibility bridge<br/>[package-info.java]"]
  node_jupiter_umbrella["Jupiter umbrella<br/>aggregate module<br/>[module-info.java]"]
  node_junit_start["JUnit Start<br/>bootstrap entry<br/>[JUnit.java]"]
end

subgraph group_vintage["JUnit Vintage"]
  node_vintage_engine["Vintage engine<br/>legacy adapter"]
end

subgraph group_build["Build & docs"]
  node_build_root["Gradle build<br/>build orchestration<br/>[build.gradle.kts]"]
  node_bom["BOM<br/>dependency alignment"]
  node_docs["Docs site<br/>documentation"]
  node_platform_tests["Platform tests<br/>integration suite"]
  node_tooling_tests["Tooling tests<br/>integration suite"]
end

node_build_root -->|"publishes"| node_bom
node_build_root -->|"drives"| node_docs
node_build_root -->|"runs"| node_platform_tests
node_build_root -->|"runs"| node_tooling_tests
node_commons -->|"shared by"| node_engine
node_commons -->|"shared by"| node_launcher
node_engine -->|"executes under"| node_launcher
node_launcher -->|"fronted by"| node_console
node_launcher -->|"emits events to"| node_reporting
node_suite_api -->|"interpreted by"| node_suite_engine
node_suite_engine -->|"orchestrated by"| node_launcher
node_suite_engine -->|"delegates to"| node_engine
node_testkit -->|"observes"| node_launcher
node_jupiter_api -->|"implemented by"| node_jupiter_engine
node_jupiter_api -->|"extended by"| node_jupiter_params
node_jupiter_engine -->|"implements SPI"| node_engine
node_jupiter_params -->|"hooks into"| node_jupiter_engine
node_jupiter_migration -->|"adapts to"| node_jupiter_engine
node_jupiter_umbrella -->|"aggregates"| node_jupiter_api
node_jupiter_umbrella -->|"aggregates"| node_jupiter_engine
node_junit_start -->|"boots"| node_launcher
node_vintage_engine -->|"implements SPI"| node_engine
node_platform_tests -->|"validates"| node_commons
node_platform_tests -->|"validates"| node_engine
node_platform_tests -->|"validates"| node_launcher
node_platform_tests -->|"validates"| node_console
node_platform_tests -->|"validates"| node_reporting
node_platform_tests -->|"validates"| node_suite_engine
node_platform_tests -->|"uses"| node_testkit
node_tooling_tests -->|"covers"| node_console
node_tooling_tests -->|"covers"| node_junit_start
node_tooling_tests -->|"covers"| node_vintage_engine
node_tooling_tests -->|"covers"| node_jupiter_api

click node_build_root "https://github.com/junit-team/junit-framework/blob/main/build.gradle.kts"
click node_bom "https://github.com/junit-team/junit-framework/blob/main/junit-bom/junit-bom.gradle.kts"
click node_docs "https://github.com/junit-team/junit-framework/blob/main/documentation/antora-playbook.yml"
click node_platform_tests "https://github.com/junit-team/junit-framework/blob/main/platform-tests/platform-tests.gradle.kts"
click node_tooling_tests "https://github.com/junit-team/junit-framework/blob/main/platform-tooling-support-tests/platform-tooling-support-tests.gradle.kts"
click node_commons "https://github.com/junit-team/junit-framework/blob/main/junit-platform-commons/src/main/java/org/junit/platform/commons/package-info.java"
click node_engine "https://github.com/junit-team/junit-framework/blob/main/junit-platform-engine/src/main/java/org/junit/platform/engine/package-info.java"
click node_launcher "https://github.com/junit-team/junit-framework/blob/main/junit-platform-launcher/src/main/java/org/junit/platform/launcher/package-info.java"
click node_console "https://github.com/junit-team/junit-framework/blob/main/junit-platform-console/src/main/java/org/junit/platform/console/ConsoleLauncher.java"
click node_reporting "https://github.com/junit-team/junit-framework/blob/main/junit-platform-reporting/src/main/java/org/junit/platform/reporting/package-info.java"
click node_suite_api "https://github.com/junit-team/junit-framework/blob/main/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/package-info.java"
click node_suite_engine "https://github.com/junit-team/junit-framework/blob/main/junit-platform-suite-engine/src/main/java/org/junit/platform/suite/engine/SuiteTestEngine.java"
click node_testkit "https://github.com/junit-team/junit-framework/blob/main/junit-platform-testkit/src/main/java/org/junit/platform/testkit/engine/EngineTestKit.java"
click node_jupiter_api "https://github.com/junit-team/junit-framework/blob/main/junit-jupiter-api/src/main/java/org/junit/jupiter/api/package-info.java"
click node_jupiter_engine "https://github.com/junit-team/junit-framework/blob/main/junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/JupiterTestEngine.java"
click node_jupiter_params "https://github.com/junit-team/junit-framework/blob/main/junit-jupiter-params/src/main/java/org/junit/jupiter/params/package-info.java"
click node_jupiter_migration "https://github.com/junit-team/junit-framework/blob/main/junit-jupiter-migrationsupport/src/main/java/org/junit/jupiter/migrationsupport/package-info.java"
click node_jupiter_umbrella "https://github.com/junit-team/junit-framework/blob/main/junit-jupiter/src/main/java/module-info.java"
click node_junit_start "https://github.com/junit-team/junit-framework/blob/main/junit-start/src/main/java/org/junit/start/JUnit.java"
click node_vintage_engine "https://github.com/junit-team/junit-framework/blob/main/junit-vintage-engine/src/main/java/org/junit/vintage/engine/VintageTestEngine.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_commons,node_engine,node_launcher,node_console,node_reporting,node_suite_api,node_suite_engine,node_testkit toneBlue
class node_jupiter_api,node_jupiter_engine,node_jupiter_params,node_jupiter_migration,node_jupiter_umbrella,node_junit_start toneAmber
class node_vintage_engine toneMint
class node_build_root,node_bom,node_docs,node_platform_tests,node_tooling_tests toneRose
```

## Components

### JUnit Platform

Shared engine, launcher, reporting, suite, console, and testkit layers.

- [Platform commons](https://github.com/junit-team/junit-framework/blob/main/junit-platform-commons/src/main/java/org/junit/platform/commons/package-info.java): shared utilities · Reflection, scanning, annotation, resource, logging, conversion, and utility boundary. · `junit-platform-commons/src/main/java/org/junit/platform/commons/package-info.java`
- [Platform engine](https://github.com/junit-team/junit-framework/blob/main/junit-platform-engine/src/main/java/org/junit/platform/engine/package-info.java): engine SPI · Core test engine SPI, descriptor model, selectors, discovery, reporting, and hierarchical execution support. · `junit-platform-engine/src/main/java/org/junit/platform/engine/package-info.java`
- [Launcher](https://github.com/junit-team/junit-framework/blob/main/junit-platform-launcher/src/main/java/org/junit/platform/launcher/package-info.java): orchestration · Coordinates discovery, filtering, sessions, listeners, and engine execution. · `junit-platform-launcher/src/main/java/org/junit/platform/launcher/package-info.java`
- [Console](https://github.com/junit-team/junit-framework/blob/main/junit-platform-console/src/main/java/org/junit/platform/console/ConsoleLauncher.java): CLI tool · Command-line and ToolProvider entry point built on the launcher. · `junit-platform-console/src/main/java/org/junit/platform/console/ConsoleLauncher.java`
- [Reporting](https://github.com/junit-team/junit-framework/blob/main/junit-platform-reporting/src/main/java/org/junit/platform/reporting/package-info.java): listeners · Consumes launcher events and produces XML and Open Test Reporting outputs. · `junit-platform-reporting/src/main/java/org/junit/platform/reporting/package-info.java`
- [Suite API](https://github.com/junit-team/junit-framework/blob/main/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/package-info.java): suite annotations · Annotations and selectors for suite definition and filtering. · `junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/package-info.java`
- [Suite engine](https://github.com/junit-team/junit-framework/blob/main/junit-platform-suite-engine/src/main/java/org/junit/platform/suite/engine/SuiteTestEngine.java): suite runtime · Interprets suite annotations, builds selectors, and delegates to other engines. · `junit-platform-suite-engine/src/main/java/org/junit/platform/suite/engine/SuiteTestEngine.java`
- [TestKit](https://github.com/junit-team/junit-framework/blob/main/junit-platform-testkit/src/main/java/org/junit/platform/testkit/engine/EngineTestKit.java): verification toolkit · In-process assertions over discovery results, execution events, and termination state. · `junit-platform-testkit/src/main/java/org/junit/platform/testkit/engine/EngineTestKit.java`

### JUnit Jupiter

Jupiter API, engine, parameters, migration support, and umbrella modules.

- [Jupiter API](https://github.com/junit-team/junit-framework/blob/main/junit-jupiter-api/src/main/java/org/junit/jupiter/api/package-info.java): user API · Assertions, assumptions, lifecycle, extensions, parameterized and parallel-test APIs. · `junit-jupiter-api/src/main/java/org/junit/jupiter/api/package-info.java`
- [Jupiter engine](https://github.com/junit-team/junit-framework/blob/main/junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/JupiterTestEngine.java): runtime engine · Discovers and executes Jupiter tests, lifecycle callbacks, extensions, templates, and dynamic tests. · `junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/JupiterTestEngine.java`
- [Params](https://github.com/junit-team/junit-framework/blob/main/junit-jupiter-params/src/main/java/org/junit/jupiter/params/package-info.java): parameterized extension · Parameterized tests and classes, argument providers, converters, aggregators, and invocation resolution. · `junit-jupiter-params/src/main/java/org/junit/jupiter/params/package-info.java`
- [Migration support](https://github.com/junit-team/junit-framework/blob/main/junit-jupiter-migrationsupport/src/main/java/org/junit/jupiter/migrationsupport/package-info.java): compatibility bridge · Bridges selected JUnit 4 rules and ignore behavior into Jupiter. · `junit-jupiter-migrationsupport/src/main/java/org/junit/jupiter/migrationsupport/package-info.java`
- [Jupiter umbrella](https://github.com/junit-team/junit-framework/blob/main/junit-jupiter/src/main/java/module-info.java): aggregate module · Aggregate dependency for the Jupiter stack. · `junit-jupiter/src/main/java/module-info.java`
- [JUnit Start](https://github.com/junit-team/junit-framework/blob/main/junit-start/src/main/java/org/junit/start/JUnit.java): bootstrap entry · Minimal runtime entry point for simple startup use cases. · `junit-start/src/main/java/org/junit/start/JUnit.java`

### JUnit Vintage

Adapters for JUnit 3/4 execution on the platform.

- [Vintage engine](https://github.com/junit-team/junit-framework/blob/main/junit-vintage-engine/src/main/java/org/junit/vintage/engine/VintageTestEngine.java): legacy adapter · Runs JUnit 3 and JUnit 4 tests on the JUnit Platform. · `junit-vintage-engine/src/main/java/org/junit/vintage/engine/VintageTestEngine.java`

### Build & docs

Gradle build, documentation, and cross-module verification suites.

- [Gradle build](https://github.com/junit-team/junit-framework/blob/main/build.gradle.kts): build orchestration · Shared Gradle Kotlin DSL build that wires the monorepo and publishing. · `build.gradle.kts`
- [BOM](https://github.com/junit-team/junit-framework/blob/main/junit-bom/junit-bom.gradle.kts): dependency alignment · Bill of materials for coordinated dependency consumption. · `junit-bom/junit-bom.gradle.kts`
- [Docs site](https://github.com/junit-team/junit-framework/blob/main/documentation/antora-playbook.yml): documentation · Antora-based documentation, examples, and executable snippets. · `documentation/antora-playbook.yml`
- [Platform tests](https://github.com/junit-team/junit-framework/blob/main/platform-tests/platform-tests.gradle.kts): integration suite · Cross-module tests for platform, launcher, console, reporting, suite, and testkit behavior. · `platform-tests/platform-tests.gradle.kts`
- [Tooling tests](https://github.com/junit-team/junit-framework/blob/main/platform-tooling-support-tests/platform-tooling-support-tests.gradle.kts): integration suite · External tool and packaging compatibility tests for starter projects and launchers. · `platform-tooling-support-tests/platform-tooling-support-tests.gradle.kts`

## Connections

- Gradle build → BOM: publishes · Build defines the BOM and release artifacts.
- Gradle build → Docs site: drives · Build generates and validates documentation.
- Gradle build → Platform tests: runs · Build orchestrates cross-module verification suites.
- Gradle build → Tooling tests: runs · Build orchestrates external tooling compatibility suites.
- Platform commons → Platform engine: shared by · Engine depends on common utilities and support code.
- Platform commons → Launcher: shared by · Launcher relies on common utilities and support code.
- Platform engine → Launcher: executes under · Launcher discovers and executes engines through the engine SPI.
- Launcher → Console: fronted by · Console wraps launcher discovery and execution.
- Launcher → Reporting: emits events to · Reporting attaches as launcher listeners.
- Suite API → Suite engine: interpreted by · Suite engine reads suite annotations and selectors from the API.
- Suite engine → Launcher: orchestrated by · Suite execution happens through the launcher flow.
- Suite engine → Platform engine: delegates to · Suite engine delegates actual test execution to other engines.
- TestKit → Launcher: observes · TestKit asserts launcher behavior and emitted events.
- Jupiter API → Jupiter engine: implemented by · Engine realizes the Jupiter programming model.
- Jupiter API → Params: extended by · Parameterized support extends the Jupiter API model.
- Jupiter engine → Platform engine: implements SPI · Jupiter engine is a platform engine implementation.
- Params → Jupiter engine: hooks into · Parameterized features plug into Jupiter execution.
- Migration support → Jupiter engine: adapts to · Migration support attaches as Jupiter extensions.
- Jupiter umbrella → Jupiter API: aggregates · Umbrella module bundles the Jupiter API.
- Jupiter umbrella → Jupiter engine: aggregates · Umbrella module bundles the Jupiter engine.
- JUnit Start → Launcher: boots · Startup entry bridges to platform launching.
- Vintage engine → Platform engine: implements SPI · Vintage is a platform engine implementation.
- Platform tests → Platform commons: validates · Platform tests cover shared utility contracts.
- Platform tests → Platform engine: validates · Platform tests cover engine SPI and descriptor behavior.
- Platform tests → Launcher: validates · Platform tests cover launcher orchestration and filters.
- Platform tests → Console: validates · Platform tests cover console output and command flow.
- Platform tests → Reporting: validates · Platform tests cover legacy and open reporting.
- Platform tests → Suite engine: validates · Platform tests cover suite discovery and execution.
- Platform tests → TestKit: uses · Platform tests use the test kit to assert execution behavior.
- Tooling tests → Console: covers · Tooling tests cover console and packaging scenarios.
- Tooling tests → JUnit Start: covers · Tooling tests cover startup and distribution scenarios.
- Tooling tests → Vintage engine: covers · Tooling tests cover legacy integration scenarios.
- Tooling tests → Jupiter API: covers · Tooling tests cover Jupiter usage in starter projects.