kotest

name

kotest

description

Write a new Kotlin test, or modernize an existing one, using Kotest matchers and idiomatic Kotlin test style — backticked names, apply/assertSoftly blocks, and existing object mothers and helpers. Use when adding a test for behavior that does not yet have one, or when improving a Kotlin test that still uses JUnit assertions or AssertJ chains. Assumes project test infrastructure exists; flag missing factories or helpers rather than building them here.

Kotest

Produce one high-quality Kotlin test in idiomatic style with Kotest matchers.

Two tracks, one skill:

• Create — write a new test for described behavior.
• Modernize — rewrite an existing Kotlin test to Kotest + idiomatic style.

Pick the track at step 1 based on inputs. The rest of the skill is the same knowledge applied to either starting point.

Non-negotiables

• Do not build broad new test infrastructure inside this skill. If a needed factory / helper / DSL is missing, add a minimal inline fallback and tell the user that extraction may be warranted separately.
• Do not change production code to make a test easier, unless the user asks.
• Modernize track only: preserve assertion semantics exactly. Order sensitivity, nullability, and exception types must not change.
• Follow project overlay (references/project.md) if present — it overrides shared defaults. The overlay is where framework-specific context lives (base classes, test annotations, single-test command, factory locations).

Step 1 — Pick the track

• Modernize if a specific Kotlin test file/class was named, or the user said "improve / rewrite / migrate / modernize this test".
• Create if the user described a behavior to cover, or pointed at production code without an existing test.

If input is a Java test file, this skill does not port it. Suggest the user either (a) describe the behavior so we run the Create track, or (b) manually stage a skeleton Kotlin test for us to run the Modernize track on.

Once the track is picked, follow the corresponding procedure below.

---

Create track

1. Understand the behavior

Read the production code the test will exercise:

• The class/method under test and its collaborators.
• Any validation, exception branches, or ordering guarantees that shape assertions.
• Existing tests nearby — use them as style reference and to avoid duplicating coverage.

If the behavior is ambiguous, ask the user before writing the test.

2. Scan for reusable infrastructure

Before writing, search for what to reuse:

• Object-mother / factory functions (typically *ObjectMother.kt, TestData.kt).
• Kotlin extensions on domain types (toDto(), Iterable<T>.names()).
• Test helpers for setup/teardown or I/O wiring.
• DSLs for object-graph assembly.
• Project base classes for tests (see references/project.md overlay).

If required infra is missing, add a minimal inline fallback or stop and flag it to the user. Do not quietly grow shared infra here.

3. Write the class header

• Pick the test base class or annotations indicated by the project overlay. If there is no overlay, use a plain class with collaborators wired via constructor parameters.
• Follow references/idiomatic-patterns.md for collaborator wiring and naming.

4. Write each test method

For each scenario:

1. Name — backticked sentence: `should reject duplicate tag names`().
2. Arrange — call existing factories; pass only arguments that matter.
3. Act — invoke the behavior.
4. Assert — Kotest matchers (references/kotest-matchers.md).

Assertion style:

• Scalar: actual shouldBe expected.
• Non-null: value.shouldNotBeNull() (smart-casts).
• Collection sizing: list shouldHaveSize n.
• Ordered: list shouldContainInOrder listOf(...).
• Any-order: list shouldContainAllInAnyOrder listOf(...).
• Field projection: items.map { it.name } shouldContainInOrder listOf(...).
• Exceptions: shouldThrow<X> { ... }.message.shouldContain("...").
• Multiple fields on one object: result.apply { ... }.
• Several related checks reporting together: assertSoftly { ... }.

Each assertion must add independent semantic coverage. Do not restate fields already proven by a full-object equality. Do not wrap conditions in assertTrue — use a matcher that describes what the condition means.

5. Run the focused test

Use the single-test command defined in the project overlay. If none is specified, the project's usual test runner with a class-name filter is the right default.

If it fails: first confirm the assertion is correct for the behavior. A green test with the wrong assertion is worse than a red one. If production code is wrong, flag to the user — do not weaken the test.

6. Report

• New file path.
• Which existing infrastructure was reused.
• Any inline fallbacks added (and whether shared extraction is warranted).
• Scenarios covered / intentionally out of scope.
• Exact verification command.

---

Modernize track

1. Read the source test

Record the existing:

• Test framework hooks and annotations — preserve them verbatim.
• Collaborator wiring style (fields vs constructor).
• Any setup/teardown behavior.

These must not drift during modernization. Changing them silently is a bug.

2. Scan for reusable infrastructure

Same scan as the Create track. Existing factories / extensions / helpers are almost always underused in pre-Kotest tests — swap them in during this pass.

3. Modernize structure first, style second

Work in this order — the class must compile between each step:

1. Switch mutable collaborator fields to constructor parameters where the test framework allows it. Keep lateinit var for fields that a framework mechanism requires (consult project overlay).
2. Rename camelCase test methods to backticked sentences, preserving intent: shouldCreateTalk → `should create talk`.
3. Leave assertions untouched for now. Only after compilation is clean, move on to the assertion rewrite.

4. Rewrite assertions to Kotest matchers

Apply the rewrite tables in references/kotest-matchers.md. Key rules:

• assertEquals(expected, actual) → actual shouldBe expected
• assertNotNull(v) → v.shouldNotBeNull()
• assertNull(v) → v.shouldBeNull()
• assertEquals(n, list.size) → list shouldHaveSize n
• assertTrue("x" in msg) → msg shouldContain "x"
• assertThrows<X> { ... } → shouldThrow<X> { ... }
• assertThat(x).isNotNull() → x.shouldNotBeNull()
• assertThat(list).containsExactly(...) → list shouldContainInOrder listOf(...)
• assertThat(list).containsExactlyInAnyOrder(...) → list shouldContainAllInAnyOrder listOf(...)
• assertThat(items).extracting("name")... → items.map { it.name } shouldContain...
• assertThatThrownBy { ... }.isInstanceOf(X::class.java).hasMessageContaining("y") → shouldThrow<X> { ... }.message.shouldContain("y")

Do not translate long AssertJ chains 1:1. Prefer explicit property assertions with apply { }.

5. Apply idiomatic blocks

For multiple field checks on one result, group with result.apply { ... } (references/idiomatic-patterns.md). Wrap in assertSoftly { ... } when all failures should be reported together. Don't wrap sequential dependent assertions in assertSoftly — earlier failures should stop the test there.

6. Simplify factory calls

Revisit DTO/entity construction:

• Prefer zero-arg when defaults suffice: createSpeakerRequest().
• Pass only assertion-relevant or uniqueness-critical arguments.
• Do not restate default values just because the pre-modernization test spelled them out.

If the test hand-constructs objects and no factory exists, leave the construction inline. Do not create factories inside this skill — flag it to the user as a follow-up.

7. Remove redundant assertions

If a full-object equality already proves a field, drop the per-field check. Keep only assertions that add independent semantic coverage (ordering, exception details, nullability, values not otherwise covered).

8. Clean up imports

Remove:

• org.assertj.core.api.Assertions.*
• org.junit.jupiter.api.Assertions.*
• Helpers that are no longer referenced.

Add the Kotest imports listed in references/kotest-matchers.md.

9. Run the focused test

Use the single-test command defined in the project overlay.

Iterate until green. Common causes of failure:

• Order-sensitive matcher where an any-order matcher was needed, or vice versa.
• Nullability mismatch between original Java-sourced types and Kotlin non-null types.
• Missing Kotest matcher import.
• Backticked name not escaped properly.

10. Report

• File modernized.
• Track taken (Modernize).
• What changed at the structure level (wiring, naming).
• Which existing infrastructure was newly adopted.
• Semantics-sensitive decisions (ordering / exceptions / nullability).
• Exact verification command.

---

Common pitfalls (both tracks)

• Hand-building DTOs when a factory exists: scan for create*Request, *Dto.toEntity(), etc. before constructing manually.
• Restating factory defaults: if the factory defaults email = "[e-mail]", do not re-pass it named-argument-style.
• assertTrue(cond) wrappers: always replace with a specific matcher.
• Assertion inflation: adding field-level checks that duplicate what a full-object equality already proves.
• Wrong assertSoftly scope: it is for "report all related failures together", not for sequential dependent assertions.
• Coroutine tests without runTest: suspend functions must run inside runTest { ... } (or the project's test-dispatcher wrapper).
• Silently dropping framework hooks (Modernize track): setup/teardown annotations, transaction boundaries, and active profiles must carry over verbatim. Dropping them can cause intermittent pollution that only fails under certain run orders.

Project overlay

If references/project.md exists in this skill's directory after install, it overrides the shared defaults. This is where framework-specific context belongs (e.g. Spring Boot test types, base classes, single-test command, mocking library, factory locations). The skill itself stays framework-neutral.