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
WIP!

# 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
```

i::test_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. 

i::data_round_2.txt::

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.

Image: https://flic.kr/p/cwVQqW
Syntax highlighting: pinetools