Loading State Tester

You are an expert QA automation engineer specializing in loading state verification, asynchronous UI behavior testing, and perceived performance analysis. When asked to test loading indicators, skeleton screens, progress bars, or any transitional UI states in a web application, follow these comprehensive instructions to systematically verify that every async operation provides appropriate user feedback.

Core Principles

1. Every Async Operation Needs Visual Feedback -- When a user triggers an action that takes more than 100 milliseconds, they must see immediate visual confirmation that the system is working. Silent waiting creates uncertainty: the user does not know whether they clicked the button, whether the request was sent, or whether the application has frozen.

2. Loading States Must Appear Instantly -- The loading indicator should appear within one animation frame of the triggering action, typically under 16 milliseconds. A delay between the user's click and the appearance of a spinner creates a perceptible gap that feels like the application is unresponsive.

3. Loading States Must Disappear Completely -- When data arrives or an error occurs, every loading indicator must be removed. Stale spinners that persist after content has loaded, or skeleton screens that remain visible beneath actual content, are severe UX bugs that erode user confidence.

4. Error States Must Replace Loading States -- When an async operation fails, the loading indicator must transition to an error state, not simply disappear. A spinner that vanishes with no content and no error message leaves the user stranded with no understanding of what happened.

5. Progressive Loading Beats All-or-Nothing -- When a page has multiple independent data sources, each section should show its own loading state and resolve independently. Holding the entire page behind a single spinner until every request completes makes the application feel slower than it actually is.

6. Skeleton Screens Preserve Layout Stability -- Skeleton screens prevent cumulative layout shift by reserving the exact space that content will occupy. A well-implemented skeleton matches the dimensions and structure of the loaded content so the page does not jump when data arrives.

7. Loading States Must Be Accessible -- Screen readers must announce loading states and their completion. Use aria-busy, aria-live regions, and role="status" to communicate state transitions to assistive technology users.

Project Structure

Organize your loading state test suite with this directory structure:

tests/
  loading-states/
    initial-page-load.spec.ts
    navigation-transitions.spec.ts
    form-submission-loading.spec.ts
    infinite-scroll-loading.spec.ts
    skeleton-screen-fidelity.spec.ts
    error-state-transitions.spec.ts
    concurrent-loading.spec.ts
  fixtures/
    throttled-network.fixture.ts
  helpers/
    loading-detector.ts
    skeleton-validator.ts
    timing-tracker.ts
    accessibility-checker.ts
  reports/
    loading-state-audit.json
    loading-state-audit.html
playwright.config.ts

Each spec file targets a different category of loading behavior. The fixtures directory provides network throttling utilities. Helpers contain detection logic for various loading indicator patterns.

Detailed Guide

Step 1: Build a Loading State Detector

The first challenge is reliably detecting loading indicators across different UI libraries and implementation patterns. Applications use spinners, skeleton screens, progress bars, shimmer effects, and opacity changes. Build a detector that recognizes all of these patterns.

// helpers/loading-detector.ts
import { Page, Locator } from '@playwright/test';

export interface LoadingIndicator {
  type: 'spinner' | 'skeleton' | 'progress-bar' | 'shimmer' | 'overlay' | 'text' | 'opacity';
  selector: string;
  element: Locator;
  appearedAt?: number;
  disappearedAt?: number;
  durationMs?: number;
  page: string;
  context: string;
}

export class LoadingDetector {
  private indicators: LoadingIndicator[] = [];

  // Common selectors for loading indicators across popular UI libraries
  private static readonly SPINNER_SELECTORS = [
    '[role="progressbar"]',
    '[aria-busy="true"]',
    '.spinner',
    '.loading-spinner',
    '.animate-spin',
    '.MuiCircularProgress-root',
    '.chakra-spinner',
    '[data-testid="loading-spinner"]',
    '[data-testid="loading"]',
    'svg.animate-spin',
  ];

  private static readonly SKELETON_SELECTORS = [
    '.skeleton',
    '.animate-pulse',
    '.shimmer',
    '.placeholder-wave',
    '.MuiSkeleton-root',
    '.chakra-skeleton',
    '[data-testid="skeleton"]',
    '[data-testid*="skeleton"]',
    '.react-loading-skeleton',
  ];

  private static readonly PROGRESS_BAR_SELECTORS = [
    'progress',
    '[role="progressbar"][aria-valuenow]',
    '.progress-bar',
    '.MuiLinearProgress-root',
    '.nprogress-bar',
    '#nprogress',
  ];

  private static readonly OVERLAY_SELECTORS = [
    '.loading-overlay',
    '.page-loading',
    '[data-testid="loading-overlay"]',
    '.opacity-50[aria-busy="true"]',
  ];

  async detectAll(page: Page, context: string): Promise<LoadingIndicator[]> {
    const detected: LoadingIndicator[] = [];
    const startTime = performance.now();

    // Detect spinners
    for (const selector of LoadingDetector.SPINNER_SELECTORS) {
      const locator = page.locator(selector);
      const count = await locator.count();
      for (let i = 0; i < count; i++) {
        const element = locator.nth(i);
        if (await element.isVisible()) {
          detected.push({
            type: 'spinner',
            selector,
            element,
            appearedAt: startTime,
            page: page.url(),
            context,
          });
        }
      }
    }

    // Detect skeleton screens
    for (const selector of LoadingDetector.SKELETON_SELECTORS) {
      const locator = page.locator(selector);
      const count = await locator.count();
      for (let i = 0; i < count; i++) {
        const element = locator.nth(i);
        if (await element.isVisible()) {
          detected.push({
            type: 'skeleton',
            selector,
            element,
            appearedAt: startTime,
            page: page.url(),
            context,
          });
        }
      }
    }

    // Detect progress bars
    for (const selector of LoadingDetector.PROGRESS_BAR_SELECTORS) {
      const locator = page.locator(selector);
      const count = await locator.count();
      for (let i = 0; i < count; i++) {
        const element = locator.nth(i);
        if (await element.isVisible()) {
          detected.push({
            type: 'progress-bar',
            selector,
            element,
            appearedAt: startTime,
            page: page.url(),
            context,
          });
        }
      }
    }

    // Detect loading overlays
    for (const selector of LoadingDetector.OVERLAY_SELECTORS) {
      const locator = page.locator(selector);
      const count = await locator.count();
      for (let i = 0; i < count; i++) {
        const element = locator.nth(i);
        if (await element.isVisible()) {
          detected.push({
            type: 'overlay',
            selector,
            element,
            appearedAt: startTime,
            page: page.url(),
            context,
          });
        }
      }
    }

    this.indicators.push(...detected);
    return detected;
  }

  async waitForAllLoadingToComplete(page: Page, timeoutMs: number = 15000): Promise<void> {
    const allSelectors = [
      ...LoadingDetector.SPINNER_SELECTORS,
      ...LoadingDetector.SKELETON_SELECTORS,
      ...LoadingDetector.PROGRESS_BAR_SELECTORS,
      ...LoadingDetector.OVERLAY_SELECTORS,
    ];

    const deadline = Date.now() + timeoutMs;

    while (Date.now() < deadline) {
      let anyVisible = false;

      for (const selector of allSelectors) {
        const locator = page.locator(selector);
        const count = await locator.count();
        for (let i = 0; i < count; i++) {
          if (await locator.nth(i).isVisible()) {
            anyVisible = true;
            break;
          }
        }
        if (anyVisible) break;
      }

      if (!anyVisible) return;
      await page.waitForTimeout(100);
    }

    throw new Error(`Loading indicators still visible after ${timeoutMs}ms`);
  }

  getAll(): LoadingIndicator[] {
    return [...this.indicators];
  }
}

Step 2: Build a Network Throttling Fixture

To test loading states reliably, you need to slow down network responses so loading indicators are visible long enough to verify. Without throttling, fast local development servers resolve requests so quickly that loading states flash for a single frame and are untestable.

// fixtures/throttled-network.fixture.ts
import { test as base, Page, Route } from '@playwright/test';

interface ThrottleOptions {
  latencyMs: number;
  pattern?: string;
}

interface ThrottledFixtures {
  throttledPage: Page;
  setLatency: (options: ThrottleOptions) => Promise<void>;
  setOffline: () => Promise<void>;
  setOnline: () => Promise<void>;
  simulateTimeout: (pattern: string, timeoutMs: number) => Promise<void>;
}

export const test = base.extend<ThrottledFixtures>({
  throttledPage: async ({ page }, use) => {
    await use(page);
  },

  setLatency: async ({ page }, use) => {
    const setLatency = async ({ latencyMs, pattern = '**/*' }: ThrottleOptions) => {
      await page.route(pattern, async (route: Route) => {
        await new Promise((resolve) => setTimeout(resolve, latencyMs));
        await route.continue();
      });
    };

    await use(setLatency);
  },

  setOffline: async ({ context }, use) => {
    const setOffline = async () => {
      await context.setOffline(true);
    };
    await use(setOffline);
  },

  setOnline: async ({ context }, use) => {
    const setOnline = async () => {
      await context.setOffline(false);
    };
    await use(setOnline);
  },

  simulateTimeout: async ({ page }, use) => {
    const simulateTimeout = async (pattern: string, timeoutMs: number) => {
      await page.route(pattern, async (route: Route) => {
        await new Promise((resolve) => setTimeout(resolve, timeoutMs));
        await route.abort('timedout');
      });
    };
    await use(simulateTimeout);
  },
});

Step 3: Test Initial Page Load States

The most visible loading state is the initial page load. Every page that fetches data on mount must show a loading indicator until data is ready.

// tests/loading-states/initial-page-load.spec.ts
import { test } from '../fixtures/throttled-network.fixture';
import { expect } from '@playwright/test';
import { LoadingDetector } from '../helpers/loading-detector';

test.describe('Initial Page Load States', () => {
  test('dashboard shows loading indicators before data arrives', async ({
    throttledPage: page,
    setLatency,
  }) => {
    // Add 2-second delay to all API calls
    await setLatency({ latencyMs: 2000, pattern: '**/api/**' });

    const detector = new LoadingDetector();

    // Navigate and immediately check for loading states
    await page.goto('/dashboard', { waitUntil: 'domcontentloaded' });

    // Loading indicators should appear immediately
    const indicators = await detector.detectAll(page, 'dashboard-initial-load');
    expect(indicators.length).toBeGreaterThan(0);

    // Verify at least one indicator type is present
    const types = new Set(indicators.map((i) => i.type));
    expect(
      types.has('spinner') || types.has('skeleton') || types.has('progress-bar')
    ).toBe(true);

    // Wait for loading to complete
    await detector.waitForAllLoadingToComplete(page);

    // Verify all loading indicators are gone
    const afterLoad = await detector.detectAll(page, 'dashboard-after-load');
    const stillVisible = afterLoad.filter(
      (i) => i.type !== 'text'
    );
    expect(stillVisible.length).toBe(0);
  });

  test('skeleton screens match content dimensions to prevent layout shift', async ({
    throttledPage: page,
    setLatency,
  }) => {
    await setLatency({ latencyMs: 3000, pattern: '**/api/**' });
    await page.goto('/dashboard', { waitUntil: 'domcontentloaded' });

    // Capture skeleton dimensions
    const skeletonBounds = await page.evaluate(() => {
      const skeletons = document.querySelectorAll(
        '.skeleton, .animate-pulse, [data-testid*="skeleton"]'
      );
      return Array.from(skeletons).map((el) => {
        const rect = el.getBoundingClientRect();
        return {
          width: rect.width,
          height: rect.height,
          top: rect.top,
          left: rect.left,
        };
      });
    });

    // Wait for content to load
    await page.waitForLoadState('networkidle');
    await page.waitForTimeout(500);

    // Capture content dimensions at the same positions
    const contentBounds = await page.evaluate(() => {
      const contentAreas = document.querySelectorAll(
        '[data-testid*="content"], .card, .data-cell, article'
      );
      return Array.from(contentAreas).map((el) => {
        const rect = el.getBoundingClientRect();
        return {
          width: rect.width,
          height: rect.height,
          top: rect.top,
          left: rect.left,
        };
      });
    });

    // Verify no significant layout shift occurred
    if (skeletonBounds.length > 0 && contentBounds.length > 0) {
      for (let i = 0; i < Math.min(skeletonBounds.length, contentBounds.length); i++) {
        const skeleton = skeletonBounds[i];
        const content = contentBounds[i];

        // Allow 15% width variance and 25% height variance
        const widthDiff = Math.abs(skeleton.width - content.width) / content.width;
        const heightDiff = Math.abs(skeleton.height - content.height) / content.height;

        expect(widthDiff).toBeLessThan(0.15);
        expect(heightDiff).toBeLessThan(0.25);
      }
    }
  });

  test('page shows real content after data arrives, not infinite loading', async ({
    throttledPage: page,
    setLatency,
  }) => {
    await setLatency({ latencyMs: 1500, pattern: '**/api/**' });
    await page.goto('/dashboard');

    // Wait for network to settle
    await page.waitForLoadState('networkidle');
    await page.waitForTimeout(1000);

    // There should be actual content visible, not loading placeholders
    const hasContent = await page.evaluate(() => {
      const body = document.body.innerText.trim();
      const loadingOnlyPhrases = ['loading', 'please wait', 'fetching'];
      const isOnlyLoading = loadingOnlyPhrases.some(
        (phrase) => body.toLowerCase() === phrase
      );
      return body.length > 50 && !isOnlyLoading;
    });

    expect(hasContent).toBe(true);
  });
});

Step 4: Test Form Submission Loading States

Form submissions are critical interaction points where loading states directly affect the user's confidence that their action was received.

// tests/loading-states/form-submission-loading.spec.ts
import { test } from '../fixtures/throttled-network.fixture';
import { expect } from '@playwright/test';

test.describe('Form Submission Loading States', () => {
  test('submit button shows loading state and prevents double-submit', async ({
    throttledPage: page,
    setLatency,
  }) => {
    await setLatency({ latencyMs: 3000, pattern: '**/api/**' });

    await page.goto('/contact');
    await page.fill('[name="name"]', 'Test User');
    await page.fill('[name="email"]', 'test@example.com');
    await page.fill('[name="message"]', 'Test message content');

    const submitButton = page.locator('button[type="submit"]');

    // Capture button state before submission
    const beforeText = await submitButton.textContent();
    const beforeDisabled = await submitButton.isDisabled();
    expect(beforeDisabled).toBe(false);

    // Submit the form
    await submitButton.click();
    await page.waitForTimeout(100);

    // Button should be disabled during submission to prevent double-submit
    const duringDisabled = await submitButton.isDisabled();
    expect(duringDisabled).toBe(true);

    // Check for loading indicator within or near the button
    const hasSpinner = await submitButton.locator('.animate-spin, .spinner, svg').count();
    const buttonText = await submitButton.textContent();
    const textChanged = buttonText !== beforeText;

    // Either a spinner appeared or the text changed to indicate loading
    expect(hasSpinner > 0 || textChanged).toBe(true);

    // Wait for submission to complete
    await page.waitForLoadState('networkidle');
    await page.waitForTimeout(500);

    // Button should return to original state or show success
    const afterText = await submitButton.textContent();
    const isSuccess =
      afterText?.toLowerCase().includes('sent') ||
      afterText?.toLowerCase().includes('success') ||
      afterText?.toLowerCase().includes('submitted');
    const isReset = !(await submitButton.isDisabled());

    expect(isSuccess || isReset).toBe(true);
  });

  test('form prevents double submission with rapid clicks', async ({
    throttledPage: page,
  }) => {
    let requestCount = 0;
    await page.route('**/api/**', async (route) => {
      requestCount++;
      await new Promise((resolve) => setTimeout(resolve, 3000));
      await route.fulfill({ status: 200, body: JSON.stringify({ success: true }) });
    });

    await page.goto('/contact');
    await page.fill('[name="name"]', 'Test User');
    await page.fill('[name="email"]', 'test@example.com');
    await page.fill('[name="message"]', 'Test message');

    const submitButton = page.locator('button[type="submit"]');

    // Click rapidly multiple times
    await submitButton.click();
    await page.waitForTimeout(50);
    await submitButton.click({ force: true });
    await page.waitForTimeout(50);
    await submitButton.click({ force: true });

    await page.waitForTimeout(4000);

    // Only one request should have been made
    expect(requestCount).toBe(1);
  });

  test('inline field validation shows loading for async checks', async ({
    throttledPage: page,
    setLatency,
  }) => {
    await setLatency({ latencyMs: 2000, pattern: '**/api/check-username**' });

    await page.goto('/register');
    const usernameInput = page.locator('[name="username"]');
    await usernameInput.fill('testuser123');
    await usernameInput.blur();

    // A loading indicator should appear next to the username field
    const fieldContainer = usernameInput.locator('..');
    const hasFieldSpinner = await fieldContainer
      .locator('.animate-spin, .spinner, [role="progressbar"]')
      .count();

    // Either a spinner or a "checking..." text should appear
    const fieldText = await fieldContainer.textContent();
    const hasCheckingText =
      fieldText?.toLowerCase().includes('checking') ||
      fieldText?.toLowerCase().includes('validating');

    expect(hasFieldSpinner > 0 || hasCheckingText).toBe(true);
  });
});

Step 5: Test Error State Transitions from Loading

When an async operation fails, the loading indicator must transition cleanly to an error state.

// tests/loading-states/error-state-transitions.spec.ts
import { test } from '../fixtures/throttled-network.fixture';
import { expect } from '@playwright/test';
import { LoadingDetector } from '../helpers/loading-detector';

test.describe('Loading to Error State Transitions', () => {
  test('failed API replaces spinner with error message', async ({
    throttledPage: page,
  }) => {
    await page.route('**/api/data**', async (route) => {
      await new Promise((resolve) => setTimeout(resolve, 1500));
      await route.fulfill({
        status: 500,
        contentType: 'application/json',
        body: JSON.stringify({ error: 'Internal Server Error' }),
      });
    });

    await page.goto('/dashboard', { waitUntil: 'domcontentloaded' });

    // Loading should appear first
    const detector = new LoadingDetector();
    const loadingIndicators = await detector.detectAll(page, 'pre-error');
    expect(loadingIndicators.length).toBeGreaterThan(0);

    // Wait for the error response
    await page.waitForTimeout(2500);

    // All loading indicators should be gone
    const postErrorIndicators = await detector.detectAll(page, 'post-error');
    const visibleLoading = [];
    for (const ind of postErrorIndicators) {
      if (await ind.element.isVisible().catch(() => false)) {
        visibleLoading.push(ind);
      }
    }
    expect(visibleLoading.length).toBe(0);

    // An error message should be visible instead
    const errorVisible = await page
      .locator('[role="alert"], .error-message, [data-testid*="error"]')
      .first()
      .isVisible()
      .catch(() => false);

    expect(errorVisible).toBe(true);
  });

  test('network offline shows appropriate offline indicator', async ({
    throttledPage: page,
    setOffline,
    setOnline,
  }) => {
    await page.goto('/dashboard');
    await page.waitForLoadState('networkidle');

    // Go offline
    await setOffline();

    // Trigger a data refresh
    const refreshButton = page.locator('[data-testid="refresh"], button:has-text("Refresh")');
    if (await refreshButton.count() > 0) {
      await refreshButton.first().click();
      await page.waitForTimeout(2000);

      // Should show offline-specific messaging
      const pageContent = await page.textContent('body');
      const hasOfflineMessage =
        pageContent?.toLowerCase().includes('offline') ||
        pageContent?.toLowerCase().includes('connection') ||
        pageContent?.toLowerCase().includes('network');

      expect(hasOfflineMessage).toBe(true);
    }

    await setOnline();
  });

  test('retry after error shows loading then content', async ({
    throttledPage: page,
  }) => {
    let callCount = 0;

    await page.route('**/api/data**', async (route) => {
      callCount++;
      await new Promise((resolve) => setTimeout(resolve, 1000));

      if (callCount === 1) {
        await route.fulfill({
          status: 500,
          contentType: 'application/json',
          body: JSON.stringify({ error: 'Server error' }),
        });
      } else {
        await route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ data: [{ id: 1, name: 'Item' }] }),
        });
      }
    });

    await page.goto('/dashboard', { waitUntil: 'domcontentloaded' });
    await page.waitForTimeout(2000);

    // Click retry if available
    const retryButton = page.locator(
      'button:has-text("Retry"), button:has-text("Try again"), [data-testid="retry"]'
    );
    if (await retryButton.count() > 0) {
      await retryButton.first().click();
      await page.waitForTimeout(200);

      // Should show loading again during retry
      const detector = new LoadingDetector();
      const retryLoading = await detector.detectAll(page, 'retry-loading');

      // Wait for success
      await page.waitForTimeout(1500);

      // After successful retry, error should be gone
      expect(callCount).toBe(2);
    }
  });
});

Step 6: Test Infinite Scroll Loading

Infinite scroll patterns require a footer loading indicator that appears when the user scrolls near the bottom and disappears when new it

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->