One thing that more classical minding testing organizations love is their ‘traceability matrices’. These, often spreadsheets, have a list of requirements in one column and the test script that exercises it in one next to it. As a concept it is fine, but there are some issues.

  • It is external to the scripts themselves so easily can get outdated
  • It is a spreadsheet (which is by nature a binary file and so not version control friendly)
  • It implies there is a one-to-one mapping of scripts to requirements. Even if you follow the Single Responsibility Principle in terms of what the purpose of the script it, it ignores all the other bits of the product it encounters

But the theory is really nice. So what if you could produce on a whim a list of what each script does? And that information was embedded right in the script? Why then you would be using something like RDoc (or similar tool depending on your platform).

RDoc is a tool for ruby which parses your code for comments and special markup and produces a nice display of the information. (See the selenium client gem site as an example of the output).

RDoc is actually part of the main Ruby distribution now which illustrates how embedded it is in the community. In fact, Ruby On Rails has a rake task (doc:app) which will generate RDoc from your application. Blatantly stealing from that task and with a bit of editing I have created a new rake task which will do the same for your selenium scripts.

<pre lang="ruby">namespace :doc do
  desc "Generate documentation for the selenium scripts. Set custom template with TEMPLATE=/path/to/rdoc/template.rb or title with TITLE=\"Custom Title\""
  Rake::RDocTask.new("selenium") { |rdoc|
    rdoc.rdoc_dir = 'doc/selenium'
    rdoc.template = ENV['template'] if ENV['template']
    rdoc.title    = ENV['title'] || "Selenium Script Documentation"
    rdoc.options 
<p>
Copy that to your Rakefile or (if in RoR) the lib/tasks dir and you're all set. The next step would be to have this as a job in some sort of CI to recreate the docs every time something in test/selenium got updated.<br></br>
<be></be><br></br>
If I could tell it not to capture the setup or teardown methods I would be thrilled, but as it stands now it is still nice. Perhaps it will be enough for your organization. Or at least give you something you can suck down via a script and tease out the interesting parts.</p>