Do not use comments in your Selenium tests

if you want to move on from being a beginner, remove all comments from your code

This is a typical test written by someone who just started learning Selenium test automation with Java:

private WebDriver driver;

@BeforeMethod
public void setUp() {
  WebDriverManager.chromedriver().setup();
  driver = new ChromeDriver();
  driver.manage().window().maximize();
}

@AfterMethod
public void tearDown() {
  driver.quit();
}

@Test
public void searchTestWithComments() throws InterruptedException {
  String homePageUrl = "https://www.vpl.ca/";
  String resultsPageUrl = "https://vpl.bibliocommons.com";
  String keyword = "java";
  String currentUrl = "";
  String resultsFound = "";
  int i = 0;
  int j = 0;
  int resultsCount = 0;
  int broadenResultsCount = 0;

  //open site
  driver.get(homePageUrl);

  //verify that the url is correct
  Assert.assertEquals(driver.getCurrentUrl(), homePageUrl);

  //type keyword in search box
  By searchBoxId = By.id("edit-search");
  WebElement searchBox = driver.findElement(searchBoxId);
  searchBox.sendKeys(keyword);

  //click search button
  By searchButtonId = By.id("edit-submit");
  WebElement searchButton = driver.findElement(searchButtonId);
  searchButton.click();

  //get current url
  currentUrl = driver.getCurrentUrl();

  //verify that url starts with vpl.bibliocommons.com
  Assert.assertTrue(currentUrl.startsWith(resultsPageUrl));

  //verify that url contains the keyword
  Assert.assertTrue(currentUrl.contains("query=" + keyword));

  //verify that the url contains searchType=smart
  Assert.assertTrue(currentUrl.contains("searchType=smart"));

  //get the results found value
  By resultsFoundXpath = 
     By.xpath("(//span[@data-key = 'pagination-text'])[1]");

  WebElement resultsFoundLabel =  driver.findElement(resultsFoundXpath);
  resultsFound = resultsFoundLabel.getText();

  //verify that the results found value contains 1 to 10
  Assert.assertTrue(resultsFound.contains("1 to 10"));

  //get the total results count from results found value
  i = resultsFound.indexOf("of") + 3;
  j = resultsFound.indexOf(" results");
  resultsCount = Integer.parseInt(resultsFound.substring(i, j));

  //display the total results count
  System.out.println("results count = " + resultsCount);

  //verify that the total results count is positive
  Assert.assertTrue(resultsCount > 0);

  //click the broaden search link
  By broadenSearchXpath = By.xpath("//a[@class = 'broaden-search-link']");
  WebElement broadenSearchLink = driver.findElement(broadenSearchXpath);
  broadenSearchLink.click();

  //get the current url
  currentUrl = driver.getCurrentUrl();

  //verify that the current url contains searchType=bkw
  Assert.assertTrue(currentUrl.contains("searchType=bkw"));

  //wait 5 seconds
  Thread.sleep(5000);

  //get the results found value after broadening the search
  resultsFoundLabel = driver.findElement(resultsFoundXpath);
  resultsFound = resultsFoundLabel.getText();

  //gets the new total results count
  i = resultsFound.indexOf("of") + 3;
  j = resultsFound.indexOf(" results");
  broadenResultsCount = Integer.parseInt(resultsFound.substring(i, j));

  //display the new total results count
  System.out.println("broaden results count = " + broadenResultsCount);

  //verify that the new total results count is positive   
  Assert.assertTrue(broadenResultsCount > 0);

  //verify that new total results count is greater than 
  //previous total results count
  Assert.assertTrue(broadenResultsCount > resultsCount);
}

The code of the test is explained in detail using comments.

There are comments explaining that

• the site is opened

• the code verifies that the home page url is correct

• a keyword is typed in the search button

• the search button is clicked

• the code verifies that the results page url is correct

• the code gets the value of the results found label

• the code gets the total results count value

• so on

Because of all these comments, one could assume that the code is very complex.

Unfortunately, the opposite is true. The code is very simple.

---

Let’s see the line that verifies that the home page url is correct:

//verify that the url is correct
Assert.assertEquals(driver.getCurrentUrl(), homePageUrl);

It obviously compares the actual page url (retrieved using the getCurrentUrl() method of the driver) to the expected page url (saved in the homePageUrl variable).

Does the comment add anything valuable to this code? No. Do we miss much if the comment is not there? No. The code is so simple that it is obvious what it does.

Let’s take another example such as the code that clicks the search button:

//click search button
By searchButtonId = By.id("edit-submit");
WebElement searchButton = driver.findElement(searchButtonId);
searchButton.click();

The code creates first a locator, then it uses it to find the searchButton element, finally, it clicks the searchButton.

Does the comment add anything useful to this code? No. Do we miss much if the comment is not there? No again.

---

So, having the comments does not help with making the code clear since the code is so simple. Anyone should be able to understand what it does. Having the comment is not adding any value to the code.

That’s important to keep in mind: comments do not add value to the code in the majority of cases. At least, not for this type of code (but also for code in general).

---

The second thing is that there are comments everywhere. They try to describe what the code does. Every few lines of code have a comment.

Having these many comments creates a problem as when the code changes, we will have to update the comments as well to keep the comments in sync with the code. So, we will have actually to do more work. Change the code but also the comments. If we do not keep the comments in sync with the code, the comments become completely useless. They also become lies as they may say one thing while the code says something else.

---

Using comments, the code gets longer than without comments. Remove all comment lines and see how much shorter the test script becomes.

---

Let’s recap what we have so far:

• comments do not add much value as Selenium code is usually pretty simple

• comments make the code longer

• keeping the comments in sync with the code makes us do more work

Why keep the comments around then?

Let’s just agree to delete them all.

Comments for code are just clutter.

If you are worried that the code is too difficult to understand, there are much better ways to fix that without comments.

One final thing.

Nothing says “beginner code” more than having comments all over the place.

If you want to not be a beginner (and who does not want to become better), please do not use comments at all.

“The best comment is the comment that you do not have to write.”

“The code itself is the best comment.”

Uncle Bob