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

Comments

  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

    ReplyDelete
  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: https://www.developsense.com/presentations/2007-10-PNSQC-AnExploratoryTestersNotebook.pdf

    ReplyDelete
  3. This article was curated as a part of the #53rd Issue of Software Testing Notes newsletter.
    https://softwaretestingnotes.substack.com/p/issue-53-software-testing-notes

    ReplyDelete

Post a Comment

Popular posts from this blog

Can Code, Can't Code, Is Useful

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-- "If testers can’t code, they’re of no use to us" My first reaction is to wonder what you expect from your testers. I am immediately interested in your working context and the way

Meet Me Halfway?

  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-- "Stop answering my questions with questions." Sure, I can do that. In return, please stop asking me questions so open to interpretation that any answer would be almost meaningless and certa

Not Strictly for the Birds

  One of my chores takes me outside early in the morning and, if I time it right, I get to hear a charming chorus of birdsong from the trees in the gardens down our road, a relaxing layered soundscape of tuneful calls, chatter, and chirrupping. Interestingly, although I can tell from the number and variety of trills that there must be a large number of birds around, they are tricky to spot. I have found that by staring loosely at something, such as the silhouette of a tree's crown against the slowly brightening sky, I see more birds out of the corner of my eye than if I scan to look for them. The reason seems to be that my peripheral vision picks up movement against the wider background that direct inspection can miss. An optometrist I am not, but I do find myself staring at data a great deal, seeking relationships, patterns, or gaps. I idly wondered whether, if I filled my visual field with data, I might be able to exploit my peripheral vision in that quest. I have a wide monito

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

Postman Curlections

My team has been building a new service over the last few months. Until recently all the data it needs has been ingested at startup and our focus has been on the logic that processes the data, architecture, and infrastructure. This week we introduced a couple of new endpoints that enable the creation (through an HTTP POST) and update (PUT) of the fundamental data type (we call it a definition ) that the service operates on. I picked up the task of smoke testing the first implementations. I started out by asking the system under test to show me what it can do by using Postman to submit requests and inspecting the results. It was the kinds of things you'd imagine, including: submit some definitions (of various structure, size, intent, name, identifiers, etc) resubmit the same definitions (identical, sharing keys, with variations, etc) retrieve the submitted definitions (using whatever endpoints exist to show some view of them) compare definitions I submitted fro

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

Vanilla Flavour Testing

I have been pairing with a new developer colleague recently. In our last session he asked me "is this normal testing?" saying that he'd never seen anything like it anywhere else that he'd worked. We finished the task we were on and then chatted about his question for a few minutes. This is a short summary of what I said. I would describe myself as context-driven . I don't take the same approach to testing every time, except in a meta way. I try to understand the important questions, who they are important to, and what the constraints on the work are. With that knowledge I look for productive, pragmatic, ways to explore whatever we're looking at to uncover valuable information or find a way to move on. I write test notes as I work in a format that I have found to be useful to me, colleagues, and stakeholders. For me, the notes should clearly state the mission and give a tl;dr summary of the findings and I like them to be public while I'm working not just w

Build Quality

  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-- "When the build is green, the product is of sufficient quality to release" An interesting take, and one I wouldn't agree with in general. That surprises you? Well, ho

Make, Fix, and Test

A few weeks ago, in A Good Tester is All Over the Place , Joep Schuurkes described a model of testing work based on three axes: do testing yourself or support testing by others be embedded in a team or be part of a separate team do your job or improve the system It resonated with me and the other testers I shared it with at work, and it resurfaced in my mind while I was reflecting on some of the tasks I've picked up recently and what they have involved, at least in the way I've chosen to address them. Here's three examples: Documentation Generation We have an internal tool that generates documentation in Confluence by extracting and combining images and text from a handful of sources. Although useful, it ran very slowly or not at all so one of the developers performed major surgery on it. Up to that point, I had never taken much interest in the tool and I could have safely ignored this piece of work too because it would have been tested by

The Best Laid Test Plans

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-- "What's the best format for a test plan?" I'll side-step the conversation about what a test plan is and just say that the format you should use is one that works for you, your coll