Here we come across an interesting topic of coding guidelines while designing automation test scripts. The scope of this article will not be limited to QTP but to an overall extent of using VB Scripting for automation projects.
Introduction Now you may ask the questions or raise doubts like – “Why should I use coding standards?” – This is no big development project – No Source Code to be delivered etc. Well if you think so, you are in for a big misconception. Most folks who move on from Manual testing to Automation do not have much knowledge of coding practices and hence do not maintain the scripts/codes, at these times it is quite difficult to manage code (scripts) used in automation in a structured manner so as to maintain them easily.
Let’s assume a case where the project has 1 automation resource (Mr. Automata) and is the sole person responsible to maintain/execute/deliver the automation scripts and corresponding reports. Now, Mr. Automata will be fully aware of what function/script is placed in what location and where is the probable cause of failure if any. Forget failures, suppose a new object is to be added in the repository, he/she can easily add it and make the necessary modifications in the scripts.
Now consider two situations – a) The team is to ramped-up and b) Mr. Automata decides to quit the organization.
In the first case, it will be fine; some new members get added to the team but will have to understand the entire code structure as to how Mr. Automata has added objects, functions, variables in the scripts. It may not be a very difficult situation but might take some time for new members to grasp his understanding.
However, in the second situation; Mr. Automata gives the required time of handover to the replacing member and now this member will have to fully understand the system without any liberty to make modifications at present. The new member will need to know each and every line of code – the use of each variable as Mr. Automata will not be available to guide him after his exit.
At this point of time, it becomes very important to follow some guidelines and standards while writing any piece of code not only VB Script functions/scripts in QTP.
Note: This was only an illustrative example and the reason behind following guidelines is not limited to these situations. There are several more benefits too.
Let us study in brief the various coding standards and guidelines that we can follow while using VB-Script code.
Naming Guidelines The purpose of naming guidelines is to aid the developer in automation to understand the characteristics of any given variable/object without having to browse through the entire code and understand the functionality.
Some general naming guidelines:
Names should ideally begin with letters and NOT numbers or special characters.
It can contain numbers or underscore (_) but not spaces or any punctuation marks.
Try to limit the length to 30 characters or less. (Range of 10-15 characters is optimal while maintaining readability).
Ideally use a prefix based on the type of variable/object it is used to define. (We will see some standard prefixes used in actual).
Use camel casing for better readability.
Avoid using similar names to variables and functions.
Avoid using regional specific naming like American/British difference in Color/Colour.
Coding Guidelines In this section, we will see some guidelines related to using functions and its surrounding structures.
Ideally functions should start with “func_”, followed by the name of the function (i.e. its intended functionality to be performed).
Example: Suppose a function is created to Login using Web interface and you will be passing the Username and password as string inputs to the function, it will be declared as –
Function header: Even though you have used all coding guidelines in creating a function and writing the related codes, it is very important that you create a small kind of documentation within the script to help identify the function and its purpose. This kind of documentation using comments is used as the function header and a typical header consists of the following parameters:
Name of the function
Description of the function
Input parameters list (if possible with its purpose/description)
Return Values of function (with description if applicable)
Name of developer modifying/creating it
Date of last modification (along with applicable changes made)
'*************************************************'Function Name : Func_WebLogin'Description : Used to login to the application through its web interface.'Input parameters : ' strUsername - Username used for login;' strPassword - Password used for login'Return parameters : ' blnResult - Returns "true" if login is successful, "false" otherwise.'Date of Creation: 30th Jan 2012'Modified By : Mr.Automata (Team Automation-Module X)'Date of Creation : 30th Jan 2012'**************************************************
Structuring your function: The function created should be well structured and using modular approach and can be further broken down into functions wherever required. This will help in better readability and code maintenance. From a readability point of view, usage of tabs will be most appropriate and helps in better structuring.
Variables passed into the function should be used as applicable and redundant variables should be avoided where possible. For example, there is no point in passing a global variable to a function as anyways it is going to be available to the function.
This one is the most important section while writing about coding standards and guidelines and is often the most neglected one too!! Coming back to the same situation of our Mr. Automata, things would be very simple if all code was properly commented with appropriate explanation of the variables used, the logic of the module, the flow of the scenario etc.
A simple english-like statement will suffice for any new member to understand the code just by its walkthrough with minimal explanation.
“Well written comments are the best documentations for the source code“
Comments communicate the information/logic and should not have syntactical jargons. The best practice will be to outline your comments first and then start writing your code around those comments. This will ensure that you have covered the entire functionality and also serve the purpose of commenting. Do ensure that the comments written as an outline is converted correctly into the code and avoid using “To be done later” or “Need to be modified” – there is usually no time for “LATER” during such developments. Try to wrap up the piece of code at one go.
General commenting guidelines:
Comment together with the code or as mentioned create an outline of comments before starting to code.
Even while modifications to existing code, ensure commenting is done and mention what was changed due to what reason.
Avoid using too many graphical characters to create frame around a comment, it may look attractive but when modification is required it tends to be an overhead.
Eg: ‘############# or ‘********************* should be avoided.
Before final deployment or release of code, ensure all unwanted comment is removed.
Unwanted or bad code should be completely removed or modified to its highest accurate level.
Always comment places that are prone to create confusions like loops or some logic branches.
Comments should be in a uniform style throughout the entire test suite/project/scripts.
The scope of this discussion is not limited to only these topics, coding standards and guidelines is a vast aspect of development, be it writing code in Java or simple QTP scripts.
There are a some specific topics that I will plan to cover in the next part of this series – viz. Usage of variables, their declaration etc., Standards for Looping and logical conditions, Maintaining Data sheets with standards – All with examples.
We will rest the scope of discussion at this junction as this will be fairly enough for someone developing scenarios using VB Scripts.
References: Open2test.org – Framework development guidelines and other tech documents
http://www.open2test.org/techdocs.html Inputs have been taken from the above material and have been expressed in my own views and based on my practical experiences in real-life projects.