%{
  title: "Learning to Swim test",
  author: "Willem van den Ende",
  tags: ~w(ATDD ComprehensionMaxxing CollaborationMaxxing SyntheticTDD Refactoring),
  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
- Standard flows and variations on them, implemented and inspectable simply

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 <x>" 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
----

- being able to see the whole and have confidence it fits together coherently
- testing as a feedback mechanism was secondary, strangely enough

Having the screens, step by step, gave me confidence where I was, and made it easy to identify the next step. It did turn out to have value as a technical feedback mechanism earlier than expected. I had worked bottom up for part of a feature, and added the next step in a flow once the parts were done. Some bits to integrate them were missing, as evidenced by the new step. Good encourgement to work acceptance test driven the next time.


On being able to have confidence in coherence
---

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 and the trees 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 work, 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 necessary for any collaborative application, visual or not, and they are different, because the combination of peoples' roles and assumptions are unique for each application.

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 <tool> 2.0?" . (more about <tool> later. previous blog posts drafts failed on digressions). 

Every application has workflows. They may not appear to be core, but they shape collaboration, so they are.


Working in small steps, AI augmented where useful
=====

I had an integration test that could serve as a starting point. But the workflow only had two steps. Several things are taken care of beforehand, analogous to the `login(''developer1')` in the Swim Systems paper. At least it was a good place to start, so the process was roughly:

1. Find out how to write pages and dialogs (a part of the page) as html
2. Decide how to collect these as the test progresses
3. Turn the collected parts into a report
4. Refactor the existing test towards a DSL
5. Add more steps
6. Go to 4.

For 1. I found a forum post, and I already had some [Synthetic](/blog/engineering/2026/07-13-synthetic-tdd.md) tests. This was also a good opportunity to re-read [the documentation](https://phoenix-live-view.hexdocs.pm/Phoenix.LiveViewTest.html). Rendering pages, components, selecting elements and getting the text back is all built in, so all we  need to do is wrap it in a page and save the parts. I did consider writing the reports out as markdown, with html snippets at some point. When rendering html to a pdf, the page breaks happen in the middle of screenshots sometimes. But the PDF already lacks the styling.

I initially iterated with [Pi](/blog/engineering/tag/pi.dev) on how to collect tests. I had a fancy idea of collecting the various dialogs in a process (well supported e.g. by Elixir GenServers), then thought of doing it the unix way (write out dialogs, than `cat` them all together), and ended up collecting step outputs in a list, and rendering the list at the end. This did require re-ordering the test a bit: the `assert` has to come at the end, after creating the report.

My assumption was that a model could generate more steps, after refactoring towards a simple flow of steps. The generated tests had some noise in parsing outputs to determine inputs for the next steps. Finding the right extractions was a bit of work, and at the same time gave me a better understanding of what I wanted.

Away from the desk, away from the screen?
----

I was mostly away from my desk last week. After getting three steps working, in small steps, refactoring by hand (my local model had some trouble moving things around in to files, and I needed to learn more about how to organise tests and support code in a Phoenix Liveview project ), the basic flow is now at five steps. Pi with Deepseek v4 flash did most of that, with me doing 'yes' prompts from my phone. 

![Screenshot of Pi session - featuring 'insufficient credits'](/static/images/blog/2026/pidev-step5-generated.png)

This insufficient credits message hasn't happened to me in a while. I deposited 25 USD in may last year on OpenRouter. Since then I mostly used Claude Code or local models. Being away from my desk means running Pi on a server, with deepseek. I spent about 10$ in the last month, preparing a keynote and TDD with AI workshops for Philips (hit me up if you are interested too, at QWAN we are responsibly extending our offerings, now that we have a better understanding of how to augment teams, and improve the outcomes and quality using coding agents). So probably about 1 or 2 $ on workshop preparation and 8 for the testing support and bringing a vibe TDD'ed app to production.

It is nice to be able to make progress while having friends over. I have learned to not multi-task too much, and when a question is too big to answer on my phone, I will just percolate on it. Good designs come from working on that - you have to be seen working for creativity to happen, and from stepping away from the screen and coming back with a fresh perspective.


Show me the reports
====

TODO add validation failure report, and full flow so far.

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. I built towards the principles above, learnt a few things, got some value out early, and now have an idea of the next steps. 



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

John Nolan on explaining what happened after the fact

Machiel Groeneveld on wanting the reasoning
