UI Test Automation

What UI automation is for — and what it is bad at

A UI test answers one question no other test can: can a user, in a real browser, complete this journey from start to finish? It catches defects that live between layers — a button wired to the wrong handler, a form that sends a field the API rejects, a script error that only appears after a redirect, a layout change that hides the submit button behind a cookie banner.

It is poor at almost everything else. Checking every validation rule, every calculation branch or every error code through the browser is slow, and when a UI test fails it tells you that the journey broke, not where. Those checks belong in unit and API tests, which run in milliseconds and point at the faulty code.

• Good fit — critical user journeys (sign-up, login, search, checkout, payment confirmation), the integration of front end and back end, cross-browser behaviour of a small set of flows, and regression of flows that have broken before.
• Poor fit — business rules with many input combinations, validation matrices, visual design judgement, usability, exploratory questions (“is this confusing?”), and screens whose design changes every sprint.
• Warning signs — a suite that takes longer than the team is willing to wait, tests that fail for reasons unrelated to the product, and failures nobody investigates because “it is probably flaky”.

How a maintainable automation framework is layered

Most UI suites that become unmaintainable fail for the same reason: test intent, page structure and tool calls are mixed in the same function, so one markup change breaks fifty tests. The cure is separation into layers, each with a single reason to change. The ISTQB Advanced Level Test Automation Engineering syllabus describes a generic test automation architecture built on the same idea — separating what is tested from how the system under test is driven. The layer names below are the ones most teams use day to day.

• Test layer — the specs. One scenario per test, written in business terms (“customer pays with a saved card”). No selectors, no waits, no driver calls.
• Page and component objects (or an equivalent abstraction such as Screenplay tasks) — the only place that knows how a screen is structured and which locators it uses.
• Driver / framework layer — the WebDriver bindings, Playwright or Cypress, plus thin wrappers for your own conventions (fixtures, custom commands). Keep wrappers thin: re-implementing the framework hides its features and its documentation.
• Test data layer — factories and API clients that create the users, orders and products a test needs, and remove them afterwards.
• Configuration — base URLs, browsers, timeouts, credentials and feature flags per environment, read from environment variables or config files, never hard-coded in tests.
• Reporting — pass/fail per test with the evidence needed to debug a failure: screenshots, videos, traces, console and network logs, published by the CI pipeline.

e2e/
  tests/        checkout.spec.ts, login.spec.ts        <- test layer (intent only)
  pages/        login-page.ts, checkout-page.ts        <- page objects
  components/   header.ts, date-picker.ts              <- component objects
  api/          orders-client.ts, users-client.ts      <- set up state via API
  fixtures/     auth.ts, test-data.ts                  <- data + setup/teardown
  config/       playwright.config.ts, env/staging.env  <- configuration
  reports/      (generated) html report, traces, junit.xml  <- reporting

Browser automation: WebDriver, Playwright and Cypress

WebDriver is a W3C specification for remote-controlling a browser: a client library sends commands over HTTP to a browser-specific driver (chromedriver, geckodriver, safaridriver and others), and the driver controls the browser. Selenium is the best-known client, with official bindings for Java, Python, C#, JavaScript and Ruby, and Selenium Grid distributes sessions across machines. Because browser vendors ship their own drivers, WebDriver is the most portable option, and the protocol also underlies other tools such as Appium for mobile apps.

Playwright is an open-source library from Microsoft that drives Chromium, Firefox and WebKit through its own browser connection rather than WebDriver. Its test runner provides auto-waiting before actions, retrying (“web-first”) assertions, isolated browser contexts, parallel workers, network interception and a trace viewer. It supports TypeScript/JavaScript, Python, Java and .NET.

Cypress runs test code inside the browser next to the application, which gives it direct access to the page and the network, automatic retrying of queries and assertions, and an interactive runner that shows every command against a snapshot of the DOM. Tests are written in JavaScript or TypeScript. The in-browser architecture brings trade-offs that its documentation lists, for example around multiple tabs and cross-origin navigation.

None of the three is “the best”. Choose by the language your team writes, the browsers your users actually run, whether you need grid or mobile infrastructure, and how clearly the tool reports failures. The concepts in the rest of this guide apply to all of them.

Locators: how tests find elements

A locator is the query a test uses to find an element, and its quality decides most of a suite’s maintenance cost. Playwright’s and Testing Library’s documentation both recommend user-facing attributes first — the element’s role and accessible name, its label, its visible text — and a dedicated test id after them; extending that order with CSS, and XPath as the last resort, gives a ranking that works with any tool.

User-facing locators survive refactors because they change only when the interface the user sees changes, and they fail when an element loses its accessible name — a useful side check for accessibility. The guide on locator strategies covers the full order, CSS versus XPath, dynamic ids, iframes, shadow DOM and anti-patterns such as absolute XPath and index-based selectors.

// Playwright — in order of preference
page.getByRole("button", { name: "Place order" })
page.getByLabel("Email")
page.getByText("Order confirmed")
page.getByTestId("order-total")
page.locator("form#checkout button[type=submit]")   // CSS: only when nothing above fits

// Selenium (Java)
driver.findElement(By.cssSelector("[data-testid=order-total]"));

// Cypress
cy.get("[data-cy=order-total]");

Waits and synchronization: never a fixed sleep

Most UI flakiness is a race: the test acts or asserts before the application is ready. A fixed sleep (Thread.sleep, time.sleep, cy.wait(5000)) “fixes” it on your laptop by guessing, then fails on a slower CI runner — and wastes its full duration on every fast run. Wait for a condition instead, with a timeout.

• Selenium implicit wait — a driver-wide setting that makes every element lookup poll until the element is present or the timeout expires. It covers presence only, not visibility or clickability.
• Selenium explicit wait — WebDriverWait with a condition (visible, clickable, text present, or your own function), applied exactly where it is needed. The Selenium documentation warns against mixing implicit and explicit waits, because the combined timeouts become unpredictable.
• Playwright auto-waiting — before an action such as click or fill, Playwright checks that the element is actionable (visible, stable, able to receive events, enabled and, for inputs, editable) and waits until it is or the timeout expires.
• Cypress retry-ability — queries such as cy.get and cy.contains are retried together with the assertion chained after them until the assertion passes or the command times out. Actions such as .click() are not re-run, so assert the state you need before acting on it.
• Wait for the application’s own signals — a specific network response, a spinner disappearing, a “Saved” status — rather than for time or a generic “network idle” state.

// Selenium (Java) — explicit wait for a condition, not a sleep
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement status = wait.until(
    ExpectedConditions.visibilityOfElementLocated(By.cssSelector("[data-testid=order-status]")));

// Playwright (TypeScript) — click auto-waits; the assertion retries
await page.getByRole("button", { name: "Pay now" }).click();
await expect(page.getByTestId("order-status")).toHaveText("Paid");

// Cypress — the query retries until the assertion passes or times out
cy.get("[data-cy=order-status]").should("have.text", "Paid");

// Never: Thread.sleep(5000) / time.sleep(5) / cy.wait(5000)

Assertions: check what the user can see, and let them retry

An assertion should describe an outcome the user or the business cares about: the confirmation heading is visible, the order total reads 199.20 SAR, the error message names the invalid field, the URL is the order page. Asserting on internal details — a CSS class, the number of divs, a component’s state — couples the test to the implementation and breaks on harmless refactors.

Use retrying assertions where the framework offers them. In Playwright, expect(locator).toBeVisible(), toHaveText() and expect(page).toHaveURL() retry until they pass or time out, whereas expect(await locator.textContent()).toBe(…) reads once and races with the page. In Cypress, .should() retries the query before it. In Selenium, wait for the condition explicitly, then assert.

• Assert one behaviour per test, with as many assertions as it takes to prove that behaviour.
• Use exact values for money, counts and statuses; use patterns only for genuinely variable parts, such as an order number like ORD-2026-000184 or a timestamp.
• When the UI renders data from an API, assert the rendered result in the UI test and the full response in an API test — do not re-verify every JSON field through the browser.
• Make failure messages read like bug titles: expected “Paid”, received “Pending” for order ORD-2026-000184.

Try it: Regex Tester

Page objects and component objects

A page object is a class that represents one page or screen. It exposes what a user can do there as methods (signIn, addToCart) and hides the locators and interaction details. When the markup changes, you fix one class instead of every test. The Selenium documentation describes the pattern and recommends that page object methods return other page objects or data, and that page objects do not make assertions — the test decides what is correct.

Component objects apply the same idea to parts that appear on many pages: a header, a date picker, a data table, a modal dialog. A checkout page object then composes a header component and an address-form component instead of duplicating their locators.

Keep page objects small and behaviour-focused. A 900-line “BasePage” full of generic helpers is a sign that the abstraction has turned into a second framework. Some teams prefer alternatives such as the Screenplay pattern (actors performing tasks) or plain domain-level helper functions; they are fine as long as they achieve the same separation. The example below uses Playwright with TypeScript.

// pages/orders-page.ts
import type { Page, Locator } from "@playwright/test";

export class OrdersPage {
  readonly heading: Locator;

  constructor(page: Page) {
    this.heading = page.getByRole("heading", { name: "My orders" });
  }
}

// pages/login-page.ts
import type { Page, Locator } from "@playwright/test";
import { OrdersPage } from "./orders-page";

export class LoginPage {
  readonly email: Locator;
  readonly password: Locator;
  readonly submit: Locator;

  constructor(private readonly page: Page) {
    this.email = page.getByLabel("Email");
    this.password = page.getByLabel("Password");
    this.submit = page.getByRole("button", { name: "Sign in" });
  }

  async goto() {
    await this.page.goto("/login");
  }

  async signIn(email: string, password: string): Promise<OrdersPage> {
    await this.email.fill(email);
    await this.password.fill(password);
    await this.submit.click();
    return new OrdersPage(this.page);
  }
}

// tests/login.spec.ts
import { test, expect } from "@playwright/test";
import { LoginPage } from "../pages/login-page";

test("customer sees their orders after signing in", async ({ page }) => {
  const login = new LoginPage(page);
  await login.goto();
  const orders = await login.signIn("layla.h@example.com", process.env.TEST_USER_PASSWORD!);
  await expect(orders.heading).toBeVisible();
  await expect(page).toHaveURL(/\/orders$/);
});

Test data and isolation

Every UI test should create what it needs and depend on nothing another test created. Shared accounts and shared orders are the most common cause of tests that pass alone and fail in the suite: one test cancels the order another test is checking, or two parallel tests edit the same profile.

Create state through the API or a database seed, not through the UI. Logging in through the form in every test, or building a cart by clicking through ten product pages, makes each test slow and exposes it to failures in screens it is not testing. Test the login form once, in its own test; elsewhere, obtain a session through the API and reuse it — Playwright can save authenticated browser state to a file, and Cypress offers cy.session for the same purpose.

• Unique data per test — add a run id or UUID to emails and names (for example layla.h+run8412@example.com) so parallel runs cannot collide.
• Fictional data only — never copy production customers into test environments; generate realistic records instead.
• Stub what you do not own — payment gateways, SMS providers and map services can be replaced with mocked responses in most UI tests (page.route in Playwright, cy.intercept in Cypress), keeping one separate check against the provider’s real sandbox.
• Clean up, or make data disposable — delete created records after the test, or use an environment that is reset for each run.

Try it: API Request Builder Try it: Fake User Generator Try it: Test Data Factory Try it: Mock API Response Generator

Cross-browser testing and parallel execution

Cross-browser testing checks that the same journeys work in the browser engines your users actually have: Chromium-based browsers (Chrome, Edge), Firefox and Safari (WebKit), at desktop and mobile widths. Let your analytics decide the matrix; running every test on every browser multiplies cost for little gain. A common split is the full suite on one browser and a smoke set of critical journeys on the others.

Playwright’s WebKit build is not the same product as Safari on macOS or iOS. If Safari users matter to you, include real Safari runs — through safaridriver or a device cloud — for the most important flows.

Parallel execution keeps a growing suite fast, and it only works when tests are isolated. Runners split tests across workers: Playwright workers and sharding, Selenium Grid nodes combined with TestNG, JUnit or pytest-xdist parallelism, and Cypress spec files spread across CI machines. Each worker needs its own browser context and its own data.

• Design for any order — occasionally run the suite in random order to prove there are no hidden dependencies between tests.
• Shard long suites across CI jobs and merge the reports into one.
• Watch shared resources — one test tenant, one rate-limited API or one mailbox can serialise a “parallel” suite or make it flaky.

Running UI tests in CI

In CI, browsers run headless (without a visible window) on clean runners, usually in containers with the browsers preinstalled. Pin browser and framework versions so that a runner image update cannot silently change results, and record the version of the application under test in the report.

A failed CI run is only useful if someone can debug it without re-running it locally. Configure the suite to keep evidence on failure — screenshots, videos, Playwright traces, browser console and network logs — and publish the HTML report and JUnit XML as build artifacts so the pipeline can show results per test. The example is a GitHub Actions job for a Playwright smoke set; GitLab CI and Jenkins pipelines follow the same shape.

• Pull request — a fast smoke set of UI journeys (minutes, not an hour) alongside unit and API tests.
• Main branch or nightly — the full UI regression across the browser matrix.
• After deployment — a handful of read-only journeys against the live environment.
• Failures block the merge. Flaky tests are fixed or quarantined with an owner, not re-run until green; the guide on flaky tests covers diagnosis, retries and quarantine.

name: ui-smoke
on: [pull_request]
jobs:
  ui-smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test --grep @smoke
        env:
          BASE_URL: ${{ vars.STAGING_URL }}
      - uses: actions/upload-artifact@v7
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/

A practical strategy: what to automate at the UI level

The test pyramid, explained in the guide on manual versus automated testing, puts many fast unit tests at the base, fewer API and service tests in the middle and a small number of UI tests at the top. For UI automation the practical rule is: automate a journey through the UI only when the thing at risk is the journey itself — the wiring between screens, front end and back end — and push every other check down to the lowest level that can detect it.

For example, a discount calculation with twelve rule combinations belongs in unit and API tests; “the discounted total is shown at checkout and charged at payment” belongs in one UI test.

• Start from risk: list the journeys whose failure costs money, data or trust (payment, sign-up, login, key search) and automate those first.
• Write each journey as Given/When/Then acceptance criteria first; the criteria become the test names and the assertions.
• Budget the suite: agree a maximum duration for the pull-request smoke set and for the full run, and delete or push down tests when you exceed it.
• Treat tests as production code: code review, naming conventions, no copy-paste, and a named owner for each area.
• Maintain continuously: update page objects in the same pull request as the UI change, agree test ids with developers, delete tests for features that no longer exist, and upgrade framework and browser versions in their own change.
• Measure what matters: time to feedback, flaky rate, and defects the suite caught before release — not the raw number of tests.

Try it: Acceptance Criteria Generator Try it: Test Case Generator

Frequently asked questions

References

• Certified Tester Advanced Level Test Automation Engineering (CTAL-TAE) v2.0ISTQB · 2024ISTQB's advanced syllabus on designing, implementing and maintaining test automation solutions and their architecture.
• WebDriver (W3C)W3C · 2026The W3C protocol browsers implement for remote control by automation tools such as Selenium (the Level 2 edition is a Working Draft).
• Selenium DocumentationSelenium ProjectOfficial documentation for browser automation with WebDriver, including waits, locators and Grid.
• Playwright DocumentationMicrosoft (Playwright)Official documentation for Playwright, an end-to-end test framework that drives Chromium, WebKit and Firefox.
• Cypress DocumentationCypress.ioOfficial documentation for end-to-end and component testing in the browser with Cypress.
• Best Practices — PlaywrightMicrosoft (Playwright)Test user-visible behaviour, keep tests isolated, prefer resilient locators and web-first assertions, and debug with traces.
• Page object models — SeleniumSelenium ProjectThe page object pattern: one class per page or component that hides locators and exposes the actions a test needs, reducing duplication.
• The Practical Test Pyramid (Ham Vocke)martinfowler.com · 2018A widely cited explanation of how to balance unit, integration, contract and UI tests in an automated test portfolio.