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

Why Do They Test Software?

My friend Rachel Kibler asked me the other day "do you have a blog post about why we test software?" and I was surprised to find that, despite having touched on the topic many times, I haven't. So then I thought I'd write one. And then I thought it might be fun to crowdsource so I asked in the Association for Software Testing member's Slack, on LinkedIn , and on Twitter for reasons, one sentence each. And it was fun!  Here are the varied answers, a couple lightly edited, with thanks to everyone who contributed. Edit: I did a bit of analysis of the responses in Reasons to be Cheerful, Part 2 . --00-- Software is complicated, and the people that use it are even worse. — Andy Hird Because there is what software does, what people say it does, and what other people want it to do, and those are often not the same. — Andy Hird Because someone asked/told us to — Lee Hawkins To learn, and identify risks — Louise Perold sometimes: reducing the risk of harming people —

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 is Knowledge Work

  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-- "We need some productivity metrics from testers" OK. I'd like to help you meet your need if I can but to do that I'll need to ask a few questions. Let's start with these: Who needs the metrics? Is there a particular pr

Risk-Based Testing Averse

  Joep Schuurkes started a thread on Twitter last week. What are the alternatives to risk-based testing? I listed a few activities that I thought we might agree were testing but not explicitly driven by a risk evaluation (with a light edit to take later discussion into account): Directed. Someone asks for something to be explored. Unthinking. Run the same scripted test cases we always do, regardless of the context. Sympathetic. Looking at something to understand it, before thinking about risks explicitly. In the thread , Stu Crook challenged these, suggesting that there must be some concern behind the activities. To Stu, the writing's on the wall for risk-based testing as a term because ... Everything is risk based, the question is, what risks are you going to optimise for? And I see this perspective but it reminds me that, as so often, there is a granularity tax in c

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

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

Testing and Semantics

The other day I got tagged on a Twitter thread started by Wicked Witch of the Test about people with a background in linguistics who’ve ended up in testing. That prompted me to think about the language concepts I've found valuable in my day job, then I started listing them, and then realised how many of them I've mentioned here over the years .   This post is one of an occasional series collecting some of those thoughts.  --00-- In this series so far we've looked at words and syntax. In both cases we've found that natural language is an imprecise medium for communication. We might know the same words and grammar as others ... but they will have their own idea about what they mean ... and even where we agree there is ambguity ... and all of us, the world, and the language are evolving ... all the time. Today we'll add semantics which, in a pleasing twist, is itself ambiguo

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

Personal Development

The other day I got tagged on a Twitter conversation between a couple of my colleagues, Ben Dowen and Dan Ashby , which ended with Ben citing me as an example: But there is a trap, in that a Dev who Tests, or Tester who codes both risk becoming Test Automators ... The counter argument is Testers who code can do as @qahiccupps does, and use and build tools to explore. A jumble of thoughts tumbled out as I read it and here they are, in no particular order. It is flattering to be mentioned but I'm far from the only person doing this. Maaret Pyhäjärvi   and Rob Sabourin are vocal about the value it can bring and go out of their way to tell and teach others how to get it. Ben is right when he says I use coding as a tool, and as a tool factory. It's a means to an end. Coding itself doesn't give me a lot of pleasure. Having created a useful thing gives me an enormous amount of pleasure. I am not a great developer. But then I rarely need to be.   Yes, I have made bug fixes that