Uncharted Waters

Mar 29 2017   1:42PM GMT

Good Technical Documentation

Justin Rohrman Justin Rohrman Profile: Justin Rohrman

Coding and documentation

Earlier in March I wrote about the difficulty of working through cost trade-offs. A team I am working with was trying to decide the best way to create an environment for nightly run of a UI automation test suite. We decided on a solution. Our IT person created a clean virtual machine and gave me admin access, and I installed the tool we are using for automation. I logged into the virtual machine, set everything up for the nightly run and called it a day. When I logged in the next morning, nothing ran.

I spent the next day and a half scouring the internet for documentation that might explain what had happened

Documentation has been an afterthought for most of my career. I think it is that way for a lot of people in software. As a tester I have been required on and off to write something called a test case. The idea here is that we write each ‘step’ down that would precisely lead someone to finding certain types of bugs in software. Test cases were never as useful as managers though, and were a pain to document and maintain. On top of that we had bug reports, release notes, and all manner of wikis.

Someone would create a set of release notes, or a wiki expecting it to never be read again. Obsolesce was our long term strategy.


Every time I come across a real software problem though, I’m thankful that someone took the time to write instructions down.

Last week I was working on a UI automation problem. Running UI automation on a Virtual Machine was immediately trouble. I would log in to this machine using Remote Desktop (RDP), get a test suite scheduled and configured to send me an email when it was done, and then nothing. There would be no email, and when I logged back on to the machine the logs showed that the test suite had never started. Remote Desktop is tricky. It seems like you are logging into a live session, but there is some magic happening behind the scenes. When you start a RDP session, the user interface started up just for you. When I close or minimize the RDP window, that session is killed. No real UI means there is no way for the browser to start up, and no way my tests would run.

Figuring out the problem wasn’t too hard. Finding a solution was a pain.

I started on the website of the company that makes the tool I am using. They had two suggestions — add an extra virtual machine what has a RDP window left open to the virtual machine where the tests are run to that the UI stays alive, and the second was an autologin registry edit so that the machine automatically comes alive after a restart. Autologin didn’t work because there wasn’t a live UI with it. I didn’t want to add a virtual machine because it is not very elegant and I’d have to talk with our IT department and convince them having a second unlocked (unsecure) virtual machine was a good idea.

I found the perfect solution for my problem on the website of a competing tool maker. This solution was is a batch script that exits remote desktop by sending the process to the windows console. This keeps the UI process alive so browsers can run and automation will kick off like I need.

It took a day and  a half to find that perfect solution because no one wants to deal with documentation. If you are one of those companies that keeps good public documentation, thank you.

 Comment on this Post

There was an error processing your information. Please try again later.
Thanks. We'll let you know when a new response is added.
Send me notifications when other members comment.

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to:

Share this item with your network: