Why Every Software Tester Should Practice Explaining Their Code Aloud

import os

import pytest
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

# Full address of the practice site the-internet.herokuapp.com
BASE_URL = os.environ["APP_URL"]


@pytest.fixture
def driver():
    drv = webdriver.Chrome()
    drv.implicitly_wait(0)
    yield drv
    drv.quit()


def test_valid_login_shows_secure_area(driver):
    driver.get(BASE_URL + "/login")
    driver.find_element(By.ID, "username").send_keys("tomsmith")
    driver.find_element(By.ID, "password").send_keys("SuperSecretPassword!")
    driver.find_element(By.CSS_SELECTOR, "button[type='submit']").click()

    flash = WebDriverWait(driver, 10).until(
        EC.visibility_of_element_located((By.ID, "flash"))
    )
    assert "You logged into a secure area!" in flash.text
    assert driver.current_url.endswith("/secure")

"The fixture creates a Chrome driver, yields it to the test,
and quits it after the test, even if the test fails.
I set implicit wait to zero so I only use explicit waits
and do not mix the two.

The test opens the login page and uses IDs for the fields,
because they are unique on this page. For the button there
is no ID, so I used a short CSS selector on the submit type.

After clicking, I wait until the flash message is visible,
up to ten seconds. If it never appears, a TimeoutException
fails the test with a clear reason.

I then assert two things: the success text, and that the
URL ends with /secure, so I am checking both the message
and that navigation really happened."

# Flaky and slow
driver.find_element(By.ID, "search").send_keys("laptop")
driver.find_element(By.ID, "go").click()
time.sleep(5)
results = driver.find_elements(By.CSS_SELECTOR, ".result")
assert len(results) > 0

# Stable: wait for the state that proves results loaded
driver.find_element(By.ID, "search").send_keys("laptop")
driver.find_element(By.ID, "go").click()
results = WebDriverWait(driver, 10).until(
    EC.presence_of_all_elements_located((By.CSS_SELECTOR, ".result"))
)
assert len(results) > 0

from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait


def table_has_rows(min_rows):
    def condition(driver):
        rows = driver.find_elements(By.CSS_SELECTOR, "table tbody tr")
        return rows if len(rows) >= min_rows else False
    return condition


# usage inside a test
rows = WebDriverWait(driver, 15).until(table_has_rows(5))
assert len(rows) >= 5

# Spoken: until() calls my function repeatedly. It returns
# False while the table is still loading, and returns the
# rows once there are at least five, which ends the wait.

# Weak: passes even if the cart is wrong
driver.find_element(By.CSS_SELECTOR, "[data-testid='add-to-cart']").click()
assert driver.find_element(By.ID, "cart").is_displayed()

# Strong: checks the outcome the user cares about
driver.find_element(By.CSS_SELECTOR, "[data-testid='add-to-cart']").click()
count = WebDriverWait(driver, 10).until(
    EC.text_to_be_present_in_element((By.ID, "cart-count"), "1")
)
assert count
item = driver.find_element(By.CSS_SELECTOR, "[data-testid='cart-item-name']")
assert item.text == "Wireless Mouse", f"Unexpected item: {item.text}"

FOR EVERY TEST YOU SHOW, BE READY FOR:

1. Why this locator and not XPath?
2. What are you waiting for, and why that condition?
3. What exactly does this assertion prove?
4. Could this test pass while the feature is broken?
5. Where does the test data come from?
6. How would this run in CI without a screen?
   -> add the --headless=new argument to ChromeOptions
7. Why is this test automated at all, and not manual?

Say each answer aloud in under 30 seconds.

TWO-MINUTE TEST WALKTHROUGH

1. Purpose  (15s) -> "This test checks that ..."
2. Setup    (20s) -> fixture, browser, test data source
3. Actions  (30s) -> each step and why that locator
4. Sync     (20s) -> what I wait for and the timeout
5. Asserts  (20s) -> what each one proves
6. Limits   (15s) -> what this test does NOT cover

Record on your phone. Re-record any part where
you said 'basically' or 'it just works'.

LINE JUSTIFICATION SHEET (one test file)

Line | Code (short)              | Why it is there
-----|---------------------------|------------------------
  1  | fixture driver            | ______________________
  2  | driver.get(...)           | ______________________
  3  | find_element(By.ID ...)   | ______________________
  4  | WebDriverWait(...).until  | ______________________
  5  | assert ...                | ______________________

Any blank in the right column = study or delete.

BEFORE YOU SHARE YOUR AUTOMATION REPO

[ ] README says how to install and run the tests
[ ] requirements.txt lists selenium and pytest
[ ] No time.sleep left in the main tests
[ ] No absolute XPath locators
[ ] Every test has at least one meaningful assertion
[ ] Test names describe behaviour, e.g. test_invalid_password_shows_error
[ ] No real passwords or personal data committed
[ ] You can explain every file in the repo