Complete Testing Tutorial

Every flaky test in a browser suite is the same bug: the test assumed the page was ready and the page was not. Selenium calls the result StaleElementReferenceException. Cypress calls it element detached from the DOM. Playwright calls it a timeout. Three tools, one mistake — a reference captured at one moment and used at another, across a boundary where a framework re-rendered the node.

Which is why the single highest-value skill in this track is not learning a tool's API but learning to wait on the right condition. sleep(2) is a bet that the app will be ready in two seconds; it fails on a slow CI runner and wastes two seconds on every other run. Waiting on a state — this element is visible, this request has completed, this text has changed — is both faster and deterministic.

The three generations of browser automation

The tools in this track sit at different points in a clear evolution, and knowing which problem each was built to solve explains their error messages.

None of them removes the need to understand what you are waiting for. They differ in how much of that waiting they do on your behalf, and in how loudly they complain when your intent is ambiguous.

Stale elements and detached nodes are a caching bug

A WebElement is a handle to a specific DOM node. If the framework re-renders — React reconciling, Angular running change detection, a Vue list re-keying — the old node is discarded and your handle points at something no longer in the document. Selenium raises StaleElementReferenceException on the next use.

The fix is not to retry the click; it is to stop holding the reference across a state change. Find the element as late as possible, and where the framework re-renders on every keystroke, re-find it per interaction.

# Fragile: the handle is captured before an action that re-renders the row
row = driver.find_element(By.CSS_SELECTOR, "[data-test=row-42]")
driver.find_element(By.CSS_SELECTOR, "[data-test=refresh]").click()
row.click()                       # StaleElementReferenceException

# Robust: re-locate after the state change, and wait on a condition
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

wait = WebDriverWait(driver, 10)
wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-test=refresh]"))).click()
wait.until(EC.staleness_of(row))  # assert the re-render actually happened
wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-test=row-42]"))).click()

Playwright strict mode: an error that is doing you a favour

Strict mode violation: locator resolved to 3 elements means your selector is ambiguous and Playwright refuses to pick one. Selenium would have silently taken the first match, which is exactly how a test ends up asserting on the wrong row and passing for months.

So the correct response is to make the intent precise rather than to suppress the check. Playwright's locator API is built for this: scope to a container, filter by text, or name the element the way a user would.

// Ambiguous - three "Delete" buttons on the page
await page.locator('button:has-text("Delete")').click();   // strict violation

// Scope to the row that matters
await page.getByRole('row', { name: 'invoice-1042' })
          .getByRole('button', { name: 'Delete' })
          .click();

// Or filter explicitly
await page.getByRole('listitem')
          .filter({ hasText: 'invoice-1042' })
          .getByRole('button', { name: 'Delete' })
          .click();

// .first() is legitimate only when "any of them" is genuinely the intent
await page.getByRole('link', { name: 'Docs' }).first().click();

Why cy.wait(ms) is the wrong tool, and what to use instead

A fixed wait is a guess about someone else's machine. On a fast developer laptop it is dead time; on a loaded CI runner with four suites in parallel it is too short, and the test fails for a reason that has nothing to do with the code under test. That is the definition of a flaky test, and flaky tests get muted, and muted tests stop protecting anything.

Every framework gives you a way to wait on the actual condition. Waiting on a network response is usually the strongest signal, because it ties the test to the app's real readiness rather than to a visual side effect of it.

// Guessing
cy.get('[data-test=save]').click();
cy.wait(3000);
cy.get('[data-test=toast]').should('contain', 'Saved');

// Waiting on the thing you actually depend on
cy.intercept('POST', '/api/invoices').as('save');
cy.get('[data-test=save]').click();
cy.wait('@save').its('response.statusCode').should('eq', 201);
cy.get('[data-test=toast]').should('contain', 'Saved');

// Playwright equivalent
const save = page.waitForResponse(r =>
  r.url().includes('/api/invoices') && r.status() === 201);
await page.getByRole('button', { name: 'Save' }).click();
await save;
await expect(page.getByTestId('toast')).toHaveText(/Saved/);