Spek – A Specification Framework

For a while now, a few of us have been working on a project called Spek, a framework that allows you to write executable specifications. It allows you to write specifications (i.e. tests) in a more human-readable, and what’s more important, descriptive manner, without having to resort to long test names, underscores or regular expressions.

It’s now reached its first milestone where it’s suitable enough to start being used on projects and we’re ready for feedback and feature requests! It even has its own site.

A brief introduction

Spek is a Specification Framework. If you’re familiar with Jasmine, Mocha, RSpec or Machine Specifications, then you’ll immediately see the resemblance.


If you’re not familiar, let me briefly explain:

  • Given – Establish the context of the test, i.e, Arrange
  • On – Execute the action, i.e. Act
  • It – Validate the results, i.e. Assert

Spek allows you to have more than one action for the same context. That is for the same given you can have multiple on’s. It also allows you to have more than assertion (it) for the same action.

Spek is not only for Kotlin

Spek is written in Kotlin. Specifications you write will also be in Kotlin. However, as Kotlin is 100% compatible with Java, you can test new and existing Java code with Spek.

How do I run it?

IntelliJ IDEA supports Spek, so does TeamCity. There’s also a console runner which outputs Text and HTML (needs improvement).


Try it

Hoping that you like what you see, head over to the Spek web site to find out more. It’s still in “EAP” so the more issues reported, the better. And since it’s OSS (Apache 2) contributions are more than welcome.

This entry was posted in Libraries. Bookmark the permalink.

17 Responses to Spek – A Specification Framework

  1. Ladislav Thon says:

    Okay, the instance initializer hack makes me sad. Almost sounds like we can’t do better with Kotlin… I’ll try to think about alternatives; IMHO, spek should be a function just like given, on and it.

    • Hadi Hariri says:


      Originally a spec was just a function. The problem is that right now we’re using JUnit to leverage and not have to re-write all the functionality of plugins etc. That’s why the base class (not too keen on it either ). But open to alternatives.

  2. Guangyu HE says:

    Does AndroidStudio support Spek? Can I use it for android development?
    It seems that Test writen in java could be executed as general junit test and as android test, kotlin tests could be executed only as junit test, so kotlin tests couldn’t be executed now.

  3. Bruno Santos says:


    Small typo in Spec usage page. Maven dependency should be something like:


  4. Bruno Santos says:


    Small typo in Spec usage page. Maven dependency should be something like:

    groupId: org.spek
    artifactId: spek
    version: 0.1-SNAPSHOT
    scope: test

  5. Bruno Santos says:

    A couple of things:

    – It would be nice to also have support for given/when/then
    – It uses a JUnit Runner. This prevents users from using other runners like Spring JUnit Runner. Any plans to go around this limitation in a near future?

    • Hadi Hariri says:


      Given/On/It is pretty much the same thing as Given/When/Then. The issue is that When is a keyword in Kotlin. I guess in output formatters we could make the option to spit out these keywords if absolutely required. In terms of JUnit runner, right now we’re leveraging a whole bunch of functionality, such as the integrated JUnit test runner in IDEA and it would be quite a bit of work to replace. On the flip side, relying on JUnit does bring some limitations that would be nice to remove. Basically, the cards are on the table for it.

  6. Даниил Водопьян says:

    Aren’t you afraid of having such short two-letter names in your framework? I mean, it is pretty ok to have short keywords in stdlib, but if you create a separate lib, there could be a conflict with others frameworks.

    I can not come up with better keywords now, but maybe I would prefer ‘itShould’ instead of ‘it’.

  7. Pingback: Spek: BDD Specification Framework For The JVM | Braveterry

  8. Даниил Водопьян says:

    Hi again!

    Some time ago I faced a problem that I did not know the file where the particular team had its tests for a particular function. So I had to guess and look over the tests till I found the one I needed.

    Thus I would request for an annotation ‘testedBy()’, which will contain the path or the full package name for the function or class it is attached to.

    Also it would be cool to have navigation on such specifications.

    Thank you

    PS By the way, where should I write my thoughts on Spec? Is there a forum or an issue tracker?

  9. David Leppik says:

    Spek runs on top of JUnit. Can it be run alongside JUnit 3, or does it require JUnit 4?

    • Hadi Hariri says:

      We use JUnit 4 internally. I’m not sure if it will work with 3. However, we’re looking at decoupling from JUnit.

  10. Christian says:

    I’d like to see an additional “flat” style, like ScalaTest FlatSpec:

    Deeply nested APIs tend to be confusing. The Spek API adds three levels of indentation compared to flat styles. And, as nice as the idea is in principle, it doesn’t add that much. It is still far away from “real specs” like Cucumber specs. From my point of view it is more a polished unit test – sorry. But I like the effort and I think that Kotlin should have a test framework. Nice table driven tests for example are not possible with TestNG and JUnit.

Comments are closed.