Autogenerate Path Visualisations

In the previous blog post I have described how to use GraphViz to describe a graph in a textual format and then generate an image from that.

This time, let’s do one more step and add some code so that the image gets generated automatically when the text file is updated.

For my project I use Guard, a Ruby gem that watches file system changes, and allows to define various reactions. Running unit tests whenever a file is saved is one example.

For my case, I let it generate a new image file, when a GraphViz file is saved. First of all, I installed the needed Ruby gems:

gem install guard guard-shell

With that in place, here’s the Guardfile I use to generate the images:

guard 'shell' do
  watch(/(.*\.gv)$/) { | m |
    dot_file = m[1]
    png_file = "#{File.basename(dot_file, '.*')}.png"
    command = "dot -Tpng -Gdpi=300 -o#{png_file} #{dot_file} && open #{png_file}"
    puts command
    puts `#{command}`
  }
end

Note: In the code above I had to revert to enter (0xff06) instead of & (0x26) in order to prevent the syntax highlighting feature from turing a & into `&`… 🤷‍♂️

The part watch(/(.*.gv)$/) invokes the following code block when a file that matches the given regular expression changes. I am interested in files that match ‘*.gv’ in the directory that the Guardfile is stored in.

The line dot_file = m[1] extracts the file name from the parameter passed into the block, and uses it to create a _new_ file name for the image file that is going to be created.

Then the shell command is put together, logged, and finally called.

Component of the commandWhat it is/does
dot The command name that
translates the gv file into a PNG image
-TpngSet the output format to ‘png’
-Gdpi=300Set the resolution to 300 dpi
(gives a good resolution for printing)
-o#{png_file} Set the file name for the png file
#{dot_file}The name of the input file
&& open #{png_file}This appends another shell command to open the image file.
(I use this on my Mac to automatically (re-) open the file whenever it’s regenerated.)

In case you would like to experiment with this, I created https://github.com/s2k/autogen_images_for_graphviz/ as a starting point, including an example GraphViz file.

Visualising Paths

In one of my projects we were faced with a high number of execution paths the system could take. While this is normal and, in fact, expected for all systems these days, in this particular project it was obvious even for the users of the system. The software accepts (interactive) input and then demands more information, as needed in the specific context. There were numerous paths through a network of decisions to get to the point where the final result could be presented to the user.

This is basically describing layers of decisions, leading to various outcomes. To get an overview of the decision tree, I created a diagram using an app (OmniGraffle in this case). The result for one real tree (with abstracted labels) is this:

Paths trough a decisions tree, updating an attribute of the result

This isn’t trivial, but it doesn’t look too hard. But then, there are 9 different paths thought the graph. The following image shows each path in one colour:

Showing all paths for the image above

That’s not as simple anymore. Also note, that the attribute is sometimes updated, leading to different result types (res1 for attribute == 0, res2 for all other cases). It was tedious to create these images to help me see the paths — and fiddling the the arrow to make it look reasonably good, was extra work. To deal with more cases I wanted another approach.

I remembered a tool I had used in a similar situation: GraphViz. It’s the combination of a text format (a graph describing language) and programs to turn this into a graphical representation: images.

Here’s the textual representation of the graph above:

digraph {
  size="40";
  bgcolor="transparent";

  node [fontsize=9, shape=rectangle, style="rounded", color=black];
  edge [fontsize=7, fontcolor=red arrowhead=onormal];

  D1[ label = "Decision 1\nattribute = 0" ];
  D2[ label = "Decision 2" ];
  D3[ label = "Decision 3" ];
  D4[ label = "Decision 4" ];

  R1[ label = "Res 1 | Res 2\ndepending on attribute" ];
  R2[ label = "Res 1 | Res 2\ndepending on attribute" ];
  R3[ label = "Res 1 | Res 2\ndepending on attribute" ]; 

  D1 -> D2 [label = "Yes"];

  D2 -> D3 [label = "Yes\nattribute += 1"];
  D2 -> D3 [label = "No"];

  D3 -> R1 [label = "≤x times"];
  D3 -> D4 [label = ">x times"];

  D4 -> R2[label = "<Y units\nattribute += 1"];
  D4 -> R3[label = "≤Y units"];
}

I find it easy to see which node there are, and how the node connect. Here is the command I used to generate a PNG file:

dot -Tpng -Gdpi=300 -o decisions.png decisions.dot

dot is one of the layout programs that comes with GraphViz. With -Ddpi=300 I’ve set the resolution to 300 dpi (to generate a file with a higher resolution than the default). The resulting image file log like this:

The generated PNG file, using dot

While the positioning of the edge labels is not perfect, it happened automatically, as the whole layout of the image. I didn’t have to move things, I could set the styles for all nodes & edges in one place, so that they are guaranteed to look consistent.

In the cases when I used this approach, I could generate the graph description automatically from a (more or less) formal description. In these cases, I could avoid mistakes by ‘hand-drawing’ the graph entirely (well, having tests for the generator code in place… 🙂).

Agile Testing Days 2020

I’m really excited that the Agile Testing Days accepted me as a speaker again. This year I’ll offer two workshops, one of them at two times.

“Get The Most Out Of This Conference” is meant for newcomers to conferences in general. If you haven’t attended a conference before, this is for you. The plan is to have the first one on Monday afternoon (9th, Nov. 2020), and then to have the second go right after the morning keynote on Tuesday morning (10th, Nov. 2020). There’s a teaser video available at vimeo.

Let’s Start Learning Elixir — Together” is the second workshop. It’s two hours of looking into a functional programming language, getting started to learning it. This is scheduled for Wednesday morning. For the Elixir workshop there’s a teaser video, too.

Physics And Testing

At a number of conferences I attended in the past, people connected several fields to software development in general and testing in particular, which (at first) seem unrelated.

Since then, I pondered this for a while (read: more than 4 years). With my background in physics, I see a number of parallels to software testing. This is also a great opportunity to answer a question I get asked frequently: How did you enter software testing, given your background in physics?

Physics

Let’s start with a definition for physics:

Physics is an experimental science. Physicists observe the phenomena of nature and try to find patterns that relate these phenomena.

— Young, Freedman. “Sears and Zemansky’s University Physics: With Modern Physics”. Pearson Education.
Also see the wikipedia article on physics.

The patterns that relate those phenomena are the theories (or laws) of physics. They are models that describe an aspect of reality. None of these models is complete, in the sense that it describes everything. There is no one physical theory that explains everything. A nice view of the landscape of physical models is shown in the image by Dominic Walliman (see sciencealert.com for details):

The landscape of physical theories, see
Dominic Walliman’s ‘Domain of Science’ video on YouTube

In physics (as in science in general), experimental results and predictions  created by models are compared, in order to find out how a model does not match observed behaviour. This is important: Experiments can only ever invalidate a model, but not generally confirm its correctness.

Software

To me software systems are models, too: Even though they may represent reality closely, a software system is not the thing it represents.
Peter Naur described the relationship between theory building and programming in his paper ‘Programming as Theory Building’ (Microprocessing and Microprogramming 15, 1985, pp. 253-261).

Testing

My mental model of software testing is very similar to the one of physics: I see software systems as partial implementations of aspects of a real expected behaviour. In my view testing a system means it and comparing observed results with expectations.
The expectations may come from requirements (written or otherwise), previous experiences with similar systems (i.e. another web application from the same company) or other sources.

There are many approaches to testing, in a similar way to the many approaches to physics. Some of them work good in one area but not so well in another. What kind of testing is done, heavily depends on the kind of the software system: Testing embedded software used in medical devices is drastically different from testing, say, a text editor.

Science

It is interesting to go one step further, from physics to science. The Cambridge Dictionary defines science as

the intellectual and practical activity encompassing the systematic study of the structure and behaviour of the physical and natural world through observation and experiment

https://dictionary.cambridge.org/dictionary/english/science

With a different wording, this seems to fit software testing as well:

Software testing the intellectual and practical activity encompassing the systematic study of the structure and behaviour of software systems through observation and experiment.

The definition with a different wording

To me, many very basic principles of scions in general and physic in particular apply to software testing, too. And that’s why I think that my physics background is very helpful in software testing.

Now, I interested in this: What is your background and how does it help you in software testing (especially if your background is not in computer science or software engineering)?

Writing a (Technical) Book in an IDE

I find myself writing again more, in particular writing technical books. For this I am using a number of tools, some of which I’ve described in Writing a Ruby Related book(let) on LeanPub.

In this post I focus on the writing itself including the setup I use. When starting fresh, I use the zip file with a default content provided by LeanPub. When unzipped, the folder structure looks like this:

% tree a_potential_book
a_potential_book
├── README.md
└── manuscript
    ├── Book.txt
    ├── chapter1.txt
    ├── chapter2.txt
    ├── chapter3.txt
    └── resources
        ├── palm-trees.jpg
        └── readme.txt

2 directories, 7 files

I have used Markdown in previous books and am now using Markua (a markup format created by LeanPub). Since both are similar and many editors & IDEs identify the file type by the file name suffix, I use ‘.md’ as the suffix for the files. Also, I find renaming the files ist easier than reconfiguring editors. To do this I use rename:

% rename -g  -s .txt .md  "a_potential_book/manuscript/chapter*.txt"
% tree a_potential_book
a_potential_book
├── README.md
└── manuscript
    ├── Book.txt
    ├── chapter1.md
    ├── chapter2.md
    ├── chapter3.md
    └── resources
        ├── palm-trees.jpg
        └── readme.txt

On a Mac rename can be installed using Homebrew:

brew install rename

Now the file Book.txt needs to be updated, to also list the ‘*.md’ files:

ls *.md > Book.txt

With this set up, I import the folder into RubMine, and have a look at ‘chapter2.md’:

Example chapter 2 of the default LeanPub book
The imported default book (click to enlarge image)

Notice this line

![Palm Trees](palm-trees.jpg)

This is the Markua (and Markdown) way of to insert an image (‘palm-trees.jpg’ in this case) into the text using the cation ‘Palm Trees’. In terms of RubyMine the image file is a resource — and it would be handy to be able to open it with just a click. Here’s how to configure this in the IDE:

  1. 320Hover the mouse pointer over the folder name ‘resources’ and
  2. Open the context menu with a right click:
  3. Open the sub menu entitled ‘Mark Directory as ▸’, and click ‘Resource Root’

Now, if you CMD-click the file name in the text, the image is displayed. Nice.

For my Ruby related book, I created a sub directory within ‘resources’ named ‘code’. Any files inside that folder will now also be found by the IDE and opened, when CMD-clicked.

%d bloggers like this: