Is it recommended to document how selenium automation tests are laid out?

Question

The automation code I'm working with was written by several people before me. It's messy, complex, etc. There are barely any comments within the code. It takes me an extremely long time to figure out what each class does.

Is it recommended to have some sort of documentation, so the next engineer can read it, and know exactly what each class etc does.

Is this common or would it be consider pointless? I can't seem to find an example of some sort of automation test documentation/maintenance structure.

Can anyone provide some sort of input?

Answer 1

According to me test automation is in itself a project - test automation as far as I believe is writing a program that will be used to test another program.

So how about you consult the other stakeholders or say the developers in your company.

If there is a project where developers have changed over time, discuss it with them about their experience of the ease of understanding the code with or without documentation.

Talk to the leads and management about how they do documentation for their code and how do they help the new programmers understand the code of existing projects.

Learn their methods and see if it suit you and also see if those documentation practices can be improved to make life easy!

Happy testing :)

Answer 2

Yes, definitely, documenting your project is absolutely necessary. But I'm not talking about for automation tests specifically, but for all programs in general.

Selenium automation tests are programs just like anything else, which means that all coding standards within your company should also apply. The quality of the automation tests should be as high as other code bases.

It depends on how your company defines the coding guidelines. As far as I know, some companies discourage the excess usage of comments, because the code itself should be self-explanatory.

For example, all method/variable names should be in some kind of pre-defined format, usages of semi-colon, brackets should be consistent company-wide, no long methods, no deeply nested control flows etc. All Selenium code should comply with the company rules completely.

In your situation, if you can't figure what a class does, then the problem is not about lack of commenting, but more about a poorly designed/named class. In that case, if your Selenium project is extremely messy and complex, I'd suggest refactor the relevant classes to make the project smell better, not simply add comments.

In my opinion, you don't need to find resources on documenting automation tests specifically, but for programming in general. For instance, Clean Code by Robert C. Martin would be a good book to start off.

Answer 3

Often Selenium tests tend to become a bit messy, mainly as naturally they are initially written in a quick manner, just to progress through the scenario and as a proof of concept. In addition, extensive usage of XPATH can make the test look even more cryptic than it is already. As a result, the scripts become very hard to understand, at least from the first glance. So, from my personal experience, possible solutions to that problem are:

Add comments. That may create much difference in terms of script readability, especially if the code is visually split into blocks and the comments appear on top of each block giving a brief explanation of what is going to be done in each such section. For example:

#Log in
Selenium code...

#Log out
Selenium code...

Use wrappers. Naturally, there are repeating blocks of code that can be wrapped within a function with more intuitive name. For example, if you are using commands like these:

element = WebDriverWait(driver, 20).until(EC.element_to_be_clickable((By.ID, elementName)))

You can create a function that will take certain parameters and will hide the ugly code behind. For example:

waitForElement(driver, elementName, searchBy)

Answer 4

If the code is for Selenium WebDriver, the documentation process can be greatly simplified with automated tools. Selenium supports Java very well, so unless you are using another language like C#, javadoc could be the way to go from a development maintenance point of view.

Answer 5

I've written some of these frameworks in the past and have followed a few guidelines in writing the code, and in creating design documents. My basic view is that if I have left and in 6 months someone needs to work on this, would they (or I) have the information they need to continue to work with the tool? If the answer is no, then you need to document. Some other guidelines I try to follow:

• Is what this test case covers obvious by name? If not, some comments within the header of the test case are good. Do these at the beginning so someone has an idea of what the code they are about the read does
• Do the steps seem obvious or make sense? If not, then a one liner about "hitting page X which will return Y" is good not only for someone else to review, but good for you to know at what step in the test case automation you are on
• Is this step something that breaks often? At times I have added extra checks just because there is fragility in the UI, or some other issue arises, I have added notes so that if I come back to this case in 6 months or more I know why I did what

Commenting your code is the best thing you can do, I once heard it put that code is a conversation, if it doesn't speak to you directly it sometimes needs translation. While a detailed design document is often not needed I have done enough for someone to get familiar with the framework as to its purpose, why I chose the one I did and most importantly why I did NOT chose others that I looked at. Sometimes the most important information is not just why you chose that particular tool, but why you did not choose a similar one.

When you are done with your code and comments, have someone else read it, or leave it alone for a few days then read it over. Fresh eyes of any sort, your own or someone else's will help remove any ambiguities that might sneak in to your comments.