How Kola Is Designed

Understand the design motivations behind Kola's DSL, toolchain choices, and contract-first testing model.

What This Page Covers

This page explains why Kola is designed the way it is, not just how to execute it.

Read it when you want to understand the tradeoffs behind Kola's DSL, runtime dependencies, and contract-first testing workflow.

The Problem Kola Tries To Solve

Traditional API tests often drift into one of two bad states:

the scenario is readable, but disconnected from the real contract
the scenario is executable, but unreadable to anyone outside the implementation team

Kola is designed to reduce that split by keeping scenario intent, contract structure, and team workflow closer together.

Why Kola Uses a BDD-Style Shape

Kola adopts a BDD-oriented structure because API scenarios are easier to discuss when they are expressed as:

a business-relevant situation
one concrete request
a small set of expected results

This makes the test easier to read across product, frontend, backend, and QA roles, even though Kola is not trying to become a generic Cucumber replacement.

Why Kola Uses Groovy DSL Files

Kola uses a Groovy-based DSL because it balances three needs well:

expressive scenario syntax
concise test authoring
straightforward integration with JVM-based build workflows

The goal is not to introduce a brand-new language. The goal is to keep scenario authoring lighter than handwritten Java test fixtures while still fitting normal Gradle projects.

Dependency Strategy

Kola builds on familiar JVM testing infrastructure instead of inventing its own isolated runtime stack.

Typical supporting libraries include:

Spring testing utilities
JUnit 5
AssertJ
Mockito
Rest Assured
JSON and XML assertion helpers

That decision keeps Kola easier to integrate into existing teams and reduces the amount of new testing infrastructure people need to learn.

Why Kola Fits ApiHug Well

Kola is designed for proto-driven ApiHug projects first.

That gives it three advantages:

scenario structure can stay close to the contract model
generated artifacts and tests evolve together
the team gets one shared testing entrypoint instead of scattered custom scripts

Kola can still be used around non-ApiHug APIs, but the closer the project is to the ApiHug contract model, the more value Kola can provide.

Result

Kola's design is intentionally practical: readable scenarios, contract-aware execution, and a JVM toolchain that feels familiar enough to adopt without rebuilding the whole testing stack.