test: create akkurate-test artifact

Author: nesk

CHANGELOG.md

@@ -8,6 +8,10 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- New `akkurate-test` artifact to test custom constraints.
+
 ### Fixed
 
 - Add a `or equal to zero` suffix to the default message for `isNegativeOrZero` and `isPositiveOrZero` constraints.

README.md

@@ -100,10 +100,6 @@ Check if 'title' is not empty otherwise write "Missing title".
   Take advantage of Kotlin Multiplatform; write your validation code once, use it both for front-end and back-end
   usages.
 
-- ⏱ **Testable out of the box** \
+- [**Testable out of the box**](https://akkurate.dev/docs/extend.html#test-your-code) \
   Finding how to test your validation code shouldn't be one of your tasks. You will find all the tools you need to write
   good tests.
-
-> [!NOTE]
-> Features marked with ⏱ are on the roadmap.
-

akkurate-test/build.gradle.kts

@@ -0,0 +1,18 @@
+import dev.nesk.akkurate.gradle.configureTargets
+
+plugins {
+    id("akkurate.kmp-library-conventions")
+    id("org.jetbrains.dokka")
+}
+
+kotlin {
+    configureTargets()
+
+    sourceSets {
+        commonMain {
+            dependencies {
+                api(project(":akkurate-core"))
+            }
+        }
+    }
+}

akkurate-test/src/commonMain/kotlin/dev/nesk/akkurate/test/Validatable.kt

@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package dev.nesk.akkurate.test
+
+import dev.nesk.akkurate.Validator
+import dev.nesk.akkurate.validatables.Validatable
+
+/**
+ * Instantiates a [Validatable] with a value, allowing to test custom constraints.
+ *
+ * Usage example:
+ *
+ * ```
+ * fun Validatable<String>.hasWordCountGreaterThan(count: Int) =
+ *     constrain { it.split(" ").size > count }
+ *
+ * @Test
+ * fun testWordCount() {
+ *     assertFalse(Validatable("one two").hasWordCountGreaterThan(2).satisfied)
+ *     assertTrue(Validatable("one two three").hasWordCountGreaterThan(2).satisfied)
+ * }
+ * ```
+ */
+public fun <T> Validatable(value: T): Validatable<T> {
+    lateinit var validatable: Validatable<T>
+    val validator = Validator<T> {
+        validatable = this
+    }
+    validator(value)
+    return validatable
+}

documentation/images/clock.png

@@ -82,3 +82,31 @@ private fun Validatable<String?>.hasWordCountGreaterThan(count: Int) =
         "Must contain more than $count words"
     }
 ```
+
+## Test your code
+
+When writing your own constraints, you might want to write unit tests to verify their behaviors.
+
+This is done by installing a new artifact:
+
+<procedure title="Install akkurate-test">
+
+<code-block lang="kotlin">
+testImplementation("dev.nesk.akkurate:akkurate-test:%version%")
+</code-block>
+
+</procedure>
+
+This artifact provides
+[the Validatable function](https://akkurate.dev/api/akkurate-test/dev.nesk.akkurate.test/-validatable.html), which
+returns a value ready to be constrained:
+
+```kotlin
+val validatable = Validatable("The Lord of the Rings")
+
+val satisfiedConstraint = validatable.hasWordCountGreaterThan(4)
+assertTrue(satisfiedConstraint.satisfied)
+
+val unsatisfiedConstraint = validatable.hasWordCountGreaterThan(5)
+assertFalse(unsatisfiedConstraint.satisfied)
+```

documentation/images/clock_dark.png

@@ -90,10 +90,8 @@ Check if 'title' is not empty otherwise write "Missing title".
   take care of the integrations for you.
 - [**Code once, deploy everywhere.**](getting-started.md#installation) Take advantage of Kotlin Multiplatform; write
   your validation code once, use it both for front-end and back-end usages.
-- ![Coming soon](clock.png){width="16"} **Testable out of the box.** Finding how to test your validation code shouldn't
-  be one of your tasks. You will find all the tools you need to write good tests.
-
-> Features marked with ![Coming soon](clock.png){width="16"} are on the roadmap.
+- [**Testable out of the box.**](extend.md#test-your-code) Finding how to test your validation code shouldn't be one of
+  your tasks. You will find all the tools you need to write good tests.
 
 <seealso style="links">
   <category ref="external">

documentation/topics/extend.md

@@ -21,6 +21,7 @@ kotlin {
             dependencies {
                 implementation(kotlin("test"))
                 implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.1")
+                implementation(project(":akkurate-test"))
             }
         }
     }

documentation/topics/overview.md

@@ -18,6 +18,7 @@
 package dev.nesk.akkurate
 
 import dev.nesk.akkurate._test.Validatable
+import dev.nesk.akkurate.test.Validatable
 import dev.nesk.akkurate.validatables.Validatable
 import kotlin.test.Test
 import kotlin.test.assertContentEquals