Further restrict DSL.

Use a scope interface to hide Kotest internals and only allow part scopes to contain tests defined by the DSL.

Author: Jadarma

aockt-test/api/aockt-test.api

@@ -22,25 +22,9 @@ public abstract class io/github/jadarma/aockt/test/AdventSpec : io/kotest/core/s
 	public final fun threads ()Ljava/lang/Integer;
 }
 
-public final class io/github/jadarma/aockt/test/AdventSpecExampleContainerScope : io/kotest/core/spec/style/scopes/ContainerScope {
-	public fun <init> (Lkotlin/jvm/functions/Function1;Lio/kotest/core/spec/style/scopes/FunSpecContainerScope;)V
-	public fun afterAny (Lkotlin/jvm/functions/Function2;)V
-	public fun afterContainer (Lkotlin/jvm/functions/Function2;)V
-	public fun afterEach (Lkotlin/jvm/functions/Function2;)V
-	public fun afterTest (Lkotlin/jvm/functions/Function2;)V
-	public fun beforeAny (Lkotlin/jvm/functions/Function2;)V
-	public fun beforeContainer (Lkotlin/jvm/functions/Function2;)V
-	public fun beforeEach (Lkotlin/jvm/functions/Function2;)V
-	public fun beforeTest (Lkotlin/jvm/functions/Function2;)V
-	public fun getCoroutineContext ()Lkotlin/coroutines/CoroutineContext;
-	public fun getTestCase ()Lio/kotest/core/test/TestCase;
-	public fun hasChildren ()Z
-	public fun registerContainer (Lio/kotest/core/names/TestName;ZLio/kotest/core/test/config/TestConfig;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
-	public fun registerTest (Lio/kotest/core/names/TestName;ZLio/kotest/core/test/config/TestConfig;Lio/kotest/core/test/TestType;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
-	public fun registerTest (Lio/kotest/core/names/TestName;ZLio/kotest/core/test/config/TestConfig;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
-	public fun registerTestCase (Lio/kotest/core/test/NestedTest;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
-	public final fun shouldAllOutput (Ljava/lang/Iterable;Ljava/lang/Object;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
-	public final fun shouldOutput (Ljava/lang/String;Ljava/lang/Object;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+public abstract interface class io/github/jadarma/aockt/test/AdventSpec$PartScope {
+	public abstract fun shouldAllOutput (Ljava/lang/Iterable;Ljava/lang/Object;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public abstract fun shouldOutput (Ljava/lang/String;Ljava/lang/Object;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
 public final class io/github/jadarma/aockt/test/AocKtExtension : kotlin/coroutines/AbstractCoroutineContextElement, io/kotest/core/extensions/DisplayNameFormatterExtension, io/kotest/core/extensions/TestCaseExtension {

aockt-test/src/main/kotlin/AdventSpec.kt

@@ -5,6 +5,7 @@ import io.github.jadarma.aockt.test.internal.AdventDayID
 import io.github.jadarma.aockt.test.internal.AdventDayPart
 import io.github.jadarma.aockt.test.internal.AdventDayPart.One
 import io.github.jadarma.aockt.test.internal.AdventDayPart.Two
+import io.github.jadarma.aockt.test.internal.AdventSpecPartScope
 import io.github.jadarma.aockt.test.internal.AocktDsl
 import io.github.jadarma.aockt.test.internal.ConfigurationException
 import io.github.jadarma.aockt.test.internal.DuplicatePartDefinitionException
@@ -110,21 +111,47 @@ public abstract class AdventSpec<T : Solution>(
     private var isPartOneDefined: Boolean = false
     private var isPartTwoDefined: Boolean = false
 
+    /** A DSL scope for defining example assertions for puzzle parts. */
+    @AocktDsl
+    public interface PartScope {
+
+        /**
+         * Creates a new test that asserts that when given this string as input, it gets the correct [expected] answer.
+         * The [expected] value can be anything and will be tested against its `.toString()` value.
+         *
+         * @receiver The example puzzle input.
+         * @param expected The correct answer to the puzzle for the given input.
+         */
+        public suspend infix fun String.shouldOutput(expected: Any)
+
+        /**
+         * For each of the values given creates a new test that asserts that when given as input, it gets the correct
+         * [expected] answer.
+         * The [expected] value can be anything and will be tested against its `.toString()` value.
+         *
+         * _NOTE:_ This should be equivalent to calling [shouldOutput] for every input.
+         *
+         * @receiver The example puzzle inputs.
+         * @param expected The correct answer to the puzzle for all given inputs.
+         */
+        public suspend infix fun Iterable<String>.shouldAllOutput(expected: Any)
+    }
+
     /**
      * Provides a context to test the implementation of one of a [Solution]'s part function.
      *
      * Will create a context with two tests:
      *  - Verifies the output, given the input file has been added to the test resources.
      *    If the solution is known as well, also validates the answer matches it.
-     *  - Verifies the given examples in an [AdventSpecExampleContainerScope], useful for a TDD approach when
+     *  - Verifies the given examples in an [AdventSpec.PartScope], useful for a TDD approach when
      *    implementing the solution for the first time.
      *
      * @param part The part selector.
      * @param enabled If set to false, part one will not be tested.
      * @param expensive This part is known to produce answers in a longer timespan.
      * @param executionMode Specifies which tests defined for this part will be enabled.
      * @param efficiencyBenchmark The maximum amount of time a solution can take to finish to be considered efficient.
-     * @param examples Test the solution against example inputs defined in this [AdventSpecExampleContainerScope].
+     * @param examples Test the solution against example inputs defined in this [AdventSpec.PartScope].
      */
     @Suppress("LongParameterList", "ThrowsCount", "LongMethod", "CyclomaticComplexMethod")
     private fun partTest(
@@ -133,7 +160,7 @@ public abstract class AdventSpec<T : Solution>(
         expensive: Boolean,
         executionMode: ExecMode?,
         efficiencyBenchmark: Duration?,
-        examples: (suspend AdventSpecExampleContainerScope.() -> Unit)?,
+        examples: (suspend PartScope.() -> Unit)?,
     ) {
         if (efficiencyBenchmark != null && !efficiencyBenchmark.isPositive()) {
             throw ConfigurationException("Efficiency benchmark must be a positive value, but was: $efficiencyBenchmark")
@@ -163,7 +190,7 @@ public abstract class AdventSpec<T : Solution>(
 
             if (examples != null) {
                 context("Validates the examples").config(enabled = execMode != ExecMode.SkipExamples) {
-                    AdventSpecExampleContainerScope(partFunction, this).examples()
+                    AdventSpecPartScope(partFunction, this).examples()
                 }
             }
 
@@ -226,29 +253,22 @@ public abstract class AdventSpec<T : Solution>(
      * Will create a context with two tests:
      *  - Verifies the output, given the input file has been added to the test resources.
      *    If the solution is known as well, also validates the answer matches it.
-     *  - Verifies the given examples in an [AdventSpecExampleContainerScope], useful for a TDD approach when
+     *  - Verifies the given examples in an [AdventSpec.PartScope], useful for a TDD approach when
      *    implementing the solution for the first time.
      *
      * @param enabled If set to false, part one will not be tested.
      * @param expensive This part is known to produce answers in a longer timespan.
      * @param executionMode Specifies which tests defined for this part will be enabled.
      * @param efficiencyBenchmark The maximum amount of time a solution can take to finish to be considered efficient.
-     * @param test Test the solution against example inputs defined in this [AdventSpecExampleContainerScope].
+     * @param test Test the solution against example inputs defined in this [AdventSpec.PartScope].
      */
     public fun partOne(
         enabled: Boolean = true,
         expensive: Boolean = false,
         executionMode: ExecMode? = null,
         efficiencyBenchmark: Duration? = null,
-        test: (suspend AdventSpecExampleContainerScope.() -> Unit)? = null,
-    ): Unit = partTest(
-        part = One,
-        enabled = enabled,
-        expensive = expensive,
-        executionMode = executionMode,
-        efficiencyBenchmark = efficiencyBenchmark,
-        examples = test,
-    )
+        test: (suspend PartScope.() -> Unit)? = null,
+    ): Unit = partTest(One, enabled, expensive, executionMode, efficiencyBenchmark, test)
 
     /**
      * Provides a context to test the implementation a [Solution.partTwo] function.
@@ -257,27 +277,20 @@ public abstract class AdventSpec<T : Solution>(
      * Will create a context with two tests:
      *  - Verifies the output, given the input file has been added to the test resources.
      *    If the solution is known as well, also validates the answer matches it.
-     *  - Verifies the given examples in an [AdventSpecExampleContainerScope], useful for a TDD approach when
+     *  - Verifies the given examples in an [AdventSpec.PartScope], useful for a TDD approach when
      *    implementing the solution for the first time.
      *
      * @param enabled If set to false, part one will not be tested.
      * @param expensive This part is known to produce answers in a longer timespan.
      * @param executionMode Specifies which tests defined for this part will be enabled.
      * @param efficiencyBenchmark The maximum amount of time a solution can take to finish to be considered efficient.
-     * @param test Test the solution against example inputs defined in this [AdventSpecExampleContainerScope].
+     * @param test Test the solution against example inputs defined in this [AdventSpec.PartScope].
      */
     public fun partTwo(
         enabled: Boolean = true,
         expensive: Boolean = false,
         executionMode: ExecMode? = null,
         efficiencyBenchmark: Duration? = null,
-        test: (suspend AdventSpecExampleContainerScope.() -> Unit)? = null,
-    ): Unit = partTest(
-        part = Two,
-        enabled = enabled,
-        expensive = expensive,
-        executionMode = executionMode,
-        efficiencyBenchmark = efficiencyBenchmark,
-        examples = test,
-    )
+        test: (suspend PartScope.() -> Unit)? = null,
+    ): Unit = partTest(Two, enabled, expensive, executionMode, efficiencyBenchmark, test)
 }

…otlin/AdventSpecExampleContainerScope.kt …n/kotlin/internal/AdventSpecPartScope.ktaockt-test/src/main/kotlin/AdventSpecExampleContainerScope.kt renamed to aockt-test/src/main/kotlin/internal/AdventSpecPartScope.kt aockt-test/src/main/kotlin/AdventSpecExampleContainerScope.kt renamed to aockt-test/src/main/kotlin/internal/AdventSpecPartScope.kt

@@ -1,10 +1,8 @@
-package io.github.jadarma.aockt.test
+package io.github.jadarma.aockt.test.internal
 
-import io.github.jadarma.aockt.test.internal.AocktDsl
-import io.github.jadarma.aockt.test.internal.PuzzleInput
+import io.github.jadarma.aockt.test.AdventSpec
 import io.kotest.assertions.throwables.shouldNotThrowAny
 import io.kotest.assertions.withClue
-import io.kotest.core.spec.KotestTestScope
 import io.kotest.core.spec.style.scopes.ContainerScope
 import io.kotest.core.spec.style.scopes.FunSpecContainerScope
 import io.kotest.matchers.shouldBe
@@ -15,40 +13,29 @@ import io.kotest.matchers.shouldBe
  * @param implementation The function to be tested.
  * @param context The parent context in which to append these test cases.
  */
-@KotestTestScope
-@AocktDsl
-public class AdventSpecExampleContainerScope(
+internal class AdventSpecPartScope(
     private val implementation: (String) -> Any,
     private val context: FunSpecContainerScope,
-) : ContainerScope by context {
+) : AdventSpec.PartScope, ContainerScope by context {
 
     /** Incrementing counter for the example test cases. */
     private var exampleNumber: Int = 0
 
-    /**
-     * Creates a new test that asserts that when given this string as input, we get the correct [expected] answer.
-     * The [expected] value can be anything and will be tested against its String value.
-     */
-    public suspend infix fun String.shouldOutput(expected: Any) {
+    override suspend infix fun String.shouldOutput(expected: Any) {
         exampleNumber++
         val input = PuzzleInput(this)
         val preview = input.preview()
         context.test("Example #$exampleNumber") {
             withClue("Expected answer '$expected' for input: $preview") {
                 val answer = shouldNotThrowAny {
-                    this@AdventSpecExampleContainerScope.implementation(input.toString()).toString()
+                    this@AdventSpecPartScope.implementation(input.toString()).toString()
                 }
                 answer shouldBe expected.toString()
             }
         }
     }
 
-    /**
-     * For each of the values given creates a new test that asserts that when given as input, we get the correct
-     * [expected] answer.
-     * The [expected] value can be anything and will be tested against its String value.
-     */
-    public suspend infix fun Iterable<String>.shouldAllOutput(expected: Any) {
+    override suspend infix fun Iterable<String>.shouldAllOutput(expected: Any) {
         forEach { it shouldOutput expected }
     }
 }