I’ve recently written a series of articles about Gherkin: its usage for requirements gathering, about its uses in BDD, and a lower-tech alternative to Cucumber, which I’m still experimenting with.

I wanted to showcase all of these ideas brought together, as well as show how comfy modern Python tooling can be. But more than writing code, I would need to explain my reasoning as we draft the program. So I picked up again a tool I always wanted to play with: Literate Programming.

Literate programming is a technique consisting of weaving together code by writing a story (blogpost to novel-sized), with code snippets embedded in the story as we think of the design. Specialised tooling exports these code blocks to their permanent location in the code repository, so that the programming language’s tooling kicks in to build, test, and validate.

Regarding what to program about, I wanted something that was simple enough to read through in one sitting, but meaty enough to have a couple surprises during implementation. The opportunity presented itself with the recent viral spread of Wordle.

So I present you my “Literate Wordle”, a modern Python codebase written in literate programming style, using TDD and BDD. Have a look at the Github repository literate-wordle, and the rendered version of the docs, on my website the pretty version of the project “story” on my website.

Other than being a novella-sized text, the extracted codebase is quite plain and normal-looking (as you can see in Github), with just a little bit of automation done around the documentation generation, so that the features/ folder (where Gherkin Features are) is picked up by the Sphinx docs as Requirements.

I am excited about ways to augment this project, such as using the implemented scoring to explore wordle solving: brute-force the scoring function for all valid inputs, store the results in database, and expose the database as a simple wordle solver interface: Given you got score “🟩🟨⬜⬜⬜” for guess “crane”, these are the possible answers…

But most importantly, this is a codebase that implements the pattern of Gherkin in test comments I described in my lower-tech alternative to Cucumber article. The code is sizeable enough that one could meaningfully compare the content of the features/ folder with the show-gherkin() content of the tests/ folder. I’m writing tool to automate such a cucumber-like check, and hope to reveal details on this blog soon.