A testing library that turns your README into executable tests  ↦

This is a very cool idea coming out of the Clojure community. I dig it because the examples in your README are guaranteed to never become stale as your project evolves.

It works by parsing your README and looking for executable code samples with expected outputs. For each one it finds, it generates a test ensuring that executing the code produces the output.

There are, as you might expect, caveats.


Sign in or Join to comment or subscribe

2020-03-04T16:59:47Z ago

2020-03-08T17:39:24Z ago

Yes, I’ve used midje-readme for years on several projects but I wanted something that was a) simpler with fewer dependencies and b) supported the more common user=> REPL session format I see in a lot of README files.

2020-03-09T04:44:40Z ago

Ah. Nice about the format.

I guess midje-readme could isolate out the single dependency on Watchtower to a sub feature for the live case. Oh well, I don’t do any Clojure anymore :) But if someone submits a PR I’ll give commit rights.

2020-03-09T05:15:40Z ago

The dependency I wanted to avoid was Midje itself! That drags in a ton of other things. I know projects that were using midje-readme but were not otherwise using Midje for testing so this is targeting those (such as HoneySQL, which I maintain these days).

2020-03-09T05:23:57Z ago

Oh. In my day midje was the thing everyone used. I guess that’s no longer the case! Thanks for clarifying this.

I’m happy to see you make the effort to have the line numbers In the tests align with the readme. This was, I believe, my original idea.

Player art
  0:00 / 0:00