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

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

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

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

Play to Play

I'm reading Rick Rubin's The Creative Act: A Way of Being . It's spiritual without being religious, simultaneously vague and specific, and unerring positive about the power and ubiquity of creativity.  We artists — and we are all artists he says — can boost our creativity by being open and welcoming to knowledge and experiences and layering them with past knowledge and experiences to create new knowledge and experiences.  If that sounds a little New Age to you, well it does to me too, yet also fits with how I think about how I work. This is in part due to that vagueness, in part due to the human tendency to pattern-match, and in part because it's true. I'm only about a quarter of the way through the book but already I am making connections to things that I think and that I have thought in the past. For example, in some ways it resembles essay-format Oblique Strategy cards and I wrote about the potential value of them to testers 12 years ago. This week I found the f

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

Test Now

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 is the best time to test?" Twenty posts in , I hope you're not expecting an answer without nuance? You are? Well, I'll do my best. For me, the best time to test is when there

Rage Against the Machinery

  I often review and collaborate on unit tests at work. One of the patterns I see a lot is this: there are a handful of tests, each about a page long the tests share a lot of functionality, copy-pasted the test data is a complex object, created inside the test the test data varies little from test to test. In Kotlin-ish pseudocode, each unit test might look something like this: @Test fun `test input against response for endpoint` () { setupMocks() setupTestContext() ... val input = Object(a, OtherObject(b, c), AnotherObject(d)) ... val response = someHttpCall(endPoint, method, headers, createBodyFromInput(input) ) ... val expected = Object(w, OtherObject(x, y), AnotherObject (z)) val output = Object(process(response.getField()), otherProcess(response.getOtherField()), response.getLastField()) assertEquals(expected, output) } ... While these tests are generally functional, and I rarely have reason to doubt that they

A Qualified Answer

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 ,   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-- "Whenever possible, you should hire testers with testing certifications"  Interesting. Which would you value more? (a) a candidate who was sent on loads of courses approved by some organisation you don't know and ru

README

    This week at work my team attended a Myers Briggs Type Indicator workshop. Beforehand we each completed a questionnaire which assigned us a personality type based on our position on five behavioural preference axes. For what it's worth, this time I was labelled INFJ-A and roughly at the mid-point on every axis.  I am sceptical about the value of such labels . In my less charitable moments, I imagine that the MBTI exercise gives us each a box and, later when work shows up, we try to force the work into the box regardless of any compatiblity in size and shape. On the other hand, I am not sceptical about the value of having conversations with those I work with about how we each like to work or, if you prefer it, what shape our boxes are, how much they flex, and how eager we are to chop problems up so that they fit into our boxes. Wondering how to stretch the workshop's conversational value into something ongoing I decided to write a README for me and