Test Authoring

Kotlin test authoring

Purpose

Write Kotlin tests that are simple to read and complete in verification. Prefer the smallest deterministic test that uses real collaborators; use a narrow integration test before replacing those collaborators with mocks.

Requirements and limitations

This skill owns Kotlin unit and narrow integration tests: pure/domain logic and a bounded application or persistence boundary. Prefer real production collaborators when they are deterministic and cheap to assemble; use a narrow repository/database or framework slice when that is the smallest way to prove its contract. A test must remain deterministic and independently diagnosable.

Do not use this skill to create or execute E2E, browser, live-service, or broad full @SpringBootTest tests. Hand those requests to the repository's dedicated E2E workflow. Do not run an E2E-profile detector merely to choose a Kotlin test framework. Use only dependencies and verification commands already supported by the target repository.

Instructions

1. Detect before writing

Inspect the target repository before selecting a style or base class:

1. Read the affected module's build.gradle[.kts] or pom.xml, version catalog, and test-task/surefire configuration.
2. Sample nearby unit tests and their small shared test utilities. Record the actual framework(s), versions, assertions, extensions, fixture conventions, and enabled engines.
3. Follow those conventions unless they conflict with a correctness requirement. Do not add a framework, engine, or dependency merely to write a test.

Route progressively:

If framework/configuration evidence is unavailable, keep the test framework-neutral and ask only if the choice would change the implementation materially.

Discovery budget

Framework selection must be evidence-based but small: inspect the affected module's build/test configuration and at most 8 nearby unit or narrow-integration tests. Record primaryFramework, engine version when discoverable, spec/annotation style, fixture base, coroutine-test evidence, and mock-library evidence in the handoff. Do not recursively read test directories, search generated output, inspect E2E infrastructure, or load both Kotest and JUnit guidance unless the build actually has a mixed suite.

2. Authoritative rules

This table is the single normative definition of the TST-n rule set. Supporting principles and KB files may cite these IDs for rationale or framework-specific examples, but must not assign them another meaning.

In generated Kotlin tests, use it for a non-nested single-parameter lambda. Name an inner parameter only when nested lambdas need scope disambiguation; preserve API-required names for multi-parameter lambdas.

The rules above are the operational contract. Read principles only when a rationale or disputed tradeoff needs explanation. Use the KB index only when the detected case has no direct route above; do not load either document before an ordinary supported test.

3. Mock selection gate

Before creating a mock, classify the collaborator and choose the first viable option:

1. Use a real value object or domain object.
2. Use the real deterministic in-process collaborator.
3. For an external adapter, use an isolated narrow integration test against its actual protocol, serializer, mapping, transaction, or framework boundary.
4. Use a small stateful fake when real infrastructure is impractical and state transitions are the contract.
5. Use a strict mock for the remaining external boundary, failure injection, or contractual interaction.

A private helper or fake is not automatically better than a mock. Do not mirror a production interface merely to satisfy a constructor. Keep deterministic pipeline stages real and replace only terminal I/O. If a shared fake claims adapter parity, execute common contract cases against both. Keep mocks strict and assert only contract-bearing interactions.

Read Test doubles and mocks when a selected mock or fake needs framework or hermetic-boundary details. Read Refactoring-resistant tests when fake ownership, change amplification, adapter parity, or a release-confidence claim is part of the task. A pure test with real deterministic collaborators does not load these topics.

4. Agentic change safety gate

Apply this gate whenever an autonomous agent authors or edits production code and tests in the same change. Read Agentic coding safety net.

Inspect production and test diffs separately, derive the oracle from the authoritative contract, and audit test-side weakening. Obtain RED-before-GREEN or controlled mutation/revert evidence, then execute selected, affected-module, actual-boundary, and repository-required checks that apply. Report every omitted rung as NOT_RUN. For high-risk state changes, require an independent reviewer or proof mechanism that does not restate the implementation.

5. Coroutine test profile

When TST-18 applies and the repository already provides coroutine-test support, read Coroutine unit testing. Do not add a dependency solely for this profile.

6. Conditional repository profile

Apply this profile only when the target repository actually provides it and nearby tests use it: module:test-support base classes, Kotest BehaviorSpec, MockK, its fixture API, Spring extensions, and utilities such as flushAndClear().

In that profile, reuse the lightest suitable base class instead of duplicating its wiring. This is a local convention, not a requirement for JUnit, Kotest, Spring, or other repositories. A JUnit project must not extend a Kotest base class, and a Kotest project must not adopt JUnit annotations merely because both run on the JUnit Platform.

Narrow persistence profile

Apply this profile only when the persistence boundary is the subject and the repository provides a DB-slice base plus the entity's JpaRepository.

• PST-1: Save and reload through the injected repository's public API.
• PST-2: Flush and clear after save and before reload; direct EntityManager flush/clear is strictly test plumbing.
• PST-3: Preserve the narrow slice and its actual configured database; do not substitute mocks or full boot.
• PST-4: Inventory and assert every relevant non-simple mapping after reload.
• PST-5: Cover populated, null, and contractually allowed empty JSON/JSONB values.
• PST-6: Use persist/find/merge only when the named subject is lifecycle, flush, or custom persistence behavior.

Read JPA persistence testing for the full application contract and exceptions.

Review check

• Detected framework, lifecycle, fixtures, and build configuration are preserved.
• Observable outcomes and meaningful boundary/failure cases use deterministic, isolated data.
• Real collaborators and actual adapter contracts precede strict, boundary-only mocks.
• No private fake mirrors production structure; unchanged behavior does not fan out test edits.
• Coroutine and JPA profiles apply only when detected, with their routed contract checks complete.
• Test-side diffs preserve an independently derived oracle and show RED or controlled mutation evidence.
• Fresh reports prove selected, module, boundary, and required-check execution; omissions are NOT_RUN.
• Deployment confidence is claimed only when observable behavior, actual boundary, and failure evidence are complete.