Testability

Your library should not rely on state in global variables or provide stateful top-level functions as part of its public API. Such variables and functions make testing code that uses the library difficult, as tests need to find ways to control these global values.

For example, a library might define a globally accessible function that provides access to the current time:

val instant: Instant = Clock.now()
println(instant)

Any code using this API will be difficult to test, as the call to the now() function will always return the real current time, while in tests it's often desirable to return fake values instead.

To enable testability, the kotlinx-datetime library has an API that lets users get a Clock instance, and then use that to get the current time:

val clock: Clock = Clock.System
val instant: Instant = clock.now()
println(instant)

This allows users of a library to inject a Clock instance into their own classes, and replace the real implementation with a fake one during tests.

If you haven't already, consider checking out these pages:

• Learn about maintaining backward compatibility in the Backward compatibility page.

• For an extensive overview on effective documentation practices, see Informative Documentation.