Clone wiki

scala-koans / Home


Koans are small lessons on the path to enlightenment. The aim of the Scala Koans project is to provide an easy learning environment in Scala based on a test suite with tests that the developer must either update to work, or fix the implementations being tested such that they pass.

Getting Started

If you haven't already retrieved the code, make sure you have a recent version of mercurial installed, and then clone the repository with the following command:

On Linux or Mac

$ hg clone

On Windows:

% hg clone

Once you have cloned scala-koans, run the built-in XSBT. IMPORTANT. Use the period to specify the current directory so it runs the built in XSBT and the global one that's possibly running on your system

On Linux or Mac:

$ ./sbt update clean test

On Windows:

% .\sbt update clean test

XSBT is a build system for Scala much like Ant, Maven, or Rake. The above commands will run the suite of koans (which are tests)

You will see some tests failing, don't sweat it. XSBT will make your koans writing experience a much quicker one.

Once you see the tests failing, but everything else working, you are ready to develop some koans!

Writing Koans

Choose an existing Koans class to work on, or create a new one of your own. If you do the latter, it is easiest to copy, rename and edit an existing Koans class like


One of these days I will get around to fixing the package names on this project. For now, that is where the tests live.

If you want to work on a specific Koans class, you will want to isolate that class from the others to test it. If you are using an IDE, you can edit `PathToEnlightenment.scala` and remove or comment out all tests except the one you are interested in. You can then set up a test execution to run that PathToEnlightenment class and you should be able to concentrate on just your test.

If you just want to use a text editor, or in some other tool that works well with XSBT, there is an easier option. Simply use:

$ sbt
[info] Building project ScalaKoans 1.0 against Scala 2.8.0
[info]    using FunctionalKoans with sbt 0.7.4 and Scala 2.7.7
> ~test-quick org.functionalkoans.forscala.AboutAsserts

Note the tilde, and replace AboutAsserts with the class you want to work on.

Now edit the class and when you save it, XSBT will automatically pick up the changes, recompile and run the tests again, giving you compile errors, test failures, or success status with a nice quick cycle time.

While in this continuous build and test mode in XSBT, you can exit at any time by hitting return. Also to exit the sbt shell, just hit CTRL-D.


The way I develop Koans is to write tests that work first, then go back and make them into exercises once the whole thing is running. For example, replace certain values with blanks (look at the other koans for examples), removing code definitions that satisfy the tests, and occasionally commenting out code that will not compile until code is written by the developer, in which case I leave a short message saying "uncomment this code and then write the extra code necessary to make it compile and work" or something like that.

Have fun!


The Scala Koans are licensed as Creative Commons -- NonCommercial.