kmp-test-runner

0.6.2 verified Fri May 01 auth: no javascript

Parallel test runner for Kotlin Multiplatform and Android Gradle projects. v0.6.2 is the current stable release, with frequent iterative releases (10+ versions since v0.3.7). Key differentiator: token-efficient output for AI coding agents — provides markdown-summarised stdout or single-line JSON envelopes, reducing token cost up to 1200× vs raw Gradle output. Supports parallel, coverage, changed, and benchmark test modes with summary JSON, parallel execution, and lockfile-based concurrent-invocation safety. Requires Node >=18 and a Gradle-based KMP or Android project.

Common errors

error Error: Cannot find module 'kmp-test-runner' ↓

cause Package not installed or global install missing.

fix

Run 'npm install -g kmp-test-runner' for CLI or 'npm install kmp-test-runner' for programmatic use.

error TypeError: runTests is not a function ↓

cause Default import instead of named import (ESM-only package).

fix

Use 'import { runTests } from "kmp-test-runner"'.

error [ERROR] No modules found matching filter: <pattern> ↓

cause Filter pattern does not match any test module, or module has no test source set.

fix

Check module names: use --list-modules to see available modules, adjust filter pattern.

error UnsupportedClassVersionError: class file version 65.0 ↓

cause Gradle toolchain requires a newer JDK (e.g., JDK 21 for class version 65.0) but runtime is older JDK.

fix

Install JDK 21+ or set GRADLE_HOME to a compatible JDK version. Use --no-fail-on-toolchain-mismatch to disable blocking error (v0.5.0+).

error Lockfile active: another kmp-test instance is running ↓

cause Another process holds the lockfile in same project root.

fix

Wait for other process to finish, or kill it. Use --force to override (risks output corruption).

Warnings

breaking v0.5.0 changed JDK toolchain mismatch from warning to blocking error by default. Projects with mismatched JDK versions will fail. ↓

fix Ensure Gradle JDK toolchain matches the runtime JDK, or use --no-fail-on-toolchain-mismatch flag.

gotcha Concurrent-invocation lockfile v0.3.8+ prevents multiple kmp-test runs on same project root. Second arrival refuses to run if first PID is alive. ↓

fix Use --force flag to bypass lockfile (careful: may corrupt output) or wait for first run to finish.

gotcha v0.5.2 build-logic coverage detection may false-positive on convention plugin names (e.g., 'androidApplicationJacoco'). ↓

fix Check build-logic files for unintended coverage signals. Consider --no-detect-build-logic-coverage.

deprecated v0.4.1 deprecated the old CLI flag --no-summary in favor of --json. --no-summary still works but will be removed in 1.0. ↓

fix Replace --no-summary with --json.

breaking v0.6.0 changed detectBuildLogicCoverageHints output format: now distinguishes CONVENTION vs SELF kover/jacoco signals. Custom consumers may break. ↓

fix Update consumer code to handle objects with property 'source' ('convention' or 'self').

gotcha --dry-run flag exits 0 without running tests, but under --json it outputs a dry_run: true envelope with all-zero counts. Agents expecting real test data will misinterpret. ↓

fix Check dry_run field before consuming test counts.

Install

npm install kmp-test-runner

yarn add kmp-test-runner

pnpm add kmp-test-runner

Imports

createTestRunner

wrong

const createTestRunner = require('kmp-test-runner')

correct

import { createTestRunner } from 'kmp-test-runner'

ESM-only package since v0.3.0. CommonJS require will fail.

runTests

wrong

import kmpTestRunner from 'kmp-test-runner'

correct

import { runTests } from 'kmp-test-runner'

Named export, not default.

parseScriptOutput

wrong

import { parse_script_output } from 'kmp-test-runner'

correct

import { parseScriptOutput } from 'kmp-test-runner'

CamelCase name. Underscore variants will not resolve.

Quickstart

Shows how to programmatically run parallel and coverage tests with JSON output, handling errors and test counts.

import { runTests } from 'kmp-test-runner';

const result = await runTests({
  projectRoot: process.cwd(),
  features: ['parallel', 'coverage'],
  json: true
});

if (result.exitCode !== 0) {
  console.error('Tests failed:', result.errors);
} else {
  console.log('Passed:', result.tests.passed, 'Failed:', result.tests.failed);
}