nielsfalk/kotlinTabularData

Kotlin Tabular Data

provides a DSL to define Data in a tabular way. It is inspired by Spock.

Examples

Tables of data can be written as in a markup-language. It results in a List of data-class-instances.

val data: List<Triple<TestEnum?, Int?, String?>> = readTabularData {
    // @formatter:off
    null ǀ null ǀ null
    Foo  ǀ 42   ǀ "Bar"
    // @formatter:on
}

This Tabular data can be used to parameterize a test.

@ParameterizedTest
@MethodSource("readTestArguments")
fun `use tabular data as test parameters`(
    testEnum: TestEnum?,
    int: Int?,
    expectedStringConcat: String?
) {
    val concatenatedInputParameters = "$testEnum $int"

    expectThat(concatenatedInputParameters).isEqualTo(expectedStringConcat)
}

companion object {
    @JvmStatic
    fun readTestArguments(): List<Arguments> =
        readTestArguments {
            // @formatter:off
            // first ǀ second ǀǀ expected string concat
               null  ǀ null   ǀǀ "null null"
               Foo   ǀ 42     ǀǀ "Foo 42"
            // @formatter:on
        }
}

Data can also be defined in Markdown-Tables. In IntelliJ with language-injection the Markdown has syntax-highlighting.

val data = readMarkdown<Triple<TestEnum?, Int?, String?>>(
  """    
  | enum | int  | string |
  |------|------|--------|
  | null | null | null   |  
  | Foo  | 42   | Bar    |
  """
)

The @MarkdownSource annotation can be used to Parameterize a test directly with a markdown-table

@ParameterizedTest
@MarkdownSource(
  """    
  | enum | int  | string       |
  |------|------|--------------|
  | null | 1    | Hallo World! |  
  | Foo  | null | Hello World! |
  """
)
fun `use values from Markdown source`(
    testEnum: TestEnum?,
    int: Int?,
    string: String?
) {
    // Test implementation
}

Getting started

Add the following to your build.gradle.kts

repositories {
    maven { setUrl("https://jitpack.io") }
}

dependencies {
    testImplementation("com.github.nielsfalk:kotlinTabularData:0+")
 }

or follow the Instructions on jitpack

Full Spock Dsl

to achieve the full Spock-Dsl use this project bundled in GivenWhenThen and write expressive tests like this:

class ShowcaseTest : GivenWhenThenTest(
    scenario(
        description {
            "Rock Paper Scissors expectedWinner=${data.expectedWinner}"
        },
        `when` { data.first defend data.second },
        then {
            expectActual()
                .isEqualTo(data.expectedWinner)
        },
        where<RockPaperScissorsTestCase> {
            // @formatter:off
            Rock     ǀ Rock     ǀǀ null
            Rock     ǀ Scissors ǀǀ Rock
            Rock     ǀ Paper    ǀǀ Paper
            Scissors ǀ Scissors ǀǀ null
            Scissors ǀ Paper    ǀǀ Scissors
            Scissors ǀ Rock     ǀǀ Rock
            Paper    ǀ Paper    ǀǀ null
            Paper    ǀ Rock     ǀǀ Paper
            Paper    ǀ Scissors ǀǀ Scissors
            // @formatter:on
        }
    )
)

private data class RockPaperScissorsTestCase(
    val first: RockPaperScissors,
    val second: RockPaperScissors,
    val expectedWinner: RockPaperScissors?
)