How to step through suspend function calls when debugging Kotlin coroutines

Question

How is it possible to debug Kotlin code when stepping into or out of a "suspend" function? (see example below).

fun mainFunction() = runBlocking {

    println("before suspend call")

    anotherFunction()

    println("after suspend call")
}

suspend fun anotherFunction() {
    // do something
}

I understand that Kotlin co-routines do a lot of magic when executing suspend functions and that the execution may switch threads at that moment. So when stepping out of "anotherFunction()" I only get to step through coroutine framework code and can't get back to the "mainFunction()".

However, I wonder if it is possible to debug this as if no co-routines were involved. Is there a tool or a library that enables this feature? Is it maybe on the roadmap for co-routine support?

A feature as simple as a compiler flag disabling co-routine magic would already go a long way, but I wasn't able to find anything.

The only useful thing I did find is: -ea JVM parameter also activates kotlin debug mode which will at least "fix" stack traces for exceptions.

Hello. In general, you're right - it is currently hard to debug coroutine code. We're actively working in this direction, for example in Kotlin 1.3.30 we shipped async stack traces support: blog.jetbrains.com/kotlin/2019/04/kotlin-1-3-30-released I failed to reproduce the problem in this particular example (Gradle project, IDEA 2019.2 EAP + Kotlin 1.3.40-eap-32): "step out" from anotherFunction goes straight to main. If it still doesn't work for you, please file an issue at kotl.in/issue with sample code to reproduce. Thanks. — Alexey Belkov

Abhijit Sarkar Abhijit Sarkar · Accepted Answer · 2020-08-07T20:47:40

This page shows some general techniques. In short, run with enabled assertions (-ea JVM flag).

kotlinx-coroutines-debug module is specifically designed for what its name says. This is how I use it in unit tests;

runBlocking {
    DebugProbes.install()
    val deferred = async { methodUnderTest() }
    delay(3000)
    DebugProbes.dumpCoroutines()
    println("\nDumping only deferred")
    DebugProbes.printJob(deferred)
    DebugProbes.uninstall()
    cleanup()
}

There's a JUnit4 rule to reduce the boilerplate, but you shouldn't be using JUnit4 in late 2020.

Also, Kotlin 1.4.0-RC and later has support for debugging Coroutines from inside the IDE, but just like everything new from JetBrains, I found it half-baked and not always showing suspended coroutines; kotlinx-coroutines-debug works better. https://blog.jetbrains.com/kotlin/2020/07/kotlin-1-4-rc-debugging-coroutines/

Edit Oct 2020:

I created a JUnit 5 Extension that can dump coroutines on timeout. https://github.com/asarkar/coroutines-test

How to step through suspend function calls when debugging Kotlin coroutines

2 Answers