Features and Overview

AocKt (short for Advent of Code - Kotlin) is a simple library that makes running and testing your Kotlin solutions to Advent of Code puzzles a breeze.

It is an opinionated testing framework built on Kotest that defines a new AdventSpec specialized for testing AoC puzzle solutions with minimal boilerplate.

✨ Features

Completely Offline - Puzzle inputs and solutions are read from local files, no need for tokens.
Test-Driven - Run your code from unit tests for faster feedback loops and fearless refactorings.
DSL-Driven - Define your test cases with minimal code.
Configurable - You decide what runs and when using optional parameters.
Minimal - The test framework is the only non-Kotlin dependency.

⚡ Quick Start

For your convenience, there is an advent-of-code-kotlin-template repository which you can use to generate your own solutions repo. It comes with a pre-configured Gradle project with all bells and whistles you might need, as well as a modified source structure for easier navigation.

(If you need a working example, check out my solutions repo.)

To add AocKt to your existing project, simply add the dependencies and configure your unit tests to run with Kotest:

plugins {
    kotlin("jvm") version "1.9.25"
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.jadarma.aockt:aockt-core:0.2.1")
    testImplementation("io.github.jadarma.aockt:aockt-test:0.2.1")
    testImplementation("io.kotest:kotest-runner-junit5:5.9.1")
}

tasks.test {
    useJUnitPlatform()
}

🧪 Test DSL Overview

AocKt provides the following DSL for testing puzzle solutions:

object Y9999D01 : Solution {                            // 1. 
    override fun partOne(input: String) = spoilers()
    override fun partTwo(input: String) = spoilers()
}

@AdventDay(9999, 1, "Magic Numbers")                    // 2.
class Y9999D01Test : AdventSpec<Y9999D01>({             // 3.
    partOne {                                           // 4.
        "1,2,3,4" shouldOutput 4                        // 5.
        listOf("2", "2,2", "2,4,6,8") shouldAllOutput 0 // 6.
    }
    partTwo()                                           // 7.
})

In the above example:

Your solution should implement the Solution interface.
Each test class should be annotated with the @AdventDay annotation. Title is optional, but the year and day are required.
Rather than passing it as an instance, the AdventSpec takes in your solution as a type parameter.
Use the partOne and partTwo functions as needed. Inside the lambda you can define test cases. The Solution functions will only be invoked if the relevant part DSL is used. If you have not yet implemented the second part, or it doesn't exist (e.g.: Every year, part two of the last day just requires collecting all other 49 stars), then you may simply omit it.
To define a test case, use the shouldOutput function. Each usage will define another test case. The value tested against is checked against its string value, so shouldOutput 4 and shouldOutput "4" are equivalent.
As a shorthand for defining multiple examples that should output the same thing, use the shouldAllOutput function.
If you don't have any examples, but do want to run the part against your input the lambda can be omitted.

Last modified: 17 November 2024