Living Documentation Using Jenkins and Selenium

Do you have problems with documentation going out of date?  I have written about what I call “living documentation” (documentation that auto-updates) a few times before.  See Never Let Your Documentation Go Out of Date and Living Documentation: The Examples Directory.  Let’s see what Selenium can do to both test our software and provide documentation.

A caveat here: I am not very familiar with Selenium at all.  My understanding is I can make it move the mouse on the screen to a certain location and click something.  I also assume it can type characters as though I were typing them on the keyboard.  Perhaps these are bad assumptions.  If so, another tool can be used.  The concept of this remains the same though.

The Concept

There are tools out there that can mimic mouse clicks and keyboard input.  Suppose we have a webpage we want to test.  More specifically, perhaps we want to click a button on that webpage, input a few characters, click an “OK” button, then verify something happens.

web browser

For example, perhaps I want to go to Google, click the input bar, type in a query, input Enter, then click the first result.

There are tools out there that can do things similar to this.  The key here is that every movement of the mouse has to be recorded.  I have to see it move to the input bar and click it.

If that is possible (I’m quite sure it is), then I need some software that records the screen.  It needs to be enabled and disabled programmatically.  Again, I’m pretty sure there are tools that do this.

I then need this to be able to be launched automatically.  Every time I make a change to code, I want to be able to use this tool.  At the very least, this tool can launch the test to make sure the user interface on the browser is the same and still works as expected.

Then I can make test cases.  For example, in the above example where I typed something in Google, I might make a test case called “Perform a Search”.  It consists of the following:

  1. Open a browser
  2. Click the URL bar
  3. Type in
  4. Click the search panel
  5. Type in “How to Automate Stuff”
  6. Make sure a new page opens that has relevant search results (perhaps the HTML contains “how to automate stuff as the first search result)

Doing this would verify that our user interface for Google still works to “Perform a Search”.

Now let’s make things more interesting.  Suppose a recorded the automation that does those above steps.  That video is saved as the test case name – “Perform a Search”.  I then archive that video in a special location.

New users of Google can now open up that video to determine how to perform their own searches.  Barring different behavior of the web user interface with the same code load, that same interaction will work… because it has just been tested.  And not only has it been tested, but now the end user can use the video of how it was tested to perform the same operation and get the same result.

Brilliant!  Living documentation at its finest!

Excited Kid with Arms in Air


I have not validated this.  However, I know there are tools that do all of these things.

  • Selenium has been around for a while and can be used to drive web browsers.  I’m not certain it can show the mouse as it moves across the screen.  If it can’t, other tools can.
  • Jenkins can kick off tasks when code gets committed.  It can start selenium, the video recording, and archive the video (and more than likely provide links to it).
  • For video recording, there’s already a Jenkins plugin to do that!

Boom.  You check in code.  If it fails the test, you know you have a web UI issue that you need to fix.  No video gets generated.  If the test passes, that video gets saved in a specific location for users to reference in the future.

You can even save videos based on different tags of your code.  So if your UI changes, you have a different video to see how to use it.



Setting this up will take a lot of effort.  I’m aware of this.  But how cool would it be to have a video generated on EVERY COMMIT showing how to use your UI?  Holy crap!  It blows my mind.  But I know it is possible.  If the investment in infrastructure is made, a user guide for every single version of your code can be made… with no additional work from developers except to verify that their GUI tests work with each build.  Which should be tested anyways, if it isn’t being done already!

There’s your golden nugget for the day.  Living documentation.  Go make it happen.

Leave a Reply

Your email address will not be published. Required fields are marked *