(Chapa 1)


Test blocks: eev @ EmacsConf 2021

My talk at the EmacsConf2021 was about test blocks.
Here are its slides and its video.
See my old page on test blocks, and my talks at the EmacsConf2020 and EmacsConf2019.

Title: Test blocks
Intended duration: 5 minutes

In this presentation I will show an idea that feels completely obvious once we see it, but that only occured to me after after using Emacs and eev as my main interface to the computer for more than 20 years. Take any interpreted language that supports multi-line comments, and whose interpreter can be run in an Emacs buffer - for example Lua, Haskell, Python, or Julia; let's say just "Lua" from here on for simplicity. So: suppose that we have a Lua script that we wrote, that is called "foo.lua" and that defines lots of functions and defines the classes Bar and Bletch. We can put after the definition of the class Bar a multi-line comment that contains an eepitch block that when executed starts a Lua interpreter, loads the script foo.lua (by running 'dofile "foo.lua"'), and then has several tests for that class and its methods; and we can put another block with tests like that after the class Bletch, and other blocks after some functions. Eepitch allows sending these tests line by line to the Lua interpreter by typing <f8> on each line that we want to send, and this lets us create tests that are very easy to understand even without writing comments; this gives us a very quick way to document code by executable tests, that is super-great for experimental code that is still going to change a lot before running the risk of being read by other people.

These multi-line comments with eepitch blocks that run an interpreter and make it load the current file are called "test blocks". The command `M-x eeit' inserts a test block at point, using the major mode to decide the right syntax to use for the multi-line comments and for the "dofile". We can configure the syntax of the test blocks for the current major mode by running `M-x find-eeit-links'; this can also be used to add support for test blocks to more languages (or, more precisely: to more major modes).


Here is a hack to use test blocks in languages without multi-line comments.
You can watch the video of my presentation with subtitles here.
You can download a local copy of it with (find-1stclassvideo-links "eev2021") or with:

# See:  http://anggtwu.net/eev-videos.html
#       http://anggtwu.net/eev-videos.html#mpv-keys
# Play: (find-eev2021video "0:00")
# Info: (find-1stclassvideo-links "eev2021")
# Subs: (find-1stclassvideolsubs  "eev2021")

wget -nc http://anggtwu.net/eev-videos/emacsconf2021.mp4
wget -N  http://anggtwu.net/eev-videos/emacsconf2021.vtt
mpv --fs --osd-level=2 emacsconf2021.mp4

A real-world example (2021nov28)

Test blocks became one of my favorite ways to document my code. I'm using them a lot in Dednat6; this video shows how, and it also shows how you can run those test blocks yourself. Note that most video introductions on eev, like this one, stress that the three basic keys of eev are M-e, M-j, and M-k, but for running test blocks you only need to use <f8>, that is the fourth of the three basic keys.

In the beginning I thought that using test blocks as documentation could scare some people, but then 1) I reminded myself that very few people use dednat6, and that now that things like Quiver are available even fewer people are going to be interested in trying a text-based tool like dednat6, 2) my friends who tried the test blocks grokked them in seconds.

sudo apt-get install lua5.1

rm -Rfv /tmp/dednat6/
mkdir   /tmp/dednat6/
cd      /tmp/dednat6/
git clone https://github.com/edrx/dednat6 .

# (find-fline "/tmp/dednat6/")
# (find-fline "/tmp/dednat6/dednat6/")
# (find-fline "/tmp/dednat6/dednat6/edrxlib.lua")
# (find-anchor "/tmp/dednat6/dednat6/zhas.lua" "MixedPicture-arch-tests")

 (code-c-d "dn6"     "/tmp/dednat6/dednat6/" :anchor)
 (setenv "LUA_INIT" "@/tmp/dednat6/dednat6/edrxlib.lua")
 (find-dn6 "zhas.lua" "MixedPicture-arch-tests")
 (find-dn6 "zhas.lua" "shortoperators-tests")

Here's a quick index to the video that shows how I use test blocks in Dednat6:

0:33  What I am going to show
0:47  Dednat6 is an extensible (semi-)preprocessor
0:58  sometimes we want to draw diagrams like this
1:12  that would understand some ... in comments
1:38  and it also supports diagrams for Category Theory
1:57  LaTeX interprets these things as comments but
2:13  Dednat6 is very extensible
2:28  very boring to draw by hand
2:43  In the beginning I thought that using test blocks...
3:06  now that we have things like Quiver
3:36  and this gave me much more freedom
3:50  I showed to some friends
4:06  Let me show how these test blocks work
4:25  Note that these things are not red stars
4:32  this sexp will make them behave as red stars
4:41  f8 four times
5:15  these two lines ... I don't want to explain
5:29  this one is easy ... is just a hyperlink
5:37  this anchor in is the middle of a very big test block
5:42  if we execute it with f8
6:07  so let me execute these tests
6:23  these lines create a certain object and display it
6:36  I can also change these tests
7:03  run some undos here
7:07  these objects correspond to these diagrams
7:24  I am also going to show another test block
7:28  this one here
7:43  they correspond to these diagrams here
7:54  this demo here can be executed by just typing
7:57  f8 in the right places

You can download the video and the subtitles of the demo using the two "wget"s below:

# See:  http://anggtwu.net/eev-videos.html
#       http://anggtwu.net/eev-videos.html#mpv-keys
# Play: (find-eev2021bvideo "0:00")
# Info: (find-1stclassvideo-links "eev2021b")
# Subs: (find-1stclassvideolsubs  "eev2021b")

wget -nc http://anggtwu.net/eev-videos/emacsconf2021-dednat6.mp4
wget -N  http://anggtwu.net/eev-videos/emacsconf2021-dednat6.vtt
mpv --fs --osd-level=2 emacsconf2021-dednat6.mp4