Applitools Tutorial: Visual AI Testing for QA Teams

A green checkout test concealed a broken page

The functional suite passed: the cart contained one item, the order API returned 200, and the Place order button was enabled. The release still shipped with the price column clipped at the supported tablet width. No assertion failed because every assertion inspected state, not presentation.

That is a useful starting point for Applitools Eyes. Add it where a user-facing arrangement carries risk that DOM assertions express poorly. Checkout totals, error banners, comparison tables, localized navigation, and responsive forms are good candidates. A backend administration page whose layout changes weekly may not be.

Before writing a checkpoint, record the failure you want the check to expose:

• At 768 pixels, item price, quantity, and total remain visible without overlap.
• A validation message appears beside the field it describes.
• The empty-cart illustration does not cover the recovery action.
• The Arabic layout mirrors controls without truncating labels.

This statement is the visual contract. It keeps the test from becoming a collection of screenshots with no review standard.

Select checkpoints from user decisions

A checkpoint is most valuable after the application reaches a meaningful, stable state. Capturing every route transition creates review volume without proportional evidence. Map checkpoints to decisions a person makes on the screen.

For an order flow, a compact set might be:

Keep ordinary assertions for behavior. Assert that an item was removed, a request completed, or focus moved correctly. Use Eyes for the rendered result. If a single checkpoint is expected to prove both a business calculation and its presentation, retain an explicit numeric assertion beside the visual one.

Name checkpoints by state, not by sequence. “Review order with discount” survives test reordering. “Screenshot 4” does not.

Make the input deterministic before adding Eyes

Visual comparison amplifies uncontrolled inputs. Prepare a test account, seeded records, feature flags, locale, time zone, viewport, and font availability before blaming the comparison engine.

For the checkout example, the setup artifact should identify:

• SKU, price, inventory state, and promotion fixture
• authenticated role and account flags
• locale, currency, and address format
• viewport and responsive breakpoint being exercised
• animations, rotating recommendations, and timestamps
• the event that means rendering is complete

Wait for application evidence, not a convenient delay. A loading indicator disappearing, a response completing, or a stable heading becoming visible is stronger than sleeping for two seconds. Load web fonts before capture when typography affects line wrapping. Turn off caret blinking and motion in the test environment when possible.

Do not hide a changing region merely because it changes. First ask whether the variation represents real risk. A fluctuating account balance may be dynamic but still needs correct format, alignment, and emphasis. Choose a comparison mode or region treatment that preserves those properties rather than ignoring the whole panel.

Connect Eyes to an existing Playwright path

Start with one reliable functional test. Install the Eyes SDK that matches the automation stack, supply the API key through the CI secret store, and never commit the key. The Playwright integration follows a small lifecycle: open Eyes for a named application and test, perform one or more checks, then close the visual test.

An intentionally small example looks like this:

import { test, expect } from "@playwright/test";
import { Eyes, Target } from "@applitools/eyes-playwright";

test("review order keeps totals readable", async ({ page }) => {
  const eyes = new Eyes();

  await page.goto("/checkout/review");
  await expect(page.getByRole("heading", { name: "Review order" }))
    .toBeVisible();

  await eyes.open(page, "Storefront", "Review order with discount");
  await eyes.check(
    "Discounted order ready to submit",
    Target.window().fully(),
  );
  await eyes.close();
});

Treat this as the seam, not a finished production test. Your suite still needs its normal fixture creation and cleanup. It also needs a failure-safe Eyes lifecycle so an interrupted test does not remain open. Implement that cleanup using the current SDK guidance for your runner.

For cross-browser or multiple viewport coverage, configure the runner and browser matrix centrally. Do not duplicate the same test body for each rendering target. Keep application name, test name, branch context, and viewport naming consistent because those values help Eyes select and organize the relevant baseline.

Establish the first baseline as a controlled review

The first successful execution has nothing historical to compare with. It creates a prospective expectation, not proof that the page is correct. Seed it against an approved build and review every checkpoint with the product or design owner.

Use a short baseline acceptance record:

The reviewer should compare the image to requirements and current design assets, not merely decide that it “looks normal.” Ask whether content is complete, hierarchy communicates the right action, alignment works at the boundary widths, and a disabled or error state could be mistaken for success.

Avoid approving a large first batch in bulk. A wrong baseline turns every later correct comparison green. For a pilot, use one feature branch, a small checkpoint set, and a named reviewer. Once accepted, rerun without application changes. That second run should be clean and demonstrates that the capture itself is stable.

Convert each result into a release decision

A detected difference is evidence to classify, not automatically a defect. Review the baseline, current rendering, and highlighted change together. Then choose one of four outcomes:

1. Product regression: reject the result, create a defect, and link the affected checkpoint.
2. Intended change: verify the requirement and approve the new expectation.
3. Test-state error: repair data, waits, or environment; do not update the baseline.
4. Comparison-policy error: narrow or change the region treatment after reviewing the lost coverage.

For intended changes, record the work item and reviewer in the pull request or test report. Baseline approval is a specification change. It deserves the same traceability as changing an assertion.

Batch related executions under the CI build or pull request so reviewers see one coherent change set. A useful review order is high-risk pages first, shared components second, then lower-risk responsive variants. If a header change appears across forty checkpoints, inspect the common cause before approving forty separate results.

The merge rule must be explicit. For example: all checkout checkpoints reviewed; no unresolved differences on blocking viewports; intentional updates approved by a product or design owner. “Visual job completed” is not a merge rule.

Reduce noise without deleting the signal

Most noisy suites fail because capture conditions vary or because the test watches more than the team is prepared to review.

Common corrections include:

• Seed names, dates, balances, and image URLs instead of masking an entire card.
• Freeze application time when time affects presentation.
• Capture after lazy content has loaded, especially on full-page checks.
• Exercise explicit responsive widths at design boundaries rather than many adjacent widths.
• Use region-specific comparison behavior for content with a legitimate variation.
• Separate theme, locale, and role variants when each has a different approved expectation.

Choose match behavior from the contract. A layout-oriented comparison can suit a feed whose content changes while structure must remain intact. A stricter comparison belongs on a stable brand header or payment summary. Applying one global setting to every screen is easy to configure and hard to trust.

Track noisy checkpoints by identity. If “Dashboard, signed-in, desktop” needs frequent non-product reruns, give it an owner and a deadline for stabilization. After two repair attempts, reconsider its fixture, scope, or value. Quieting it by accepting unexplained results trains reviewers to ignore the suite.

Run Eyes as an owned quality control

The operating model matters more than the first integration. Assign ownership for test code, baseline approval, and product interpretation. These may be three different people. Document who can approve changes on shared components and what happens when the designated reviewer is unavailable.

Review a small set of measures per release:

• percentage of blocking checkpoints reviewed before merge
• number of genuine presentation defects found before release
• reruns caused by unstable state or environment
• median age of unresolved visual differences
• checkpoints removed because they no longer protected a decision

Do not report raw screenshot count as coverage. Coverage is the set of visual contracts exercised across important states, viewports, themes, and locales.

After a production UI defect, ask whether the risky state was absent, the capture was unstable, the comparison policy was too permissive, or a result was incorrectly approved. Update that specific control. After an intentional redesign, retire obsolete baselines through a reviewed change rather than letting old expectations drift.

A dependable Applitools workflow ends with an auditable statement: this build rendered these business-critical states under these controlled conditions, and named reviewers resolved every meaningful difference. That is stronger evidence than either a green functional suite or an unattended visual dashboard.