The AocKtExtension now handles spec execution order.

Author: Jadarma

aockt-test/api/aockt-test.api

@@ -25,11 +25,12 @@ public abstract class io/github/jadarma/aockt/test/AdventSpec : io/kotest/core/s
 	public final fun testExecutionMode ()Lio/kotest/engine/concurrency/TestExecutionMode;
 }
 
-public final class io/github/jadarma/aockt/test/AocKtExtension : io/kotest/core/extensions/DisplayNameFormatterExtension, io/kotest/core/extensions/SpecExtension {
+public final class io/github/jadarma/aockt/test/AocKtExtension : io/kotest/core/extensions/DisplayNameFormatterExtension, io/kotest/core/extensions/SpecExecutionOrderExtension, io/kotest/core/extensions/SpecExtension {
 	public synthetic fun <init> (JLio/github/jadarma/aockt/test/ExecMode;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public synthetic fun <init> (JLio/github/jadarma/aockt/test/ExecMode;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun formatter ()Lio/kotest/engine/names/DisplayNameFormatter;
 	public fun intercept (Lio/kotest/core/spec/Spec;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public fun sort (Ljava/util/List;)Ljava/util/List;
 }
 
 public final class io/github/jadarma/aockt/test/ExecMode : java/lang/Enum {

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

@@ -3,9 +3,9 @@ package io.github.jadarma.aockt.test
 /**
  * Marks an [AdventSpec] as being the tests of a solution to a specific advent puzzle.
  *
- * @property year The year this puzzle appeared in.
- * @property day The day this puzzle appeared in.
- * @property title The title of the puzzle. If unspecified will default to the date.
+ * @property year    The year this puzzle appeared in.
+ * @property day     The day this puzzle appeared in.
+ * @property title   The title of the puzzle. If unspecified will default to the date.
  * @property variant Serves as disambiguation if the project contains multiple solutions for the same day.
  */
 @Target(AnnotationTarget.CLASS)
@@ -14,5 +14,5 @@ public annotation class AdventDay(
     val year: Int,
     val day: Int,
     val title: String = "",
-    val variant: String = "default",
+    val variant: String = "",
 )

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

@@ -5,14 +5,13 @@ 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.AocktDsl
-import io.github.jadarma.aockt.test.internal.MissingAdventDayAnnotationException
 import io.github.jadarma.aockt.test.internal.PuzzleTestData
 import io.github.jadarma.aockt.test.internal.TestData
+import io.github.jadarma.aockt.test.internal.adventDay
 import io.github.jadarma.aockt.test.internal.definePart
 import io.github.jadarma.aockt.test.internal.id
 import io.github.jadarma.aockt.test.internal.injectSolution
 import io.kotest.common.ExperimentalKotest
-import io.kotest.common.reflection.annotation
 import io.kotest.core.spec.IsolationMode
 import io.kotest.core.spec.style.FunSpec
 import io.kotest.core.test.TestCaseOrder
@@ -64,7 +63,7 @@ public abstract class AdventSpec<T : Solution>(
     public val solution: Solution
 
     init {
-        val adventDay = this::class.annotation<AdventDay>() ?: throw MissingAdventDayAnnotationException(this::class)
+        val adventDay = this::class.adventDay
         solution = injectSolution()
         testData = TestData.inputFor(adventDay.id)
         body()

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

@@ -1,10 +1,13 @@
 package io.github.jadarma.aockt.test
 
 import io.github.jadarma.aockt.test.internal.AdventSpecConfig
-import io.github.jadarma.aockt.test.internal.AocktDisplayNameFormatter
+import io.github.jadarma.aockt.test.internal.AocKtDisplayNameFormatter
+import io.github.jadarma.aockt.test.internal.SpecOrderer
 import io.kotest.core.extensions.DisplayNameFormatterExtension
+import io.kotest.core.extensions.SpecExecutionOrderExtension
 import io.kotest.core.extensions.SpecExtension
 import io.kotest.core.spec.Spec
+import io.kotest.core.spec.SpecRef
 import io.kotest.engine.names.DisplayNameFormatter
 import kotlinx.coroutines.currentCoroutineContext
 import kotlinx.coroutines.withContext
@@ -38,17 +41,11 @@ import kotlin.time.Duration
 public class AocKtExtension(
     efficiencyBenchmark: Duration = AdventSpecConfig.Default.efficiencyBenchmark,
     executionMode: ExecMode = AdventSpecConfig.Default.executionMode,
-) : SpecExtension, DisplayNameFormatterExtension {
+) : SpecExtension, DisplayNameFormatterExtension, SpecExecutionOrderExtension {
 
     /** The project-level config that will apply to all [AdventSpec]s. */
     private val configuration: AdventSpecConfig = AdventSpecConfig(efficiencyBenchmark, executionMode)
 
-    /** The formatter to use for [AdventSpec] names. */
-    private val displayNameFormatter = AocktDisplayNameFormatter
-
-    /** Provide the custom formatter to the extension. */
-    override fun formatter(): DisplayNameFormatter = displayNameFormatter
-
     /**
      * Intercept the [spec] execution.
      * If it is an [AdventSpec], add the project-level config to its coroutine context.
@@ -60,6 +57,12 @@ public class AocKtExtension(
             execute(spec)
         }
     }
+
+    /** Provide the custom formatter to the extension. */
+    override fun formatter(): DisplayNameFormatter = AocKtDisplayNameFormatter
+
+    /** Provide the custom execution order. */
+    override fun sort(specs: List<SpecRef>): List<SpecRef> = specs.sortedWith(SpecOrderer)
 }
 
 /** Configures which inputs the tests will run on. */

aockt-test/src/main/kotlin/internal/AdventSpecExt.kt

@@ -1,6 +1,7 @@
 package io.github.jadarma.aockt.test.internal
 
 import io.github.jadarma.aockt.core.Solution
+import io.github.jadarma.aockt.test.AdventDay
 import io.github.jadarma.aockt.test.AdventPartScope
 import io.github.jadarma.aockt.test.AdventSpec
 import io.github.jadarma.aockt.test.AocKtExtension
@@ -16,13 +17,18 @@ import io.kotest.matchers.comparables.shouldBeLessThanOrEqualTo
 import io.kotest.matchers.shouldBe
 import kotlinx.coroutines.currentCoroutineContext
 import kotlin.reflect.KClass
+import kotlin.reflect.full.findAnnotation
 import kotlin.reflect.full.isSubtypeOf
 import kotlin.reflect.full.starProjectedType
 import kotlin.reflect.jvm.jvmErasure
 import kotlin.reflect.typeOf
 import kotlin.time.Duration
 import kotlin.time.measureTimedValue
 
+/** Return the required-to-be-registered [AdventDay] annotation for this spec. */
+internal val KClass<out AdventSpec<*>>.adventDay: AdventDay
+    get() = findAnnotation<AdventDay>() ?: throw MissingAdventDayAnnotationException(this)
+
 /**
  * Construct and inject a solution instance for this [AdventSpec].
  * This function is designed to be called at spec instantiation time.

aockt-test/src/main/kotlin/internal/AocktDisplayNameFormatter.kt renamed to aockt-test/src/main/kotlin/internal/AocKtDisplayNameFormatter.kt

@@ -2,34 +2,26 @@ package io.github.jadarma.aockt.test.internal
 
 import io.github.jadarma.aockt.test.AdventDay
 import io.github.jadarma.aockt.test.AdventSpec
-import io.kotest.common.reflection.annotation
 import io.kotest.core.test.TestCase
 import io.kotest.engine.names.DisplayNameFormatter
 import kotlin.reflect.KClass
 import kotlin.reflect.full.isSubclassOf
 
 /** A name formatter extension that adjusts the names of [AdventSpec]s with the info of their [AdventDay]. */
-internal object AocktDisplayNameFormatter : DisplayNameFormatter {
+internal object AocKtDisplayNameFormatter : DisplayNameFormatter {
 
     // Test cases are not formatted.
     override fun format(testCase: TestCase) = null
 
     override fun format(kclass: KClass<*>): String? {
-        val annotation = kclass.annotation<AdventDay>() ?: return null
         if (!kclass.isSubclassOf(AdventSpec::class)) return null
 
-        return with(annotation) {
+        @Suppress("UNCHECKED_CAST")
+        return with((kclass as KClass<out AdventSpec<*>>).adventDay) {
             buildString {
                 append(AdventDayID(year, day))
-                if (title.isNotEmpty()) {
-                    append(": ")
-                    append(title)
-                }
-                if (variant != "default") {
-                    append(" (")
-                    append(variant)
-                    append(')')
-                }
+                if (title.isNotEmpty()) append(": ", title)
+                if (variant.isNotEmpty()) append(" (", variant, ")")
             }
         }
     }

aockt-test/src/main/kotlin/internal/SpecOrderer.kt

@@ -0,0 +1,36 @@
+package io.github.jadarma.aockt.test.internal
+
+import io.github.jadarma.aockt.test.AdventDay
+import io.github.jadarma.aockt.test.AdventSpec
+import io.kotest.core.spec.Spec
+import io.kotest.core.spec.SpecRef
+import kotlin.reflect.KClass
+import kotlin.reflect.full.isSubclassOf
+
+/**
+ * Defines the execution order of [SpecRef]s.
+ * All non-[AdventSpec] are executed first in the order they were discovered.
+ * Advent specs are then executed in chronological order.
+ */
+internal object SpecOrderer : Comparator<SpecRef> {
+
+    override fun compare(a: SpecRef, b: SpecRef): Int {
+        val specA: KClass<out Spec> = a.kclass
+        val specB: KClass<out Spec> = b.kclass
+
+        @Suppress("UNCHECKED_CAST")
+        return when (specA.isSubclassOf(AdventSpec::class) to specB.isSubclassOf(AdventSpec::class)) {
+            true to false -> 1
+            false to true -> -1
+            false to false -> 0
+            else -> compareValuesBy(
+                a = (specA as KClass<out AdventSpec<*>>).adventDay,
+                b = (specB as KClass<out AdventSpec<*>>).adventDay,
+                AdventDay::year,
+                AdventDay::day,
+                AdventDay::title,
+                AdventDay::variant,
+            )
+        }
+    }
+}

aockt-test/src/test/kotlin/internal/SpecOrdererTest.kt

@@ -0,0 +1,67 @@
+package io.github.jadarma.aockt.test.internal
+
+import io.github.jadarma.aockt.core.Solution
+import io.github.jadarma.aockt.test.AdventDay
+import io.github.jadarma.aockt.test.AdventSpec
+import io.kotest.assertions.withClue
+import io.kotest.core.spec.SpecRef
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.collections.shouldContainInOrder
+import io.kotest.matchers.shouldBe
+import io.kotest.property.Arb
+import io.kotest.property.arbitrary.shuffle
+import io.kotest.property.checkAll
+
+class SpecOrdererTest : FunSpec({
+
+    test("Orders specs correctly") {
+        val otherSpecs = listOf(OtherA::class, OtherB::class).map(SpecRef::Reference)
+        val adventSpecs = listOf(
+            SpecA::class, SpecB::class, SpecC::class, SpecD::class,
+            SpecE::class, SpecF::class, SpecG::class, SpecH::class,
+        ).map(SpecRef::Reference)
+        val allSpecs: List<SpecRef> = adventSpecs + otherSpecs
+
+        checkAll(iterations = 128, Arb.shuffle(allSpecs)) { discoveryOrder ->
+            val otherOrder = discoveryOrder.filter { it in otherSpecs }
+            val sortedOrder = discoveryOrder.sortedWith(SpecOrderer)
+
+            withClue("Sorting changed the relative order of non-AdventSpecs") {
+                sortedOrder.shouldContainInOrder(otherOrder)
+            }
+
+            withClue("Final sort order is incorrect.") {
+                val expectedOrder = otherOrder + adventSpecs
+                sortedOrder.shouldBe(expectedOrder)
+            }
+        }
+    }
+})
+
+// Some inactive specs to test with.
+private class OtherA : FunSpec()
+private class OtherB : FunSpec()
+
+@AdventDay(3000, 1)
+private class SpecA : AdventSpec<Solution>()
+
+@AdventDay(3000, 1, variant = "default")
+private class SpecB : AdventSpec<Solution>()
+
+@AdventDay(3000, 1, title = "A")
+private class SpecC : AdventSpec<Solution>()
+
+@AdventDay(3000, 1, title = "A", variant = "custom")
+private class SpecD : AdventSpec<Solution>()
+
+@AdventDay(3000, 1, title = "A", variant = "dumb")
+private class SpecE : AdventSpec<Solution>()
+
+@AdventDay(3000, 1, title = "B")
+private class SpecF : AdventSpec<Solution>()
+
+@AdventDay(3000, 2)
+private class SpecG : AdventSpec<Solution>()
+
+@AdventDay(3001, 1)
+private class SpecH : AdventSpec<Solution>()

docs/topics/changelog.md

@@ -2,13 +2,11 @@
 
 ## 0.3.0-SNAPSHOT
 
-**Breaking Changes:**
-- Minimum JDK is now 21.
-- Minimum Kotlin version is now `2.0`.
-- Minimum Kotest version is now `6.0`. Check the [release notes](https://kotest.io/docs/release6), and how to
-  [configure](project-extension.md) the extension.
+- New minimum requirements: JDK 21, Kotlin `2.0`, and Kotest `6.0`.
+  Check the [release notes](https://kotest.io/docs/release6), and how to [configure](project-extension.md) the extension.
 - Removed `formatAdventSpecNames` configuration property.
-  Formatting is automatically enabled when using the project extension.  
+  Formatting is automatically enabled when using the project extension.
+- Advent specs are guaranteed to be executed chronologically when the project extension is registered.
 
 ## 0.2.1
 

docs/topics/project-extension.md

@@ -21,18 +21,18 @@ It offers the following features:
     `Y2015D01: Not Quite Lisp (FP)`.
     All other specs and tests follow the normal Kotest formatting rules.
 
-## Registering The Extension
+- **Automatic Execution Ordering**
 
-To register it, add it to your Kotest [project level config](https://kotest.io/docs/framework/project-config.html):
+    `AdventSpec`s will always execute in chronological order.
+    All other specs will run before them, in the order they were discovered.
+    Note that this overrides Kotest's own [spec ordering`](https://kotest.io/docs/framework/spec-ordering.html).
 
-```kotlin
-package my.aoc
+## Registering The Extension
 
-import io.github.jadarma.aockt.test.AocKtExtension
-import io.github.jadarma.aockt.test.ExecMode
-import io.kotest.core.config.AbstractProjectConfig
-import io.kotest.core.extensions.Extension
+To register it, add it to your Kotest [project level config](https://kotest.io/docs/framework/project-config.html), for
+example in `src/test/my/aoc/TestConfig.kt`:
 
+```kotlin
 object TestConfig : AbstractProjectConfig() {
     override val extensions = listOf<Extension>(
         AocKtExtension()
@@ -58,8 +58,6 @@ tasks.test {
 }
 ```
 
-
-
 ## Configuration Properties
 
 Preferences that can be set as constructor arguments.