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 new file mode 100644 index 0000000..bd49ab3 --- /dev/null +++ b/app/priv/blog/engineering/2026/07-27-swim-the-test.md @@ -0,0 +1,80 @@ +%{ + title: "Swim the Test", + author: "Willem van den Ende", + tags: ~w(ATDD ComprehensionMaxxing CollaborationMaxxing), + description: "Every application has some kind of workflow. Understanding larger workflows, making them cohesive and understandable to users and developers is non-trivial. I re-discovered Ward Cunningham's Swim the Test approach, this is the Further Reading section of future posts.", + published: true +} +--- + +TLDR; +---- +Every application has some kind of workflow. Understanding larger workflows, making them cohesive and understandable to users and developers is non-trivial. I re-discovered Ward Cunningham's Swim the Test approach, this is the Further Reading section of future posts. + +[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, + +> 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 +> documentation. + +Why this post? +==== + +Refactoring integration tests towards *Swim the Test* turns out to be easier than to write about it. And was not as hard as I thought - it can be done in baby steps. I keep both losing the literature references, and at the same time finding more or them. So getting them out of the way should help me post a 'how' post more easily. + +Swim the test +==== + +> Finally you can *swim the test*. Here the steps and results are laid out in a +> 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) +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. + +The "Swim" paper +==== + +I learnt about the Swim system when Ward Cunningham ran a session about it at the first Agile Open Northwest (2006 or 2007 I think - this is a blog post, I may do the research later or it doesn't ship..) + +[The "Swim" System for User-Oriented Presentation for Test-Case results](https://wiki.eclipse.org/images/2/20/Swim_System_PNSQC_2007_Paper.pdf) by Ward Cunningham +Bjorn Freeman-Benson and Karl Matthias + +I only found this paper existed now that I went looking for it. It also explained (when you read it back to front) on how to get started. The workflow with swimlanes looks very sophisticated. It mentiones `run.php` further down, which is 'just' one flow with some screenshots. + +The reason I was attracted to domain modelling (long before Eric Evans' 2003 DDD book) was this: + +> 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 +> documentation. + +Simplicity is achieved when there is nothing left to take away. Compare this to DDD's "Ubiquitous Language". The scare quotes are intentional. As a non-native speaker I had to look up Ubiquitous. Compare this with the paragraph above. I appreciate many of the user-focused things that come out of the DDD community, like Event Storming, but ask yourself, if a patterns introduce barriers to outsiders, or if it removes them (and when introducing barriers, is the trade-off worth it?). + +>At the same time, +> our abstractions are detailed enough to be believed because we are running the real code in our +> simulations instead of bubbles and arrows diagrams. We respect the user's expertise without +> dumbing down our system or forcing them to use our terminology. + + +A large application is built in many small steps +===== + +This looks like a lot of work, and I haven't integrated this in an application. Yet. Reworking existing integration tests to output dialogs as HTML for each step was not _that_ much work, and the rewards are instantaneous: multi-step workflows now become glanceable. And as they get longer, I can make small improvements to improve glanceability. + +I am trying to draw in the users as well, let's see how this goes. + +Further Reading +==== + +This is meta - a Further Reading section in a further reading post ;-). + +[A Harness for Behaviour: Ensuring Ai-generated Code Does What We Want - TDD in the Age of AI ](https://www.youtube.com/watch?v=3tdmoj35HG0) +I was reminded of the swim system by this talk of Matteo Vaccari on youtube which focuses on tests that are understandable by the stakeholders. He referenced Fit and focuses on writing tests that work as a communication medium between users, stakeholders and developers. He uses an external DSL in YAML. I am not against YAML, but someoone's remark last year that all new programming languages appear to be YAML gives me pause, whenever I see it. The main thing is when it works it works. Context is key. (not further reading: I ended up with an internal DSL and screenshots in small steps as a medium - the users don't need to be able to write tests, yet, communication about what we are building and how it works is key. In small steps - I don't believe good UX comes from large batches). [LinkedIn post on Matteo's account](https://www.linkedin.com/posts/matteovaccari_the-video-of-my-presentation-at-platmosphere-share-7478330775579586560-vSoX) in case you want to comment. + + +[Visible Workings]( https://web.archive.org/web/20110202132102/http://visibleworkings.com) on archive.org, as the original site is no longer active. I like the notion of "Tinkerable Software". + +[Acceptance tests for AI Assisted development](https://matteo.vaccari.name/posts/acceptance-tests-for-ai-assisted-development/) on "grey box testing". Refers to [Approved Fixtures Pattern](https://lexler.github.io/augmented-coding-patterns/patterns/approved-scenarios/) and is also worth reading on its' own.