diff --git a/app/priv/blog/engineering/2026/07-27-swim-the-test.md b/app/priv/blog/engineering/2026/07-27-swim-the-test.md index 98e5f79..feb4a1f 100644 --- a/app/priv/blog/engineering/2026/07-27-swim-the-test.md +++ b/app/priv/blog/engineering/2026/07-27-swim-the-test.md @@ -13,7 +13,7 @@ Every application has some kind of workflow. Understanding larger workflows, mak [Jon Uddell's 2008 post about Ward Cunninghams' implementation of Brian Marick's 'Visible Workings'] https://blog.jonudell.net/2008/03/04/ward-cunninghams-visible-workings/ is a succinct introduction . connecting the Visible Workings pattern to the implementation made for a workflow system on behalf of the Eclipse Foundation. -[The "Swim" System for User-Oriented Presentation for Test-Case results](https://wiki.eclipse.org/images/2/20/Swim_System_PNSQC_2007_Paper.pdf). Plain spoken Paper by Ward Cunningham, +[The "Swim" System for User-Oriented Presentation for Test-Case results](https://wiki.eclipse.org/images/2/20/Swim_System_PNSQC_2007_Paper.pdf). Plain spoken Paper by Ward Cunningham, Bjorn Freeman-Benson and Karl Matthias. > Perhaps the highest compliment we received was when one of our customers (SC) said that she > easily understood how everything worked because it "uses her words" in the interface panels and @@ -31,9 +31,10 @@ Swim the test > table. Time advances as you move down the rows, and there’s a column for every actor in the workflow. -![Screenshot by Jon Udell](https://i0.wp.com/jonudell.net/img/visibleworking3.png?w=656) +!["Change personal address" Sequence diagram. 'Start' at the left, 'big2' and 'emo' column. big2 did some actions, and this results in 'User address changed'. Followed by some 'variations' (the swim paper in the linked post explains this). The 'emo' column has one 'emo address changed' box. Screenshot by Jon Udell](https://i0.wp.com/jonudell.net/img/visibleworking3.png?w=656) Screenshot by Jon Udell. -[Jon Uddell's] https://blog.jonudell.net/2008/03/04/ward-cunninghams-visible-workings/ is a succinct introduction . connecting the Visible Workings pattern to the implementation made for a workflow system on behalf of the Eclipse Foundation. +[Jon Uddell's post]( https://blog.jonudell.net/2008/03/04/ward-cunninghams-visible-workings/) is a succinct introduction . connecting the Visible Workings pattern to the implementation made for a workflow system on behalf of the Eclipse Foundation. + The "Swim" paper ==== diff --git a/app/priv/blog/engineering/2026/07-28-learning-to-swim-test.md b/app/priv/blog/engineering/2026/07-28-learning-to-swim-test.md new file mode 100644 index 0000000..3cae7a0 --- /dev/null +++ b/app/priv/blog/engineering/2026/07-28-learning-to-swim-test.md @@ -0,0 +1,111 @@ +%{ + title: "Learning to Swim test", + author: "Willem van den Ende", + tags: ~w(ATDD ComprehensionMaxxing CollaborationMaxxing), + description: "The faster you can build, the more pressing communication with others and understanding together becomes. You can build software to promote understanding and collaboration, but where do you start? I found a foothold in the 'swim tests' paper and existing integration tests.", + published: false +} +--- + +I often find it easier to do and build stuff than to write about it. Getting over the 'further reading' section in [swim the test](https://willemvandenende.com/blog/engineering/swim-the-test) appears to have freed me up to write more. + +I wrote with the LinkedIn comment announcing that post: + +> The faster you can build, the more pressing communication with others and understanding together becomes. + +A view of a foothold +==== + +Reading the "Swim System" paper, it is clear that you can build software to promote understanding and collaboration, but where do you start? I found a foothold in the existing integration tests, and a discussion on page 14 and 15 of the [Swim Systems paper](https://wiki.eclipse.org/images/2/20/Swim_System_PNSQC_2007_Paper.pdf). + +![Screenshots. A dialog with test annotations on the left, a sequence diagram with test results on the right](/images/blog/2026/swim-asterisk-dialog.png) + +The left part of the screenshot, a dialog with some steps, was something I could build. There is a description of how they abstracted the report creation so one source produces multiple targets, e.g. the dialog on the left and the swimlane view on the right. That is also something that can be factored out later, starting with a point solution. + +I eventually read the whole paper front to back after skimming it and pondering it over. I also remember what Ward Cunningham mentioned when he presented this work: that tools like Fit(Nesse) and this are contextual, and these are something to be made in context, not off-the-shelf tools. So I read this paper, contrasted it with Matteo Vaccari's work, and my own experience in stakeholder and user-focused tests, and what we needed for the application I am working on. + +What do we want? +==== + +From the swim systems paper +--- + +I liked: + +- application dialogs as a way to explain the system +- backlinks to the tests from the dialogs in the actual application +- display of errors inline +- The swimlanes, and the way events are used + +I think the paper predates the Event Sourcing hype, seeing the past-tense framed things in the swimlanes + +What I missed from the paper, and can now see after starting to build: + +- Failing tests also displayed in the report (see the red "Trouble can't find " sections on the right) + +![Screenshots. Passed example on the left - title is a green bar. Failed example on the right, red heading and two 'trouble' bars. A clock and timestamp indicate when the tests were run.](/images/blog/2026/swim-asterisk-example.png) + +What I wanted to do differently: + +Some actions are abstract enough, eg. _login 'developer1'_ others are too UI focused for what I need. The order in which fields are filled in is often not important. Or so I thought, when writing this I have written some tests where one action makes another one (im)possible. So most of the time a whole dialog can be worked through by data, using the Test Data Builder pattern to allow for differences. + +I have a test setup out of the box (Phoenix Liveview Test) that works well enough, and I guessed (correctly) that it would have primitives to export HTML for the reports as well. + +So to start with, I decided to produce reports, and leave reporting on unmet expectations to regular assertions in the existing test framework. + +From Matteo Vaccari's ATDD and AI talk +---- + +Matteo presented an external DSL. I liked the idea of a DSL, and decided to start with an internal DSL first. Elixir has good support for this, and I could drive this by extracting helpers from existing tests and making the scenarios longer so there are more steps in the workflow. + +Some of the lines in Matteo's DSL I found a bit HTTP specific on seeing it, but then found that my tests made by [Synthetic TDD](/blog/engineering/synthetic-tdd) also suffered from this. At one point a response is parsed for an identifier that is used in subsequent tests. + +See below in working in small steps on how I am dealing with that. + +From my own failures +---- + +The swim systems paper appealed to me, because I have trouble keeping an overview of workflows with multiple steps. This was always a challenge working in the XP way, as we very quickly can create a well-tested app with complicated flows. Keeping the whole coherent and 'ready to mind' is hard. "Ready to hand" with good unit tests became very cheap, but seeing the forest was sometimes difficult. + +This became worse with LLM generated systems. When I can create a prototype out of thin air in a couple of hours, with hundreds of tests, and several screens and can let a coding agent produce the demos (see previous posts) it feels great. But when someone else is interested and asks me how it fits together, that becomes a lot harder. + +I was hesitant to take some of my visual collaboration tools to market, and I did not understand why. After building the first steps of workflow tests I do understand. It may look like a collaboration tool is about the sticky notes, but the magic is in the collaboration rules that are encoded in things like how groups are structured, how invitations works, what the unit of a 'tenant' is in a SaaS applications, who gets to (dis)invite who, how, when? Or in moderation: who invited this _Person_ and why? + +It is great brainstorm-building a mobile first product outcomes focused board, but then adding teams and seeing bits of flow missing is annoying. These flows are neccessary for any collaborative application, visual or not, and the are different, because peoples' roles and assumptions are different for each. + +So I wanted, just for myself, to see as much of the flow as possible. End-to-End tests through browsers are now very cheap to make (I can make dozens in a day), but maintaining and running them is not. Especially when I am working on my laptop with a coding agent. Having sandboxed the agent, accessing a browser is not trivial. + +The unit and integration tests I have so far do give me confidence that most things work, but not that the whole application flows hang together as I want. This was triggered by a stakeholder asking: "Where are we with 2.0?" . (more about later). + + + + + + + + +Working in small steps, AI augmented where useful +===== + + + + + + +Reworking is easier than writing +==== + +Reworking and refactoring existing user-focusing integration tests towards this turns out to be easier than writing about it. A number of ideas collide, and I had trouble keeping track of the references. So the first blogpost about this was the "further reading" section. + +And here as well, Programming as theory building works. + + +Further Reading +---- +[Swim the test](https://willemvandenende.com/blog/engineering/swim-the-test) has more of the literature background, including the Sim Systems paper and what I mentioned about Matteo Vaccari. + +The Swim Systems paper is well worth reading, it is as good as any of my favourite software engineering papers from the 1970s (but 30 years more recent). + +Felienne on Programming as Theory Building + +Refactoring to Patterns