TestBalloon

TestBalloon is a DSL-based, Kotlin-first test framework designed to replace restrictive, annotation-based testing with plain Kotlin configuration. It provides a concise and flexible API that is easy to customize for various test setups.

Key Features

• Advanced Testing Patterns: Supports parameterized tests, multi-level hierarchies, fixtures, and expressive naming.
• Concurrency: Built-in full coroutine support with coroutine context inheritance and deep parallelism.
• Extensibility: Uses a scope-friendly DSL and decorator chains for configuration.
• Assertion Compatibility: Works with existing assertion libraries and Kotlin Power Assert.
• Platform Integration: Deeply integrated with Gradle tasks and Kotlin's platform-specific test runtimes.

TestBalloon is a DSL-based, Kotlin-first testing framework designed to replace restrictive, annotation-based testing with plain Kotlin configuration. It provides a concise and flexible API that is easy to customize for various test setups.

Key Capabilities:

• Advanced Test Features: Supports parameterized tests, multi-level hierarchies, fixtures, expressive naming, and decorator chains for configuration.
• Concurrency: Built-in full coroutine support with coroutine context inheritance and high-degree parallelism.
• Compatibility: Works with existing assertion libraries and Kotlin Power Assert.
• Platform Support: Native support for all Kotlin target platforms, including JVM, JS, WebAssembly, Native (Linux, Windows, iOS, macOS), Android (host-side and device-side), and Robolectric.

TestBalloon integrates with IntelliJ IDEA (ideally via the TestBalloon plugin).

Features:

• Run/Debug gutter icons for individual tests and suites.
• Test status indicators (success/fail) for JVM targets.
• Results appear in the standard IntelliJ test run window.
• Stack traces automatically fold framework-internal lines.
• Kotlin inspections for title-case naming of suite properties.

Limitations:

• The "Rerun Failed Tests" action in the test run window is not supported.

TestBalloon supports both Android host-side (unit) tests and Android device-side (instrumented) tests.

Key Capabilities & Limitations:

• JUnit 4 Support: Releases 0.7.0 and above support using JUnit 4 rules within TestBalloon tests.
• Compatibility: Existing JUnit 4 tests can run alongside TestBalloon tests.
• Nested Suites: Nested test suites are supported.
• Limitation: Concurrent or parallel test invocation is not supported on Android because it conflicts with how the Android test infrastructure handles Activities.

TestBalloon is a Kotlin-first, DSL-based testing framework designed to eliminate bloat and provide a small-surface API. It is built to scale with complex interactions and across multiple targets.

Core Capabilities:

• Parameterized tests: Easily run the same test logic with different inputs.
• Multi-level hierarchy: Organize tests into structured, expressive hierarchies.
• Coroutine support: Full built-in support for Coroutines and coroutine context inheritance.
• Deep parallelism: High-performance test execution via concurrent runs.
• Fixtures: Managed test data and environment setup.
• Expressive names: Clear, readable test identification.
• Scope-friendly DSL: A domain-specific language that respects Kotlin scopes.
• Configuration via decorator chains: Flexible test configuration using decorators.

A fixture is a state holder for a lazily initialized value used across multiple tests. Fixtures allow you to define setup and tear-down logic for test data or resources.

Fixtures are created using the testFixture function, where the trailing lambda produces the value. The initialization can be a suspending block.

Creating a fixture

You can return an existing class instance or a custom object:

// Using an existing class
testFixture {
    Account(balance = 42.0)
}

// Using a custom object for multiple properties
testFixture {
    object {
        val initialBalance = 42.0
        val account = Account(balance = initialBalance)
    }
}

TestBalloon is production-ready, but users should expect potential migration issues as the public API evolves. From release 1.0 onwards, TestBalloon follows a strict three-step deprecation cycle for API changes:

1. Version n: The old API is marked with a deprecation WARNING.
2. Version n+1: The old API is marked with a deprecation ERROR.
3. Version n+2: The old API is removed.

For changes that provide source-compatible overloads, the old API will receive a HIDDEN deprecation immediately.

TestBalloon aims for:

• Functional stability: No unexpected or incompatible behavior changes.
• Source compatibility: Providing migration paths for necessary changes.
• Binary compatibility: Providing a stable binary API for extensions.

TestBalloon is designed to work within the existing Kotlin ecosystem:

• Assertion Libraries: Compatible with existing assertion libraries and Kotlin Power Assert.
• Build Tooling: Integrates with Gradle tasks and uses Kotlin's platform-specific test runtimes.
• Kotlin Versions: Remains compatible with all Kotlin releases since version 2.0.

TestBalloon uses a hierarchical model to organize tests, allowing for flexible grouping beyond simple class-based suites. The hierarchy is composed of:

• TestSession: The root of the hierarchy for an individual test run.
• TestSuite: A grouping element that contains child elements (other suites or tests). Suites cannot contain direct test logic.
• Test: An element containing the actual test logic and assertions. Tests cannot have child elements.
• TestElement: The base interface/type for all elements in the hierarchy.

This structure allows for deep nesting and complex organization of test sets.

TestBalloon organizes tests and suites into a test element hierarchy. Each element in this hierarchy (test, suite, compartment, or session) is assigned its own coroutine. The parent-child relationship between these coroutines mirrors the relationship between the test elements themselves, meaning coroutine contexts are inherited down the hierarchy.

This structure allows for structured testing where configuration and context flow from the top-level session down to individual tests.

Gradle uses the JUnit Platform API for test selection but applies its own restricted selection logic.

Selection Mechanisms

Gradle's Test task uses:

• ClassSelector: Gradle passes a selector for every class it finds (it does not know which are test classes beforehand).
• UniqueIdSelector: Used by Gradle Enterprise to distribute tests across processes.
• ClassNameFilter: Used when explicit test filtering is applied.

Known Limitations

Gradle's selection logic can be erratic and may fail to match patterns for certain JUnit 4/5 structures, such as:

• @Nested tests in JUnit 5.
• Parameterized tests in JUnit 4 or 5.

If patterns fail to match, it is often due to Gradle's internal TestSelectionMatcher assuming a restricted test structure.