Skip to main content

Notes on Testing Notes

Ben Dowen pinged me and others on Twitter last week, asking for "a nice concise resource to link to for a blog post - about taking good Testing notes." I didn't have one so I thought I'd write a few words on how I'm doing it at the moment for my work at Ada Health, alongside Ben.

You may have read previously that I use a script to upload Markdown-based text files to Confluence. Here's the template that I start from:

# Date + Title

# Mission

# Summary

# Notes
Then I fill out what I plan to do. The Mission can be as high or low level as I want it to be. Sometimes, if deeper context might be valuable I'll add a Background subsection to it.

I don't fill in the Summary section until the end. It's a high-level overview of what I did, what I found, risks identified, value provided, and so on. Between the Mission and Summary I hope that a reader can see what I initially intended and what actually happened.

The Notes section is primarily for me. It supports my testing while it's in progress and is completely freeform: I can work however I want to within it. By default, I fill it chronologically (so it can be read back in the order I did things) but I'm not constrained by that. Sometimes I organise it by component tested, or size of test data, or something else.

Depending on the task at hand, how broad and deep I think it'll be, and how long I think I'll be spending,  I might dump a bunch of test ideas first into the Notes. Other common starting points might be a risks subsection, links to a mindmap, or a quick summary of the testing I did informally before realising I'd found enough that I wanted to document it.
Let's look at a real recent example with extracts sanitised from the last set of notes I wrote at work on Friday. The Mission and Summary were:
# Mission
Explore the changes in Tickets X, Y, and Z using the UI and bulk 
analysis at the API to look for inconsistencies. # Summary From a high-level analysis through the API I didn't see any issues.
All the cases I checked were either correct, empty, or not applicable
for valid reasons. I was not able to check for adverse effects in other components because
I don't have access to them. There's a risk that the function used to perform this action won't generalise,
but the developer has checked all currently-supported scenarios.
The Notes section is structured like this, reflecting work done in roughly time order:
## Code Review
## Check on Scope
## UI Sanity
## Review
## Underlying Function
## Final Checks
In Code Review I looked at the code changes as there were multiple tickets altering different parts of the stack. I noted a particular function otherFunction() that I thought might not generalise well.
I looked through the changes in the tickets. somefile.ts does this:

export const function = ... otherFunction() ...;
Once I'd done that, I proposed to the developer what I thought the work was and how I could check it, but also noted that (as a guest on this team for this project) I didn't have access to all of back-end components. That conversation happened in Slack but I copy-pasted a summary of it into Check on Scope.
Me:  If I read the code right, I think that I should expect ...

Developer: exactly, that’s it: instead of ... we do ...
It was a useful exchange to have because the developer said she had a couple more commits still to make, in a couple of tickets I hadn't been aware of, and she'd let me know when she was done.

I had a quick look at the UI and found no problems, which I noted in UI Sanity.

As I already had some bulk API data I worked up a few bash commands (essentially a temporary test rig) to check it for inconsistencies. I didn't see anything problematic and I copy-pasted the details of the commands into the Review section, and attached my data (the i::filename:: notation):
Extract relevant data from yesterday's runs: 

$ grep -h "<pattern1>" * | jq '.' | grep <pattern2>  > data.txt
$ sort -u -b data.txt > data.sorted.txt


Look for any inconsistent strings:

$ grep "<pattern3>" data.sorted.txt

OK This looks fine.
Next, I went back and exercised otherFunction()with some variant data then spoke to the developer again. She'd had a similar idea about generalisability and done research already. I summarised that in Underlying Function.

Finally, once all the changes were ready, I generated some bulk API test data, ran it through my rig, sanity checked the behaviour of the rig (you do that too, don't you?) and confirmed that, again, no inconsistencies were found. The finding but not the approach this time was documented in Final Checks.
I looked again after a couple more changes in Ticket N, Ticket M. 


OK No inconsistencies
This was a short session, over in an hour maybe, but I can use the same notes file across days in some investigations.

I don't always write notes. Sometimes I'll spike first and see if anything interesting crops up. If I know it's going to be quick and dirty, or I don't think I need to document it, or it's really speculative I might not write anything down. 

On the other hand, sometimes I'll stop one set of notes and start another for a side-investigation on a different topic that's cropped up. I'll also pause and write some notes when I realise that I'm holding a lot of things in my head. I might make a list of ideas in the current notes, write a temporary file holding new missions, or scribble down some reminders on a piece of paper.

I write as I go, recording questions to myself, answers to those questions, approaches taken, to-dos to come back to, and so on. Why? For example, because I often have to put work aside and I want to be able to pick it up again later, because I can then run searches over my notes for ways I have done things in the past and re-use them, because I want my work to be transparent so that others can spot mistakes I've made, and because any piece of my testing might be audited.

I organise my notes by date in this kind of directory structure:

I work in the same directory as my notes, collecting artefacts there for easy attachment and so that all of the materials I've used for a piece of work are together. I've lost count of the number of times this has been valuable to go back to: How did I ...? What was that thing ...? Didn't I see this before ...?  

I write my notes in Markdown augmented with some of my own macros for convenience. This means that I can easily upload configuration files, test data and so on alongside my notes just by referencing them in the text file. 

I use other tools such as mind maps or spreadsheets or whiteboards when they make more sense. I link them from my notes though and I cross-reference back to the notes too. 

I've put an enormous amout of deliberate thought and effort over the years into practicing getting down just the information that I think will be useful, first time, concisely. I want to minimise friction and distraction from testing to take my notes
Typically I will tab into the text editor, write a note or paste something from the console, and then tab back to application I'm testing within a second or two. Optimising for flow is a key requirement for me, which I why I also work hard on learning and improving the tooling around my note taking.
Ben, I hope that's helpful.
Syntax highlighting: pinetools


  1. There are also some tools made for note taking and collecting data during exploratory sessions like Rapid Reporter by Shmuel Gershon.
    Looking back over the past 25 years, I recall starting using paper notebooks, then moving to Notepad++ for most of my notes.
    Now a days the younger generation don't hold pens on them anymore, even I stopped doing that at some point :-) , so unless we go for a pre-arranged meeting and take a notebook and pen, most times people around me are not keeping written notes apart from the defined meeting scribe.
    On-Line meetings over MS-Teams/Zoom etc. allows working from the comfort of your office/home desk - where its mostly easier to scribe some notes

  2. Hi James,

    Not to detract from your excellent blog/writing.

    Michael Bolton hits the ball out of the ball park with this article on note taking:

  3. This article was curated as a part of the #53rd Issue of Software Testing Notes newsletter.


Post a Comment

Popular posts from this blog

Enjoy Testing

  The testers at work had a lean coffee session this week. One of the questions was  "I like testing best because ..." I said that I find the combination of technical, intellectual, and social challenges endlessly enjoyable, fascinating, and stimulating. That's easy to say, and it sounds good too, but today I wondered whether my work actually reflects it. So I made a list of some of the things I did in the last working week: investigating a production problem and pairing to file an incident report finding problems in the incident reporting process feeding back in various ways to various people about the reporting process facilitating a cross-team retrospective on the Kubernetes issue that affected my team's service participating in several lengthy calibration workshops as my team merges with another trying to walk a line between presenting my perspective on things I find important and over-contributing providing feedback and advice on the process identifying a

Testing (AI) is Testing

Last November I gave a talk, Random Exploration of a Chatbot API , at the BCS Testing, Diversity, AI Conference .  It was a nice surprise afterwards to be offered a book from their catalogue and I chose Artificial Intelligence and Software Testing by Rex Black, James Davenport, Joanna Olszewska, Jeremias Rößler, Adam Leon Smith, and Jonathon Wright.  This week, on a couple of train journeys around East Anglia, I read it and made sketchnotes. As someone not deeply into this field, but who has been experimenting with AI as a testing tool at work, I found the landscape view provided by the book interesting, particularly the lists: of challenges in testing AI, of approaches to testing AI, and of quality aspects to consider when evaluating AI.  Despite the hype around the area right now there's much that any competent tester will be familiar with, and skills that translate directly. Where there's likely to be novelty is in the technology, and the technical domain, and the effect of

The Great Post Office Scandal

  The Great Post Office Scandal by Nick Wallis is a depressing, dispiriting, and disheartening read. For anyone that cares about fairness and ethics in the relationship that business and technology has with individuals and wider society, at least. As a software tester working in the healthcare sector who has signed up to the ACM code of ethics through my membership of the Association for Software Testing I put myself firmly in that camp. Wallis does extraordinarily well to weave a compelling and readable narrative out of a years-long story with a large and constantly-changing cast and depth across subjects ranging from the intensely personal to extremely technical, and through procedure, jurisprudence, politics, and corporate governance. I won't try to summarise that story here (although Wikipedia takes a couple of stabs at it ) but I'll pull out a handful of threads that I think testers might be interested in: The unbelievable naivety which lead to Horizon (the system at th

Agile Testing Questioned

Zenzi Ali has been running a book club on the Association for Software Testing Slack and over the last few weeks we've read Agile Testing Condensed by Janet Gregory and Lisa Crispin. Each chapter was taken as a jumping off point for one or two discussion points and I really enjoyed the opportunity to think about the questions Zenzi posed and sometimes pop a question or two back into the conversation as well. This post reproduces the questions and my answers, lightly edited for formatting. --00-- Ten principles of agile testing are given in the book. Do you think there is a foundational principle that the others must be built upon? In your experience, do you find that some of these principles are less or more important than others?  The text says they are for a team wanting to deliver the highest-quality product they can. If we can regard a motivation as a foundational principle, perhaps that could be it: each of the ten pr

Testers are Gate-Crashers

  The Association for Software Testing is crowd-sourcing a book,  Navigating the World as a Context-Driven Tester , which aims to provide  responses to common questions and statements about testing from a  context-driven perspective . It's being edited by  Lee Hawkins  who is  posing questions on  Twitter ,   LinkedIn , Mastodon , Slack , and the AST  mailing list  and then collating the replies, focusing on practice over theory. I've decided to  contribute  by answering briefly, and without a lot of editing or crafting, by imagining that I'm speaking to someone in software development who's acting in good faith, cares about their work and mine, but doesn't have much visibility of what testing can be. Perhaps you'd like to join me?   --00-- "Testers are the gatekeepers of quality" Instinctively I don't like the sound of that, but I wonder what you mean by it. Perhaps one or more of these? Testers set the quality sta

Leaps and Boundary Objects

Brian Marick  recently launched a new podcast, Oddly Influenced . I said this about it on Twitter: Boundary Objects, the first episode of @marick's podcast, is thought-provoking and densely-packed with some lovely turns of phrase. I played it twice in a row. Very roughly, boundary objects are things or concepts that help different interest groups to collaborate by being ambiguous enough to be meaningful and motivational to all parties. Wikipedia  elaborates, somewhat formally:  [boundary objects are] both plastic enough to adapt to local needs and constraints of the several parties employing them, yet robust enough to maintain a common identity across sites ... The creation and management of boundary objects is key in developing and maintaining coherence across intersecting social worlds. The podcast talks about boundary objects in general and then applies the idea to software development specifically, casting acceptance test

Where No-one Else Looks

In yesterday's post, Optimising start of your exploratory testing , Maaret Pyhäjärvi lists anti-patterns she's observed in testers that can lead to shallow outcomes of testing. She ends with this call: Go find (some of) what the others have missed! That strikes a chord. In Toujours Testing I recalled how my young daughter, in her self-appointed role as a Thing Searcher, had asked me how she could find things that no-one else finds. I replied Look where no-one else looks. Which made her happy, but also made me happy because that instinctive response externalised something that had previously been internal.  The phrase has stuck, too, and I recall it when I'm working. It doesn't mean targeting the obscure, although it can mean that.  It also doesn't mean not looking at areas that have previously been covered, although again it can mean that. More, for me, it is about seeking levels of granularity, or perspectives, or methods of engagement, or personas, or data, or im

Am I Wrong?

I happened across Exploratory Testing: Why Is It Not Ideal for Agile Projects? by Vitaly Prus this week and I was triggered. But why? I took a few minutes to think that through. Partly, I guess, I feel directly challenged. I work on an agile project (by the definition in the article) and I would say that I use exclusively exploratory testing. Naturally, I like to think I'm doing a good job. Am I wrong? After calming down, and re-reading the article a couple of times, I don't think so. 😸 From the start, even the title makes me tense. The ideal solution is a perfect solution, the best solution. My context-driven instincts are reluctant to accept the premise, and I wonder what the author thinks is an ideal solution for an agile project, or any project. I notice also that I slid so easily from "an approach is not ideal" into "I am not doing a good job" and, in retrospect, that makes me smile. It doesn't do any harm to be reminded that your cognitive bias

External Brains

A month or two ago, after seeing how I was taking notes and sharing information, a colleague pointed me at Tiego Forte's blog on Building a Second Brain : [BASB is] a methodology for saving and systematically reminding us of the ideas, inspirations, insights, and connections we’ve gained through our experience. It expands our memory and our intellect... That definitely sounded like my kind of thing so I ordered the upcoming book, waited for it to arrive, and then read it in a couple of sittings. Very crudely, I'd summarise it something like this: notes are atomic items, each one a single idea, and are not just textual notes should capture what your gut tells you could be valuable notes should capture what you think you need right now notes should preserve important context for restarting work notes on a topic are bundled in a folder for a Project, Area, or Resource and moved into Archive when they're done. ( PARA )