Test blur validation without faking the focus change

The email error appears when you click around manually, yet the automated test leaves the field looking valid. The test filled the value but never proved that the input lost focus. Calling a handler or dispatching a blur event can make an assertion pass without reproducing the browser state the form relies on.

Start with the focus transition the browser actually performs

Playwright's locator.blur() calls the DOM element's blur() method. That is the complete documented behavior and the right mental model. It is not a mouse click, it does not type a key, and it does not choose a next control for the user. It asks the matched element to relinquish focus.

The field must own focus first. fill() normally gives an editable control focus while setting its value, but the test should assert toBeFocused() when focus is part of the contract. A direct call on an input that is not focused has no focus-loss transition for application code to observe. A test can otherwise report that blur() completed while never exercising validation.

When focus leaves an element, the browser fires the native blur event. MDN documents that blur does not bubble. The related focusout event follows and does bubble. A listener attached directly to the input sees blur; a listener delegated from the form must use focusout or register a capture-phase blur listener. That distinction explains many cases where a field-level demo works but a production form's delegated handler does not.

FocusEvent.relatedTarget identifies the element receiving focus when one exists. A direct HTMLElement.blur() call does not model the user's choice of a next target, so it is a poor oracle for logic that depends on where focus goes. Pressing Tab or clicking a known control is better for that behavior. Keep direct blur for validation whose requirement is simply “run after this field loses focus.”

Avoid locator.dispatchEvent('blur') as a shortcut. Dispatching an event invokes event listeners, but it does not call the element's focus method or make the browser move focus. Product code that checks document.activeElement, relies on focusout, or uses the next target can behave differently. A synthetic event test proves only that a listener responds to a synthetic event.

Blur-triggered validation has at least three observable layers. First, focus changes. Second, the application marks field state, perhaps by setting aria-invalid and associating an error description. Third, downstream behavior changes, such as disabling Continue or preventing submission. A strong test asserts the layers the user depends on rather than treating method completion as success.

Native HTML validity and application validity are not interchangeable. An <input type="email" required> has a browser validity state. The browser does not automatically invent your error paragraph, set your chosen ARIA attributes, or apply your touched-state policy. A framework may wait until blur before surfacing the native result. Test the final contract explicitly and do not assume one attribute proves every layer.

Timing depends on the implementation. A synchronous listener may update the DOM in the same task. A framework can schedule rendering. An async validator can call a service. Playwright's web-first assertions retry the resulting condition, so fixed sleeps are unnecessary. The event trigger should be precise; the assertion can wait for the product state.

Prove synchronous validation and recovery

A self-contained field is useful for learning the boundary because no framework or server can hide it. The example below fills an invalid email, confirms focus, calls blur(), and asserts focus loss, accessible invalid state, and the visible error. It then corrects the value and repeats the transition to prove recovery.

import { expect, test } from '@playwright/test';

test('shows and clears an email error after genuine focus loss', async ({ page }) => {
  await page.setContent(`
    <form>
      <label for="email">Email</label>
      <input id="email" name="email" type="email" required aria-describedby="email-error">
      <p id="email-error" role="alert" hidden></p>
    </form>
    <script>
      const email = document.querySelector('#email');
      const error = document.querySelector('#email-error');
      email.addEventListener('blur', () => {
        const invalid = !email.validity.valid;
        email.setAttribute('aria-invalid', String(invalid));
        error.hidden = !invalid;
        error.textContent = invalid ? 'Enter a valid email address' : '';
      });
    </script>
  `);

  const email = page.getByLabel('Email');
  const error = page.getByRole('alert');

  await email.fill('wrong-format');
  await expect(email).toBeFocused();
  await email.blur();

  await expect(email).not.toBeFocused();
  await expect(email).toHaveAttribute('aria-invalid', 'true');
  await expect(error).toHaveText('Enter a valid email address');

  await email.fill('qa@example.test');
  await expect(email).toBeFocused();
  await email.blur();

  await expect(email).toHaveAttribute('aria-invalid', 'false');
  await expect(error).toBeHidden();
});

Every assertion has a possible product failure. Removing the event listener leaves aria-invalid unset and the error hidden. Breaking recovery leaves the old error visible. Calling dispatchEvent() instead of changing focus would fail the focus assertion. The test does not inspect a constant or repeat the fixture's input as its only expected value.

The recovery half matters. Forms often validate invalid input correctly but retain touched-state errors after correction. A one-direction test misses stale descriptions, disabled submit controls, and screen-reader announcements that no longer match the value. Clear-state behavior is a different failure mode, not a repetition of the invalid case.

Use the application's actual message contract. If content can change by locale, assert the stable accessible relationship and locale-specific message in separate cases. A broad regex such as /invalid/i may pass for an internal diagnostic that users never see. A role and exact seeded-locale text make the oracle reviewable.

Do not assert that document.activeElement is always body after direct blur. Browser behavior around focus, document chrome, and event handling can differ. The durable requirement is that the email no longer owns focus and that validation ran. When the next target matters, choose it through an interaction and assert that target directly.

A framework version of this test should still avoid framework internals. Do not read a Vue touched ref or React Hook Form object from the page. Assert the DOM state the framework produces. That keeps the test valid through a state-management refactor and catches missing accessibility output.

Use Tab when the destination is part of the requirement

Keyboard users usually leave a field with Tab or Shift+Tab. If validation depends on the next control, focus order, or relatedTarget, direct blur is too narrow. Send the key while the field is focused and assert where focus lands. This tests both validation and one segment of keyboard navigation.

import { expect, test } from '@playwright/test';

test('validates email while moving keyboard focus to country', async ({ page }) => {
  await page.setContent(`
    <form>
      <label>Email <input id="email" type="email"></label>
      <label>Country <select id="country"><option>India</option></select></label>
      <output id="transition"></output>
      <p id="email-error" role="alert" hidden></p>
    </form>
    <script>
      const email = document.querySelector('#email');
      const transition = document.querySelector('#transition');
      const error = document.querySelector('#email-error');
      email.addEventListener('blur', event => {
        const target = event.relatedTarget;
        transition.value = target instanceof HTMLElement ? target.id : 'none';
        const invalid = !email.value.includes('@');
        error.hidden = !invalid;
        error.textContent = invalid ? 'Email must contain @' : '';
      });
    </script>
  `);

  const email = page.getByLabel('Email');
  const country = page.getByLabel('Country');

  await email.fill('missing-at-sign');
  await page.keyboard.press('Tab');

  await expect(country).toBeFocused();
  await expect(page.locator('#transition')).toHaveText('country');
  await expect(page.getByRole('alert')).toHaveText('Email must contain @');
});

The test will fail if an unexpected focusable element is inserted between Email and Country. Whether that is a regression depends on the form's keyboard contract. If designers intentionally add a help link, update the expected path after reviewing accessibility. Do not replace Tab with direct blur merely to ignore a broken or changed focus order.

Shift+Tab deserves its own case only when reverse navigation matters. Repeating every field in both directions can double suite cost without new risk. Target composite widgets, conditional controls, and forms where validation opens an element that changes focus order. A simple two-field form may need one representative keyboard transition.

Clicking another control is a third option. It resembles a pointer user's action and supplies a real destination. It can also trigger that control's behavior, such as form submission, navigation, or another validation pass. Choose a harmless target when the requirement is only focus loss. If clicking Continue is the real journey, assert both field error and prevention of progression so the extra behavior is intentional.

Mobile and touch interfaces may not have a Tab path. Tapping another control can be the representative interaction, while direct blur remains a focused component contract. Do not describe a keyboard-only case as complete mobile coverage. The input method is part of what the test proves.

The near-miss is autofocus or focus restoration. A component may validate on blur and then immediately return focus to the invalid field. An assertion that only checks the error would pass, while not.toBeFocused() might fail even though returning focus is intentional. Decide the product's focus-management rule. For an inline validation message, forced focus restoration can trap users; for a modal error workflow, focus movement may be required.

Separate event delivery from asynchronous validation

An async validator adds a network boundary after focus loss. A username field may call an availability endpoint on blur, show a pending state, and eventually announce that the name is taken. A timeout at the final assertion can mean the blur handler never ran, the request never started, the response was wrong, or the UI ignored a correct response.

Register network routing and waits before the action. blur() can start the request immediately, so attaching waitForResponse() afterward creates a race. The test below controls the service response, waits for the matching exchange, and asserts the accessible product result.

import { expect, test } from '@playwright/test';

test('shows the service result after username blur', async ({ page }) => {
  await page.route('**/api/users/availability?*', async route => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ available: false }),
    });
  });
  await page.goto('/signup');

  const username = page.getByLabel('Username');
  await username.fill('existing-user');

  const responsePromise = page.waitForResponse(response => {
    const url = new URL(response.url());
    return url.pathname === '/api/users/availability'
      && response.request().method() === 'GET';
  });

  await username.blur();
  const response = await responsePromise;

  expect(response.status()).toBe(200);
  await expect(username).toHaveAttribute('aria-invalid', 'true');
  await expect(page.getByRole('alert')).toHaveText('That username is already taken');
  await expect(page.getByRole('button', { name: 'Create account' })).toBeDisabled();
});

The route pattern is registered before navigation because the application might preload related data. The response wait is registered immediately before blur so it owns the request under examination. If the route fulfills but the wait never resolves, inspect the actual method and URL rather than broadening the predicate to every response.

Debounce changes the chronology. Some forms wait briefly after input settles, then validate only after blur. Use the visible pending state or the matching request as the boundary, not waitForTimeout(). A fixed sleep can pass locally and fail under CI load. A web-first error assertion will wait for rendering, but the response evidence makes a missing request distinguishable from bad DOM handling.

Stale async responses are a second failure mode. A user can type one value, blur, refocus, change it, and blur again before the first response returns. The application should not apply the first result to the second value. Test that race with controlled response ordering at the service boundary. It is not the same scenario as a single invalid value, and it earns a separate case because it can mark a valid username as taken.

Server errors need their own product oracle. A 500 response should not usually label the username invalid. The form may show “Could not check availability” and permit retry while keeping Create account disabled. Do not reuse the “taken” assertion for every non-success response. That would turn infrastructure failure into a false business decision.

Browser-native validation can prevent the application request if the field fails a local pattern first. If no network call appears, check the field's value and validity before deciding the blur listener is broken. Product code may correctly short-circuit an impossible username. The test data must reach the branch it claims to exercise.

Record the event order before adding waits

When validation never appears, instrument the field in the browser and retain the sequence. Listen for focus, input, change, blur, and focusout, then run the same Playwright actions. This tells you whether focus was ever acquired, whether value input happened, and whether both focus-loss events were delivered.

import { expect, test } from '@playwright/test';

test('records the field event sequence for diagnosis', async ({ page }, testInfo) => {
  await page.goto('/profile');
  const displayName = page.getByLabel('Display name');

  await displayName.evaluate(element => {
    const diagnosticWindow = window as Window & {
      __fieldEvents?: Array<{ type: string; activeElement: string }>;
    };
    diagnosticWindow.__fieldEvents = [];

    for (const type of ['focus', 'input', 'change', 'blur', 'focusout']) {
      element.addEventListener(type, event => {
        diagnosticWindow.__fieldEvents?.push({
          type: event.type,
          activeElement: document.activeElement instanceof HTMLElement
            ? document.activeElement.id
            : '',
        });
      });
    }
  });

  await displayName.focus();
  await displayName.fill('QA Engineer');
  await displayName.blur();

  const events = await page.evaluate(() => {
    const diagnosticWindow = window as Window & {
      __fieldEvents?: Array<{ type: string; activeElement: string }>;
    };
    return diagnosticWindow.__fieldEvents ?? [];
  });

  await testInfo.attach('display-name-focus-events', {
    body: Buffer.from(JSON.stringify(events, null, 2)),
    contentType: 'application/json',
  });

  expect(events.map(event => event.type)).toEqual(
    expect.arrayContaining(['focus', 'input', 'blur', 'focusout']),
  );
});

The diagnostic assertion can fail if the input never focused, fill did not reach the expected element, or focus loss did not occur. It deliberately does not require change, because whether that event participates should come from the application contract and control behavior under test. The attachment retains the actual sequence for comparison.

Nothing happens before the listeners go on, and that is deliberate. An earlier draft of this test called blur() on the field first, which is exactly the no-op this article warns about: the element was never focused, so there was no focus-loss transition for anything to observe, and the call ran before the recorder existed anyway. It cost a step, produced no evidence, and taught a habit that quietly weakens real tests. Attach the listeners to a resting field, then perform focus, fill, and blur in the order a person would, so every event in the attachment came from the sequence under diagnosis.

If field-level blur appears but the form handler does not run, inspect delegation. A parent listener registered with the default bubbling phase will not receive native blur. A parent focusout listener should. Alternatively, a blur listener can use capture. Fix the application event registration; adding another Playwright action cannot make a non-bubbling event bubble.

If the input loses focus and validation state changes internally but the alert never appears, inspect rendering and accessibility wiring. The error may be present with display: none, lack an alert or description relationship, or be replaced during a rerender. Use the trace's DOM snapshot, not only its screenshot. A screenshot cannot show an element removed between actions or an incorrect ARIA reference.

If the locator resolves to the wrong field, the event log may still look perfect. Retain the element's label, id, and nearby form context when several inputs share a placeholder. Prefer getByLabel() or role and accessible name. A flawless blur on the search box does not test the profile form.

Trace Viewer shows locator.blur() as the action and provides before and after DOM snapshots. Confirm the locator, focused styles, error insertion, and any control that became disabled. Console and network panels then reveal exceptions or async work. Increase a timeout only after this evidence shows a correct but slow transition.

Test stale responses as a separate blur failure

Async field validation has a race that the ordinary taken-name case cannot reveal. A user enters one value and leaves the field, which starts request A. Before A returns, the user changes the value and leaves again, which starts request B. If B returns first and says the new value is valid, a late response from A must not mark the new value invalid.

Applications usually solve this in one of two ways. They abort the earlier request when the value changes, or they associate each response with the value or request generation that produced it and ignore stale results. Both are valid product designs. The user contract is the same: the displayed state must describe the current input, not whichever response arrived last.

Control the response order rather than relying on a slow shared service. The example below holds the old-name response, returns the new-name result, then releases the old result. It models an application that allows both requests to complete and ignores stale data. If your client cancels the first request, write the assertion around cancellation and final state instead.

import { expect, test } from '@playwright/test';

test('ignores an old blur response after the username changes', async ({ page }) => {
  let releaseOldResponse!: () => void;
  const oldResponseGate = new Promise<void>(resolve => {
    releaseOldResponse = resolve;
  });

  await page.route('**/api/users/availability?*', async route => {
    const url = new URL(route.request().url());
    const username = url.searchParams.get('username');

    if (username === 'old-name') {
      await oldResponseGate;
      await route.fulfill({
        status: 200,
        contentType: 'application/json',
        body: JSON.stringify({ available: false }),
      });
      return;
    }

    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ available: true }),
    });
  });

  await page.goto('/signup');
  const username = page.getByLabel('Username');

  const oldRequest = page.waitForRequest(request =>
    request.url().includes('username=old-name'),
  );
  await username.fill('old-name');
  await username.blur();
  await oldRequest;

  const currentResponse = page.waitForResponse(response =>
    response.url().includes('username=new-name'),
  );
  await username.fill('new-name');
  await username.blur();
  await currentResponse;

  await expect(username).toHaveValue('new-name');
  await expect(username).toHaveAttribute('aria-invalid', 'false');
  await expect(page.getByTestId('username-status')).toHaveText('Username is available');

  const oldResponse = page.waitForResponse(response =>
    response.url().includes('username=old-name'),
  );
  releaseOldResponse();
  await oldResponse;

  await expect(username).toHaveValue('new-name');
  await expect(username).toHaveAttribute('aria-invalid', 'false');
  await expect(page.getByTestId('username-status')).toHaveText('Username is available');
});

The final three assertions repeat the state after a different event boundary, not as summary padding. Before the gate opens they prove request B applied. After request A arrives they prove stale data did not overwrite that result. Remove the application's stale-response guard and the second state check can fail while the first still passes.

Use an exact query parser in production tests when encoding can vary. The example's wait predicate is readable for fixed ASCII fixture names, while the route handler correctly uses URL.searchParams. If values can contain spaces or punctuation, parse every wait URL rather than searching the raw string.

Retain both request URLs and response order in the trace or an attachment. A final “expected false, received true” message cannot show whether the wrong validator ran or a stale result won. Do not attach authorization headers or a real username. Synthetic values make the chronology useful without leaking account data.

Debounced validation can introduce a third request state: the first scheduled call may never start because the value changes during the debounce window. That is not the same as aborting an in-flight request. Decide whether the product promises cancellation before send, cancellation after send, or stale-result suppression, and put the test at the boundary it can actually observe.

The race test costs more than the simple blur case. It holds a route, performs two transitions, and depends on product concurrency behavior. Keep one focused case per validator implementation rather than duplicating it across every field. Unit-test a shared request-generation helper thoroughly, then retain a browser case that proves the helper is connected to the accessible form state.

Do not use a test retry to address this race. A retry changes network timing and may let request A finish first, hiding the defect. The controlled ordering is the fix for the test, while ignoring or cancelling stale work is the fix for the product. Preserve the first failed trace because its response order is the evidence.

Roll out the pattern narrowly and know when not to use it

Begin with fields whose requirements explicitly say “validate on leaving the field.” Add direct blur cases for their synchronous field contract. Add a smaller set of Tab cases for keyboard order and destination-sensitive behavior. Keep submission cases separate so a failure says whether field validation or form orchestration broke.

Use trace-on-first-retry in CI to preserve the failed transition without recording every passing form interaction. One retry can be useful for evidence, but a passing retry does not erase the original focus race.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  retries: process.env.CI ? 1 : 0,
  reporter: [['html', { open: 'never' }], ['line']],
  expect: { timeout: 7_000 },
  use: {
    ...devices['Desktop Chrome'],
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});

Do not create a helper that blurs every field after every fill. Some forms validate on input, change, submit, or a server response. An automatic helper hides the event contract and can trigger requests the user journey would not. Keep the focus-changing action visible in tests where it matters.

Direct blur is not the right choice when keyboard navigation is the requirement. Use Tab or Shift+Tab. It is not sufficient when pointer interaction outside the field closes an overlay or commits a selection; click the real target. It is not a substitute for form submission when validation deliberately waits until Submit.

Avoid asserting browser-native validation bubbles or browser chrome that Playwright does not expose as stable application DOM. Assert validity through a focused DOM check when native constraints are the contract, and assert your own accessible error UI separately. A screenshot of a browser tooltip is not a portable cross-engine oracle.

Be careful when the application removes a focused element. MDN notes browser differences around whether removal triggers blur. If conditional rendering replaces the input, test the user-facing replacement and cleanup across the supported engines rather than assuming a direct blur event always fires during removal. That is a browser lifecycle case, not ordinary field validation.

Migrate existing tests by finding synthetic dispatchEvent('blur') calls first. Add an assertion that the intended field is focused, replace the synthetic notification with locator.blur(), and keep the existing user-facing oracle. If the new test fails while the old one passed, inspect focusout delegation and active-element checks before changing the expectation. The failure is evidence that the synthetic test skipped product behavior.

Audit generic form helpers next. A helper that fills a record and blurs every input can start async checks in an order no user follows, especially when fields depend on each other. Replace it with journey-level actions for integrated tests and small field helpers only where the blur contract is shared. Keep request waits beside the field that initiates them so a reviewer can see the concurrency boundary.

Checkboxes, radios, comboboxes, and contenteditable controls may commit state through different interactions than a text field. Do not copy the email pattern mechanically. Identify whether the component listens to input, change, blur, selection, or an explicit Done action, then trigger the representative interaction. The event recorder can establish what the browser delivered, but the product requirement decides which event matters.

Focus traps need an integrated keyboard case. Calling blur() on a field inside a modal can temporarily leave no meaningful destination, while the trap may restore focus according to its own logic. Use Tab to prove focus remains inside the dialog and validation still appears. Keep a direct field case only if the validation handler itself needs isolated coverage.

An iframe creates a similar boundary. Focus can move within the embedded document or back to the parent page, and the intended next target belongs to that journey. Locate the field through its frame, perform the real navigation action, and assert the target in the correct document. A direct blur inside the frame cannot by itself prove cross-document focus management.

Autofill and password-manager behavior is another separate path. fill() gives deterministic text input; it does not prove a browser extension or native autofill UI will emit the same sequence in every engine. Cover the form's response to populated values with Playwright, and reserve actual autofill integration for a supported browser-specific test or manual check. Do not label a fill-and-blur case as password-manager coverage.

The trade-off is representativeness versus isolation. locator.blur() is fast and isolates one focus-loss handler, but it does not exercise tab order or a destination. Tab is closer to keyboard use but can fail when unrelated focusable content changes. Clicking a target models pointer use but may trigger extra product behavior. Choose the smallest interaction that still represents the requirement, and name the test so reviewers know which path it covers.

Blur is not a generic way to force a framework to flush state. If the product should update while typing, test the input behavior and fix the product or test wait. A hidden blur at the end of a helper can make stale UI appear correct only because the test performed an action the user did not need. Focus loss should be part of the requirement, not a generic synchronization trick.