Spockk Framework Documentation

Introduction

Spockk is a testing and specification framework for Kotlin. It is heavily inspired by the Spock framework for Groovy and aims to provide a Kotlin-native version of Spock’s expressive specification syntax. Spockk runs on the JUnit Platform, making it compatible with most build tools and IDEs.

Getting Started

To try Spockk in your local environment, clone the Spockk Example Project.

Spockk consists of three core modules that must be applied to your project to start using its expressive specification syntax.

The Spockk Core module defines the specification syntax and provides a TestEngine implementation that allows Spockk tests to run on the JUnit Platform.

Enable the Spockk test engine in your Gradle project

// build.gradle.kts

dependencies {
    testImplementation("io.github.pshevche.spockk:spockk-core:0.1.0")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher:6.0.1")
}

tasks.named<Test>("test") {
    useJUnitPlatform()
}

The Spockk Gradle plugin applies a Kotlin compiler plugin that transforms Spockk’s concise specification syntax into runnable tests during compilation.

Apply the Spockk Gradle plugin to support specification syntax

// build.gradle.kts

plugins {
    id("io.github.pshevche.spockk") version "0.1.0"
}

Finally, for a smooth development experience in JetBrains IDEs, install the Spockk IntelliJ plugin from the Marketplace. The plugin recognizes Spockk syntax in your tests and enables you to execute them directly from the IDE via Gradle.

Writing Tests

Building blocks

Similarly to Spock, Spockk lets you define specifications that describe expected features of the system under specification. A specification is represented as a Kotlin class, while features are defined as its methods.

class MyFirstSpecification {
    fun `adding an element to a list`() {
        // define preconditions, actions, and conditions
    }
}

Spockk expects features to be structured into so-called blocks. The framework provides built-in elements that help you define such blocks using the Behavior-Driven Development style. Currently, the framework supports five types of blocks:

given: defines feature setup and preconditions;
when: defines actions applied to the system under specification;
then: declares the expected state of the fixture after applying actions;
expect: defines a standalone condition block;
and: allows combining multiple precondition, action, and condition blocks.

A feature method must have at least one block to be eligible for execution. A block consists of all statements between two block labels, or between a block label and the end of the feature.

import io.github.pshevche.spockk.lang.and
import io.github.pshevche.spockk.lang.given
import io.github.pshevche.spockk.lang.`when`
import io.github.pshevche.spockk.lang.then

class MyFirstSpecification {
    fun `adding an element to a list`() {
        given
        val myList = mutableListOf<Int>()

        `when`
        myList.add(1)

        and
        myList.add(2)

        then
        assert(myList.size == 2)
    }
}

Specifications as Documentation

Block labels can include natural-language descriptions, making your specifications more expressive and readable — even for non-engineers.

Block labels with descriptions

given("an empty bank account")
// ...

`when`("the account is credited $10")
// ...

then("the account's balance is $10")
// ...

Defininig Conditions

Spockk does not yet provide built-in fixtures for defining conditions (assertions). However, it works seamlessly with Kotlin’s native assertion framework, as well as popular libraries such as AssertJ and Hamcrest. A more ergonomic way to define conditions is planned for a future release.

Limitations

Spockk is still in active development and currently lacks several features typically expected from an enterprise-level testing framework. For example, it does not yet support lifecycle methods (e.g. setup), data-driven features, or built-in fixtures for interaction-based testing. These and other enhancements are on the roadmap. Stay tuned for future releases!

Changelog

v0.1

[Core] Implement rich BDD-style syntax for defining test features
[IntelliJ plugin] Detect Spockk syntax in test sources
[IntelliJ plugin] Execute Spockk tests with Gradle from IDE