DEV Community: Aniket Bhattacharyea

Spring Boot Integration Tests Are Slow and Messy: Here's How to Fix Them

Aniket Bhattacharyea — Wed, 21 Oct 2026 16:49:16 +0000

Integration test suites can get slow without anyone deciding they should. Another @SpringBootTest here, some in-memory H2 wiring there, a flaky test "fixed" with a stray @DirtiesContext – and eventually the suite is the thing everyone quietly dreads before merging a PR, flaky on every other CI run, with nobody able to point to the one change that caused it.

Spring Boot integration tests do real work, validating behavior across controllers, services, repositories, databases, and messaging systems. That breadth is what makes them valuable, and it's also what makes them expensive. When you wire together a real application context, connect to databases, and exercise multiple layers in a single test run, costs add up fast. The question is whether those costs are unavoidable or whether your test suite pays for things it doesn't need.

This article walks through the specific mechanisms that make Spring Boot integration suites slow and brittle, and the practical strategies that address them. You'll also see how Kotlin's extension functions, DSLs, data classes, named arguments, and scope functions reduce the boilerplate that accumulates in integration test code over time, making the resulting suite easier to maintain regardless of the language you're already using.

Why Spring Boot integration tests slow down over time

Most suites start with a single @SpringBootTest class and a handful of tests. That first test class is harmless. The problems compound when a second developer adds another @SpringBootTest with a slightly different configuration, a third adds @ActiveProfiles("integration") to one class and @ActiveProfiles("test") to another, and a fourth drops a @DirtiesContext on a test that was flaky. Six months later, the suite boots five or six separate application contexts across a single run, and nobody realizes it.

Before you optimize anything, profile the actual bottleneck. Spring Boot's context initialization is usually the dominant cost, but database container startup and heavyweight test setup can be significant too. Run your tests with -Dspring.test.context.cache.maxSize=10 alongside JUnit's --report-dir output to see how many contexts are being created. If you see more than two or three distinct contexts in a moderate-sized suite, context proliferation is your problem.

Nearly every fix in this article reduces to a single idea: repeated initialization is the thing you're paying for, not the tests themselves. Whether that initialization is a Spring application context, a database container, or heavyweight test data, the fastest fix is almost always to do it once and reuse it rather than make each instance cheaper.

Keep the number of Spring application contexts small

@SpringBootTest loads your full application context, all beans, all configuration, all auto-configuration. For a non-trivial Spring Boot application, that initialization can take several seconds. The Spring TestContext Framework caches loaded contexts and reuses them across compatible tests, so the first test in a group pays the startup cost and subsequent tests don't.

The cache key is a composite of everything that affects the context, including configuration classes, active profiles, property sources, and context customizers. Change any of these between two test classes and Spring boots a second context. Common cache-busting patterns include using different @ActiveProfiles values across test classes, importing different @TestConfiguration classes with incompatible beans, and overusing @DirtiesContext.

@DirtiesContext signals that a test has modified the application context and that Spring should discard it. Using it broadly because a single test is flaky trades a flakiness problem for a performance problem. The test that genuinely modifies shared mutable state may warrant it, but the test that just needs a clean database table doesn't.

The practical target is a single shared context for your full integration tests, achieved by keeping configuration consistent. A shared base class or a single shared @TestConfiguration import applied consistently across test classes is the most reliable way to ensure the cache key matches. In Kotlin, the recommended approach combines constructor injection with @TestConstructor(autowireMode = TestConstructor.AutowireMode.ALL), which avoids lateinit vars and keeps test fields immutable:

@SpringBootTest
@TestConstructor(autowireMode = TestConstructor.AutowireMode.ALL)
class OrderServiceIntegrationTest(
    private val orderService: OrderService,
    private val orderRepository: OrderRepository
) {

    @Test
    fun `placing an order persists it to the database`() {
        val order = orderService.place(OrderRequest(productId = "p-42", quantity = 3))
        val saved = orderRepository.findById(order.id)
        assert(saved.isPresent)
    }
}

The Kotlin plugin.spring compiler plugin automatically opens Spring-annotated classes, resolving the friction Kotlin's default final classes would otherwise cause with Spring's proxying, so no additional configuration is needed for this to work correctly.

None of this means avoiding @SpringBootTest. A full application context is the right tool whenever a test genuinely needs to exercise behavior that spans multiple layers, for example, an HTTP request that flows through a controller, a service, and a repository. The goal isn't eliminating full-context tests; it's making sure you're not accidentally paying the full-context startup cost two, three, or five times over in a single suite when one shared context would do.

Test slices selectively, not as a default performance fix

Spring Boot's test slices (@WebMvcTest, @DataJpaTest, @JdbcTest, @JsonTest, @RestClientTest) load only the portion of your application relevant to a specific concern. A @DataJpaTest context contains JPA repositories and the JPA layer, nothing else. A @WebMvcTest context contains MVC infrastructure without starting a full servlet container.

Slices are useful when a test genuinely exercises only one layer. A repository test that validates a complex JPQL query doesn't need your HTTP layer. A controller test that validates request validation logic doesn't need your database. For those cases, a slice gives you a faster, more focused test.

The trap is treating slices as a general performance fix. Each distinct slice configuration that differs from another creates its own application context. A suite with ten @DataJpaTest classes using the same configuration shares one context. A suite with five different slice types, each loaded with different imports, creates five separate contexts, and the cumulative startup cost can exceed that of a single, well-shared full context.

Use a slice when it provides a meaningful testing boundary for the layer under test. For tests that validate behavior spanning multiple layers, prioritize reusing a small number of shared full contexts over reaching for a narrower slice.

Use Testcontainers without repeatedly starting containers

H2 is a convenient in-memory database for local testing, but it doesn't behave like PostgreSQL or MySQL in ways that affect production correctness. PostgreSQL enforces stricter type checking, so implicit casts that H2 accepts silently will fail at runtime against Postgres. Indexing semantics differ, and constraint enforcement, particularly around deferred constraints and transaction isolation, behaves differently. A green test suite against H2 can mask bugs that surface only under the production database engine.

Testcontainers solves this by running your actual database engine in a Docker container during tests. The startup cost is real (a PostgreSQL container cold-start typically takes a few seconds), but you pay it once per suite, not once per test class.

With Spring Boot 3.1+, the @ServiceConnection annotation eliminates the boilerplate of manually wiring container ports into Spring's datasource configuration, and it's unchanged under Spring Boot 4. Declare the container in a shared @TestConfiguration class and import it wherever needed:

@TestConfiguration(proxyBeanMethods = false)
class TestcontainersConfiguration {

    @Bean
    @ServiceConnection
    fun postgresContainer(): PostgreSQLContainer<*> =
        PostgreSQLContainer("postgres:17-alpine")
}

For @DataJpaTest slices, Spring attempts to replace your datasource with an embedded database by default. Suppress that behavior with @AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE) and import your shared container configuration:

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Import(TestcontainersConfiguration::class)
class BookmarkRepositoryTest @Autowired constructor(
    private val bookmarkRepository: BookmarkRepository
) {

    @Test
    fun `should find bookmark by id`() {
        val bookmark = bookmarkRepository.save(
            Bookmark(title = "Kotlin Docs", url = "https://kotlinlang.org")
        )
        val found = bookmarkRepository.findById(bookmark.id!!)
        assertThat(found).isPresent
        assertThat(found.get().title).isEqualTo("Kotlin Docs")
    }
}

Two dependency details are worth getting right here if you're on Spring Boot 4. First, @DataJpaTest itself now lives in spring-boot-data-jpa-test, pulled in via the spring-boot-starter-data-jpa-test starter, not the plain spring-boot-starter-test. Second, @AutoConfigureTestDatabase moved too: it's now org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase, shipped in a separate spring-boot-starter-jdbc-test starter that spring-boot-starter-data-jpa-test doesn't pull in automatically, so you need to add it explicitly:

testImplementation("org.springframework.boot:spring-boot-starter-data-jpa-test")
testImplementation("org.springframework.boot:spring-boot-starter-jdbc-test")
testImplementation("org.springframework.boot:spring-boot-testcontainers")
testImplementation("org.testcontainers:junit-jupiter")
testImplementation("org.testcontainers:postgresql")

@ServiceConnection itself, by contrast, didn't move; it's still org.springframework.boot.testcontainers.service.connection.ServiceConnection on Spring Boot 4. Not everything in the test-support space was reshuffled, just the test-slice annotations and the autoconfiguration classes that back them.

If you prefer declaring the container directly in the test class, Kotlin's companion objects with @JvmStatic ensure the container lifecycle spans all methods in the class rather than restarting for each test:

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
class OrderRepositoryTest {

    companion object {
        @Container
        @ServiceConnection
        @JvmStatic
        val postgres = PostgreSQLContainer("postgres:17-alpine").apply {
            withDatabaseName("testdb")
        }
    }

    @Autowired
    private lateinit var orderRepository: OrderRepository

    @Test
    fun `should save and retrieve an order`() {
        // test body
    }
}

The goal is to combine a reused container with a reused Spring context. When your test configuration is consistent, Spring's cache keeps the same context alive across all test classes that share the same container configuration, and the database container itself stays running for the duration of the build.

For database state, build only what each test actually needs. A test that validates order retrieval doesn't need a populated product catalog. Lightweight, targeted setup with @BeforeEach and @AfterEach cleanup (or transaction rollback via @Transactional) keeps tests isolated without requiring full database resets between every run.

A practical strategy for a fast integration test suite

The context sharing model below keeps a suite fast by mapping each test type to its context and container lifecycle:

The diagram below is the editable Mermaid source — useful if you want to adjust colors or labels. A rendered image follows it.

flowchart TD
    A[Full Integration Tests<br/>@SpringBootTest + Testcontainers] --> B[Single shared<br/>Spring context]
    C[Slice Tests<br/>@DataJpaTest etc.] --> D[Shared slice<br/>context per type]
    E[Unit Tests] --> F[No Spring context]
    B --> G[Postgres container<br/>started once]
    D --> G

The strategy has seven parts:

Keep one @TestConfiguration class that declares your Testcontainers beans with @ServiceConnection and import it consistently across all tests that need it.
Align profiles. If some test classes use @ActiveProfiles("test") and others don't declare a profile at all, Spring treats them as different configurations and creates separate contexts.
Reserve @DirtiesContext for tests that genuinely modify application-level state, not for tests with database state issues. Database state cleanup belongs in @AfterEach or via transactional rollback.
Reach for a test slice only when the test's meaningful scope is genuinely limited to that layer. A repository test for a complex query is a good slice candidate. A test that exercises an HTTP endpoint through to the database is not.
Start containers once and reuse them. Use withReuse(true) on your container definition to persist containers across JVM runs during local development, where it cuts iteration time substantially.
Build only the database state each test actually needs. Seeding a full product catalog for a test that only checks order retrieval adds setup cost without adding coverage.
Measure before and after changes. Run the test suite twice and enable DEBUG-level logging on org.springframework.test.context.cache (or equivalent context cache reporting) to confirm that context creation counts dropped and wall-clock time improved.

Make integration tests readable with Kotlin

Kotlin reduces the boilerplate that accumulates around integration tests, meaning less noise when a test fails and less maintenance when fixtures change. The techniques below don't make a suite faster on their own; they make an already-fast suite easier to read and maintain, which is what keeps it fast six months from now instead of sliding back into the state this article opened with.

Data classes eliminate the Java builder pattern for test fixtures. A Bookmark data class with sensible defaults can be constructed with a single named argument for the one field a specific test cares about:

data class BookmarkFixture(
    val title: String = "Default Title",
    val url: String = "https://kotlinlang.org",
    val isActive: Boolean = true
)

Named arguments make test data construction self-documenting. BookmarkFixture(title = "Archived Post", isActive = false) is readable without a builder chain.

Extension functions let you add setup utilities or assertion helpers directly to Spring test classes without inheritance hierarchies. A setup helper for building a JSON POST request:

fun MockMvc.postJson(url: String, payload: Any, objectMapper: ObjectMapper): ResultActionsDsl =
    post(url) {
        contentType = MediaType.APPLICATION_JSON
        content = objectMapper.writeValueAsString(payload)
        accept = MediaType.APPLICATION_JSON
    }

If you're on Spring Boot 4, the ObjectMapper import above is worth double-checking. Spring Boot 4 defaults to Jackson 3, pulled in through a new spring-boot-starter-jackson module, and Jackson 3's base package moved from com.fasterxml.jackson to tools.jackson, so the type you inject here is tools.jackson.databind.ObjectMapper, not the Jackson 2 class of the same simple name. If you're posting a Kotlin data class as the request body, also add tools.jackson.module:jackson-module-kotlin (the Jackson 3 equivalent of the familiar jackson-module-kotlin) as a dependency. Without it, Jackson can't resolve the data class's primary-constructor parameters, and the request fails with a 400 instead of a compile error, making it easy to lose an afternoon to.

And an assertion helper, scoped to the type it asserts on rather than to a test class:

fun Bookmark.assertIsActiveWithTitle(expectedTitle: String) {
    assertTrue(isActive)
    assertEquals(expectedTitle, title)
}

Kotlin DSLs built on extension functions and lambdas-with-receivers are what make the postJson helper above readable in the first place: post(url) { contentType = ...; content = ... } reads as configuration, not as a chain of setter calls. Spring's own MockMvc Kotlin DSL (post, get, .andExpect { status { isCreated() } }) follows the same pattern, and it's worth reaching for directly rather than only through a wrapping extension function when a test doesn't need one.

Scope functions (apply, also, run) clean up construction and setup code at the declaration site without extracting helper methods. apply is the one you'll reach for most, configuring an object and returning it, as in the companion-object container declaration from the Testcontainers section:

@JvmStatic
val postgres = PostgreSQLContainer("postgres:17-alpine").apply {
    withDatabaseName("testdb")
    withUsername("test")
    withPassword("test")
}

also is useful when you want to do something with a value, like logging it, without changing what gets returned, and run is useful for computing a value inline from a short block instead of a separate val statement:

val fixture = BookmarkFixture(title = "Kotlin Docs").also {
    println("creating bookmark fixture: ${it.title}")
}
val request = run {
    BookmarkRequest(title = fixture.title, url = fixture.url, isActive = fixture.isActive)
}

Put together, a small integration test combining a fixture, the postJson extension function, and a scope function reads as a short, flat sequence of steps rather than a wall of setup:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK)
@AutoConfigureMockMvc
@Import(TestcontainersConfiguration::class)
@TestConstructor(autowireMode = TestConstructor.AutowireMode.ALL)
class BookmarkControllerIntegrationTest(
    private val mockMvc: MockMvc,
    private val objectMapper: ObjectMapper
) {

    @Test
    fun `creating a bookmark returns it in the response`() {
        val fixture = BookmarkFixture(title = "Kotlin Docs").also {
            println("creating bookmark fixture: ${it.title}")
        }
        val request = run { BookmarkRequest(title = fixture.title, url = fixture.url, isActive = fixture.isActive) }

        mockMvc.postJson("/api/bookmarks", request, objectMapper)
            .andExpect { status { isCreated() } }
    }
}

Note that @AutoConfigureMockMvc moved packages in Spring Boot 4 too, same as @WebMvcTest: it's org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc now, shipped in spring-boot-webmvc-test via the spring-boot-starter-webmvc-test starter.

These are incremental improvements, not architectural changes. You can introduce Kotlin test code into an existing Java Spring project without touching production code, which makes it a low-risk starting point for teams evaluating what Kotlin brings to their codebase.

Organize integration tests for long-term maintainability

A suite that's fast today becomes slow again if there's no shared understanding of its structure. Keep three distinct categories separate: unit tests (no Spring context, run fast), slice tests (partial context, targeted), and full integration tests (full context, shared container). Mixing these in the same test source set makes it difficult to see at a glance why a build is slow. Consistent naming helps here too; a suffix convention like *Test for units and slices versus *IntegrationTest for full-context tests, or separate source directories, lets you tell at a glance (and in CI timing reports) which category is growing.

Integration tests should assert on business behavior, not implementation details. A test that verifies the correct HTTP status code and response body when a user places an order is durable. A test that verifies the exact SQL statement executed against the database is brittle and couples the test to an implementation that can change without breaking the business requirement.

Avoid duplicating setup logic across test classes just because it's easier than sharing it. A second @TestConfiguration import that's nearly identical to an existing one is exactly the kind of inconsistency that busts the context cache described earlier, so the maintainability concern and the performance concern point to the same fix.

Shared base classes are worth using when they genuinely simplify the suite, typically for consistent annotation setup and shared infrastructure, and worth avoiding when they become a dumping ground for setup logic that only some tests need. A shared annotations file (using Kotlin's @Target(AnnotationTarget.CLASS) composed annotations) is often cleaner:

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
@SpringBootTest
@Import(TestcontainersConfiguration::class)
@TestConstructor(autowireMode = TestConstructor.AutowireMode.ALL)
annotation class IntegrationTest

Any @SpringBootTest class that uses @IntegrationTest instead gets a consistent cache key by definition, because the annotation composition is identical.

Treat test suite performance as an ongoing metric. Add context creation count and total suite duration to your CI output so regressions are visible before they compound. A suite that takes four minutes today will take twenty-two again in six months if nobody is watching the cost.

The fixes that move the needle on Spring Boot integration test performance share a common thread: reducing repeated initialization. Keep your Spring application contexts few and consistent so the cache does its job. Start Testcontainers infrastructure once and keep it alive across the test run. Use test slices when they define a genuine testing boundary, and avoid them when the goal is just a smaller context. Measure before and after so you know which bottleneck you actually solved.

Kotlin's language features sit naturally on top of this foundation. Data classes, extension functions, DSLs, named arguments, and scope functions cut boilerplate without changing how Spring tests work, making them a practical addition to a Java Spring project even before you change any production code. The formal partnership between JetBrains and Spring reflects this kind of incremental integration, with Kotlin as a natural evolution of the JVM development experience that complements your existing ecosystem. For a sense of what that looks like at scale, Verifone's architect discussed running Kotlin in mission-critical payment systems at KotlinConf, where reliability requirements are just as unforgiving as anything a slow test suite is standing in for.

JUnit 6 Parameterized Tests: The Complete Guide to Data-Driven Testing on the JVM

Aniket Bhattacharyea — Wed, 21 Oct 2026 16:44:55 +0000

Writing the same test five times with different inputs is copying, not testing. Parameterized testing breaks that habit by letting you write a single assertion once and run it against as many datasets as the problem demands. JUnit 6 (the Jupiter framework) gives you a rich set of argument sources, clean display names, and enough flexibility to handle everything from a handful of strings to deeply nested domain objects.

For developers building Spring Boot services, getting good at parameterized testing pays compound interest. Service layer logic, validation rules, pricing calculations, and repository queries all share the same structure: given some input, expect some output. Parameterized tests make that pattern explicit and give you a test suite that grows with your domain model.

Most developers run into friction with complex inputs: DTOs, entity objects, configuration records, and the boilerplate required to construct them in Java.

This guide walks through every major parameter source in JUnit 6, shows when and why to reach for each one, covers the specific patterns that surface in Spring Boot test suites across every layer (service, controller, repository, and configuration), and then demonstrates how Kotlin's data classes and named arguments cut test setup code without touching a single line of production Java.

What parameterized tests are

A parameterized test is a test method that JUnit runs multiple times, injecting a different set of arguments on each invocation. You write the assertion logic once, and the framework handles the loop. Each invocation is tracked, named, and reported independently in the test runner, so a failure on input three doesn't mask a pass on input five.

The key annotation is @ParameterizedTest, which replaces @Test. You pair it with a source annotation that tells JUnit where to pull argument values from. JUnit 6 ships with sources for inline values, CSV rows, CSV files, factory methods, and pluggable providers, each suited to a different complexity tier.

Setup for parameterized tests

Required dependencies

If you're starting from a Spring Boot project, spring-boot-starter-test already pulls in the JUnit Jupiter engine. You need to add junit-jupiter-params explicitly if it's not coming in transitively from your BOM.

JUnit 6 raises the minimum Java version to 17 (JUnit 5 only required 8), and if you're writing tests in Kotlin, you'll need Kotlin 2.2 or newer. Spring Boot 4.x already baselines on Java 17 and manages compatible JUnit and Kotlin versions for you, so the simplest path is to build on Spring Boot 4.

Gradle (Kotlin DSL):

plugins {
    id("org.springframework.boot") version "4.1.1"
    id("io.spring.dependency-management") version "1.1.7"
    kotlin("jvm") version "2.3.21"
    kotlin("plugin.spring") version "2.3.21"
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testImplementation("org.junit.jupiter:junit-jupiter-params")
}

tasks.withType<Test> {
    useJUnitPlatform()
}

For Maven, add junit-jupiter-params with test scope alongside spring-boot-starter-test.

IDE support

IntelliJ IDEA renders each parameterized invocation as a child node in the Run tool window, using whatever display name you configure. It warns you at edit time if you declare @ParameterizedTest without a source, highlights type mismatches between the source and the method signature, and excludes @MethodSource provider methods from "unused declaration" warnings. The gutter run icon lets you execute the entire parameterized suite or rerun only the specific invocations that failed.

Running tests in Maven and Gradle

Both build tools need useJUnitPlatform() (Gradle) or the maven-surefire-plugin configured for JUnit Platform to pick up Jupiter tests. Without this, parameterized tests either skip silently or report as errors rather than test failures.

One JUnit 6 constraint worth knowing up front: Maven Surefire and Failsafe versions older than 3.0.0 are no longer supported. If your pom.xml pins an older plugin version, bump it, or parameterized tests may not execute under the JUnit Platform at all.

Display names

@ParameterizedTest accepts a name attribute. The placeholders {index}, {0}, {1}, and {arguments} let you build readable names from the supplied values:

@ParameterizedTest(name = "[{index}] discount for {0} loyalty years = {1}%")

The test runner displays something like [3] discount for 5 loyalty years = 10%, which makes failures self-explanatory without opening the test body.

Using @ValueSource

@ValueSource supplies a single array of literals (strings, ints, longs, doubles, or class references) and is the right choice when your test needs one argument per invocation and the values are small enough to inline.

@ParameterizedTest
@ValueSource(strings = {"radar", "level", "kayak"})
void isPalindrome(String word) {
    assertTrue(IsPalindromeChecker.check(word));
}

When your data grows beyond three or four values, or when you need more than one argument per invocation, move to @CsvSource or @MethodSource.

Using @NullSource, @EmptySource, and @NullAndEmptySource

These three annotations inject edge-case inputs for null and empty states. They're most useful on service methods and validators that need to handle blank input gracefully.

@ParameterizedTest
@NullAndEmptySource
@ValueSource(strings = {" ", "\t", "\n"})
void rejectsBlankUsername(String username) {
    assertThrows(InvalidInputException.class,
        () -> userService.register(username, "valid@example.com"));
}

Combining @NullAndEmptySource with @ValueSource on the same method covers null, empty string, and whitespace-only inputs in one test method. JUnit 6 supports stacking these annotations.

One interop detail matters if the method under test is written in Kotlin: a Kotlin function with a non-nullable parameter (fun register(username: String, ...)) compiles a null-check at the start of the method body. Feed it a literal null from @NullSource, and you get a bare NullPointerException before your own validation logic ever runs — not the InvalidInputException the test expects. Declare the parameter as nullable (username: String?) and check it with username.isNullOrBlank() if you want @NullAndEmptySource to exercise your validation path rather than Kotlin's own null-check.

Using @CsvSource

@CsvSource supplies multiple arguments per invocation as comma-separated rows defined inline. Use it when you need two or three related values, and you want to keep the data close to the test:

@ParameterizedTest(name = "{0} + {1} = {2}")
@CsvSource({
    "1, 2, 3",
    "5, 5, 10",
    "-1, 1, 0",
    "100, -100, 0"
})
void addsCorrectly(int a, int b, int expected) {
    assertEquals(expected, calculator.add(a, b));
}

JUnit handles type conversion automatically, so the string "3" becomes the int 3 without any adapter code. For values that contain commas, wrap the field in single quotes, as in "'Smith, John', john@example.com, 30".

Under the hood, JUnit 6 replaced the CSV parser (it now uses FastCSV instead of univocity-parsers), and a few edge cases around quoting changed as a result — extra characters after a closing quote now throw instead of being silently ignored, for example. The common case above, including quoted fields containing commas, parses exactly the same as it did under JUnit 5.

@CsvSource starts to strain when you have more than six or seven rows, when values are long, or when you're reusing the same dataset across multiple test classes. At that point, use @CsvFileSource.

Loading test data with @CsvFileSource

@CsvFileSource reads rows from a file on the classpath:

@ParameterizedTest
@CsvFileSource(resources = "/test-data/pricing-scenarios.csv", numLinesToSkip = 1)
void calculatesPriceCorrectly(String tier, int loyaltyYears, boolean isVip, String expectedPrice) {
    // assertions
}

The numLinesToSkip = 1 skips the header row. The file sits under src/test/resources. Reach for this approach when your test dataset is large enough to be maintained separately, when it's shared with non-Java stakeholders (QA, product), or when it's generated by another tool.

Creating dynamic test data with @MethodSource

@MethodSource delegates to a factory method that returns a Stream<Arguments>, a List, or an Iterable. It's the right choice for complex objects, computed values, and any scenario where inline CSV can't express your data structure.

@ParameterizedTest(name = "{index}: {0}")
@MethodSource("pricingScenarios")
void calculatesPriceForAllTiers(PricingScenario scenario) {
    DiscountResult result = pricingService.calculate(scenario.input());
    assertEquals(scenario.expected(), result);
}

static Stream<Arguments> pricingScenarios() {
    return Stream.of(
        Arguments.of(new PricingScenario(
            "VIP with 5 loyalty years",
            new DiscountInput(new BigDecimal("200.00"), 5, true),
            new DiscountResult(new BigDecimal("150.00"), 25)
        )),
        Arguments.of(new PricingScenario(
            "Standard user, no discount",
            new DiscountInput(new BigDecimal("100.00"), 0, false),
            new DiscountResult(new BigDecimal("100.00"), 0)
        ))
    );
}

The factory method must be static by default because JUnit instantiates a new test class per invocation under the default PER_METHOD lifecycle. You can lift that restriction with @TestInstance(TestInstance.Lifecycle.PER_CLASS), which becomes particularly useful in Kotlin (covered in a later section).

Supplying data with a custom ArgumentsProvider

When you want to share a dataset across multiple test classes, or load data from an external source at runtime, implement ArgumentsProvider:

public class DiscountScenariosProvider implements ArgumentsProvider {
    @Override
    public Stream<? extends Arguments> provideArguments(ParameterDeclarations parameters, ExtensionContext context) {
        return Stream.of(
            Arguments.of(new DiscountInput(new BigDecimal("100.00"), 5, false),
                new DiscountResult(new BigDecimal("90.00"), 10)),
            Arguments.of(new DiscountInput(new BigDecimal("200.00"), 0, true),
                new DiscountResult(new BigDecimal("170.00"), 15))
        );
    }
}

Then reference it with @ArgumentsSource(DiscountScenariosProvider.class). The provider has access to the ExtensionContext, which means it can read annotations on the test class, inspect the test method name, or pull configuration from the JUnit store. That access is useful when you want a single provider to behave differently across different test contexts.

Note the two-argument provideArguments(ParameterDeclarations, ExtensionContext) signature above. The older single-argument provideArguments(ExtensionContext) still compiles and runs under JUnit 6, but it's deprecated — the compiler will flag it, and new providers should use the two-argument form.

Testing complex objects

Passing plain primitives through @CsvSource works until you need to test against DTOs, entity objects, or configuration objects. At that point, use @MethodSource or a custom ArgumentsProvider and construct your objects directly in the factory method.

DTOs. For a Spring Boot user registration endpoint, a validation test might look like this:

@ParameterizedTest(name = "{index}: {0}")
@MethodSource("invalidRegistrationRequests")
void rejectsInvalidRequests(String scenario, UserRegistrationRequest request, int expectedViolations) {
    Set<ConstraintViolation<UserRegistrationRequest>> violations = validator.validate(request);
    assertEquals(expectedViolations, violations.size(), scenario);
}

static Stream<Arguments> invalidRegistrationRequests() {
    return Stream.of(
        Arguments.of("blank username",
            new UserRegistrationRequest("", "valid@example.com", 25), 1),
        Arguments.of("invalid email",
            new UserRegistrationRequest("alice", "not-an-email", 25), 1),
        Arguments.of("negative age",
            new UserRegistrationRequest("bob", "bob@example.com", -1), 1),
        Arguments.of("blank username and invalid email",
            new UserRegistrationRequest("", "not-an-email", 25), 2)
    );
}

The scenario string argument doubles as a display name fragment and as an assertion message, so a failure tells you exactly which case broke without making you decode an index number.

Entity objects. The same pattern applies directly to JPA entities — construct them in the factory method and assert against their behavior:

@ParameterizedTest(name = "{index}: {0} matches category {1}? {2}")
@MethodSource("productsByCategory")
void filtersProductsByCategory(Product product, String category, boolean expectedMatch) {
    assertEquals(expectedMatch, product.getCategory().equals(category));
}

static Stream<Arguments> productsByCategory() {
    return Stream.of(
        Arguments.of(new Product("Laptop", "ELECTRONICS", new BigDecimal("999.00")), "ELECTRONICS", true),
        Arguments.of(new Product("Laptop", "ELECTRONICS", new BigDecimal("999.00")), "BOOKS", false)
    );
}

Configuration objects. Configuration-bound objects can be constructed directly too, which is useful for testing the logic that consumes them without spinning up a Spring context:

@ParameterizedTest(name = "{index}: enabled={0}, cap={1} -> bonus={2}")
@MethodSource("pricingConfigurations")
void loyaltyBonusRespectsConfiguration(boolean enabled, int cap, int expectedBonus) {
    PricingProperties properties = new PricingProperties(enabled, cap);
    int bonus = properties.isLoyaltyBonusEnabled() ? properties.getLoyaltyBonusCap() : 0;
    assertEquals(expectedBonus, bonus);
}

static Stream<Arguments> pricingConfigurations() {
    return Stream.of(
        Arguments.of(true, 10, 10),
        Arguments.of(true, 5, 5),
        Arguments.of(false, 10, 0)
    );
}

This verifies the logic that reads a configuration object in isolation. When you need to verify that Spring actually binds your application.properties values into that object correctly, that's a job for @SpringBootTest or ApplicationContextRunner, covered next.

Parameterized testing in Spring Boot

Combining @ParameterizedTest with Spring test slice annotations gives you data-driven coverage across every layer of a Spring Boot application.

Service layer tests run with plain constructor instantiation or with @SpringBootTest and @Autowired constructor injection:

@SpringBootTest
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class PricingServiceTest {

    @Autowired
    private PricingService pricingService;

    @ParameterizedTest
    @MethodSource("pricingCases")
    void calculatesPriceCorrectly(DiscountInput input, DiscountResult expected) {
        assertEquals(expected, pricingService.calculate(input));
    }

    Stream<Arguments> pricingCases() {
        return Stream.of(
            Arguments.of(new DiscountInput(BigDecimal.valueOf(100), 5, false),
                new DiscountResult(BigDecimal.valueOf(90).setScale(2), 10))
        );
    }
}

Validation tests follow the pattern shown earlier, building a jakarta.validation.Validator directly (no Spring context required) and running each invalid payload through it.

Before wiring up controller or repository tests, there's a dependency change worth knowing about: Spring Boot 4 split its test-support autoconfiguration into per-feature modules. spring-boot-starter-test alone no longer pulls in @WebMvcTest or @DataJpaTest — each needs its own starter:

testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
testImplementation("org.springframework.boot:spring-boot-starter-data-jpa-test")

The annotations also moved packages. @WebMvcTest is now org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest, and @DataJpaTest is org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest. Spring Boot's own @MockBean was removed in the same release — use Spring Framework's @MockitoBean (org.springframework.test.context.bean.override.mockito.MockitoBean) in its place.

Controller tests with @WebMvcTest and MockMvc work naturally with @CsvSource or @MethodSource. You build the request body, fire it through mockMvc.perform(), and assert the response status per invocation:

@WebMvcTest(UserController.class)
class UserControllerParameterizedTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private UserService userService;

    @ParameterizedTest(name = "{index}: {0}/{1} -> {2}")
    @CsvSource({
        "alice, valid@example.com, 201",
        "'', valid@example.com, 400",
        "bob, not-an-email, 400"
    })
    void registersUser(String username, String email, int expectedStatus) throws Exception {
        mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content("""
                    {"username": "%s", "email": "%s", "age": 30}
                    """.formatted(username, email)))
            .andExpect(status().is(expectedStatus));
    }
}

Repository tests with @DataJpaTest can drive @ParameterizedTest to verify query correctness across different filter combinations (entity status enums, date ranges, or tier codes) without repeating setup for each case:

@DataJpaTest
class ProductRepositoryTest {

    @Autowired
    private ProductRepository productRepository;

    @ParameterizedTest(name = "{index}: {0} has {1} product(s)")
    @MethodSource("categoryExpectations")
    void countsProductsByCategory(String category, long expectedCount) {
        productRepository.save(new Product("Laptop", "ELECTRONICS", new BigDecimal("999.00")));
        productRepository.save(new Product("Monitor", "ELECTRONICS", new BigDecimal("199.00")));
        productRepository.save(new Product("Novel", "BOOKS", new BigDecimal("15.00")));

        long count = productRepository.findByCategory(category).size();
        assertEquals(expectedCount, count);
    }

    static Stream<Arguments> categoryExpectations() {
        return Stream.of(
            Arguments.of("ELECTRONICS", 2L),
            Arguments.of("BOOKS", 1L)
        );
    }
}

Configuration property testing with Spring's ApplicationContextRunner lets you verify that each possible value for a feature flag or config property produces the expected binding, with every scenario named and independently reportable — without the overhead of a full @SpringBootTest:

@ParameterizedTest(name = "{index}: enabled={0}, cap={1} -> bonus={2}")
@CsvSource({
    "true, 10, 10",
    "true, 5, 5",
    "false, 10, 0"
})
void loyaltyBonusRespectsConfiguration(boolean enabled, int cap, int expectedBonus) {
    new ApplicationContextRunner()
        .withUserConfiguration(PricingPropertiesConfig.class)
        .withPropertyValues(
            "pricing.loyalty-bonus-enabled=" + enabled,
            "pricing.loyalty-bonus-cap=" + cap)
        .run(context -> {
            PricingProperties properties = context.getBean(PricingProperties.class);
            int bonus = properties.isLoyaltyBonusEnabled() ? properties.getLoyaltyBonusCap() : 0;
            assertEquals(expectedBonus, bonus);
        });
}

This combines Spring's test infrastructure with parameterized execution in both directions: the ApplicationContextRunner builds a minimal context per invocation, and @CsvSource drives the property values through it.

@TestInstance(TestInstance.Lifecycle.PER_CLASS) is worth applying to Spring integration tests by default, because it allows @MethodSource factory methods to live as instance methods rather than static methods. This is particularly useful in Kotlin, where a companion object with @JvmStatic is the alternative and instance methods are the cleaner option.

Cleaner parameterized tests with Kotlin

Kotlin's interoperability with the JVM means you can call JUnit 6 from Kotlin without any adapters. The annotations work identically. The gain comes from what Kotlin removes from the picture: builder classes, new, verbose static-factory-method requirements, and the noise that accumulates when you construct several complex objects inline.

How to call JUnit 6 from Kotlin

By default, JUnit's @MethodSource requires a static factory method. Kotlin uses a companion object with @JvmStatic for this purpose. You can avoid that boilerplate entirely by annotating the test class with @TestInstance(TestInstance.Lifecycle.PER_CLASS), which lets the factory method be a regular Kotlin instance function:

@SpringBootTest
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class PricingServiceTest @Autowired constructor(
    private val pricingService: PricingService
) {
    fun pricingCases() = listOf(
        Arguments.of(DiscountInput(BigDecimal("100.00"), 5, false),
            DiscountResult(BigDecimal("90.00"), 10)),
        Arguments.of(DiscountInput(BigDecimal("200.00"), 0, true),
            DiscountResult(BigDecimal("170.00"), 15))
    )

    @ParameterizedTest
    @MethodSource("pricingCases")
    fun `calculates price correctly`(input: DiscountInput, expected: DiscountResult) {
        assertEquals(expected, pricingService.calculate(input))
    }
}

Data classes for concise test cases

A common pattern in Kotlin test suites is defining a small data class that bundles the inputs and the expected output for a single scenario. Because data class auto-generates a readable toString(), the test runner displays each invocation with a meaningful description rather than an index number.

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class PricingServiceParameterizedTest {

    private val pricingService = PricingService()

    data class PricingTestCase(
        val description: String,
        val input: DiscountInput,
        val expected: DiscountResult
    )

    private fun pricingScenarios() = listOf(
        PricingTestCase(
            description = "Standard user with no loyalty gets no discount",
            input = DiscountInput(BigDecimal("100.00"), loyaltyYears = 0, isVip = false),
            expected = DiscountResult(BigDecimal("100.00"), 0)
        ),
        PricingTestCase(
            description = "VIP with high loyalty (>=5 yrs) gets 25%",
            input = DiscountInput(BigDecimal("200.00"), loyaltyYears = 6, isVip = true),
            expected = DiscountResult(BigDecimal("150.00"), 25)
        )
    )

    @ParameterizedTest(name = "{index} => {0}")
    @MethodSource("pricingScenarios")
    fun `should calculate discounted price accurately`(testCase: PricingTestCase) {
        val result = pricingService.calculate(testCase.input)
        assertEquals(testCase.expected, result)
    }
}

(The data class above is declared without private — a public @ParameterizedTest method can't expose a parameter type that's private to the class, so if you factor your test case class out, keep its visibility at least as public as the test method that consumes it.)

Named arguments for improved readability

Kotlin named arguments make each test case self-documenting. Compare the Java version of a complex object construction:

// Java
new DiscountInput(new BigDecimal("200.00"), 6, true)

With the Kotlin version:

// Kotlin
DiscountInput(basePrice = BigDecimal("200.00"), loyaltyYears = 6, isVip = true)

At a glance, the Kotlin version tells you what each argument means. Scale this across fifteen test cases and the readability difference compounds.

Cleaner object construction than Java builders

When a Java constructor has more than a couple of same-typed parameters sitting next to each other (two ints, two booleans), teams often reach for a builder to make call sites self-describing:

DiscountInput input = new DiscountInputBuilder()
    .basePrice(new BigDecimal("200.00"))
    .loyaltyYears(6)
    .isVip(true)
    .build();

That builder exists purely to work around Java's lack of named arguments — it's an entire extra class (fields, a fluent setter per field, a build() method) whose only job is call-site clarity. Kotlin's named arguments give you the same clarity directly at the call site, with no builder class to write or maintain:

val input = DiscountInput(basePrice = BigDecimal("200.00"), loyaltyYears = 6, isVip = true)

For test suites specifically, this matters more than it might in production code: a parameterized test's factory method constructs the same object repeatedly with different values, so every parameter it's missing a name for is a small tax paid on every single test case.

Destructuring declarations and extension functions

Destructuring declarations let you unpack a data class in the test method signature when you prefer to work with its fields directly:

data class ValidationCase(
    val description: String,
    val request: UserRegistrationRequest,
    val expectedViolations: Int
)

private fun validationCases() = listOf(
    ValidationCase("valid payload", UserRegistrationRequest("alice", "alice@example.com", 30), 0),
    ValidationCase("blank username", UserRegistrationRequest("", "alice@example.com", 30), 1)
)

@ParameterizedTest(name = "{index}: {0}")
@MethodSource("validationCases")
fun `validates registration requests`(testCase: ValidationCase) {
    val (_, request, expectedViolations) = testCase
    assertEquals(expectedViolations, validator.validate(request).size)
}

Extension functions on the test class give you reusable assertion helpers scoped to the test context, which is a clean way to extract repeated assertion logic without moving it to a utility class:

private fun DiscountResult.assertMatchesExpected(expected: DiscountResult) {
    assertEquals(expected.discountedPrice, this.discountedPrice)
    assertEquals(expected.discountPercent, this.discountPercent)
}

Java vs Kotlin side by side

The same @MethodSource test in Java and Kotlin illustrates where Kotlin cuts boilerplate:

// Java
static Stream<Arguments> pricingCases() {
    return Stream.of(
        Arguments.of(
            new DiscountInput(new BigDecimal("100.00"), 0, false),
            new DiscountResult(new BigDecimal("100.00"), 0)
        ),
        Arguments.of(
            new DiscountInput(new BigDecimal("200.00"), 6, true),
            new DiscountResult(new BigDecimal("150.00"), 25)
        )
    );
}

// Kotlin
fun pricingCases() = listOf(
    Arguments.of(
        DiscountInput(basePrice = BigDecimal("100.00"), loyaltyYears = 0, isVip = false),
        DiscountResult(discountedPrice = BigDecimal("100.00"), discountPercent = 0)
    ),
    Arguments.of(
        DiscountInput(basePrice = BigDecimal("200.00"), loyaltyYears = 6, isVip = true),
        DiscountResult(discountedPrice = BigDecimal("150.00"), discountPercent = 25)
    )
)

The Kotlin version is shorter, each argument is named, and there's no static, new, or explicit Stream.of(). The test assertions stay identical because you're calling the same JUnit 6 API against the same JVM bytecode.

For teams with existing Java Spring Boot services, Kotlin test code compiles to the same bytecode and runs on the same JVM, so you can introduce Kotlin in the test source set (src/test/kotlin) without touching a single production class. The two coexist without conflict, which reflects the strategic partnership between JetBrains and the Spring team, a collaboration aimed at improving the experience for backend developers on both sides of the language boundary. For a real-world account of Kotlin running mission-critical backend systems at scale, see this KotlinConf recap of Verifone's work on Kotlin in payments infrastructure.

Best practices for maintainable parameterized tests

Keep datasets focused. A factory method that returns forty rows is probably testing more than one logical concept. Split by concern: one method for valid inputs, one for invalid inputs, and one for edge cases.
Prefer descriptive argument names. When your test case object has a description or scenario field, surface it in the display name with {0}. A failure that reads [3] VIP with 5 loyalty years gets 25% discount is actionable; [3] is not.
Separate data generation from assertions. The factory method should only construct data, and the assertion logic lives in the test method. This separation makes both easier to read and refactor independently.
Use reusable providers. When the same dataset validates both a service and a controller, extract an ArgumentsProvider implementation and reference it from both test classes with @ArgumentsSource. Copying and pasting the factory method creates a maintenance problem.
Balance flexibility with readability. A generic @MethodSource that builds objects from a dozen intermediate variables is harder to follow than an explicit list of typed data class instances. Optimize for the next developer reading the failure report, not for line count.
Organize shared datasets across modules. In multi-module Gradle or Maven builds, a shared test-fixtures source set (Gradle's java-test-fixtures plugin) lets you publish ArgumentsProvider implementations that multiple modules can depend on.
Avoid over-parameterization. If every test in a class is parameterized, the class is probably doing too much. Use parameterized tests for cases where variation in data genuinely changes the outcome. A test that always expects the same result with cosmetically varied inputs isn't verifying anything new.
Choose the simplest source that fits the problem — whether @ValueSource for a handful of scalars, @CsvSource for related tuples that fit on one line each, @MethodSource for complex objects, or a custom ArgumentsProvider for shared or dynamically loaded datasets. Reaching for the most powerful option by default makes tests harder to scan than necessary.

JUnit 6's parameterized testing API covers how each source annotation works, why you'd choose one over another, and how the patterns map to real Spring Boot test suites across service, validation, controller, repository, and configuration layers.

The Kotlin patterns covered here (data classes, named arguments, @TestInstance(PER_CLASS), extension functions) reduce test setup code without any production-side changes. For teams already on Spring Boot with Java production code, writing Kotlin in the test source set is a low-risk, incremental adoption path. The two languages share the same classpath, the same JUnit 6 runner, and the same Spring test infrastructure. Your production code stays exactly as it is while your test tables get measurably cleaner, which is the right way to evaluate any addition to a working stack: ask whether it solves a real friction point without demanding a wholesale commitment.

AssertJ vs Kotest Assertions: picking the right assertion library for JVM tests

Aniket Bhattacharyea — Wed, 21 Oct 2026 16:41:43 +0000

JUnit 6 ships with assertEquals, assertTrue, and a handful of other primitives. They work, but they leave a lot to be desired the moment a test fails. You get a message like expected: <true> but was: <false>, with no context about what was actually wrong. In a large Spring Boot project with dozens of test classes, that kind of noise slows everyone down.

AssertJ and Kotest Assertions both give you fluent, human-readable assertions with failure messages that tell the full story. They come from different design philosophies, and the one that fits your team depends on whether you're working in a pure Kotlin codebase, a mixed Java/Kotlin project, or something in between.

This article compares AssertJ and Kotest Assertions on syntax and readability, IntelliJ IDEA support, custom assertion strategies, soft assertions, Spring Boot integration, and adoption. The goal is a practical answer, not a feature matrix.

How this comparison works

Each section covers one dimension of the decision, starting with language design and syntax, then IDE support, custom assertions and soft assertions, Spring Boot integration, and a final recommendation. Code examples use real domain objects you'd find in a Spring Boot service, including a User entity, a REST response DTO, and a repository query result.

Both libraries are treated with equal seriousness. AssertJ has a decade-long track record as the default assertion library in the Spring Boot starter. Kotest Assertions brings a Kotlin-native DSL that aligns with how idiomatic Kotlin reads and works. Each fits a specific context, and that's what this article maps out.

Language design, syntax, and readability

AssertJ was designed for Java. Its API is a fluent chain of method calls, so assertThat(user.getName()).isEqualTo("Alice").startsWith("A") translates cleanly to Kotlin with no changes required. Kotlin adds things Java can't express, though, and AssertJ's API doesn't take advantage of them.

Kotest Assertions was built specifically for Kotlin. It uses infix functions and extension functions to produce assertions that read like natural language:

// AssertJ
assertThat(user.name).isEqualTo("Alice")
assertThat(user.email).isNotNull().endsWith("@example.com")

// Kotest
user.name shouldBe "Alice"
user.email.shouldNotBeNull() shouldEndWith "@example.com"

The difference becomes more pronounced when null safety comes into play. AssertJ runs on top of the JVM and doesn't know whether your value is nullable. To assert on a nullable field, you call .isNotNull() first, then continue chaining. Kotest's shouldNotBeNull() asserts the value is non-null and returns it as a non-null-typed result, so you can keep chaining matchers directly off the return value, without an extra null check of your own.

Exception assertions follow the same pattern. AssertJ uses assertThatThrownBy, which wraps the code under test in a lambda. For Kotest, shouldThrow does the job:

// AssertJ
assertThatThrownBy { userService.findById(-1L) }
    .isInstanceOf(NotFoundException::class.java)
    .hasMessageContaining("User not found")

// Kotest
val exception = shouldThrow<NotFoundException> {
    userService.findById(-1L)
}
exception.message shouldContain "User not found"

Kotest returns the thrown exception as a typed value, which means you can assert on its specific fields with full type information. AssertJ gives you an AbstractThrowableAssert, and while you can chain off it, you lose the concrete type unless you cast (or reach for assertThatExceptionOfType/catchThrowableOfType, which do return the concrete type if you need it).

For collection assertions, both libraries are capable, but their ergonomics differ. AssertJ uses extracting and containsExactly to navigate through collections, while Kotest delegates to standard Kotlin operations and then applies matchers:

val users = listOf(
    User(id = 1L, role = "ADMIN"),
    User(id = 2L, role = "USER")
)

// AssertJ
assertThat(users)
    .hasSize(2)
    .extracting("role")
    .containsExactly("ADMIN", "USER")

// Kotest
users shouldHaveSize 2
users.map { it.role } shouldContainExactly listOf("ADMIN", "USER")

The Kotest version reads like code you'd write anyway. The AssertJ version is clear, but extracting("role") uses a string property name, which loses type safety and won't be caught by the compiler if you rename the field. (AssertJ also has a type-safe overload, extracting(User::getRole), that avoids this specific problem if you prefer a method reference over a string.)

Use AssertJ when you need a single assertion style that works uniformly across Java and Kotlin sources. Kotest Assertions earns its place when your codebase is Kotlin-first and you want assertions that feel native to the language.

IDE support and developer experience

Both libraries work well inside IntelliJ IDEA, but their discoverability stories differ.

AssertJ's API is a method chain off assertThat(...). Once you type that call, IntelliJ's autocomplete presents the full list of available matchers for the specific type you passed in. Type a dot and browse the options. Static imports for Assertions.assertThat are handled by IntelliJ's import completion. IntelliJ's "Click to see difference" diff viewer opens side-by-side on assertion failure, and the IDE's general type-mismatch inspections apply to AssertJ calls the same way they apply to any other Java/Kotlin method chain — if you're not sure how far IntelliJ's AssertJ-specific inspections go in your version, it's worth checking the current release notes rather than assuming a specific check exists.

Kotest's extension functions change the discovery model. Because Kotest matchers are Kotlin extension functions defined on specific types, IntelliJ surfaces them through the same mechanism that surfaces any extension function, giving you autocomplete on the object itself. Type user.name and then a space, and IntelliJ will suggest shouldBe, shouldNotBe, and every other matcher that applies to String. The matchers are tied to the type system, so you won't see a string matcher when you're asserting on a number.

For teams new to Kotest, this has a practical effect: developers discover matchers organically by typing on their object and reading what appears. There's less need to memorize the API surface or rely on static import completion, because the type system does some of the teaching. That said, Kotest's API surface is still large, and a team new to the library will spend real time learning which matcher names exist in the first place, especially for the less common ones (shouldBeEqualIgnoringScale, shouldContainExactlyInAnyOrder, and similar) — autocomplete narrows the list, but it doesn't substitute for reading the matcher catalog once.

The Kotest project also publishes an IntelliJ IDEA plugin, distributed through the JetBrains Marketplace. Install it, and you get gutter icons next to individual test blocks, a dedicated Kotest tool window for browsing test hierarchies, and IntelliJ's diff viewer wired directly to Kotest assertion failures. For BehaviorSpec and DescribeSpec styles, the plugin renders the nested Given/When/Then or Describe/It hierarchy in the Structure tool window, which makes navigating a large test class much faster.

Navigation and refactoring behave the same way they do for any other Kotlin or Java code: go-to-declaration on a Kotest matcher takes you to its extension-function source, and renaming a property is a standard Kotlin rename-refactor regardless of which assertion library references it afterward. AssertJ's assert classes are ordinary Java types, so navigation into them (and documentation popups showing their Javadoc) works the same way it does for any other library on your classpath. Kotest's matchers carry KDoc, so hovering a matcher name shows the same kind of documentation popup you'd get from any Kotlin extension function.

AssertJ's experience is more static-import-dependent. On a new machine or a fresh project, getting assertThat to resolve without a red squiggly requires the import to be present. Teams used to this workflow find it natural, but teams migrating from JUnit's built-in assertions sometimes find the static import pattern mildly tedious until they configure IntelliJ's "add unambiguous imports on the fly" setting. That's the main developer frustration on the AssertJ side; on the Kotest side, the more common frustration is the opposite problem — so many matchers exist across so many modules that it can take a project or two before a team has internalized the vocabulary.

For daily use in a Kotlin project, Kotest's extension function-based discovery and the dedicated plugin make it the more ergonomic option inside IntelliJ IDEA. For mixed Java/Kotlin codebases where both languages write tests, AssertJ's consistent method-chain API across both languages is a real advantage.

Custom assertions and soft assertions

Custom assertions

Every meaningful Spring Boot project reaches the point where you're writing the same group of assertions in multiple test classes. A User entity has a handful of fields you always check together. A REST response DTO carries a status, a message, and a payload that need coordinated verification. A validation result needs its error list checked as a group. The right answer is a reusable custom assertion.

With AssertJ, you have two patterns. The first uses Kotlin extension functions on ObjectAssert<T>, which keeps your custom matchers chainable without subclassing:

fun ObjectAssert<User>.isActiveAdmin(): ObjectAssert<User> = satisfies(Consumer { user: User ->
    assertThat(user.status).isEqualTo(Status.ACTIVE)
    assertThat(user.role).isEqualTo("ADMIN")
})

// In tests
assertThat(user).isNotNull.isActiveAdmin()

Note the explicit Consumer { ... } wrapper around the lambda. AssertJ's satisfies method has three overloads — one taking a Condition, and two taking varargs of Consumer or ThrowingConsumer — and Kotlin can't infer which functional interface a bare trailing lambda should become when two of those overloads have an identical shape. Wrapping the lambda in Consumer { ... } resolves the ambiguity.

The second pattern extends AbstractAssert directly for complex domain objects where you want a dedicated assertion class with its own failure messages:

class UserAssert(actual: User?) : AbstractAssert<UserAssert, User>(actual, UserAssert::class.java) {
    fun hasValidEmail(): UserAssert {
        isNotNull()
        if (actual.email?.contains("@") != true) {
            failWithMessage("Expected valid email but was <%s>", actual.email)
        }
        return this
    }
}

fun assertThatUser(actual: User): UserAssert = UserAssert(actual)

// In tests
assertThatUser(user).hasValidEmail()

Two details matter here. First, actual.email is nullable, so the check needs a safe call (actual.email?.contains("@") != true) rather than a direct .contains(...) call. Second, name your factory function something other than assertThat. If you call it assertThat(actual: User): UserAssert — which is the more common way this pattern is written — it will silently lose to org.assertj.core.api.Assertions.assertThat the moment both are in scope in the same file, which is any file that also uses plain AssertJ assertions elsewhere. Kotlin's import-scope rules rank an explicitly imported name above a same-named function declared in your own package, so assertThat(user) resolves to the generic AssertJ overload every time, and your custom method never gets called — it just fails with "unresolved reference" at the call site, with nothing wrong-looking in the custom class itself. Naming the factory assertThatUser (or putting it behind an aliased import) avoids the collision entirely.

Kotest handles custom assertions through extension functions on the subject itself, which fits naturally with how Kotlin is written:

fun User.shouldBeActiveAdmin() {
    this.status shouldBe Status.ACTIVE
    this.role shouldBe "ADMIN"
}

// In tests
user.shouldBeActiveAdmin()

Kotest also supports Matcher<T>, a composable interface that lets you build matchers from other matchers and give them reusable names. This scales well for assertion libraries shared across multiple modules in a large project.

The Kotest approach produces less boilerplate and doesn't require you to understand the AbstractAssert class hierarchy or its overload quirks. For a team writing Kotlin, extension functions on the subject type are the pattern they already know, and reusing them in tests feels consistent with the rest of the codebase.

A validation result is a good example of a domain object that benefits from this treatment, since you're usually checking a boolean flag and a list of messages together:

data class ValidationResult(val valid: Boolean, val errors: List<String>)

// AssertJ
assertThat(result.valid).isFalse()
assertThat(result.errors)
    .hasSize(2)
    .contains("email must not be blank", "age must be positive")

// Kotest
result.valid shouldBe false
result.errors shouldContainExactlyInAnyOrder listOf(
    "email must not be blank",
    "age must be positive"
)

Wrapping either version in a hasValidationErrors(vararg messages: String)-style custom assertion (an AbstractAssert subclass for AssertJ, an extension function for Kotest) removes the repetition once this check shows up in more than one test class — the same tradeoff as the User examples above.

Soft assertions

Both libraries support soft assertions (Kotest's assertSoftly included), which collect all failures in a block instead of stopping at the first one. When you're asserting ten fields on a response object, reporting all failures at once saves debugging cycles.

// AssertJ
SoftAssertions.assertSoftly { softly ->
    softly.assertThat(order.status).isEqualTo(OrderStatus.CONFIRMED)
    softly.assertThat(order.totalPrice).isEqualByComparingTo(BigDecimal("99.99"))
    softly.assertThat(order.items).hasSize(3)
}

// Kotest
assertSoftly(order) {
    status shouldBe OrderStatus.CONFIRMED
    totalPrice.shouldBeEqualIgnoringScale(BigDecimal("99.99"))
    items shouldHaveSize 3
}

Kotest's assertSoftly block scopes the receiver, so you reference status, items, and totalPrice directly without repeating softly.assertThat(order.x) on every line. The reduction in noise is real in test classes that verify complex aggregates like an Order with nested line items or a validation result with multiple error messages. shouldBeEqualIgnoringScale is the Kotest equivalent of AssertJ's isEqualByComparingTo here — it compares the numeric value and ignores trailing-zero scale differences, so BigDecimal("99.99") and BigDecimal("99.990") are treated as equal. AssertJ's assertSoftly requires the softly prefix on every assertion line, which is more verbose but also more explicit about which assertion library you're calling.

Spring Boot integration

AssertJ ships inside spring-boot-starter-test. Add the Spring Boot test starter and AssertJ is available with no additional configuration:

dependencies {
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

Kotest Assertions requires an additional dependency. If you want Kotest's full test framework (its FunSpec, BehaviorSpec, and other styles), you also add the JUnit Platform runner. For teams that want only Kotest's assertion DSL inside JUnit 6 tests, kotest-assertions-core is enough. If you're also mocking with MockK inside Spring test slices (as in the controller example below), add springmockk for its @MockkBean annotation:

dependencies {
    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testImplementation("io.kotest:kotest-assertions-core:5.9.1")
    // Optional: full Kotest framework
    testImplementation("io.kotest:kotest-runner-junit5:5.9.1")
    testImplementation("io.kotest.extensions:kotest-extensions-spring:1.3.0")
    // Needed for @MockkBean in Spring test slices
    testImplementation("com.ninja-squad:springmockk:4.0.2")
}

Both libraries integrate with the full Spring Boot test stack. A @WebMvcTest controller test using MockK for mocking and Kotest for assertions looks like this:

@WebMvcTest(UserController::class)
class UserControllerTest(@Autowired private val mockMvc: MockMvc) {

    @MockkBean
    private lateinit var userService: UserService

    @Test
    fun `should return user by id`() {
        val user = User(id = 42L, email = "alex@example.com", status = Status.ACTIVE)
        every { userService.findById(42L) } returns user

        val response = mockMvc.get("/api/users/42") {
            accept = MediaType.APPLICATION_JSON
        }.andExpect {
            status { isOk() }
        }.andReturn().response.contentAsString

        val dto = jacksonObjectMapper().readValue<UserResponseDto>(response)
        dto.email shouldBe "alex@example.com"
        dto.status shouldBe "ACTIVE"
    }
}

For a thinner service-layer test — no Spring context, no web layer, just the business logic — the same syntax from the opening sections applies directly, with no annotations at all:

class UserServiceTest {
    private val userService: UserService = InMemoryUserService()

    // AssertJ
    @Test
    fun `assertj service test`() {
        assertThat(userService.findById(1L).status).isEqualTo(Status.ACTIVE)
    }

    // Kotest
    @Test
    fun `kotest service test`() {
        userService.findById(1L).status shouldBe Status.ACTIVE
    }
}

For repository tests with @DataJpaTest, the AssertJ version uses satisfies to group assertions on a single result.

The following is an example of a Java test next to its Kotlin counterpart — in a mixed codebase, AssertJ's API doesn't change shape between the two:

// Java
@DataJpaTest
class UserRepositoryJavaTest {

    @Autowired
    private UserRepository repo;

    @Autowired
    private TestEntityManager em;

    @Test
    void shouldFindActiveUsersByDomain() {
        repo.save(new User(0L, "Alice", "alice@company.com", "USER", Status.ACTIVE));
        repo.save(new User(0L, "Bob", "bob@company.com", "USER", Status.INACTIVE));
        em.flush();

        List<User> results = repo.findActiveByDomain("company.com");

        assertThat(results).hasSize(1);
        assertThat(results.get(0).getEmail()).isEqualTo("alice@company.com");
        assertThat(results.get(0).getStatus()).isEqualTo(Status.ACTIVE);
    }
}

// Kotlin
@DataJpaTest
class UserRepositoryTest(
    @Autowired private val repo: UserRepository,
    @Autowired private val em: TestEntityManager
) {
    @Test
    fun `should find active users by domain`() {
        repo.save(User(email = "alice@company.com", status = Status.ACTIVE))
        repo.save(User(email = "bob@company.com", status = Status.INACTIVE))
        em.flush()

        val results = repo.findActiveByDomain("company.com")

        // AssertJ
        assertThat(results).hasSize(1).first().satisfies(Consumer { u ->
            assertThat(u.email).isEqualTo("alice@company.com")
            assertThat(u.status).isEqualTo(Status.ACTIVE)
        })

        // Kotest equivalent
        results shouldHaveSize 1
        with(results.single()) {
            email shouldBe "alice@company.com"
            status shouldBe Status.ACTIVE
        }
    }
}

As with the custom-assertion example earlier, .satisfies(...) needs an explicit Consumer { ... } wrapper in Kotlin — a bare trailing lambda doesn't compile against AssertJ's vararg overloads.

If your repository tests run against a real database via Testcontainers instead of an embedded one, none of the assertion syntax above changes — assertThat(...) and shouldBe/shouldHaveSize work the same way against a Testcontainers-backed PostgreSQLContainer as they do against H2, since they're asserting on the List<User> the repository returns, not on anything container-specific. The assertion library and the integration-test infrastructure are orthogonal choices.

When using the full Kotest test framework alongside Spring Boot, you register SpringExtension to enable context loading and constructor-based dependency injection inside Kotest specs:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class UserServiceIntegrationTest(
    private val restTemplate: TestRestTemplate
) : FunSpec({
    extension(SpringExtension)

    test("should fetch user profile") {
        val response = restTemplate.getForEntity("/api/users/1", String::class.java)
        response.statusCode shouldBe HttpStatus.OK
        response.body.shouldNotBeNull()
    }
})

Notice the constructor parameter has no @Autowired annotation. Kotest's SpringExtension resolves constructor dependencies itself, independently of Spring's own TestConstructor autowire mode (which, under plain JUnit, defaults to requiring @Autowired per parameter or a global property, as covered in our companion piece on JUnit, Testcontainers, MockK, Kotest, and Spring Boot Test). Inside a Kotest spec specifically, it just works.

For teams already using Mockito in Java test sources, AssertJ slots in without friction. For teams that have adopted MockK (the idiomatic Kotlin mocking library), pairing it with Kotest Assertions produces a consistent, Kotlin-native test stack.

One real-world consideration worth noting: Kotest's native coroutine support applies to the full Kotest test framework, not to Kotest Assertions by itself. Inside a Kotest spec (FunSpec, BehaviorSpec, and the rest), test bodies are themselves suspend lambdas run by the Kotest engine, so you can call suspend functions directly with no wrapper. If you're using only kotest-assertions-core inside an ordinary JUnit @Test method, that method is not a suspend function, and calling a suspend function from it fails to compile — you still need runBlocking or runTest around the call, exactly as you would with any other assertion library.

Which assertion library to choose

There's no universally correct answer, but the decision tree is short.

Choose AssertJ when your team maintains both Java and Kotlin test sources and wants a single assertion style across both. AssertJ is already in spring-boot-starter-test, so the cost of adoption is zero. Its method-chain API is widely understood by Java developers and requires no onboarding. Teams that value a minimal dependency footprint and standard tooling will find AssertJ the path of least resistance.

Choose Kotest Assertions when your project is Kotlin-first and you want assertions that align with idiomatic Kotlin. The infix DSL reduces noise in test output and in code review. The assertSoftly scoping removes softly.assertThat(...) repetition. Null safety is handled through return-type narrowing rather than manual checks. If you're already using the Kotest test framework for its spec styles, this is the obvious choice. You can also adopt Kotest Assertions inside JUnit 6 tests without migrating to the full framework, which makes it a low-risk addition to an existing Spring Boot project.

On performance and adoption: neither library adds meaningful runtime overhead to a test suite. Both are thin DSL layers over ordinary JVM assertion failures — the cost is a method call or two per check, not a separate execution engine (the one exception is adopting the full Kotest test framework as your test runner, which does replace JUnit's default test discovery and execution, though not in a way that changes wall-clock test time in any way that matters day to day). On adoption, AssertJ has the longer track record simply by virtue of having shipped as the Spring Boot default for about a decade; Kotest's adoption has grown alongside Kotlin's own growth on the backend, particularly among teams already using Kotest's spec styles or MockK. Neither is a niche choice at this point — the decision is about fit with your codebase's language, not about betting on an unproven library.

Mixing assertion libraries is viable within limits. Using Kotest Assertions inside JUnit 6 tests alongside AssertJ for specific cases (such as Condition-based matchers already established in the codebase) works without conflict. Mixing the full Kotest test framework with JUnit 6 test classes in the same module requires more care in configuration but is supported. Mixing becomes a liability when new team members can't tell which style to follow when writing a new test; in that case, the team is better served by picking one library and standardizing.

Migrating from AssertJ to Kotest Assertions in a Kotlin codebase follows an incremental path: start with new test classes, use shouldBe and assertSoftly there, and leave existing AssertJ tests in place. The two styles don't interfere, and the migration pressure comes naturally as old tests get refactored.

Choosing based on language gravity

AssertJ and Kotest Assertions both make test failures informative and test code readable, but they reflect different assumptions about who's writing the tests and what the language can do. AssertJ's Java-first fluent API surprises no JVM developer and integrates at zero cost via the Spring Boot starter. Kotest's Kotlin-native DSL aligns with how Kotlin code reads and works, particularly around null safety and extension function discoverability in IntelliJ IDEA — though its native coroutine-testing story is a feature of the full Kotest spec framework, not of Kotest Assertions on its own.

For Java developers working in mixed codebases and evaluating whether to bring Kotest into their Kotlin test sources, you can adopt Kotest Assertions incrementally, one test class at a time, without disturbing what's already there. The kotest-assertions-core dependency is the only addition required, and it coexists cleanly with AssertJ and JUnit 6. The official JetBrains–Spring partnership continues to improve Kotlin's position as a first-class language for Spring development, and Kotest is part of a mature Kotlin testing ecosystem that includes MockK, kotlin.test, and full Spring Boot test integration. For a concrete account of Kotlin running mission-critical backend systems in production, see this KotlinConf recap of Verifone's work on Kotlin in payments infrastructure.

Pick the library that matches your codebase's language gravity. If your tests are trending Kotlin, Kotest Assertions will feel like a natural fit.

5 Java testing frameworks that work better with Kotlin

Aniket Bhattacharyea — Thu, 15 Oct 2026 07:30:26 +0000

Your test suite doesn't have to wait for production to meet Kotlin. If you're working on a Java Spring Boot project, you can start writing Kotlin tests today, against your existing Java code, without changing a single production class. Because Kotlin compiles to JVM bytecode, a Kotlin test can call any Java class directly, with no wrappers or adapters, which makes it a low-risk way to get familiar with the language.

Kotlin needs roughly 40% less code than equivalent Java, and test code, which is mostly setup and assertions, benefits from that. This roundup covers five widely adopted libraries, from JUnit to Kotlin-native additions like MockK and Kotest, and shows how each works with Kotlin. You can add any of them to an existing project without touching the others.

How these tools were chosen

Each tool here cleared three bars: being widely adopted and mature, offering first-class or excellent Kotlin support, and, together, the five cover the main testing layers, including unit, mocking, integration, assertions, and the full Spring context. You can add any one of them to an existing Java project without touching the others.

JUnit 6

JUnit 6 is the latest version of JUnit, the de facto standard testing framework for JVM applications. If you're on a Java project, you may already be using JUnit, making it a natural entry point for writing your first Kotlin test.

Kotlin's backtick function names noticeably improve test code readability. Take a Java test that looks like this:

@Test
void shouldReturnDiscountedPrice() {
    OrderService service = new OrderService();
    assertEquals(90.0, service.applyDiscount(100.0, 10), 0.001);
}

The Kotlin equivalent reads like this:

@Test
fun `should return discounted price`() {
    val service = OrderService()
    assertEquals(90.0, service.applyDiscount(100.0, 10), 0.001)
}

Backticks let you write full English sentences as test names, which appear directly in your test reports, with no camelCase decoding required.

Parameterized tests also get cleaner in Kotlin. Using @MethodSource with a companion object keeps your test data close to the test without the ceremony of a static utility class:

companion object {
    @JvmStatic
    fun discountScenarios() = listOf(
        Arguments.of(100.0, 10, 90.0),
        Arguments.of(200.0, 25, 150.0),
        Arguments.of(50.0, 0, 50.0)
    )
}

@ParameterizedTest
@MethodSource("discountScenarios")
fun `applies discount correctly`(
    price: Double,
    pct: Int,
    expected: Double
) {
    assertEquals(
        expected,
        OrderService().applyDiscount(price, pct),
        0.001
    )
}

JUnit's @Nested tests also work well with Kotlin, but nested test classes must be declared as inner class because JUnit requires nested test classes to be non-static:

@Nested
inner class WhenDiscountIsApplied {
    // tests
}

Kotlin works with JUnit 6 through standard JVM interoperability, with two differences from Java. Kotlin classes are final by default, but JUnit 6 test classes don't need to be open. For @BeforeAll and @AfterAll, you can either expose the methods as static JVM methods using a companion object and @JvmStatic, or use JUnit's PER_CLASS test instance lifecycle to keep them as instance methods.

Testcontainers

Testcontainers lets you run integration tests against real dependencies such as PostgreSQL, Kafka, and Redis by starting disposable Docker containers during the test run. Instead of relying on an in-memory substitute or a service installed on the developer's machine, your tests can exercise the same type of infrastructure your application uses.

Kotlin's apply scope function makes container configuration concise. apply lets you call the container's methods directly inside the lambda, then returns the container itself, so you don't have to repeat the variable name:

val postgres =
    PostgreSQLContainer(
        DockerImageName.parse("postgres:16-alpine")
    ).apply {
        withDatabaseName("testdb")
        withUsername("testuser")
        withPassword("testpass")
    }

For JUnit integration, @Testcontainers and @Container manage the container lifecycle. A container declared as a static field is shared across the test methods in that class, while an instance container is started and stopped for each test method.

When using Kotlin, a shared container can be exposed as a JVM static field with @JvmStatic:

@Testcontainers
@SpringBootTest
class OrderRepositoryIntegrationTest {

    companion object {
        @Container
        @JvmStatic
        val postgres =
            PostgreSQLContainer(
                DockerImageName.parse("postgres:16-alpine")
            ).apply {
                withDatabaseName("testdb")
                withUsername("testuser")
                withPassword("testpass")
            }

        @JvmStatic
        @DynamicPropertySource
        fun properties(registry: DynamicPropertyRegistry) {
            registry.add("spring.datasource.url",
                postgres::getJdbcUrl)
            registry.add("spring.datasource.username",
                postgres::getUsername)
            registry.add("spring.datasource.password",
                postgres::getPassword)
        }
    }

    @Test
    fun `persists order and retrieves by ID`() {
        // test against a real PostgreSQL instance
    }
}

@DynamicPropertySource registers dynamically determined values, such as a Testcontainers database URL and credentials, with the Spring ApplicationContext. In Kotlin, Spring's documentation uses @JvmStatic for both the container field and the dynamic-property method.

For reusable test infrastructure, Kotlin extension functions can keep configuration helpers close to the types they operate on:

fun PostgreSQLContainer<*>.jdbcUrl() = jdbcUrl

This can reduce repetition when several integration tests need similar container configuration.

Testcontainers also supports modules for common dependencies such as PostgreSQL, Redis, and Kafka. Combining Testcontainers with Spring's context caching can cause failures in later test classes, though. JUnit stops a container when its test class finishes, but Spring may keep the ApplicationContext for the next class, and that cached context can still point at the stopped container. If several test classes share a container, declare it as a Spring bean so its lifecycle follows the ApplicationContext instead of a single test class.

MockK

Mockito is widely used in Java projects and works with Kotlin, but Kotlin-specific language features can introduce some friction. Kotlin classes are final by default, while older Mockito setups often required additional configuration to mock final classes. Kotlin's when keyword also conflicts with Mockito's when() method, requiring escaped syntax such as Mockito.`when`(...). Mockito and the mockito-kotlin library support coroutine-based code, but MockK offers Kotlin-specific APIs that make stubbing and verification more idiomatic.

MockK was designed specifically for Kotlin. It can mock final classes without additional configuration and provides a Kotlin-oriented DSL for stubbing and verification:

val orderService = mockk<OrderService>()

every { orderService.findById(1L) } returns Order(id = 1L, total = 99.99)

val result = invoiceService.generateInvoice(1L)

verify { orderService.findById(1L) }
assertEquals(99.99, result.amount)

For suspending functions, MockK provides coEvery and coVerify, allowing coroutine calls to be stubbed and verified directly:

coEvery { orderService.findByIdAsync(1L) } returns
    Order(id = 1L, total = 99.99)

runTest {
    val result = invoiceService.generateInvoiceAsync(1L)

    coVerify { orderService.findByIdAsync(1L) }
    assertEquals(99.99, result.amount)
}

MockK also provides a JUnit 5/6 extension that works with @MockK annotations, avoiding the need to create each mock manually:

@ExtendWith(MockKExtension::class)
class InvoiceServiceTest {

    @MockK
    lateinit var orderService: OrderService

    // tests
}

For mocks where you only care about a subset of interactions, MockK's relaxed = true option can provide default return values without requiring every call to be stubbed explicitly:

val orderService = mockk<OrderService>(relaxed = true)

For teams maintaining both Java and Kotlin tests, there's no need to migrate an existing Mockito-based test suite just to introduce MockK. Mockito and MockK can coexist in the same project, letting teams keep existing Java tests unchanged while using MockK for new Kotlin tests where its Kotlin-specific APIs are useful.

Kotest assertions

Kotest is a Kotlin testing ecosystem that provides a complete testing framework as well as standalone libraries for assertions, property-based testing, and other testing utilities. You can use Kotest's assertions and property testing in Kotlin tests while JUnit 6 remains the test framework, so Java teams can adopt Kotlin incrementally without changing their test runner. This section focuses on Kotest's assertion library and property-testing capabilities. Its test framework isn't covered in depth.

Kotest's assertion APIs use Kotlin's language features to make test expectations more readable:

@Test
fun `calculates order total`() {
    val total = orderService.calculateTotal(
        Order(items = listOf(Item(price = 49.99)))
    )

    total shouldBe 49.99
}

Instead of passing the actual and expected values to a traditional assertion method, shouldBe expresses the relationship directly. Kotest provides similar assertions for collections, exceptions, strings, nullable values, and other common testing scenarios.

These DSL-style assertions can make Kotlin tests more concise and expressive without requiring a team to replace its existing JUnit 6 test infrastructure.

Kotest also provides property-based testing capabilities. Rather than checking a function against only a few manually selected examples, you can describe a property that should hold across a range of generated inputs.

For example:

import io.kotest.matchers.collections.shouldContainAll
import io.kotest.matchers.shouldBe
import io.kotest.property.Arb
import io.kotest.property.arbitrary.int
import io.kotest.property.arbitrary.list
import io.kotest.property.checkAll
import kotlinx.coroutines.test.runTest
import org.junit.jupiter.api.Test

class SortingPropertyTest {

    @Test
    fun `sorting preserves all elements`() = runTest {
        checkAll(Arb.list(Arb.int())) { numbers ->
            val sorted = numbers.sorted()

            sorted shouldContainAll numbers
            sorted.size shouldBe numbers.size
        }
    }
}

The test describes properties that should always hold, while Kotest generates multiple inputs to check those properties. This can help uncover edge cases that a small set of hand-written examples might not exercise.

Property-based testing is particularly useful when code has clear invariants, such as sorting, serialization, parsing, validation, or mathematical operations. Existing JUnit 6 tests can remain unchanged while new Kotlin tests use Kotest's assertion APIs. You can then add property-based testing selectively where generated inputs add value.

Spring Boot Test

For Spring Boot applications, spring-boot-starter-test provides the testing infrastructure needed to test Spring components and application behavior in a realistic application context. Kotlin works with the same Spring Boot testing infrastructure used by Java applications, while Kotlin-specific features can make some test code more concise.

Spring Boot Test is particularly useful when a test needs more than an isolated unit test, for example, when you want to verify how multiple Spring-managed components work together.

The most practical improvement is constructor injection in test classes. In Java, @SpringBootTest tests typically use @Autowired field injection, which means mutable fields and no compile-time guarantee that dependencies are actually available. In Kotlin, you can use @TestConstructor(autowireMode = AutowireMode.ALL) to wire dependencies through the primary constructor:

@ExtendWith(SpringExtension::class)
@TestConstructor(autowireMode = TestConstructor.AutowireMode.ALL)
@SpringBootTest(webEnvironment =
    SpringBootTest.WebEnvironment.RANDOM_PORT)
internal class OrderApiIntegrationTest(
    val orderRepository: OrderRepository,
    val testRestTemplate: TestRestTemplate
) {
    @Test
    fun `GET orders returns 200 with order list`() {
        orderRepository.save(Order(total = 49.99))
        val response = testRestTemplate.getForEntity("/orders",
            List::class.java)
        assertEquals(HttpStatus.OK, response.statusCode)
    }
}

To set this globally for all test classes, add spring.test.constructor.autowire.mode=all to src/test/resources/junit-platform.properties. All your Kotlin test classes then get constructor injection automatically.

Kotlin works with all standard Spring test slice annotations, including @DataJpaTest, @WebMvcTest, and @AutoConfigureMockMvc. Spring Framework's Kotlin extensions add idiomatic API variants where the Java API feels verbose, particularly for MockMvc and WebTestClient.

For integration tests in mixed Java/Kotlin projects, a useful pattern is a Kotlin base class that declares the @Testcontainers setup and @DynamicPropertySource, combined with Spring Boot Test's context-caching behavior. Both JUnit Java tests and Kotlin tests can extend the same base class, reusing the same application context and container instance across the test run.

JetBrains and Spring formalized a strategic partnership in May 2025 to improve the Kotlin developer experience in Spring applications. The collaboration covers full null-safety integration for Kotlin in Spring, official Spring learning materials in Kotlin, and enhanced tooling in IntelliJ IDEA. The same announcement reports that 27% of Spring developers use Kotlin.

What to do next

These five tools cover the full testing stack, from unit mocks to full-context integration tests, and you can adopt each one at a time without touching your production code. A practical starting point is adding Kotlin to your test source set, writing your next new test in Kotlin using JUnit 6, and pulling in MockK when you hit the first case where Mockito's final-class behavior gets in the way.

Kotlin's concise syntax, null safety, extension functions, and DSLs carry over from test code to production code, which is why the test suite is a natural on-ramp. Once your team has written a few dozen Kotlin tests and developed an intuition for the idioms, expanding Kotlin into production services becomes a lower-risk conversation.

kotlinlang.org has the language reference, coding conventions, and getting-started guides for JVM and Spring Boot development. The official JUnit testing tutorial for Kotlin covers the Gradle setup steps in detail.

6 Business Levers to Evaluate Before Adopting a New Language

Aniket Bhattacharyea — Thu, 15 Oct 2026 07:12:50 +0000

A language proposal framed purely as a productivity argument is incomplete. The real decision touches hiring pipelines, incident rates, migration timelines, audit controls, and long-term strategic positioning. Verifone's experience with Kotlin illustrates why. In a large, regulated payments environment, adopting a new language is a targeted decision about which systems benefit and which should stay untouched.

This guide provides a repeatable six-lever framework for making that decision. Kotlin appears as a concrete example throughout, but the framework itself applies to any language under consideration.

Lever 1: Delivery throughput and time-to-market

The hypothesis behind most language adoption proposals is that developers will ship faster. The burden of proof is yours to assign, meaning faster compared to what baseline, on what kind of work, and measured how?

Start with your current delivery metrics. DORA's lead time for changes, deployment frequency, change failure rate, and MTTR can provide a baseline, supplemented by domain-specific metrics. If you don't have those, instrument your metrics pipelines before you run any pilot. Also, define a kill switch before the pilot. If build times, incident rates, review overhead, or required security controls move beyond agreed thresholds, pause expansion and reassess.

You're trying to determine whether the language increases delivery capacity or reduces the cost of delay, because shipping sooner on a high-value feature has a measurable dollar value. Reduced boilerplate and safer refactoring are two mechanisms that need to produce shorter cycles at the product level.

Kotlin, for example, produces roughly 40% fewer lines of code than equivalent Java, and JetBrains documents that Kotlin developers spend 15 to 20% less wall-clock time on comparable work. Those are plausible throughput signals, but they mean nothing if your actual bottleneck is unclear requirements or slow code review. A bounded pilot on one team's new module, measured against your existing lead-time data, tells you whether the throughput hypothesis holds for your context before you commit the organization.

Lever 2: Defect cost avoidance

Built-in mechanisms that prevent particular classes of defects are only a business case once they're tied to what those defects actually cost you.

Start by identifying your most expensive defect categories, including severity-1 incidents, emergency releases, support escalations, regulatory findings, and customer-impacting bugs. Then ask whether the language you're evaluating has type-system mechanisms that would have caught those failures at compile time.

Kotlin's null safety is built directly into the type system. Variables are non-nullable by default, so the compiler enforces that distinction at compile time. For codebases where NullPointerExceptions show up regularly in incident retrospectives, that's a targeted reduction in a specific defect class. Sealed classes and exhaustive when expressions push domain modeling errors to compile time, catching incomplete state handling before it reaches production.

Track the specific defect classes your type system would constrain, assign a cost per incident from your post-mortem data, and project the reduction. That number, even as an estimate, grounds the conversation in outcomes.

Lever 3: Legacy modernization without full-rewrite risk

The highest-risk path to adopting a new language involves a full-rewrite, where you freeze features, rebuild from scratch, deliver the replacement months or years later, and hope the codebase didn't drift and the team didn't burn out.

Evaluate whether the language supports incremental adoption and what that path concretely looks like for your estate. Can you introduce the language in new modules while leaving existing code untouched? Can both languages call each other without a translation layer? Can you migrate active systems module by module while continuing to ship features? You can opt for an incremental adoption that doesn't involve migrating every legacy system. Stable, low-change systems may not generate enough benefit to justify the migration cost. In those cases, leaving the existing system in place can be the economically rational choice.

Big companies, especially those with payments environment shows why this incremental approach matters in practice. With dozens of systems across dozens of engineering squads and strict EMV L3, PCI DSS, and ISO 8583 requirements, a language migration cannot reasonably be treated as a single organization-wide rewrite.

Kotlin's Java interoperability instead allows adoption to be evaluated within individual domains and systems, while existing Java systems continue to operate. The broader lesson is to treat modernization as a portfolio of bounded investment decisions. Target systems where the expected benefits justify the migration cost, while keeping stable, low-change systems in place when they do not.

When evaluating an incremental migration, ask these questions: where can you introduce the new language with a limited blast radius, which systems justify migration, and which stable or end-of-life systems should remain untouched?

IntelliJ IDEA includes a built-in Java-to-Kotlin converter that handles mechanical conversion, and AI-assisted refactoring in the IDE supports larger transformations where test coverage is solid. JetBrains' documented adoption playbook has distinct stages. Start with tests, introduce new modules, migrate active systems module by module, and leave end-of-life applications untouched.

When you build your migration cost model, include the full picture. Conversion effort is the smallest line item. The real costs are training time, mixed-language code review overhead, governance and style guide updates, tooling configuration for two-language CI pipelines, parallel operation periods, compliance documentation for new dependencies, and eventual cleanup. Teams that model only conversion effort routinely underestimate total migration cost by a significant margin.

Lever 4: Talent economics

Language adoption changes your hiring market, your onboarding timeline, and your knowledge concentration risk. All three have an associated financial cost.

Broad developer popularity rankings (TIOBE, Stack Overflow survey rank) tell you about global sentiment, not about the candidate pool available in your geography and domain. A financial services firm hiring in Frankfurt has a different Kotlin talent market than a startup hiring remotely across North America. Run the actual job-search data for your location and role tier before drawing conclusions from global statistics.

For most JVM shops, you need to know whether existing engineers can transfer skills into the new language and how long that takes. Kotlin is a evolution of Java, so a Java developer with solid JVM fundamentals can often build on existing knowledge, but time to productive, idiomatic Kotlin varies by team, domain, and training approach. JetBrains Academy provides structured Kotlin learning in JetBrains IDEs, including Kotlin Onboarding and Kotlin Koans.

Knowledge concentration risk increases if your Kotlin adoption concentrates expertise in a small number of senior engineers who championed the migration, creating a bus-factor problem. Plan for knowledge distribution through pair programming, internal documentation, and making Kotlin adoption part of the standard onboarding path for new hires.

Whether a smaller external talent pool is manageable depends on your attrition rate, your time-to-hire baseline, and your planned pace of adoption. If JVM continuity means your Java engineers ramp quickly and internal training covers the difference, the hiring constraint often stays within tolerance.

Lever 5: Multichannel consistency

This lever applies only when your organization runs business logic across multiple platforms and duplicated implementations create real cost or behavioral drift. You don't need to worry about this if you're building a backend-only product.

For organizations that ship a mobile app, a web frontend, and a backend service where the same validation rules, pricing calculations, or domain models must behave identically across channels, duplicated implementations in different languages become a maintenance liability. When the backend rule changes, all three implementations need to change, and the risk of divergence grows with velocity.

Kotlin Multiplatform (KMP) lets you write shared modules in Kotlin and compile them to JVM, JavaScript, and native targets. You can implement a pricing rule or validation function in shared Kotlin code and compile it for Android, iOS, and JVM targets, reducing the need to maintain separate implementations.

Shared code is worth the added complexity only when it eliminates meaningful duplication across channels you already operate, not as a hypothetical future benefit. Be aware that Kotlin Multiplatform is a separate architectural decision from adopting Kotlin on the JVM, and you can adopt Kotlin for server-side development without committing to KMP.

Lever 6: Security, compliance, and auditability

In regulated environments and security-sensitive industries, language adoption is a supply-chain event. Introducing a new language adds runtime artifacts, transitive dependencies, toolchain components, and new questions for your compliance team. You should evaluate that surface area before you commit.

On the supply-chain side, ask whether the language's standard library has a documented security support policy with formal end-of-support dates, CVE assignment processes, and a public vulnerability disclosure page. Starting with Kotlin 2.4.0, the Kotlin standard library for the JVM has an 18-month support window for each release line. Security fixes are backported to all active release lines and given CVE identifiers, published on the JetBrains Fixed Security Issues page. That policy structure is directly relevant for teams that need documented evidence of dependency support coverage for auditors.

On the SAST and auditability side, verify that your existing static analysis tooling covers the new language. JetBrains' Qodana integrates into CI/CD pipelines via GitHub Actions, GitLab CI/CD, Jenkins, and TeamCity, and runs Kotlin-specific inspections alongside Java analysis in mixed codebases. Within IntelliJ IDEA, real-time inspections flag null-safety violations and other issues before code reaches the pipeline. For SBOM generation, the Kotlin ecosystem supports CycloneDX-format SBOM plugins for Gradle, which feed into existing compliance workflows.

Be aware that introducing a second language can increase audit surface area if it multiplies the runtime artifacts and toolchain components your security team must track. It can also reduce audit surface area if the new language's type system eliminates categories of vulnerabilities your current codebase generates regularly. Model both directions for your specific regulatory context, and don't assume that one dominates.

Security is only one part of the risk calculation. Enterprise teams should also assess governance concentration, vendor and ecosystem risk, release and support windows, build and CI overhead, operational tooling, and the additional 'polyglot tax' of maintaining more than one language. These costs should be measured during the pilot.

Turn the checklist into an investment case

To use these six levers to decide whether adoption is worth funding, baseline the target domain's current cost and performance, model the expected benefits conservatively, and include the learning curve, mixed-language overhead, tooling, governance, compliance, parallel operation, and eventual decommissioning. For larger initiatives, translate the resulting cash flows into metrics such as NPV, IRR, and payback period. Run conservative, base, and upside scenarios, and define the conditions that would cause you to pause further rollout.

A language can look attractive on individual metrics while still producing a negative investment case for a particular system.

Apply the 6 levers as a checklist

Before committing to any language adoption, work through each lever with your team and document the answers:

Delivery throughput: what's your lead-time baseline, and how will you validate the throughput hypothesis in a bounded pilot?
Defect cost avoidance: which specific defect classes would the type system constrain, and what does each class cost you?
Legacy modernization: what does an incremental adoption path look like, and does your total migration cost model include training, governance, and parallel-operation overhead?
Talent economics: what does the actual candidate market look like in your geography, and how long do your existing engineers take to reach productive output?
Multichannel consistency: does your organization actually have duplicated implementations across channels, and would shared code meaningfully reduce that cost?
Security and compliance: what does the language add to your supply-chain surface, and what does your security tooling coverage look like for the new language?

Different systems and teams will produce different answers, and the same language can score differently across your own portfolio.

Enterprises' experience illustrates the broader principle: language adoption needs to be an investment decision, backed by numbers your team can defend. The right answer can differ by system, team, and business domain.

Use the six levers to establish your baseline, identify where the candidate language can create measurable value, account for migration and operating costs, and determine where adoption is and isn't justified.

If you're evaluating Kotlin specifically, the A Legacy Modernization Strategy and Business Case Playbook for Enterprise Kotlin Adoption provides a concrete example of how incremental adoption can work in an enterprise environment. What language decisions is your team currently weighing? Share your evaluation criteria in the comments.

Kotlin Governance Framework: How Enterprises Modernize Without Losing Control

Aniket Bhattacharyea — Thu, 15 Oct 2026 07:03:05 +0000

Technology modernization usually starts with a technical choice. You choose the most appropriate language, framework, or stack for your case. But in practice, even the best choice can go wrong if it's applied unevenly across teams.

One group adopts Kotlin while another is still debating whether to allow it, and a few months in, whoever shipped code that week is setting the architecture, with no way to tell the finance committee what the return on investment actually was.

This guide lays out a governance framework for successful modernization built around five pillars: financial evaluation, ownership structure, architectural standards, coding conventions, and the enablement activities that keep adoption going. It is based on a real-world enterprise transition led by Yuri at Verifone (for further details, see Yuri's KotlinConf talk and case study).

While written around modernizing Java codebases with Kotlin, the same framework applies more broadly across stack transitions.

Financial governance

Technology modernization proposals compete for capital against infrastructure work, product features, and operational improvements. To win those budget conversations and make sound decisions, engineering leaders need the same financial vocabulary that finance committees use.

Three models carry the most weight in stack modernization decisions. Net Present Value (NPV) calculates the present worth of all future cash flows from the initiative, discounting them at the organization's required rate of return. A positive NPV indicates value creation at the chosen discount rate, although organizations may set a higher portfolio threshold. Internal Rate of Return (IRR) is the discount rate at which the initiative breaks even. An IRR above your organization's cost of capital signals the project creates value. Total Cost of Ownership (TCO) captures what NPV and IRR often miss by including the ongoing operational costs of running the modernized stack, such as toolchain licensing, training, maintenance, and any migration-period overhead where two runtimes operate in parallel.

For Kotlin adoption in a Java-dominant codebase, NPV calculations should account for the transition window upfront. A credible business case needs an estimate of how much duplicated toolchain, review, and dependency overhead adds to the NPV while both languages run in parallel.

Capital allocation gates translate NPV, IRR, and TCO into decision checkpoints. A practical structure runs three gates, starting with an initial feasibility gate requiring a documented NPV estimate and a codebase classification (covered in the Enablement Activities section), then a pilot gate requiring measured productivity and quality data from an initial adoption module, and finally a scale gate releasing broader investment only after the pilot validates the NPV model. Without these gates, modernization programs tend to either stall at the pilot stage indefinitely or expand faster than governance structures can support.

Ownership structure and governance roles

A lack of defined ownership structure and governance roles often causes the adoption process to fail. Teams end up waiting for decisions no one is empowered to make, or the process sprawls beyond control, as different teams introduce conflicting patterns, incompatible dependency versions, and local conventions that make cross-team code reviews painful.

A governance structure that assigns four named owner groups, each with a distinct scope, helps fix this by making sure every decision has a clear owner.

The Architecture Board is the cross-functional decision body responsible for module classification governance, the organization's technology radar, and change gatekeeping. It approves which modules are candidates for Kotlin adoption, maintains the approved technology list, and reviews architectural patterns before they propagate across teams. Board membership typically spans architects and CTOs from multiple business functions.

Platform Engineering owns the toolchain baseline that every team runs on. This includes standardized build systems’ configurations, the approved Kotlin version matrix, shared CI/CD pipeline templates, and the artifact repository policies that control which dependencies can enter the build. When Platform Engineering ships a build system convention plugin that encodes the approved Detekt ruleset and Ktlint configuration, teams get compliant pipelines by default, without extra work on their part.

The Security and Compliance group owns supply chain controls and risk assessment for the technology transition. For Kotlin adoption specifically, this means evaluating the Software Bill of Materials (SBOM) implications of new Kotlin-specific dependencies, setting policy on how platform types from Java interop are handled in security-sensitive code paths, and reviewing the process for Kotlin compiler and library upgrades.

The Kotlin Guild is the community layer that the other three groups depend on to function. The Kotlin Guild provides the practitioner layer of governance and enablement, running peer reviews, curating internal knowledge resources, hosting internal talks on idiomatic patterns, and serving as the first escalation path for teams encountering adoption friction. A guild helps ensure that governance's policy documents actually get translated into working practice.

The governance model only works if every role has a named owner with explicit authority. Shared ownership of the architecture board agenda, or a guild with no dedicated time allocation in engineering capacity planning, produces the same outcome as no governance at all.

Architecture best practices

During a technological modernization transition, architectural governance needs to decide where the new stack or language is introduced and what rules govern the boundaries between legacy and modern components. Leaving these open leads to inconsistent integration across teams.

The Architecture Board's module classification determines adoption order. Modules with high test coverage, well-defined service boundaries, and low coupling to legacy architecture are better candidates for early adoption than modules tightly woven into shared legacy infrastructure. New services and greenfield modules are natural starting points because they carry no migration overhead at boundaries. For existing systems, teams should establish clear API and domain boundaries before expanding adoption, decomposing tightly coupled components where necessary to reduce interop complexity.

A comprehensive interoperability policy defines how legacy and modern code coexist. Explicit standards should govern type mapping, boundary annotations, and nullability or safety guarantees across the runtime boundary to prevent runtime errors and ensure seamless cross-language calling conventions.

For public API surfaces, architects should inspect compiled representations and intermediate metadata prior to publishing. Conducting public API surface reviews catches boundary mismatches, unexpected dependency shapes, and compatibility issues before downstream consumer services depend on them.

Coding conventions and enforcement

Coding standards require both a documented reference guide and an automated enforcement mechanism. Establishing clear organizational conventions covers naming schemes, source organization, formatting, and public API documentation standards to maintain maintainability across distributed teams.

IDE-level enforcement provides real-time guidance to developers as they write code. Shared inspection and formatting profiles committed directly to version control automatically propagate standards across developer workspaces, flagging stylistic deviations prior to build or PR submission.

Automated CI gatekeeping combines formatting checks and static analysis tools to maintain quality across builds. Static analysis rules should cover design complexity, code smells, and security risks. Using baseline configurations during initial adoption allows organizations to suppress pre-existing legacy issues while strictly gating new changes.

In practice, the policy decision involves sorting violations into ones that block merges and ones that are just advisory. For example, in a Java-to-Kotlin transition, Ktlint's formatting violations block merges, as do high-severity Detekt rules like unused variables, null-safety bypasses, and excessive cyclomatic complexity. Lower-severity style suggestions are presented as advisory warnings and accumulate in the Detekt HTML report without blocking the pipeline.

Enablement activities

Governance structures and tooling create the conditions for successful adoption, but sustaining it needs some specific enablement activities.

People and capability building

A governance framework that requires Kotlin without building Kotlin capability leads to resentment. Structured training tracks are the investment that makes the rest of the framework work.

JetBrains Academy provides an in-IDE learning experience built around real coding tasks with instant feedback, structured into modular tracks that cover Kotlin fundamentals through advanced topics, including collections, coroutines, and testing. Integration with IntelliJ IDEA lets developers practice in the same environment they'll use for production work. For organizations that need credentialed outcomes, the Kotlin Professional Certificate by JetBrains, hosted on LinkedIn Learning, is an approximately 11-hour structured program covering Kotlin essentials, object-oriented and async code, and multiplatform development, with a final exam and a shareable certificate.

Progression milestones are worth defining explicitly. For example, you could use a three-stage model that runs from Kotlin Reader (can understand and review Kotlin code), to Kotlin Contributor (can write idiomatic Kotlin in an existing codebase), to Kotlin Author (can design new Kotlin modules and mentor others). Pairing each stage with a concrete deliverable (a completed JetBrains Academy track, a reviewed pull request, an internal knowledge-sharing session) keeps the progression from being purely notional.

Code infrastructure and tooling

Standardized build infrastructure prevents the configuration drift that makes cross-team work painful. Platform Engineering's responsibility here is to publish a Gradle convention plugin that encodes the organization's approved Kotlin version, the Detekt configuration with the agreed ruleset and baseline, the Ktlint version and .editorconfig settings, and the approved dependency management rules including any version catalog entries.

Teams applying this plugin get compliant builds without reconstructing the configuration themselves. The version matrix (which Kotlin releases are approved, under evaluation, or deprecated) lives in a versioned document owned by Platform Engineering and reviewed on a defined cadence, such as quarterly. An internal support policy should make that cadence explicit, with upgrade reviews scheduled rather than triggered when someone notices a new release.

An immediate action plan for teams starting this work follows a short sequence. First, classify your organization's existing codebases using a simple readiness matrix that covers test coverage, coupling to legacy internals, team familiarity with Kotlin, and strategic importance. Modules that score well on the first three and high on the fourth are your first adoption candidates. Second, draft the interop policy as a two-page document covering the annotation rules and platform-type handling described above. Third, stand up the Kotlin Guild with a founding group of volunteers before you need it (guilds that form in response to a crisis rarely build the community cohesion that makes them useful).

Bringing the framework together

The five pillars of this framework (financial governance, ownership structure, architectural standards, coding conventions, and enablement activities) are individually straightforward. The difficulty is running them in parallel rather than sequentially, because each one creates conditions the others depend on.

Financial governance gives the program political durability. Ownership structure gives it accountability. Architectural standards prevent the technical fragmentation that kills adoption at scale. Coding conventions and CI enforcement make sure those standards are applied in practice, not just aspirational. Enablement activities ensure the organization can execute what the governance structure requires.

This framework draws on a field-tested, practical approach to enterprise tech stack modernization and Kotlin adoption. JetBrains tooling (from IntelliJ IDEA's built-in Code Style enforcement and bytecode inspection to the JetBrains Academy training tracks) is integrated directly into the governance infrastructure described here, reducing the friction of putting the framework into practice.

Review the complete Enterprise Playbook for detailed guidance on enterprise stack modernization and Kotlin adoption at kotlinlang.org/lp/enterprise-playbook/. Have you started classifying your organization's codebases for technology stack readiness? Share your approach in the comments.

Handling Auth in Next.js 16 with Server Actions and Middleware

Aniket Bhattacharyea — Mon, 12 Oct 2026 10:44:27 +0000

TL;DR: Authentication in Next.js has changed significantly — patterns like client-side session hooks and middleware-only authorization can become insecure in a server-first application. Auth0's Next.js SDK v4 aligns with the App Router by replacing legacy route handlers, simplifying session access across server contexts, and supporting route protection.

Authentication in Next.js has changed significantly over the last few major releases. With Next.js 16, the framework fully embraces a server-first architecture: Server Components render on the server by default, Server Actions execute mutations server-side, and the App Router pushes developers toward colocated backend logic rather than traditional API-centric patterns.

That shift changes how authentication should be implemented. Patterns that worked well in older Next.js applications, such as client-side session hooks, /api/auth/* route handlers, and middleware-only authorization checks, can become awkward or even insecure in a server-first application. Session assumptions that were safe in client-heavy architectures no longer hold with Server Actions. Many developers upgrading existing applications discover that older Auth0 integration patterns simply no longer map cleanly to the App Router model.

Instead of working around the framework, the latest Auth0 Next.js SDK is designed specifically for this architecture and integrates directly with the server-first model that Next.js 16 promotes. In this guide, you will learn how to build a production-grade authentication layer in a Next.js 16 App Router application using Auth0’s Next.js SDK v4. This article will cover:

The architectural shift from SDK v3 to v4
How proxy.ts replaces legacy auth route handlers
Session access patterns in Server Components, Server Actions, and API routes
Practical route protection strategies
Security considerations that matter in real-world deployments

What Changed in Auth0 Next.js SDK v4 (and Why It Matters)

Before App Router and Server Components became the default, authentication in Next.js typically revolved around API routes. In the Pages Router era, Auth0 integrations commonly looked like this:

// pages/api/auth/[auth0].ts

import { handleAuth } from '@auth0/nextjs-auth0';

export default handleAuth();

Protected API routes used wrappers like:

withApiAuthRequired()

Session access relied on request/response objects:

getSession(req, res)

This model worked well because applications were heavily request-oriented. Rendering often happened client-side or through getServerSideProps, and API routes formed the natural backend boundary. Next.js 16 changes the execution model entirely. Server Components run directly on the server without explicit request handlers. Server Actions execute independently from page renders, and route segments can stream progressively. The framework assumes that most logic lives server-side from the beginning.

The diagram below shows how Auth0 SDK v4 aligns directly with that architecture, tracing a request from initial HTTP call through to protected mutation.

Instead of manually defining /api/auth/[auth0], the SDK now auto-mounts authentication routes like /auth/login, /auth/logout, /auth/profile, etc. when you include a properly configured proxy.ts file (more on this file in the next section).

The SDK also simplifies configuration substantially. For example, you can create a shared Auth0 client with only one line of code:

// src/lib/auth0.ts

import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client();

The SDK automatically reads environment variables like AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_SECRET, APP_BASE_URL

This minimal, boilerplate-free setup is intentional. The SDK naturally integrates into the Next.js server-first runtime rather than requiring extensive bootstrapping code.

The biggest practical change is session access. Instead of:

getSession(req, res)

you now use:

await auth0.getSession()

with no request or response arguments.

That works because the SDK reads encrypted session cookies directly from the current server execution context.

The proxy.ts Pattern

The most important architectural concept in Auth0 SDK v4 is proxy.ts.

In Next.js 16, proxy.ts acts as a request interceptor that executes before the framework processes a route. It replaces the former middleware.ts convention, with the new name emphasizing that this code runs at the network boundary and can rewrite, redirect, or modify requests and responses before they reach your application routes. For Auth0, this interception point allows the SDK to handle authentication routes and session-related processing before the request continues into the application.

Here is the standard implementation:

// src/proxy.ts

import type { NextRequest } from 'next/server';
import { auth0 } from './lib/auth0';

export async function proxy(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    /*
     * Match all request paths except:
     * - _next/static
     * - _next/image
     * - favicon.ico
     * - sitemap.xml
     * - robots.txt
     */
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

This file is the mechanism that enables the SDK to intercept and handle authentication routes automatically. Without it, requests to /auth/login or /auth/callback will typically return 404 errors.

Note: If your application uses a src/ directory, the proxy.ts file must live inside this src directory. Otherwise, it belongs at the project root. Misplacing the file often causes silent failures where auth routes return 404s even though the SDK appears configured correctly.

Understanding the matcher pattern

The matcher pattern is more important than it initially appears.

This line tells Next.js which requests should pass through the Auth0 proxy layer:

'/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)'

The exclusions affect both performance and security. For example, paths like _next/image serve optimized image requests, which should not be intercepted as this can introduce unnecessary auth processing overhead and break asset delivery. On the other hand, paths like favicon.ico and robots.txt are public assets that should not be protected behind authentication. You must also set up the matcher to exclude any other public routes in your app, but be careful not to accidentally exclude sensitive paths, as this may cause them to bypass auth interception entirely. This is why you should treat matcher configuration as part of your security model, not merely routing boilerplate.

Auto-mounted routes

Once proxy.ts is configured, the SDK automatically mounts several auth endpoints:

/auth/login
/auth/logout
/auth/callback
/auth/profile
/auth/access-token
and others

These routes are now part of the SDK contract, and you no longer need to manually implement them yourself.

Session Access in the Server with Components, Actions, and API Routes

One of the most important concepts in Next.js 16 authentication is understanding that each server execution context behaves differently. Server Components, Server Actions, and API routes all run on the server, but session access patterns are not identical across them.

Server Components

Server Components are the cleanest place to access session state. Because they execute directly on the server, they can read encrypted session cookies without any client-side round trip.

Here is an example:

// app/dashboard/page.tsx

import { redirect } from 'next/navigation';
import { auth0 } from '@/lib/auth0';

export default async function DashboardPage() {
  const session = await auth0.getSession();

  if (!session) {
    redirect('/auth/login');
  }

  return (
    <main>
      <h1>Welcome, {session.user.name}</h1>
    </main>
  );
}

getSession() reads directly from encrypted cookies. If no session is found, the user is redirected. No API request is required, and no token exchange happens during rendering. The redirect occurs server-side before protected content renders. This is both simpler and more secure than relying on client-side auth checks after hydration.

Server Actions

Server Actions are where many developers accidentally introduce security gaps. Even though Server Actions execute on the server, they are invoked independently from the client. That means they cannot assume the session state from a previous page render is still valid, and every Server Action must re-validate authentication explicitly.

For example:

// app/actions/update-profile.ts

'use server';

import { auth0 } from '@/lib/auth0';

export async function updateProfile(data: FormData) {
  const session = await auth0.getSession();

  if (!session) {
    throw new Error('Unauthorized');
  }

  const userId = session.user.sub;

  // Protected mutation logic
  await saveUserProfile(userId, data);
}

Some developers see this repeated session validation as redundant, but it is not. Server Actions are independent execution contexts. A user may have logged out, had their session invalidated, or switched accounts between the initial render and the action invocation. That is why you should treat every Server Action as a fresh authenticated request in order to avoid critical authorization bugs.

API routes

For API routes, the SDK still provides a convenient protection wrapper:

// app/api/admin/route.ts

import { auth0 } from '@/lib/auth0';

export const GET = auth0.withApiAuthRequired(async function GET() {
  return Response.json({
    success: true,
  });
});

This is often the most straightforward approach for protected APIs because unauthenticated requests automatically receive a 401 Unauthorized response.

Accessing User Data and Tokens

Once you have a session, you can access user information directly:

const session = await auth0.getSession();

const user = session?.user;

If you need to call a third-party API on behalf of the user, you can also retrieve the access token:

const token = await auth0.getAccessToken();

Route Protection Strategies

There is no single “correct” protection strategy in Next.js 16. The right approach depends on how much of your application is private and how centralized you want authorization logic to be.

Page-level protection

The most explicit strategy is protecting individual pages:

const session = await auth0.getSession();

if (!session) {
  redirect('/auth/login');
}

This approach gives maximum control and clarity since you can tweak the authorization logic for each page.

Protecting individual pages works especially well when:

Only some routes are protected
Authorization rules vary per page
You need custom redirect logic

The downside is repetition at scale. Having this guard for every page can get too verbose.

Layout-level protection

For larger applications, layout-level protection is usually more maintainable.

For example, this specifies that everything nested under /dashboard now requires authentication automatically:

// app/dashboard/layout.tsx

import { redirect } from 'next/navigation';
import { auth0 } from '@/lib/auth0';

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const session = await auth0.getSession();

  if (!session) {
    redirect('/auth/login');
  }

  return <>{children}</>;
}

This is often the best tradeoff for applications with clearly separated public and private route segments, such as a CMS with a public homepage and a dashboard for authenticated users.

proxy.ts-level protection

For applications where nearly every route requires authentication, protection can move even higher into the request pipeline. You can extend the proxy matcher to blanket-protect large portions of the app. This reduces duplication and centralizes enforcement. However, it is usually less flexible than page or layout-level checks for applications that mix public marketing pages with authenticated dashboards.

Using useUser()

So far, you have seen how we can authenticate the user on the server. But what about user profile access on the client-side? The SDK also provides a client-side hook:

useUser()

useUser() is useful for authentication and authorization in the UI, such as conditional UI rendering, user avatars, client-side personalization, navigation states, etc., but it should not be trusted for authorization decisions. Client-side state can be stale, manipulated, or temporarily inconsistent. For anything involving data access, mutations, permissions, or protected rendering, you should always validate using getSession() on the server.

Security Considerations

The following are some of the most common security tips that you should keep in mind when using Auth0 with Next.js Server Actions and Middleware.

AUTH0_SECRET rotation

The AUTH0_SECRET environment variable encrypts session cookies. If it changes, existing cookies can no longer be decrypted, resulting in errors like JWEDecryptionFailed.

In practice, users may need to clear cookies or re-authenticate after secret rotation. This becomes particularly important in CI/CD environments where secrets may accidentally differ across deployments.

Allowed callback, logout, and origin URLs

These Auth0 dashboard settings are security controls, not just configuration details.

Examples include:

Allowed Callback URLs
Allowed Logout URLs
Allowed Web Origins

These settings protect against malicious redirect flows and unauthorized origins. If they do not match your deployed application URLs exactly, authentication flows will fail intentionally.

Do not trust client-side session state

Authorization decisions should always happen server-side. This principle deserves repeating:

useUser() is for UI
getSession() is for authorization in the server

Relying on the client state for protected actions is one of the easiest ways to introduce privilege escalation bugs into Next.js applications.

Protect environment variables

Secrets like AUTH0_CLIENT_SECRET must never be exposed to the client bundle. Fortunately, Next.js only exposes variables prefixed with NEXT_PUBLIC_ to client-side code. None of the Auth0 secrets use that prefix, so they are safe from being exposed by Next.js.

However, they can still be accidentally made public. To prevent that, always store them in a .env file, and never check it into version control.

Rethinking Auth in the Server Actions Era

Authentication in Next.js 16 requires a different mindset than earlier generations of the framework. The App Router, Server Components, and Server Actions fundamentally change where code executes and how you trust boundaries should be enforced.

In this guide, you learned how Auth0’s Next.js SDK v4 aligns with that architecture by replacing legacy route handlers with the proxy.ts interception model, simplifying session access through server-native APIs, and supporting protection strategies that scale from individual pages to entire application segments. You also saw why session validation must happen independently across Server Components, Server Actions, and API routes, and why server-side authorization remains essential even in highly interactive React applications.

Auth0 is the identity platform behind all of this: developer-first, deeply flexible, and designed to scale from a weekend project to enterprise-grade infrastructure without forcing teams to trade control for convenience.

The Next.js SDK v4 is a strong example of that philosophy in practice. Instead of layering abstractions on top of the framework, it embraces the Next.js server-first architecture directly through patterns like proxy.ts, server-native session access, and streamlined configuration. The result is an authentication model that feels natural inside modern Next.js applications while still supporting the advanced authorization, multi-tenant identity, and extensibility requirements that growing applications eventually need.

Type-Safe Authentication in Rust with Auth0 and Axum

Aniket Bhattacharyea — Mon, 12 Oct 2026 10:36:40 +0000

CLI tools are deeply embedded in modern developer workflows. But while browser-based authentication is naturally integrated into web applications, and desktop and mobile applications work well with it, CLI applications present a unique challenge: there is no available browser or redirect URL to complete a standard OAuth login flow.

This is exactly the problem the OAuth 2.0 Device Authorization Flow was designed to solve. Rather than redirecting users within the application, the CLI requests a temporary device code, displays a short verification URL and user code, and waits while the user authenticates in their browser. Once complete, the CLI receives tokens it can use for authenticated operations. You have likely encountered this flow before without realizing it. Smart TVs, IoT devices, and headless servers all rely on it when launching or redirecting to a browser is inconvenient or impossible.

In this tutorial, you will build a complete end-to-end system in Rust and Axum using Auth0. First, you will create a Rust CLI that authenticates users using the Auth0’s Device Authorization Flow and retrieves both an ID token and an access token. Then, you will build an Axum API to validate that access token before allowing access to a protected route. Together, these two pieces demonstrate the full authentication and authorization lifecycle: one application obtains trust, and another verifies it.

Prerequisites

To follow along with this tutorial, you will need:

An Auth0 account. You can sign up for free.
The Rust toolchain installed on your system.

Configure Auth0

Start by creating a new Native Application in the Auth0 dashboard.

Open the Auth0 Dashboard, navigate to Applications > Applications, and click Create Application. Select Native and give the application a name like Rust CLI Demo, as you can see in the following screenshot.

Native applications are designed specifically for desktop applications and CLI tools that cannot securely store a client secret.

Once the application is created, open the Settings tab, scroll to Advanced Settings > Grant Types, and enable Device Code as illustrated in the screenshot below.

This step is critical because Auth0 disables the Device Authorization grant by default. If you skip it, the token polling request will fail with an unauthorized_client error that is difficult to diagnose if you do not already know the grant type is disabled.

Now, save your changes.

You will also need to copy the Domain and Client ID values from the Settings page. Store these somewhere safe, as you will need them later.

Next, you will create an API in Auth0. This represents the secure API that you will access. Navigate to Applications > APIs, click Create API, give it a name, and set an identifier such as https://rust-api-demo.example.com, as shown in the following screenshot.

This API identifier becomes the audience for your access tokens.

Now, you need to give your application access to the API. Go to Application Access and click Edit next to the name of your application. In the User-Delegated Access tab, click Grant Access. Your screen should look like the screenshot below.

Create a CLI in Rust

With Auth0 configured, you can now start writing the Rust code. The first thing you need to create is a Rust CLI that uses the Device Authorization Flow to authenticate with Auth0.

Create a new Rust workspace:

mkdir rust-auth0-demo
cd rust-auth0-demo

cargo new auth-lib --lib
cargo new auth0-cli
cargo new auth0-api

These commands create a rust-auth0-demo directory and three Rust projects within it.

Configure the workspace root Cargo.toml:

[workspace]
resolver = "2"

members = [
    "auth-lib",
    "auth0-cli",
    "auth0-api"
]

Build the Shared Authentication Library

The token verification logic lives in the shared auth-lib library crate used by both the CLI and API.

Inside auth-lib/Cargo.toml, add the following dependencies:

[dependencies]
anyhow = "1.0.102"
jsonwebtoken = { version = "10.4.0", features = ["rust_crypto"] }
reqwest = { version = "0.13.4", features = ["form", "json"] }
serde = { version = "1.0.228", features = ["derive"] }
serde_json = "1.0.150"

These dependencies each serve particular functions:

anyhow: Simplifies error handling and propagation across the application.
jsonwebtoken: Validates and decodes JWTs using Rust-based cryptographic verification.
reqwest: Sends HTTP requests to Auth0 APIs with form and JSON support.
serde: Serializes and deserializes Rust structs to and from JSON.
serde_json: Provides JSON parsing, generation, and the json! macro for structured responses.

Create the following structure in the auth-lib directory:

auth-lib/
├── src/
│   ├── lib.rs
│   ├── auth.rs
│   └── models.rs

Define typed models

Inside auth-lib/src/models.rs, define the data models, which eliminate entire categories of bugs:

use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize)]
pub struct DeviceCodeResponse {
    pub device_code: String,
    pub user_code: String,
    pub verification_uri: String,
    pub verification_uri_complete: String,
    pub expires_in: u64,
    pub interval: u64,
}

#[derive(Debug, Deserialize)]
pub struct TokenResponse {
    pub access_token: String,
    pub id_token: String,
    pub expires_in: u64,
    pub token_type: String,
}

#[derive(Debug, Deserialize)]
pub struct TokenError {
    pub error: String,
    pub error_description: Option<String>,
}

#[derive(Debug, Serialize, Deserialize)]
#[serde(untagged)]
pub enum Audience {
    Single(String),
    Multiple(Vec<String>),
}

#[derive(Debug, Serialize, Deserialize)]
pub struct UserClaims {
    pub sub: String,
    pub name: Option<String>,
    pub email: Option<String>,
    pub iss: String,
    pub aud: Audience,
    pub exp: usize,
}

#[derive(Debug, Deserialize)]
pub struct Jwk {
    pub kid: String,
    pub n: String,
    pub e: String,
}

#[derive(Debug, Deserialize)]
pub struct Jwks {
    pub keys: Vec<Jwk>,
}

Without these typed structs, authentication code often becomes fragile JSON parsing logic with unchecked assumptions about response fields. Here, every expected field is explicit and validated during deserialization.

Implement JWT Validation

Inside auth-lib/src/auth.rs, add the logic that verifies the JWT:

use anyhow::Result;
use jsonwebtoken::{
    decode,
    decode_header,
    Algorithm,
    DecodingKey,
    Validation,
};
use reqwest::Client;

use crate::models::{Jwks, UserClaims};

const DOMAIN: &str = "YOUR_DOMAIN";

pub async fn validate_token(
    token: &str,
    audience: &str,
) -> Result<UserClaims> {

    // Decode JWT header
    let header = decode_header(token)?;

    let kid = header
        .kid
        .ok_or_else(|| anyhow::anyhow!("Missing kid"))?;

    // Fetch JWKS
    let client = Client::new();

    let jwks: Jwks = client
        .get(format!(
            "https://{}/.well-known/jwks.json",
            DOMAIN
        ))
        .send()
        .await?
        .json()
        .await?;

    // Find matching key
    let jwk = jwks
        .keys
        .into_iter()
        .find(|k| k.kid == kid)
        .ok_or_else(|| anyhow::anyhow!("No matching JWK"))?;

    // Build RSA decoding key
    let decoding_key = DecodingKey::from_rsa_components(
        &jwk.n,
        &jwk.e,
    )?;

    // Configure validation
    let mut validation =
        Validation::new(Algorithm::RS256);

    validation.set_audience(&[audience]);

    validation.set_issuer(&[
        &format!("https://{}/", DOMAIN)
    ]);

    // Decode and validate
    let token_data = decode::<UserClaims>(
        token,
        &decoding_key,
        &validation,
    )?;

    Ok(token_data.claims)
}

The validate_token function verifies that a JWT was genuinely issued by Auth0 and has not been tampered with. It fetches Auth0’s public signing keys (JWKS), selects the correct key using the token’s kid, validates the token signature and claims such as issuer and audience, and finally deserializes the payload into a strongly typed UserClaims struct.

Here, you can again see Rust’s strong typing in action. The deserialization into the UserClaims struct guarantees the presence of all the required fields. If any field is absent, you get a hard error instead of silently failing parsing.

Finally, export the modules in auth-lib/src/lib.rs:

pub mod auth;
pub mod models;

Build the CLI and Device Authorization Flow

To start building the CLI and device authorization flow, first, move into the CLI project:

cd auth0-cli

Add the following dependencies in Cargo.toml:

[dependencies]
anyhow = "1.0.102"
jsonwebtoken = { version = "10.4.0", features = ["rust_crypto"] }
reqwest = { version = "0.13.4", features = ["form", "json"] }
serde = { version = "1.0.228", features = ["derive"] }
serde_json = "1.0.150"
tokio = { version = "1.52.3", features = ["full"] }
auth-lib = { path = "../auth-lib" }

Request the device code

Before you can add a function to request the device code, which is the first step in the authorization flow, you need to add the following imports and variables inside auth0-cli/src/main.rs:

use anyhow::Result;

use auth_lib::{
    auth::validate_token,
    models::{
        DeviceCodeResponse,
        TokenError,
        TokenResponse,
    },
};

const DOMAIN: &str = "YOUR_DOMAIN";
const CLIENT_ID: &str = "YOUR_CLIENT_ID";
const AUDIENCE: &str = "YOUR_AUDIENCE";

Note: This code hardcodes the domain, client ID, and audience values for simplicity. These values are not sensitive and can be safely stored in code. For more flexibility or to store sensitive secrets, you can use a crate like dotenv to store values as environment variables.

Make sure you replace the placeholder values with the data from Auth0.

Add the request_device_code() function in main.rs to request the device code and start the Device Authorization Flow:

async fn request_device_code() -> Result<DeviceCodeResponse> {

    let client = reqwest::Client::new();

    let response = client
        .post(format!(
            "https://{}/oauth/device/code",
            DOMAIN
        ))
        .form(&[
            ("client_id", CLIENT_ID),
            ("scope", "openid profile email"),
            ("audience", AUDIENCE),
        ])
        .send()
        .await?;

    let device_code = response
        .json::<DeviceCodeResponse>()
        .await?;

    Ok(device_code)
}

This endpoint makes a request to /oauth/device/code in your Auth0 domain with the client ID, scope, and audience data. Auth0 returns a short-lived device code along with instructions for the user.

Poll for the token

Once the code is retrieved, the next step is to show the user the code and the login URL. Since a CLI has no redirect URL or callback mechanism, the only way to know when the authorization is finished is to poll for the status in regular intervals.

Add the following code in main.rs:

async fn poll_for_token(
    device_code: &str,
    interval: u64,
) -> Result<TokenResponse> {

    let client = reqwest::Client::new();
    let mut interval = interval;

    loop {

        let response = client
            .post(format!(
                "https://{}/oauth/token",
                DOMAIN
            ))
            .form(&[
                (
                    "grant_type",
                    "urn:ietf:params:oauth:grant-type:device_code"
                ),
                ("device_code", device_code),
                ("client_id", CLIENT_ID),
            ])
            .send()
            .await?;

        if response.status().is_success() {
            return Ok(
                response
                    .json::<TokenResponse>()
                    .await?
            );
        }

        let error = response
            .json::<TokenError>()
            .await?;

        match error.error.as_str() {

            "authorization_pending" => {
                println!("Waiting for authentication...");
            }

            "slow_down" => {
                println!("Slowing polling interval...");
                interval += 5;
            }

            "expired_token" => {
                anyhow::bail!("Device code expired");
            }

            "access_denied" => {
                anyhow::bail!("User denied access");
            }

            other => {
                anyhow::bail!(
                    "Unhandled error: {}",
                    other
                );
            }
        }

        tokio::time::sleep(
            tokio::time::Duration::from_secs(interval)
        )
        .await;
    }
}

The poll_for_token function repeatedly checks Auth0’s token endpoint to see whether the user has completed authentication in the browser. This function:

Sends the device code obtained earlier
Handles all possible OAuth device authorization flow responses such as authorization_pending, slow_down, and access_denied,
Waits between polling attempts using Tokio’s async sleep
Returns the access and ID tokens once authentication succeeds.

Once again, the strong typing ensures that the JSON has all the required fields.

OAuth device authorization flow responses are inherently asynchronous, and Rust forces you to consciously handle every possible outcome using the match statement instead of silently ignoring error states.

Wire the two functions

Finally, wire these two functions together in the main function:

#[tokio::main]
async fn main() -> Result<()> {

    let device =
        request_device_code().await?;

    println!(
        "Visit:\n{}",
        device.verification_uri_complete
    );

    println!(
        "Code: {}",
        device.user_code
    );

    let token = poll_for_token(
        &device.device_code,
        device.interval,
    )
    .await?;

    println!("Access Token: {}", token.access_token);

    Ok(())
}

The main function calls the request_device_code function, prints the verification URL and the device code, and calls the poll_for_token function. The access token returned from this function is printed.

You can run the CLI by executing cargo run. You should see an output like this:

Visit:
https://your-tenant.auth0.com/activate?user_code=ABCD-EFGH
Code: ABCD-EFGH
Waiting for authentication...
Waiting for authentication...
Waiting for authentication...

Once you visit the URL in your browser, you will be prompted to log in with Auth0. You can use an existing Auth0 account to log in or create a new account. Once you log in, Auth0 generates a token, which your code will automatically fetch. You will see the access token printed in the terminal:

Access Token: eyJhbGciOiJSUzI1NiIsIn....

Note that this example prints the access token for demo purposes only. In a real-world application, you should never log the access token.

Fetch the Authenticated User

The token returned from the poll_for_token function also includes an ID token, which contains information about the user's identity. The CLI can validate the ID token and extract information about the user, like name or email.

Add the following function in the same file:

fn say_hi(claims: &auth_lib::models::UserClaims) {

    let name = claims
        .name
        .as_deref()
        .unwrap_or("user");

    println!("Welcome, {}!", name);
}

This function extracts the name field from a UserClaims object and prints a greeting.

You can also fetch the user info from the /userinfo endpoint by passing the access token.

Change the main function to call the validate_token function and pass the returned claims to say_hi:

#[tokio::main]
async fn main() -> Result<()> {

    let device =
        request_device_code().await?;

    println!(
        "Visit:\n{}",
        device.verification_uri_complete
    );

    println!(
        "Code: {}",
        device.user_code
    );

    let token = poll_for_token(
        &device.device_code,
        device.interval,
    )
    .await?;

    let claims = validate_token(
        &token.id_token,
        CLIENT_ID,
    )
    .await?;

    say_hi(&claims);

    println!(
        "Access token:\n{}",
        token.access_token
    );

    Ok(())
}

Now, when you run it, you will see the user's name being printed:

Visit:
https://your-tenant.auth0.com/activate?user_code=ABCD-EFGH
Code: ABCD-EFGH
Waiting for authentication...
Waiting for authentication...

Welcome, Alice!

Access token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

At this stage, you have a fully authenticated CLI application using Auth0’s Device Authorization Flow.

Protect an Axum API Route with Auth0

Now that the CLI can retrieve an access token, the next step is building a protected API accessible through it.

Move into the API project:

cd ../auth0-api

Add dependencies to Cargo.toml:

[dependencies]
auth-lib = { path = "../auth-lib" }

axum = "0.8"
tokio = { version = "1", features = ["full"] }
serde_json = "1"

Axum is a modern asynchronous web framework for Rust built on top of Tokio and Hyper. With its simple and modular design, Axum makes it easy to route requests to handlers with a macro-free API and generate responses with minimal boilerplate. This tutorial uses Axum to create a protected API route that validates Auth0 access tokens before allowing access to authenticated users.

Create a JWT extractor

The first step in protecting your API route is creating a JWT extractor middleware that reads the Authorization header, extracts the Bearer token, validates the JWT, and rejects invalid tokens with 401 Unauthorized.

Inside auth0-api/src/main.rs, add the following code:

use axum::{
    extract::FromRequestParts,
    http::{request::Parts, StatusCode},
    routing::get,
    Json,
    Router,
};

use serde_json::json;

use auth_lib::{
    auth::validate_token,
    models::UserClaims,
};

const AUDIENCE: &str = "YOUR_AUDIENCE";

pub struct AuthUser(pub UserClaims);

impl<S> FromRequestParts<S> for AuthUser
where
    S: Send + Sync,
{
    type Rejection = (
        StatusCode,
        Json<serde_json::Value>,
    );

    async fn from_request_parts(
        parts: &mut Parts,
        _state: &S,
    ) -> Result<Self, Self::Rejection> {

        let auth_header = parts
            .headers
            .get("Authorization")
            .and_then(|v| v.to_str().ok())
            .ok_or((
                StatusCode::UNAUTHORIZED,
                Json(json!({
                    "error":
                    "Missing authorization header"
                })),
            ))?;

        let token = auth_header
            .strip_prefix("Bearer ")
            .ok_or((
                StatusCode::UNAUTHORIZED,
                Json(json!({
                    "error":
                    "Invalid bearer token"
                })),
            ))?;

        let claims = validate_token(
            token,
            AUDIENCE,
        )
        .await
        .map_err(|err| (
            StatusCode::UNAUTHORIZED,
            Json(json!({
                "error": "Invalid token",
                "details": err.to_string(),
            })),
        ))?;

        Ok(AuthUser(claims))
    }
}

This middleware centralizes authentication logic so that protected routes only execute if validation succeeds.

Create the protected route

The API validates the access token. If the token is valid, a message is shown:

async fn protected(
    AuthUser(claims): AuthUser,
) -> Json<serde_json::Value> {

    Json(json!({
        "message":
            "You are seeing a protected route",

        "subject": claims.sub,
    }))
}

Create the main function to set up the router:

#[tokio::main]
async fn main() {

    let app = Router::new()
        .route("/protected", get(protected));

    let listener = tokio::net::TcpListener
        ::bind("0.0.0.0:3000")
        .await
        .unwrap();

    println!("Server listening on port 3000");

    axum::serve(listener, app)
        .await
        .unwrap();
}

Call the API from the CLI

The final step of the whole flow is for the CLI to call the API and pass the access token in the Authorization header. Add the following function in auth0-cli/src/main.rs:

async fn call_api(access_token: &str) -> anyhow::Result<()> {
    let client = reqwest::Client::new();

    let response = client
        .get("http://localhost:3000/protected")
        .bearer_auth(access_token)
        .send()
        .await?;

    if response.status().is_success() {
        let body: serde_json::Value = response.json().await?;

        println!("API response:");
        println!(
            "{}",
            serde_json::to_string_pretty(&body)?
        );
    } else {
        println!(
            "API returned {}",
            response.status()
        );

        let body = response.text().await?;
        println!("{}", body);
    }

    Ok(())
}

This code calls the protected route you created in the previous step, passes the access token, and prints the response in the terminal.

Test the Full Flow

To test the flow, first, run the API server from the auth0-api directory:

cargo run

Authenticate using the CLI as before. The CLI will call the API, and you should see the success response:

{
  "message": "You are seeing a protected route",
  "subject": "google-oauth2|123456789"
}

You can find the full app on GitHub.

Rust, Auth0, and Axum Bring Type-Safe Authentication to Your CLI

In this tutorial, you built a complete authentication flow in Rust using Auth0 and Axum. The CLI used Auth0’s Device Authorization Flow to securely authenticate users in a browserless environment, while the Axum API validated the resulting access token before allowing access to protected endpoints. Rust’s type system plays an important role throughout the implementation, with typed API responses preventing malformed OAuth responses from slipping through silently.

From here, you could add refresh token support to keep the CLI authenticated across sessions, extend the Axum server with role-based authorization using Auth0 custom claims, or explore fine-grained authorization for relationship-based access control.

The same Auth0 platform that powers this example also scales to MFA, enterprise SSO, and multi-tenant B2B identity as your needs grow. Check out the Auth0 documentation and the Device Authorization Flow guide to keep building.

How to Be the Best Tutorial Writer in the Room

Aniket Bhattacharyea — Wed, 26 Aug 2026 12:34:57 +0000

There's a special kind of pain reserved for people who follow a tutorial at 11 PM and hit a wall on step 4 because the author renamed a variable between step 3 and step 5 and never told you. You stare at your terminal. The error makes no sense. You check the code four times. Eventually you realize the tutorial was never run, start to finish, by a human being — it was assembled from memory, vibes, and whatever the author thought they did six months ago.

I don't want to be that person, and after enough tutorials spanning across clients like Docker, Auth0, JetBrains, and others, I've settled on a short list of things that actually separate a tutorial that works from one that just looks like it does. None of this is exotic. It's mostly discipline, applied at the right moments, and a healthy suspicion of your own memory.

I'm not going to talk about the same old boring advices like "Improve your English, use your own language." I myself am not a native English speaker, and I write very simple sentences -- no flowery language, no complicated prose -- and I can tell you that no client has ever questioned me about that. I'm going to give you some real advice, battle tested with real clients.

Disclaimer: All of the points below are my own advice, learned from my experience with Draft.dev. These aren't absolute gospels, and you shouldn't take them as such.

1. Clearly Define the Article Requirement

Before you write a single sentence, know what the article is actually supposed to deliver. Not the topic — the shape. Is this a 500-word "here's a neat trick" post, or a 3,000-word soup-to-nuts build? Does it stand alone, or does it assume the reader already has your last three articles' worth of setup done? Is the deliverable a working demo app, or is the demo just scaffolding to explain one specific concept?

I cannot stress enough the advantages of creating an outline before you start writing. I prefer to collect all the information I can from my clients, including details about their company, their product, and the topic, and create an outline with it. An outline gives you the basic shape of the article and tells you what to do, and what not to do.

You can download a copy of the "content plan" template I use with my clients here.

2. Create a Compelling Scenario

Once you know the requirement and before you touch the audience question, decide what the demo app is actually about. This is where a lot of otherwise-solid tutorials go flat, because the author reaches for the most generic possible container for the feature they're demonstrating.

Say you're writing a tutorial about authentication and authorization. The lazy version of the prompt to yourself is "let's create a basic app and add authn and authz." Technically accurate, and it produces exactly what it promises: a to-do list or a "hello, dashboard" page with a login screen bolted onto it, and a role check somewhere that simply prints your roles on an HTML page. Nobody remembers that tutorial a week later, because there was nothing to remember.

Compare that to: "let's build a CMS where anyone can sign up, write and publish articles, but can't delete someone else's article." Same underlying feature -- authn and authz -- but now it's a scenario, not a checklist item, and the scenario does several things the generic version can't:

It forces you to define real roles before you write any code, because "someone else's article" only means something once you've decided who owns what. That's authorization design, not authorization theater.
It gives you a built-in negative test case for free. "User B tries to delete User A's article and gets blocked" is a genuinely satisfying moment to demonstrate -- readers get to see the authorization actually stop something, instead of trusting your word that the middleware is wired up correctly. A generic "protected route" demo never gets to prove a negative like that.
It reads well in a title and in a search result. "How to Build a CMS with Role-Based Permissions" gets clicked. "How to Add Authn and Authz to a Basic App" reads like a boring text.
It gives your screenshots something to be of. A login form looks like every other login form ever screenshotted. An article list with a greyed-out delete button next to someone else's post is an image that actually explains the feature at a glance.

A compelling scenario is really the requirement and the audience decisions from the last two points, made concrete enough to build. If your scenario is interesting enough, half of your outline writes itself, because the scenario itself implies the steps: sign-up, write a post, publish it, try to break it as someone else. Boring scenarios don't do that work for you -- you end up having to invent steps to pad the tutorial out, and padding is always the first thing a reader notices.

Note: A compelling scenario doesn't have to be elaborate. It just has to be specific enough that a stranger, reading only the title, already has a rough guess of what the finished thing does. Don't get carried away and try to make it too complex.

3. Clearly Define the Audience

This ties to the previous point as this is part of the outline for me, but it's so important that this requires its own paragraph. This is the single biggest lever on how much detail you show, and it's the one people skip because they think they already know. "Developers" is not an audience. "Someone who's shipped a REST API before but has never touched OAuth" is an audience.

Audience determines everything downstream: whether you explain what a JWT is or just link to a reference, whether you spell out npm install or assume it, whether you show the full error message or just say "if you see an auth error, check your redirect URI." Undershoot the audience and you lose beginners on page one. Overshoot it and your expert reader skims past three paragraphs of npm install ceremony looking for the one paragraph that matters, and maybe doesn't find your article again next time.

I write a one-line audience note to myself before drafting — something like "assumes React familiarity, zero assumption of Next.js server actions" — and I keep it visible while writing. Every time I'm about to explain (or skip explaining) something, I check it against that line instead of against my own head, because my own head thinks everything is obvious by the third read-through.

Here's a concrete example of how audience shapes the article details for me. Imagine I am teaching how to create a Next.js app. If my audience is a beginner who has zero to minimal Next.js experience, I'll start with:

Run the following command to create a Next.js app:

npx create-next-app@latest my-app --yes

Now move into the directory by running "cd my-app" and start the dev server by running "npm run dev"

But if my audience is intermediate or expert in Next.js, I'll write:

Create a Next.js app and start it.

Note: There is one situation where I'll spell out the details irrespective of the audience. That is, if I'm doing something that is not the default. For example, I'm using a different version of a tool, or passing a non-default option to the command.

4. Build the App First, to Know It Works

This should not need saying, and yet. Before you write a word of prose, build the actual thing, end to end, on your machine, from a clean slate if you can manage it. Not "I did something like this six months ago and it's basically the same." Build it now with the versions of the tools that exist.

The reason this matters isn't pride — it's that software drifts under you while you're not looking. An SDK bumps a major version and renames a constructor argument. A framework moves from pages to app router. A CLI flag gets deprecated with a warning nobody reads. If your mental model of "how this works" is even a few months stale, you will confidently write down something that used to be true.

This happened to me on my own side project, actually — not an article, but close enough to sting the same way. I stubbed an external client in my tests, the tests passed, and I moved on trusting that green checkmark. Then I ran the app for real and discovered that the library had changed its constructor from keyword arguments to positional ones between the version I remembered and the installed version. My stub accepted anything, so nothing caught it. The lesson transfers directly to writing: a test (or an article) that was never run against the real thing isn't verification; it's a nice story you're telling yourself.

This is also useful when you're writing about a client's product. Many clients -- typically young startups -- don't pay as much attention to their documentation as they do to their marketing. Often, their docs will say "do X to get Y," but when you actually try it, you'll discover it doesn't work. Either the feature doesn't exist, but the Sales team got excited and claimed boldly that it's available, or that the docs were hallucinated by an AI, or maybe it worked at some point, but something changed, and nobody updated the docs.

That's why build it first. Confirm it works. Then start writing about it. As you build the app, try to develop a mental model of the steps you will show in the article, in what order. Building the app will tell you everything you need to do to get it working. You can write it down or memorize it. Either way, you now have a solid foundation of what works and what doesn't.

5. Build the App Once More as You Write

Here's the part people skip because they just did step 4, so surely they remember what happened. You don't, not precisely enough. The gap between "I built this, and it worked" and "I wrote down, in order, the exact commands and code that make it work" is wider than it feels.

As you write each step, actually perform that step again, right then, and paste in what genuinely happened — not what you remember happening. This catches the stuff that ruins tutorials: the config value you tweaked halfway through and forgot to write down, the folder you created out of order, the environment variable you set in one terminal tab and never mentioned. Writing and rebuilding in lockstep turns your article into a transcript of something real rather than a summary of something remembered.

Building the app as you write the article will also let you capture screenshots and outputs immediately, making the article feel more alive. More on this later.

6. Build the App One More Time as You Go Through the Final Copy

By the time you're proofreading, you're reading your own writing, and your own writing is exactly the thing you're least equipped to catch errors in — you know what you meant, so your eyes helpfully autocorrect what you wrote. A missing cd into the right directory, a code block that's missing the import you added at the last minute, a step that got reordered when you moved a paragraph for flow and never noticed the code above it now depends on something that hasn't happened yet.

The fix is unglamorous: go through the final copy one more time, but instead of just reading it, execute it, literally, in a fresh terminal, following your own instructions exactly as written rather than as intended. Not "run something like this" — copy the actual commands out of your own article and run those. This is the pass that catches the copy-paste artifact from an earlier draft, the snippet that references a variable you renamed three sections ago, the step you accidentally deleted while editing for length.

Three build passes sound like a lot until you consider that each one is catching a completely different class of mistake: the first confirms the thing is possible, the second confirms your narration of it is accurate, the third confirms your edited, final narration is still accurate after you've been moving paragraphs around for an hour.

The next few tips are "cosmetic." They don't improve the correctness of your article, but they make it better by a huge margin.

7. Show Full File Paths in Code Snippets

A code block that starts with export default function Page() { and nothing else creates more questions than it answers. Where does this go? Is it a new file? Does it replace something? Which folder, at what level, relative to what?

Show the actual path, every time, even when it feels repetitive: frontend/src/app/api/quote/route.ts, not route.ts. Especially in a monorepo, or anything with more than one plausible src/, guessing the path is exactly the kind of low-value puzzle that makes a reader feel dumb for a reason that has nothing to do with their skill and everything to do with your laziness. Full paths cost you only a few extra words per snippet and save the reader a headache and a moment of quiet resentment toward you specifically.

Here you might argue that if the audience is an expert, surely they can figure out where to put the code if I say "the quote route" instead of frontend/src/app/api/quote/route.ts, and that's a valid argument. I prefer to reduce confusion as much as possible, so I almost always mention the full path, regardless of the audience. Better safe than sorry.

8. Clearly Indicate Where to Put the Code

Adjacent to the path problem, but distinct: a snippet with a correct path can still land in the wrong place inside that file. "Add this" is not an instruction. "Add this snippet at the top of frontend/src/lib/strapi.ts, right after the existing imports" is. "Replace the return statement at the bottom of the handler function with the following" is. Say whether it's a new file, an insertion, or a replacement, and say exactly where the insertion point is relative to something the reader can already see in their own editor.

This matters more, not less, as snippets get shorter. A ten-line code block dropped in the middle of a paragraph with no context is the single most common way I've seen a technically correct tutorial become a frustrating one — not because the code was wrong, but because the reader had to guess what to do with it and guessed wrong.

Don't refer to code by line number, like "Paste this code after line 15." Even if a reader has been following your article and has been copy pasting the exact codes from your article, they may end up having different line numbers. The most common reason is IDE auto-formatting that automatically formats the code as they paste. The reader themselves may decide to format the code in a different way. Always indicate lines via some sort of marker, like "Paste this after the closing tag."

9. Provide Screenshots, Outputs and a Repo

Three different deliverables, all necessary in my opinion.

The screenshot has two jobs. One, it is proof, aimed at the reader following along: "here's what it should look like when you get this right," so they can check their own result against something concrete instead of just trusting that the code compiled. It's also aimed at people skimming to decide whether the article is worth their time at all — a screenshot of a real, working thing does more convincing in half a second than three paragraphs of description.

It's second purpose is to give the reader a visual cue. A screenshot of the web page with the button circled in red is easier and faster to understand than "Click the small + button in the top right corner of the page."

Note: Two things you must never forget with screenshots: Point out the interesting things (for example, circle the button you want the reader to click, or put an arrow next to it) and include an alt text and caption.

The code outputs have a similar responsibility as the screenshots. They provide a visual indicator. If the user gets the same output as you, they will know they are on the right path. To switch things up a bit (or to save yourself for pasting a huge output), you can also indicate what to look for. For example, "If the status command shows Running, you're good to go.

The repo is the escape hatch, aimed at the reader who's stuck. Tutorials are read out of order, skimmed, half-followed, interrupted by lunch. A linked repo at the final commit state means "I did something slightly wrong three steps back" doesn't have to become "I give up" — it becomes "let me diff my folder against theirs." Also, a repo is a better proof of "It works" than a screenshot. Someone can simply check out the repo and test whether the app works or not before deciding to read your article. I link a repo on effectively everything now, and it's the single piece of feedback I get thanked for most often, more than any clever explanation in the prose itself.

I link the repo twice. The first link is before starting the tutorial section, saying something like "All the code I am using in this article can be found in this repo." This gives the reader the escape hatch mentioned earlier before they actually start investing into the tutorial. The second link is after the tutorial is over, with something like "You can check out the full app in this repo." This works as a "tie everything together" moment. If they didn't check out the repo earlier, they can do so now, and compare their app with mine.

A couple of principles I follow when creating a repo for my tutorials:

The repo should be the exact same as what my article produces. I basically use the repo I got from following step 6. This makes sure someone who is reading the article gets the exact same app as someone who simply checked out the repo. I don't do any "final touches" or improvements over what the article has. If I must, I make sure it's not an extensive functionality change. For example, I used basic CSS in the article, but that looks ugly, so I added some CSS styles in the final app. This is ok. But using SQLite in the article because it's easy, but changing it to PostGreSQL in the repo is too big of a change. Not cool.
Sometimes I may provide a starter version of an app. In case the initial setup is too long, I provide a small prebuilt app that I want the reader to use as a starting point for the article. In that case, I provide the starter version and the final version in different branches of the same repo. Starter version in starter and final version in main, or starter version in main and final version in final -- choose whatever suits you.

10. Provide a List of Prerequisites

How many times have you started reading a tutorial and halfway through you realized, "Looks like I need an AWS account for this. No one made that clear!" You don't want to be the person who leaves their readers in the dark about what they need for the tutorial. That's why I add a prerequisites section before the tutorial actually starts. There, I list:

The tools that are needed, e. g. Docker, Node.js
The versions of the tools, where to install them, and which versions I used.
If any third-party tools or services are needed, and where to sign up for them.
If the tools behave sufficiently differently based on OS.

Here's one example prerequisite section:

To follow along with this tutorial, you will need:

* An Auth0 account. You can sign up for free [here](link-to-auth0-registration).
* The latest version of Node.js. This article uses version 22.0.1. You can download Node from [here](link-to-node-website).

Be the Tutorial Nobody Has to Debug

None of the ten points above are secret techniques picked up from some technical writing seminar. Every one of them is really the same instinct wearing a different hat: don't trust what you think you know, trust what actually happened five minutes ago on your own machine. Every "vibes" tutorial I've ever gotten burned by skipped some of these -- usually not out of laziness, but because it felt done already, and the deadline was in three hours.

That's the trap, and it's the same trap every time. A tutorial reads as finished to its author long before it's finished for the reader, because the author already knows what everything means. The reader doesn't. Every point above is just a way of closing that gap -- one more rebuild, one more real file path, one more screenshot, one more line telling them what account to go create before they get 60% of the way in and hit a wall you knew was coming.

I've written these for clients and the ones that got read, bookmarked, and pasted into someone's internal wiki were never the ones with the cleverest explanation of why something works. They were the ones that just worked, on the first try, for a total stranger, with no help from me sitting next to them. That's the whole job. Everything else is decoration on top of that one requirement.

So if you want to be the best tutorial writer in the room, here's the short version: be the one whose tutorial nobody has to debug.

Building a Privacy-Focused Social Media: What It Taught Me

Aniket Bhattacharyea — Fri, 07 Aug 2026 08:43:10 +0000

I've been working on a side project called Vidha for the past few months. It's a social platform with a somewhat unusual premise: instead of choosing between "public" and "private" like every other platform, you control exactly who sees what about you, and it's not just "show my profile picture to my friends and hide it from the public." You can show different versions of every piece of information you enter in Vidha. You can show a formal picture in suits to your office colleagues, the picture you took on your vacation to your close friends, and the picture with your fiancée to your family — all at the same time. Each attribute is scoped to an audience you define.

I want to be upfront: this is purely a personal educational project. There's no company behind it, no funding, no roadmap I'm pitching to anyone. I built it to learn. Specifically, I wanted to understand what actually goes into building a social platform — not the surface-level stuff, but the data model decisions that haunt you at 2 am three weeks in.

This article is about the things that surprised me, the decisions I made and would change, and the problems that turned out to be much harder than they looked.

Tech Stack

Before diving in, here's what I built this with:

Layer	Choice
Framework	Rails 8.1 with Ruby 3.4.9
Database	PostgreSQL
Frontend	Hotwire (Turbo + Stimulus), Tailwind CSS v4
Auth	Devise (with `:confirmable`)
Activity Feeds	GetStream.io (`stream-ruby` v6)
Background Jobs	Solid Queue
Rich Text	ActionText
Deployment	Railway
Dev Environment	Nix devenv

I deliberately chose a "boring" stack. I'm a big fan of Rails because of how robust it is, and how easy it is to get started. The hard problem here is the domain — the visibility system, the feed logic, the moderation — not the infrastructure. Rails is good at getting out of the way, and that's what I needed.

The Core Idea: Audiences, Not Privacy Modes

The central concept in Vidha is groups. Every user has named groups — "Public", "Followers", "Close Friends", whatever they want. Every profile attribute (display name, bio, location, profile picture) is associated with a group rather than directly with the profile. When someone views your profile, the app figures out which group they belong to and shows only the attributes you've configured for that group.

The app only requires your email and a username to register. You're free to define your own attributes, such as Location, Job, etc., and assign a type, such as String, Image, Number, or URL.

Once you define a new attribute, you can assign different values to it for different groups.

The visibility resolution logic looks like this:

def visible_attributes_for(viewer)
  group = group_for_viewer(viewer)
  return {} unless group

  attribute_definitions
    .joins(:attribute_values)
    .where(attribute_values: { group_id: group.id })
    .pluck("attribute_definitions.name", "attribute_values.value")
    .to_h
end

And the group resolution itself:

def group_for_viewer(viewer)
  public_group = groups.find_by(is_public: true)
  return public_group if viewer.nil?

  membership = GroupMembership.find_by(member_id: viewer.id, owner_id: id)
  membership ? membership.group : public_group
end

Three cases: an unauthenticated visitor gets the public group, an authenticated user with a membership gets their group, and an authenticated user with no membership also gets the public group. The fallback to public means your public attributes are always visible to logged-in users who don't follow you. That's a deliberate design decision — if you've put something in your public group, you want strangers to see it.

There are a few "special" attributes (for now, only Display name and Profile picture) that the app uses automatically. Again, you're free to skip them, in which case you get a placeholder value. If you keep your display name undefined, it'll show up as "Anonymous". If you keep your profile picture set to undefined, it'll show a placeholder image.

Conceptually, this is clean. In practice, every new feature affecting profiles had to thread through the same logic, which meant many opportunities to get it subtly wrong. There are many edge cases. For example, you don't have to define the value of an attribute for every group. In that case, it falls back to the public group.

You can then attach groups to posts, and only members of those groups will see the post.

Posts and Comments Are Tricky

Oh, did I mention that posts support full rich-text, including image attachments? And so do comments. You can also mention a user by typing @, and you can reply to a comment. All of that brings new problems.

ActionText looks simple until you actually deploy it. The first surprise was CORS. ActionText supports direct uploads — the browser uploads images straight to your storage backend (in my case, an S3-compatible bucket on Railway), bypassing Rails entirely. That means your S3 bucket needs CORS headers that allow PUT requests from your app's origin; otherwise, the upload fails in production while working perfectly in development with local disk storage. I spent an embarrassingly long time trying to set CORS policies to the bucket from Railway's web dashboard, but it turns out that you need to do that via the S3 CLI. The dashboard lacks the feature.

The second surprise was unattached blobs. When a user picks an image in the editor, Active Storage creates and uploads the blob immediately — before the form is submitted. If they close the tab, navigate away, or just change their mind, that blob sits in your storage bucket forever, attached to nothing. The Rails guide shows how you can purge this using a custom Rake task, but it's up to you to perform this regularly. However, there might be an interesting edge case where your cleanup job runs while someone is in the middle of writing a post or comment and it deletes the files they had uploaded. I don't have a solution for this yet.

The third was mentions. ActionText gives you rich HTML, but @username detection has to be layered on top manually. I scan the post body's plain text for the pattern, batch-look up real users, and write GetStream notifications:

def self.notify_mentions(body, actor, post, comment_id: nil)
  text      = body.try(:to_plain_text) || body.to_s
  usernames = text.scan(MENTION_PATTERN).flatten.uniq
  return if usernames.empty?

  User.where(username: usernames).where.not(id: actor.id).each do |mentioned|
    object = comment_id ? "comment:#{comment_id}" : "post:#{post.id}"
    add_to_feed(mentioned.id, {
      actor:      "user:#{actor.id}",
      verb:       "mention",
      foreign_id: "mention:#{object}:user:#{mentioned.id}",
      post_slug:  post.slug,
      post_title: post.title
    })
  end
end

Rendering mentions as links in the stored HTML is a separate problem. ActionText's stored HTML is a sanitized fragment, so I wrote a helper that uses Nokogiri to walk the text nodes, split on the @username pattern, and replace matches with anchor tags — being careful to collect all text nodes before modifying the tree, because mutating the DOM mid-traversal skips nodes:

text_nodes = []
doc.traverse { |n| text_nodes << n if n.text? && n.content.match?(MENTION_SPLIT) }

text_nodes.each do |node|
  parts = node.content.split(MENTION_SPLIT)
  html  = parts.map do |part|
    m = part.match(MENTION_MATCH)
    m && existing.include?(m[1]) ?
      %(<a href="/users/#{CGI.escapeHTML(m[1])}">@#{CGI.escapeHTML(m[1])}</a>) :
      CGI.escapeHTML(part)
  end.join
  node.replace(Nokogiri::HTML::DocumentFragment.parse(html))
end

The Data Model Rabbit Hole

I spent a genuinely embarrassing amount of time on the data model before writing a single controller. Every entity that seemed simple on day one kept revealing a layer of hidden complexity. The biggest example: GroupMembership. My first instinct was to allow a follower to be in multiple groups simultaneously. You're my colleague and my friend — why can't you be in both the "Colleagues" and "Friends" groups?

The answer is: because then I don't know which group's attributes to show you. The visibility resolution breaks the moment a viewer can belong to more than one group. So I added a hard constraint: a follower belongs to exactly one group per owner. That one constraint simplified everything downstream. But it also meant that moving someone to a new group is a replace operation, not an add — and I had to make sure the feed subscriptions stayed in sync whenever that happened.

Another fun one: every new user automatically gets a "Public" group and a "Followers" group, created in after_create callbacks. Those two groups are protected — you can't delete them, and you can't have more than one of each. But I also had to make sure that a deleted user doesn't cascade-delete their group memberships in a way that violates foreign key constraints before the groups themselves are removed. The fix was a before_destroy callback that strips the protected flags first:

after_create  :create_public_group
after_create  :create_followers_group
before_destroy :strip_protected_group_flags, prepend: true

def create_public_group
  groups.create!(name: "Public", is_public: true)
end

def strip_protected_group_flags
  groups.update_all(is_public: false, is_followers: false)
end

The prepend: true matters — without it, dependent destroys on associations run before this callback, and you'd get constraint violations.

Activity Feeds Are Harder Than They Look

I didn't want to roll my own fan-out-on-write feed system, so I integrated GetStream. It handles the mechanics: when a post is published to a group feed, it fans out to every timeline that follows that feed. My job is just to keep the follow/unfollow graph correct. That turned out to be enough work. Here's what happens when someone follows another user:

def add_to_followers_group_and_follow_feeds
  followers_group = followed.groups.find_by(is_followers: true)
  public_group    = followed.groups.find_by(is_public: true)
  target_group    = followers_group || public_group

  GroupMembership.find_or_create_by!(group: target_group, member: follower)

  timeline = StreamClient.instance.feed("timeline", follower_id.to_s)
  timeline.follow("group", target_group.id.to_s)
  timeline.follow("group", public_group.id.to_s) if public_group && target_group != public_group
end

The follower's timeline subscribes to two feeds: the followers group feed and the public group feed. That's because a post can be shared to either group and the follower should see both.

And on unfollow:

def remove_from_group_and_unfollow_feeds
  membership   = GroupMembership.find_by(member_id: follower_id, owner_id: followed_id)
  timeline     = StreamClient.instance.feed("timeline", follower_id.to_s)
  public_group = followed.groups.find_by(is_public: true)

  timeline.unfollow("group", membership.group_id.to_s)
  timeline.unfollow("group", public_group.id.to_s) if public_group && membership.group_id != public_group.id

  membership.destroy
end

There's an edge case buried in there: if someone is in the public group (their only group), you'd call unfollow on the same feed twice. Hence the if check.

The biggest mistake I made here: I stubbed the GetStream client in tests with a double. Every test passed. Then I actually ran the app and discovered that stream-ruby v6 changed its constructor from keyword args to positional args. My stub accepted anything, so it never caught it. Lesson learned — if you're going to stub an external client, at least verify the calling convention against the actual gem.

Private Accounts and the Follow Request

When a user sets their account to private, new followers need approval. This is a common feature on social platforms and sounds simple. It is not. The core model is a FollowRequest that remains in a pending state until it is approved or rejected. But the follow flow now has four distinct paths, and each one has to keep groups, feeds, and notifications in sync:

follow(public account)    → create Follow immediately
follow(private account)   → create FollowRequest, notify owner
approve(follow_request)   → destroy FollowRequest, create Follow, assign group
cancel(pending request)   → destroy FollowRequest

I made the mistake of putting most of the side-effect logic in model callbacks — after_create and after_destroy on Follow. It kept the controllers thin, which felt clean at the time. But callbacks are hard to test in isolation, and when something went wrong, the stack trace was a mess of implicit triggers.

Also, there's a subtle interaction with Devise. I added an is_invited flag to gate access during the closed beta:

def active_for_authentication?
  super && is_invited?
end

def inactive_message
  is_invited? ? super : :inactive
end

When I changed the column default from true to false, every single test broke — 204 failures at once. The sign_in helper in RSpec goes through Warden's full session validation, which calls active_for_authentication?. All my test users had is_invited: false by default, and Warden was silently blocking them. The fix was adding is_invited: true to every User.new(...) call in every request spec. Tedious, but at least the cause was obvious once I figured it out. Lesson learned - think about closed betas as early as possible.

Invisible Mode: Like u/[deleted] But Better

Vidha also has an invisible mode for the privacy fanatics. Invisible mode is a toggle users can enable from their account settings. When it's on, the user effectively doesn't exist from anyone else's perspective: their profile returns a 404, they're excluded from search results and member typeahead suggestions, and attempting to follow them returns a 404 too. It's more private than a private account — closer to "ghost mode." The implementation is blunt but honest: every entry point that could expose the user has an explicit guard.

# UsersController
def show
  raise ActiveRecord::RecordNotFound if @user != current_user && @user.invisible_mode?
  # ...
end

def follow
  head :not_found and return if @user.invisible_mode?
  # ...
end

# Search queries exclude invisible users at the DB level
User.where("username ILIKE ?", term).where(invisible_mode: false)

The raise ActiveRecord::RecordNotFound approach is intentional — it renders the same 404 page as any other missing resource, leaking no information about whether the account exists at all. However, you can still comment (shows up as "Anonymous"), and your posts can be viewed by someone with a direct link. This is to make sure you can still use the social media as intended. I suppose this might come in handy for activists or protesters who don't want to reveal their identity, yet want to post on the platform.

One thing I'm undecided on: right now, people who already follow you can still see your timeline posts even in invisible mode (the feed subscription persists). Whether that's a bug or a feature is genuinely unclear to me. Also, this feature is pretty terrifying: Anything that can leak info about an invisible user is a big no-no, and I have to make sure every new feature respects invisible users.

Currently the best approach in my mind is this:

When an invisible user joins a community (or a visible user switches to invisible), it creates a pseudo-username, like "anon-abcde". This pseudo-username is scoped to the user and community. So the same user will get different pseudo-usernames in different communities.
This pseudo-username will be visible to the mods, and they can see the list of posts and comments by this user and ban/suspend them.
Since the same user will get different pseudo-usernames in different communities, it means if someone is a moderator in two different communities, they'll not be able to link the same user in those communities.
This pseudo-username is persistent. So, if the user changes back to visible or leaves and rejoins the community, that won't generate a new one. This prevents someone from circumventing the ban by leaving and rejoining.

Communities: Like Subreddits, But Simpler

Later in the build, I added communities — shared spaces with their own post feeds, member lists, and moderation. A community post publishes to a "community" feed on GetStream instead of the author's personal group feeds. Membership works the same way: joining subscribes your timeline feed to the community's feed, while leaving unsubscribes.

The trickiest part was access control. A post in a private community should be visible only to members. A personal post should only be visible to people in the right group. Both PostsController and CommentsController need this logic. Here's the concern I extracted:

module PostVisibility
  extend ActiveSupport::Concern

  private

  def can_view_post?(post)
    if post.community_id?
      community = post.community
      return true unless community.is_private?
      return false unless current_user
      return true if current_user.id == community.creator_id
      CommunityMembership.exists?(community_id: community.id, user_id: current_user.id)
    else
      return true if current_user&.id == post.user_id
      return true if post.groups.any?(&:is_public?)
      return false unless current_user
      GroupMembership.exists?(member_id: current_user.id, group_id: post.group_ids)
    end
  end
end

I initially had variations of this logic scattered across both controllers before I noticed I was copying code and extracted it into a separate file. I should have written it in one place from the beginning. Access control sprawl is a real thing — every new context (show, edit, destroy, comment) tempts you to just paste the check inline. I'm thinking about using an authorization gem like CanCanCan or Pundit, but I'm not sure how big a rewrite it'd be or whether it'd be worth it. Lesson learned: Think about authorization and access control from the beginning, and try to reuse the logic as much as possible.

One more thing that I'm still trying to figure out: How should invisible accounts interact with community moderation? Letting invisible accounts run rampant in a community is a recipe for disaster, so moderators should have some way of telling "invisible dude A" from "invisible dude B." One approach is to let a moderator view a "community profile" of an invisible user: just the posts they have made in that particular community, plus the ban/suspend/remove buttons. But that still doesn't answer how to identify that particular user in the user list. This is something I'm thinking about very hard.

Frontend: Hotwire Over React

I chose Hotwire (Turbo + Stimulus) and deliberately avoided React. The whole point was to stay inside the Rails idiom and keep the stack simple. For most things, this worked well. Likes are a good example — toggling a like or dislike replaces just the button component in place:

def respond_with_reaction(current_kind)
  respond_to do |format|
    format.turbo_stream do
      render turbo_stream: turbo_stream.replace(
        dom_id(@likeable, :likes),
        partial: "likes/like_button",
        locals: {
          likeable: @likeable,
          liked:    current_kind == "like",
          disliked: current_kind == "dislike"
        }
      )
    end
    format.html { redirect_back fallback_location: root_path }
  end
end

No JavaScript state management, no API endpoint, no serializer. The server renders the updated partial and sends it down the wire. For the 90% case, this is genuinely fast to build.

The 10% case is where Hotwire gets awkward: complex client-side state that doesn't map cleanly to server-rendered partials. The rich text editor with group targeting, for instance, involves coordinating ActionText, a custom group selector, and a preview — all in one form. Stimulus controllers are composable, but they don't share state easily. A few times I genuinely wished I had a React app.

What I'd Tell Myself at the Start

Model the domain on paper first. The group-based visibility system is the core of the entire app. I arrived at the right data model through iteration, but a couple of hours on a whiteboard before writing any code would have saved me a week of refactoring.

Don't stub external services in tests and call it done. Stubs lie. They accept anything and catch nothing. Either test against the real service (with a sandbox account), or write a thin adapter layer that the stub actually validates against (or read the documentation well).

Access control needs a home from day one. Don't spread visibility checks across controllers. Put them somewhere dedicated — a concern, a policy object, a query object — and route everything through it.

Callbacks hide complexity, they don't eliminate it. Model callbacks feel clean until you're debugging a 12-step trigger chain at midnight. For anything that touches external services or multiple models, a service object with explicit methods is worth the extra file.

Building Vidha has been the most effective learning exercise I've done in a while. Every feature that looks simple from the outside — following someone, liking a post, showing a profile — has a graph of constraints underneath it. You don't see that graph until you try to build it yourself.

If you're thinking about building something similar, I'd say: start with the hardest domain problem and work outward from there. The framework will take care of itself.

And if you want to check out Vidha, go ahead and sign up. Then drop a comment with your username so that I can activate your account. Expect bugs, lots of them.

Vidha is a personal side project built for my own education. It is not a commercial product.

The Best AI Code Review Tools of 2026

Aniket Bhattacharyea — Fri, 20 Feb 2026 13:25:32 +0000

Early AI code review tools had a math problem. For every real bug they caught, they flagged nine false positives. Teams got buried in comments about variable naming conventions and whitespace. They started ignoring the bot entirely. Productivity tanked.

The tools that made it past 2025 didn't just throw better models at the problem. They rebuilt how code review works from scratch.

This guide covers the AI code review tools worth using in 2026, what they're actually good at, and which specific problems they solve for your team.

The Core Problem: Context Windows vs. Large Diffs

AI reviewers break down when you feed them too much code at once. A 1,000-line diff overwhelms the context window. The model loses coherence, misses connections between changes, and falls back on pattern matching for style issues.

The same reviewer that produces noise on large diffs produces useful feedback on small ones. The tool didn't get smarter. You gave it a problem it could actually solve.

This is why the effective tools in 2026 either enforce small changes (Graphite), sacrifice depth for speed (GitHub Copilot), or index your entire codebase upfront (Greptile).

Tool Comparison Matrix

Tool	Best For	Platform Support	Analysis Depth	False Positive Rate	Price/User/Mo
Graphite Agent	Teams adopting stacked PRs	GitHub only	Deep (full codebase)	~3% unhelpful	\$40
GitHub Copilot	Existing Copilot users	GitHub only	Surface (diff-based)	Medium	\$10-39 (bundled)
CodeRabbit	Multi-platform teams	GitHub, GitLab, Bitbucket, Azure	Surface (diff-based)	Medium	\$24-30
Greptile	Maximum bug detection	GitHub, GitLab	Deep (full codebase)	Highest	\$30
BugBot	Cursor-native teams	GitHub only	Medium (8-pass diff)	Low-Medium	\$40 + Cursor

Graphite Agent

Graphite Agent combines full-codebase understanding with stacked PRs. Instead of one massive pull request, you break changes into small, dependent PRs that merge in sequence.

Here's how stacked PRs work:

Shopify reported 33% more PRs merged per developer after adoption, with 75% of PRs now going through Graphite. Asana saw engineers save 7 hours weekly, ship 21% more code, and cut median PR size by 11%.

Agent maintains an unhelpful comment rate under 3%. When it flags an issue, developers change the code 55% of the time. Human reviewers hit 49%.

The tool provides one-click fixes, resolves CI failures inline, and includes a merge queue that coordinates landing changes in order.

The constraint: GitHub-only, and your entire team needs to adopt stacked workflows. For teams that commit to this change, median PR merge time drops from 24 hours to 90 minutes.

Pricing: Team plan at \$40/user/month with unlimited reviews. Free tier for individuals. Enterprise pricing on request.

GitHub Copilot Code Review

GitHub Copilot Code Review hit general availability in April 2025 and reached 1 million users in a month. You assign Copilot as a reviewer like any teammate. It leaves inline comments with suggested fixes.

The October 2025 update added context gathering. Copilot now reads source files, explores directory structure, and integrates CodeQL and ESLint for security scanning.

What it's good at: Zero friction if you already pay for Copilot. Catches typos, null checks, and simple logic errors.

What it misses: Architectural problems and cross-file dependencies. It's diff-based, so it only sees what changed in the PR.

Pricing: Bundled with Copilot subscriptions (\$10-39/month depending on tier). Code review features not available on free tier.

CodeRabbit

CodeRabbit is the most widely installed AI code review app on GitHub and GitLab. Over 2 million repositories connected, 13 million+ PRs processed. It runs automatically on new PRs, leaving line-by-line comments with severity rankings and one-click fixes.

The advantage: Platform breadth. Supports GitHub, GitLab, Bitbucket, and Azure DevOps. Integrates 40+ linters and SAST scanners. Offers self-hosted deployment for enterprises with 500+ seats.

The limitation: Diff-based analysis. It sees what changed in the PR, not how changes interact with your codebase. Independent benchmarks gave it a 1/5 completeness score for catching systemic issues.

Pricing: Pro plan at \$24-30/user/month. Free tier with basic PR summaries. Enterprise plans with self-hosting available.

Greptile

Greptile indexes your entire repository and builds a code graph. It uses multi-hop investigation to trace dependencies, check git history, and follow leads across files.

Version 3 (late 2025) uses the Anthropic Claude Agent SDK for autonomous investigation. The tool shows you evidence from your codebase for every flagged issue.

At \$30/developer/month with a \$180M valuation after its Benchmark-led Series A, Greptile offers the deepest context-aware analysis available.

The tradeoff: Highest catch rate, but also highest false positive rate in independent evaluations. You get more real bugs and more noise.

Pricing: \$30/developer/month for unlimited reviews. Discounts for annual commitments. Open-source projects may qualify for free usage. Self-hosted and enterprise pricing on request.

BugBot

BugBot from Cursor launched in July 2025 and reviews 2 million+ PRs monthly. It runs 8 parallel review passes with randomized diff order on every PR, catching bugs that single-pass reviewers miss.

The "Fix in Cursor" button jumps you from review comment to editor with the fix pre-loaded. Discord's engineering team reported BugBot finding real bugs on human-approved PRs. Over 70% of flagged issues get resolved before merge.

The constraint: Tightly coupled to Cursor. You need a Cursor subscription, and it works best when your team already uses Cursor as their primary editor.

Pricing: \$40/user/month plus Cursor subscription. 14-day free trial. GitHub-only.

Why Smaller PRs Get Better Results

Research shows 30-40% cycle time improvements for PRs under 500 lines, with diminishing returns above that threshold. Teams using stacked PRs ship 20% more code with 8% smaller median PR size, saving roughly 10 hours per week waiting to merge.

The same AI reviewer produces signal on a 150-line diff and noise on a 1,000-line one. The tool didn't change. The workflow gave it a solvable problem.

Decision Framework

Pick based on what you're willing to change:

No workflow changes: Start with GitHub Copilot if you already pay for it. Zero setup, catches obvious bugs.

Multi-platform support: CodeRabbit is the only option that works across GitHub, GitLab, Bitbucket, and Azure DevOps.

Maximum bug detection: Greptile's full-codebase indexing finds issues other tools miss. Accept higher noise as the tradeoff.

Cursor workflow: If your team lives in Cursor, BugBot extends your existing setup.

Workflow transformation: Graphite treats code review as a systems problem. The numbers from Shopify (33% more PRs per developer) and Asana (7 hours saved weekly) came from adopting stacked workflows, not just adding AI.

Integration and Security

AI code review tools plug directly into GitHub, GitLab, and Bitbucket as automated reviewers. They integrate with CI/CD pipelines, offer IDE plugins for real-time feedback, and support webhook triggers for automatic reviews on code push.

Security varies by provider. Look for encryption in transit and at rest, SOC 2 compliance, and clear data retention policies. Some tools offer self-hosted options for maximum control. Graphite has a privacy-first approach that guarantees code stays private and isn't used for model training.

Cost ranges from \$10-50 per user monthly for standard plans. GitHub Copilot Code Review bundles with existing subscriptions (\$10-39/month). Enterprise plans with custom rules and dedicated support cost more. Self-hosted options may use infrastructure-based pricing instead of per-user costs.

What Actually Matters

The AI code review tools that survived 2025 didn't just add smarter models. They rethought workflows. Graphite built a platform around stacked changes. GitHub Copilot traded depth for zero friction. CodeRabbit went for breadth across platforms. Greptile went all-in on context. BugBot integrated tightly with an editor.

The right tool depends on what you're willing to change. If you want AI review with no disruption, GitHub Copilot works. If you need multi-platform support, CodeRabbit is your only option. If catching deep bugs matters more than noise, Greptile's full-codebase indexing finds things others miss. If your team lives in Cursor, BugBot fits naturally.

If you're willing to change how your team works, not just add a bot, Graphite treats code review as a workflow problem. Stacked PRs, AI review, and merge queue work together in ways that separate tools can't replicate. The productivity gains came from the workflow change, not just the AI.

Stacking up Graphite in the World of Code Review Tools

Aniket Bhattacharyea — Fri, 23 Jan 2026 13:07:13 +0000

A developer's guide to navigating the crowded market of AI code review assistants in 2026.

The "Review Bot" Explosion

2025 is the year every engineering team tried to automate code review. If you opened a pull request this year, chances are an AI left a comment on it. Some of those comments caught real bugs. Many did not.

The problem isn't that AI code review doesn't work. It's that the market is flooded with tools that look similar on the surface but solve fundamentally different problems. One tool might catch off-by-one errors in your IDE before you even push. Another scans your entire repository history to understand cross-file dependencies. A third lives in your GitHub comments, leaving feedback that ranges from brilliant to pedantic.

For the average developer or tech lead, it's hard to tell the difference between a wrapper around an LLM and an actual platform. This article cuts through that noise.

I'll compare five tools—Graphite, GitHub's native review, CodeRabbit, Greptile, and BugBot—using three criteria:

Depth: Does it understand your whole codebase, or just the diff?
Workflow: Does it change how you review, or just what you read?
Noise: Does it help you ship faster, or spam your PR timeline?

Let's start by categorizing these tools by what they actually do.

Category 1: The "Workflow Platform"

Tool: Graphite Agent

Graphite is an AI-augmented code review and pull request workflow platform designed to help teams ship higher-quality code faster by rethinking how reviews and merges work. It integrates AI feedback directly into pull requests, supports stacked pull request workflows, and provides automated merge orchestration.

When you open a pull request with Graphite, the Graphite Agent provides AI-driven feedback directly in the PR page. It focuses on delivering high-signal insights rather than large volumes of superficial comments. The platform is built to help teams catch substantive bugs and issues early in the review cycle.

A key workflow innovation is stacked pull requests. With the Graphite CLI and tooling, developers can create a series of dependent PRs—each building on the last—so you can continue working on PR #3 while PR #1 and #2 are still under review. When an earlier PR merges, subsequent stacked changes are automatically rebased, helping reduce merge conflicts and keeping development unblocked.

Graphite also includes a stack-aware merge queue. Instead of merging PRs sequentially and running CI for each one in isolation, the merge queue can batch and test multiple PRs in parallel once they’re ready, speeding up the merge process and reducing wait times.

In addition to AI review and stacking workflows, Graphite offers a modern PR review interface with unified inboxes, GitHub integrations, a CLI, and editor extensions (e.g., VS Code). These features aim to streamline the development and review experience and reduce context switching.

Best for: Teams that find traditional GitHub review workflows slow or fragmented, and that would benefit from structured, smaller changesets, automated rebasing, and integrated AI feedback throughout the pull request lifecycle.

Pricing:

Free (Hobby): Essentials, including CLI for stacked PRs, VS Code extension, and limited access to Graphite Agent and AI reviews.
Starter: $20/user/month (billed annually), includes support for all GitHub organization repos and team insights.
Team: $40/user/month (billed annually), adds unlimited Graphite Agent access, unlimited AI reviews, review customizations, automations, and merge queue.
Enterprise: Custom pricing with advanced controls, security features, and support.

Category 2: The "Native Giant"

Tool: GitHub

GitHub’s native code review workflow is the baseline most teams start from. It is reliable, familiar, and requires no additional tooling beyond what teams are already using for source control and pull requests.

GitHub has added AI-assisted review features through Copilot (including Copilot for Business and Copilot Enterprise). These capabilities can summarize pull requests, explain changes, and suggest improvements directly in comments. In practice, the quality of these suggestions varies: some feedback is genuinely helpful, while other comments are generic or low value. Importantly, Copilot acts as an assistive layer rather than a fully autonomous review agent.

A core limitation is architectural. GitHub’s pull request model is fundamentally linear: one branch, one PR, one review lifecycle. There is no native support for stacked or dependent pull requests, which makes it harder to work on large changes incrementally without introducing workflow friction.

For static analysis and security scanning, GitHub offers CodeQL. Public repositories get CodeQL scanning by default. For private repositories, full CodeQL integration—security alerts, dashboards, and UI support—requires GitHub Advanced Security, which introduces additional cost and setup. CodeQL analysis is deep and reliable, but it prioritizes correctness over speed and is not optimized for fast, conversational PR feedback like AI-first reviewers.

Best for: Teams that value stability and minimal workflow disruption, and that prefer to stay within the existing GitHub ecosystem. If adopting new tools or changing review workflows is a hard sell, GitHub’s native features are often “good enough” for baseline review automation.

Notable limitation: Merge queue availability is restricted to higher-tier GitHub plans and is not universally accessible. Many teams still merge PRs sequentially and run CI per-PR rather than benefiting from batch testing.

Category 3: The "Comment Bots"

Tool: CodeRabbit

CodeRabbit is a feature-rich AI code reviewer that operates entirely within pull request comments. It combines large language models with a broad set of linters and security scanners to generate comprehensive feedback on code changes. In addition to identifying issues, it can generate PR summaries, create sequence diagrams, suggest fixes, and propose test cases.

The breadth of analysis is both its main strength and its primary trade-off. CodeRabbit surfaces a wide range of findings, but this often includes stylistic feedback and minor suggestions alongside substantive issues. As a result, teams frequently invest time in tuning configuration and rules to reduce noise and focus the output on what matters most for their codebase.

CodeRabbit integrates with major source control platforms, including GitHub, GitLab, Bitbucket, and Azure DevOps. It also provides a VS Code extension that enables pre-PR review, allowing developers to catch issues before opening a pull request. This broad platform support makes it suitable for organizations operating across multiple repositories or hosting providers.

Best for: Open source maintainers or teams that want extensive automated feedback directly in their existing PR workflow, without introducing a new review interface. Its multi-platform support is particularly valuable for organizations that are not GitHub-only.

Pricing: Offers a free tier with basic features such as PR summarization. Paid plans are approximately $24–$30 per user per month (Pro), depending on billing, and unlock advanced analysis and customization options.

Category 4: The "Deep Context" Engine

Tool: Greptile

Greptile takes a fundamentally different approach. Instead of analyzing just the PR diff, it builds a full graph of your codebase—understanding how functions connect, where code is used, and how similar patterns have evolved over time.

This deep context means Greptile can catch issues that span multiple files or reference historical changes. It's like having a reviewer who has memorized your entire repository. The trade-off is complexity: Greptile requires more setup and resources than a simple diff-based tool.

Greptile emphasizes enterprise features: self-hosted deployment, custom AI models, SOC 2 compliance, and support for both GitHub and GitLab. You can run it on-premises if your security team requires it.

Best for: Large codebases where understanding cross-module dependencies is critical. If you're working on a system with millions of lines of code and complex architectural patterns, Greptile's full-repo analysis catches issues that simpler tools miss.

Pricing: ~$30/user/month (cloud), enterprise negotiation for on-prem. 100% off for open-source and 50% off for startups.

Category 5: The "Pre-Merge" Hunter

Tool: BugBot (by Cursor)

Bugbot is a narrowly focused AI code review tool designed to identify logic bugs and security issues with a low false-positive rate. Rather than acting as a full code review or workflow platform, it concentrates on surfacing concrete, actionable problems in code changes.

Bugbot primarily operates on GitHub pull requests. When a PR is opened, it automatically reviews the diff and leaves comments highlighting potential bugs, edge cases, or security concerns. For users of the Cursor IDE, flagged issues can be opened directly in the editor, where suggested fixes can be applied or modified before committing updates.

The tool is optimized for depth over breadth. It intentionally avoids stylistic feedback and general code quality suggestions, focusing instead on issues that are likely to cause incorrect behavior or security risk. Bugbot also supports custom review rules, allowing teams to encode project-specific constraints and conventions.

The primary limitation is scope. Bugbot does not aim to replace a full code review platform: it does not generate PR summaries, manage approvals, or integrate with project management workflows. Its role is confined to automated detection of substantive bugs within pull requests.

Best for: Individual contributors or teams who want automated, high-signal bug detection during PR review—especially those already using Cursor. It can be particularly useful in environments where logic or security defects carry a high operational cost.

Pricing: Bugbot offers a limited free tier for Cursor Teams and Individual plan users. Paid plans are approximately $40 per user per month, depending on usage limits and team features, and are available as add-ons to Cursor plans.

Comparison Matrix

Feature	Graphite	GitHub	CodeRabbit	Greptile	BugBot
Installation	GitHub App + CLI	Native	GitHub App	GitHub App + API	GitHub App
Primary Focus	Workflow + AI	Manual Review	PR Comments	Deep Context	PR Comments
Analysis Scope	PR diff + context	PR diff	PR diff + linters	Full repo graph	Current PR + existing PR comments
Noise Level	Very Low (~5%)	Varies	Medium-High	Low	Very Low
Stacked PRs	✅ Native	❌	❌	❌	❌
Merge Queue	✅	Enterprise only	❌	❌	❌
Pricing	$20-40/user	Included + Copilot	$12-30/user	~$30/user	Limited usage included with Cursor

Which Tool Fits Your Stack?

There's no universal winner. The right choice depends on where your team is blocked.

If your bottleneck is the review process itself—PRs sit too long, developers get blocked, context-switching kills momentum—Graphite's workflow improvements matter more than any AI feature. The stacked PRs and merge queue can cut review time from days to hours, even before the AI comments help.

If you're fully invested in GitHub and Microsoft tools, the native features are adequate. You won't get workflow improvements, but you also won't need to onboard a new platform.

If you need cross-platform support or want comprehensive coverage including linters and security scanners, CodeRabbit delivers. Be prepared to tune its configuration to reduce noise.

If you're working on a massive legacy codebase where understanding historical context is critical, Greptile's full-repo analysis is worth the complexity.

If you're already using Cursor IDE and want to catch bugs before they are merged, BugBot is the most focused solution.

The real question isn't "which AI reviewer is best?" It's "what's actually slowing down my team's shipping velocity?" Answer that first, then pick the tool that addresses it.

What are you running in production? Are you trusting AI to auto-approve yet, or strictly using it for summaries? I'm curious what everyone else is seeing. Drop a comment below.