Start a new topic

Test documentation


I have come more and more into the need to document (unit) tests. For the time being, I take screenshots, however, this has some shortcomings.


  • Result: While one probably should be able to create queries resulting in a simple TRUE or FALSE. I consider this as good enough, but if, for some strange reason, the result set consists of several records, one might run out of the screen.
  • Connection: I can display the connection name, but that is no proof of where the connection goes to.
  • The query can, especially if one is to write it such that only a TRUE or FALSE is to be the result, can get complicated and foremost long. I see the danger that it won't fit onto the screen entirely.

If I were to design such a test documentation feature, I would propose the following requirements.

Must have:

  • Difficult to fake, i.e. not just text output.
  • Timestamp information of the test execution
  • Connection information available such that one can rebuild the connection, preferably copy-pastable
  • Infinite query space (not necessarily visible entirely), but accessible for copying
  • No special tools needed to read the document. If web browsers could read it out of the box, it'd be perfect. I am thinking of JIRA/TFS or other web based tools where such documents could be placed in.
Nice to have
  • Infinite result set space (not necessarily visible entirely)
  • Signing of the test document, like with files that are provided on the internet together with a signature file to prove its origin.
Maybe SVG could be a way, if one can have sort of a screenshot with a clickable area for showing the entire query and another for the result set.

I wonder whether QR codes could be a sensible part of a solution.

Varma hälsningar


Hi Thiemo,

If I understand correctly, this feature would be a unit testing UI which can also generate test reports for tests. I do think this is an interesting idea. However, instinctively I would suggest to do this as a stored procedure or the like, depending on what database is being used, and just output the test results as text. But the first requirement states text is not viable. In order to understand your use case I have to ask: Why should the test report be difficult to fake? Is it transported somewhere and in that case why can't the transportation handle it securely?

Here is a guide I found of how this can be achieved with SQL Server:

Kind Regards, 

Hej Edward

Thanks for taking this up. I actually was not thinking of a unit test framework, much less automated regression testing. There are dedicated tools, for the former in the case of PostgreSQL pgunit or pgtap, though I never used them and do not know what it does. I just hat a quick glance into pgtap and it seems it is good for testing the DB objects, but not supporting content of a tables. Something a bit more sophisticated than a mere screenshot in the sense, that it is not just about documentation but also about easy of reproduction,  is what I would fancy. Sure, I can type the test query to an editor from the screenshot, given that it is visible in its entirety, but useless if the connection details are not known.

With respect to faking. It all boils down to trust, maybe. I was not thinking of any transportation issue. Just, if the trust was complete, one would not need any protocols. Your superviser would just trust you to have done your work properly. But this does not happen too often. And it is not because the superviser are bad people by definition. We all are flawed people. I as a developer don't enjoy unit testing. I also forget sometimes some aspects I should test. For the time being, I take screenshots. They lack certain information, like the actual connection details. I like screenshots because I deem the hassle to fake it is bigger than to test properly. Why not plain text. Too easy to fake. I know, it would be malicious but the temptation is there. If I have write a test sql like the sample one in my initial comment, it is easy to write it returns 1. To me, it makes sense totally to have something that cannot be faked with little effort to cut the temptation and to have something that lends a hand if the need for reproduction should arise. Having said that, I feel it would take an effort to create something like that.

Varma hälsningar


I think I understand this a bit better now. It is less about testing that existing SQL scripts perform a certain task correctly, and more about providing proof that scripts have been run on a particular host and that they have met certain criteria when doing so. In other words: verification, except the customer is not involved in the actual verification process (they just witness some type of proof instead).

If we exclude the part about "No special tools needed to read the document", this could be a digital verification, like a certificate bundled with the script with the result and any other meta. The recipient could perhaps open the bundle inside their copy of DbVisualizer and check it there.

Like you say, I do think this requires some effort if it were to be implemented, and I don't see its priority being justified over other things currently being considered. But I could be wrong. I'll let you know if the situation changes.

And please let me know if I have misunderstood something about the feature criteria.

Thanks for helping with the formulation. Right on point.

In all my works where I had to give proof, it was to document in tools like JIRA or TFS. So, I'd rather would turn it around. Some document one can paste or attach to tools like the mentioned.

Maybe SVG or PDF can be signed digitally by DbVis? Sort of a button to generatet the document containing the details. Thinking of it again, a visual representation would be nice but not actually necessary which would reduce the implementation effort, I suppose.


With respect to implementation of the feature. I do not expect it to happen. Having that said, I am a bit unhappy with the title of the forum. I see my posts here not as requests, but as suggestions. As a single person, I am fully aware that I am in no position at all to request anything.

Login or Signup to post a comment