To debug a single failing test in Kotlin with Atlas, run just that test through the bash tool using Gradle's filter flag, so the output is small enough to reason about instead of a full JUnit 5 report from every module. Atlas reads the test and the Kotlin code it exercises, uses the lsp tool's goToDefinition and findReferences operations to walk the call path, and only then edits. Because Atlas's bash is a real shell, the same debugging levers you would use by hand are all available: a focused JUnit 5 filter, temporary logging, a verbose Gradle flag. The goal is to fix the production code, not to weaken the assertion until it passes.
How do I run just one failing Kotlin test with Atlas?
Run the single failing test with Atlas's bash tool using Gradle's filter flag, for example ./gradlew test --tests 'com.example.billing.InvoiceServiceTest.appliesTaxForEuRegion'. Filtering matters in Kotlin because a bare gradle test on a multi-module build compiles and runs everything, and 4000 lines of output buries the one JUnit 5 assertion you care about.
Atlas runs the single test in isolation with bash so the failure is legible. Gradle's --tests filter takes a fully qualified name or a wildcard, and Atlas uses it rather than running the whole suite, because a smaller output is a better input to reasoning. Atlas's bash tool is a real shell, so the ordinary Kotlin levers are all available: add --info or --stacktrace for more detail, add -Dkotest or a JUnit 5 tag filter to narrow further, and pass --rerun-tasks when Gradle's up-to-date checks hide a genuine re-run. When output is very large, Atlas saves the full log to a file you can read, so a stack trace that scrolled past is still recoverable rather than lost.
How does Atlas trace why a Kotlin test fails instead of guessing?
Atlas reads the failing Kotlin test and the module it exercises, then uses the lsp tool's goToDefinition and findReferences operations to walk the call path. A JUnit 5 assertion failing on an expected 2026 value tells you the output is wrong; goToDefinition tells you which suspend function actually produced it.
Kotlin call paths are easy to lose track of, especially in coroutine-based code where a suspend function's real work happens inside a launched job or a flow operator several layers away from the callsite. Atlas's lsp tool goToDefinition operation jumps to the actual declaration, and findReferences enumerates every caller, so the path from the test's act step to the line that computed the wrong value is reconstructed rather than guessed. Atlas also indexes code by AST declarations using tree-sitter, not blind line windows, so a Kotlin file with several extension functions and a companion object is understood as structure. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, which finds the relevant Kotlin code even when the test's vocabulary and the implementation's vocabulary do not match.
How do I test a hypothesis about a failing Kotlin test?
Form a hypothesis and check it. Atlas adds temporary logging with the edit tool, or re-runs through bash with a verbose Gradle flag such as --info, then reads the result. Guessing at a Kotlin coroutine bug is expensive; one println at the right point in a flow collector settles it in a single 30-second gradle test run.
The hypothesis loop is the core of debugging, and Atlas runs it explicitly rather than trying to reason its way to an answer in one shot. Atlas edits in a temporary log line, re-runs the filtered ./gradlew test --tests command through bash, reads the output, and either confirms the hypothesis or discards it. Because bash is a real shell, verbose flags, environment variables, and JVM system properties are all available exactly as they are when you run them by hand. Atlas keeps track of the temporary instrumentation it added, and the final step of the workflow is removing it, so the diff you review at the end contains the fix and nothing else. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so ./gradlew test can be allowed while a publish task stays denied.
How does Atlas edit Kotlin production code safely during a fix?
Atlas fixes the production Kotlin code with edit, and when the change spans more than 1 hunk it uses apply_patch instead of chaining brittle edits. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so the change to src/main/kotlin/com/example/billing/InvoiceService.kt is reviewed first.
The single most common failure in test debugging is fixing the assertion instead of the code, and the second most common is a fix that quietly breaks a neighbor. Atlas guards the second with its edit model. A one-line change goes in with edit. A change that touches several hunks in the same Kotlin file goes in with apply_patch as one coherent patch, rather than a chain of edits where each one shifts the offsets the next one depends on. Atlas surfaces the unified diff before writing, and snapshots file changes as git patches so a wrong fix to a suspend function can be diffed and rolled back. Run ktlint on the changed Kotlin files afterwards so the fix matches project style.
How do I confirm a Kotlin test fix did not break anything else?
Atlas re-runs the single failing test first, then the full JUnit 5 suite via gradle test, and removes any temporary logging it added. In a Gradle multi-module Kotlin build, a fix in a shared :core module can break tests in :api and :worker that never mention the class you touched, and only a full ./gradlew test surfaces that.
Confirmation is a widening loop. Atlas re-runs the filtered ./gradlew test --tests command to prove the original JUnit 5 failure is gone, then runs the full gradle test across the Gradle build to catch collateral damage. Then Atlas removes the temporary logging it added, so the reviewed diff contains only the real fix. Run ktlint on every changed Kotlin file so the change conforms to the project's style before it reaches review. Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf, so the fix lands as a clean commit. If the fix turns out wrong later, Atlas snapshots file changes as git patches, so it can be rolled back without archaeology.
Step by step
- 01Run just the failing Kotlin test with the bash tool using Gradle's filter flag, for example ./gradlew test --tests 'com.example.billing.InvoiceServiceTest.appliesTaxForEuRegion', so the output is small enough to reason about.
- 02Read the failing test and the Kotlin module it exercises, then use the lsp tool's goToDefinition and findReferences operations to walk the call path through the suspend functions and flow operators involved.
- 03Form a hypothesis and check it: add temporary logging with edit, or re-run through bash with a verbose Gradle flag such as --info or --stacktrace.
- 04Fix the production Kotlin code with edit; if the change spans several hunks in the same file, use apply_patch instead of chaining brittle edits.
- 05Review the unified diff Atlas surfaces before it writes to src/main/kotlin, since Atlas computes a diff for every file edit and asks for approval.
- 06Re-run the single filtered test through bash to prove the JUnit 5 failure is gone, then run the full gradle test across every Gradle module.
- 07Remove any temporary logging you added, then run ktlint on the changed Kotlin files so the fix matches project style before you commit.
Frequently asked questions
- how to run a single failing test in kotlin with gradle
- Ask Atlas to run it through the bash tool with Gradle's filter flag, for example ./gradlew test --tests 'com.example.billing.InvoiceServiceTest.appliesTaxForEuRegion'. Filtering keeps the output small enough to reason about, instead of producing a full JUnit 5 report from every module in the Gradle build.
- how does atlas find why my kotlin coroutine test is failing
- Atlas reads the test and the Kotlin module it exercises, then uses the lsp tool's goToDefinition and findReferences operations to walk the call path into the suspend functions and flow operators where the real work happens, several layers away from the callsite the test touches.
- will atlas change my assertion to make a kotlin test pass
- The job is to find why one specific test fails and fix the code, not the assertion. Atlas walks the call path to the line that produced the wrong value and edits the production Kotlin, and every edit is surfaced as a unified diff for your approval before it is written.
- can atlas add temporary logging to debug a kotlin test
- Yes. Atlas adds temporary logging with edit, re-runs the filtered gradle test through bash, and reads the output. Because Atlas's bash is a real shell, verbose flags like --info and --stacktrace are also available. The final step removes the temporary logging so the reviewed diff contains only the fix.
- what is apply_patch and when does atlas use it instead of edit
- Atlas uses apply_patch when a Kotlin fix spans several hunks in the same file, because chaining individual edits means each one shifts the offsets the next depends on. apply_patch applies the change as one coherent patch, and Atlas surfaces the diff for approval before writing.
- does atlas run ktlint after fixing kotlin code
- Ask it to. After the test is green and temporary logging is removed, run ktlint on the changed Kotlin files so the fix matches project style. Formatting runs through the bash tool subject to your allow, ask, and deny permission rules.
- how do i stop atlas from running arbitrary gradle tasks
- Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs. Allow ./gradlew test and ktlint, put publishing or deployment Gradle tasks behind an ask prompt, and deny the rest. Atlas also drafts a plan in a read-only plan agent and asks before switching to a build agent.
- does atlas work with build.gradle.kts projects
- Yes. Run atlas in a project with a build.gradle.kts and let Atlas read your modules, coroutines, and Gradle configuration. Ask Atlas to convert callbacks to coroutines or add tests, and review the diff before it writes.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Debug a Single Failing Test with Atlas in 2026
How to debug one failing test with Atlas in 2026: run it in isolation with bash, walk the call graph with the lsp tool, and fix the code, not the assertion.
Atlas for Kotlin in 2026
In 2026, Atlas empowers Kotlin developers with terminal-native AI coding. It integrates with Gradle and coroutines, offering secure, privacy-focused code assistance with local embeddings and granular control.
Locate Where a Behavior Is Implemented in Kotlin with Atlas (2026)
Find the Kotlin file and symbol behind a behavior when you only know what the app does. Atlas attacks it in 2026 with codebase_search, grep, and the lsp tool.
Research a Third-Party API Before Integrating It in Kotlin With Atlas (2026)
How to research a third-party API before integrating it in Kotlin with Atlas in 2026: websearch finds the docs, webfetch pulls them, and every request is permissioned.
Rename a Symbol Across the Repo in Kotlin with Atlas (2026 Guide)
Rename a Kotlin class or function across every Gradle module with Atlas: lsp findReferences, grep, edit replaceAll, then JUnit 5 via gradle test and ktlint.
Run the test suite and triage the failures in Kotlin with Atlas (2026)
How Atlas runs a Kotlin test suite and triages failures in 2026: bash truncates at 2000 lines, retains the full log, and grep groups 60 red tests into distinct root causes.
Extract a Shared Helper from Duplicated Kotlin Code with Atlas in 2026
Streamline your Kotlin codebase in 2026 by extracting duplicated logic into a single, tested helper using Atlas. Leverage Gradle, JUnit 5, and ktlint for robust refactoring.
Plan a multi-file change before editing in Kotlin with Atlas (2026)
Plan a multi-file Kotlin change in 2026 before editing: Atlas's plan agent denies edit for every path except .atlas/plans/*.md, so build.gradle.kts stays untouched.