initial-render.test.ts

Overview

initial-render.test.ts is an end-to-end (E2E) test file designed to validate the rendering behaviors of React applications that utilize the SWR data fetching library under complex asynchronous conditions. Specifically, it tests scenarios involving React Suspense integration, preload mechanisms, retry capabilities on fetch failures, mutation-triggered retries, and server component serialization of cache keys.

These tests are implemented using Playwright to simulate real user interactions in a browser context, navigating to example pages, triggering retry actions, and checking for expected UI states. The file ensures the robustness and correctness of SWR hooks when combined with React's Suspense, error boundaries, and mutation APIs across different React routing paradigms.

Detailed Explanation of Tests

Test Suite: rendering

The entire file is wrapped in a test.describe block labeled "rendering", grouping related rendering behavior tests.

1. Test: suspense with preload

test('suspense with preload', async ({ page }) => {
  await page.goto('./suspense-after-preload', { waitUntil: 'commit' })
  await page.getByRole('button', { name: 'preload' }).click()
  await expect(page.getByText('suspense-after-preload')).toBeVisible()
})

• Purpose:
  Validates that data preloading works correctly with React Suspense, ensuring that suspense fallbacks are replaced promptly by loaded content after preloading.

• Parameters:

  • page: Playwright's Page object representing the browser tab.

• Flow:

  1. Navigates to the ./suspense-after-preload page with a commit-level wait.

  2. Clicks the button labeled "preload".

  3. Asserts that the text "suspense-after-preload" becomes visible, confirming successful preload and render.

• Usage Context:
  This test checks that users see the intended UI without unnecessary delays after preloading data.

2. Test: should be able to retry in suspense with react 19 (app router)

test('should be able to retry in suspense with react 19 (app router)', async ({ page }) => {
  await page.goto('./suspense-retry', { waitUntil: 'commit' })
  await expect(page.getByText('Something went wrong')).toBeVisible()
  await page.getByRole('button', { name: 'retry' }).click()
  await expect(page.getByText('data: SWR suspense retry works')).toBeVisible()
})

• Purpose:
  Tests that the retry mechanism works correctly within a Suspense boundary in React 19 using the App Router.

• Flow:

  1. Loads the ./suspense-retry page.

  2. Checks that an error message "Something went wrong" is visible, simulating an initial fetch failure.

  3. Clicks the "retry" button.

  4. Verifies that the successful data text "data: SWR suspense retry works" is displayed after retry.

• Significance:
  Ensures users can recover from errors by manually triggering retries and that Suspense boundaries handle these retries properly in the App Router setup.

3. Test: should be able to retry in suspense with react 19 (pages router)

test('should be able to retry in suspense with react 19 (pages router)', async ({ page }) => {
  await page.goto('./suspense-retry-19', { waitUntil: 'commit' })
  await expect(page.getByText('Something went wrong')).toBeVisible()
  await page.getByRole('button', { name: 'retry' }).click()
  await expect(page.getByText('data: SWR suspense retry works')).toBeVisible()
})

• Purpose:
  Similar to the previous test but verifies retry functionality when using the traditional Pages Router in React 19.

• Difference:
  Uses the page ./suspense-retry-19 instead of ./suspense-retry to reflect the Pages Router context.

• Importance:
  Confirms consistent retry behavior across different routing paradigms in React.

4. Test: should be able to retry in suspense with mutate

test('should be able to retry in suspense with mutate', async ({ page }) => {
  await page.goto('./suspense-retry-mutate', { waitUntil: 'commit' })
  await expect(page.getByText('Something went wrong')).toBeVisible()
  await page.getByRole('button', { name: 'retry' }).click()
  await expect(page.getByText('data: SWR suspense retry works')).toBeVisible()
})

• Purpose:
  Tests retry mechanics that are triggered via the mutate function of SWR rather than a direct re-fetch.

• Flow:

  1. Navigates to ./suspense-retry-mutate.

  2. Checks for an error message.

  3. Clicks the retry button.

  4. Verifies the successful data load.

• Significance:
  Validates that manual mutation (cache updates or revalidation) can effectively trigger retries within Suspense workflows.

5. Test: should be able to use 'unstable_serialize' in server component

test('should be able to use `unstable_serialize` in server component', async ({ page }) => {
  await page.goto('./react-server-entry', { waitUntil: 'commit' })
  await expect(page.getByText('unstable_serialize: useSWR')).toBeVisible()
  await expect(
    page.getByText('infinite_unstable_serialize: $inf$useSWRInfinite')
  ).toBeVisible()
})

• Purpose:
  Ensures that SWR's internal serialization utility unstable_serialize works correctly in server components, supporting server-side rendering (SSR) and hydration.

• Details:
  Checks the visibility of serialized cache keys rendered on the page.

• Importance:
  Verifies SSR compatibility and correct hydration of SWR cache keys, critical for server-side React apps.

Important Implementation Details

• Testing Framework:
  Uses Playwright's testing API (test, expect) to perform browser automation and assertions.

• Page Navigation:
  Each test navigates to a relative URL (e.g., ./suspense-retry) with waitUntil: 'commit' to ensure the navigation is sufficiently settled before further actions.

• Role-based Queries:
  Uses semantic queries like getByRole('button', { name: 'retry' }) for robust element selection aligned with accessibility practices.

• Text Visibility Checks:
  Verifies UI states by asserting the visibility of specific text nodes, representing success or error messages.

• Retries and Mutations:
  Tests simulate user-triggered retry flows via buttons that internally call SWR's retry or mutate APIs, reflecting real user recovery from data fetching failures.

Interaction with Other System Components

• Example Application Pages:
  The tests interact with example pages (./suspense-after-preload, ./suspense-retry, etc.) that implement SWR hooks with Suspense, retry logic, and server components.

• SWR Library:
  Exercises the SWR core functionalities—especially Suspense integration, manual retry via mutate, and serialization utilities.

• React Framework:
  Validates behavior across React routing strategies (App Router vs. Pages Router) and server-side rendering.

• Playwright Test Runner:
  Automates browser-based testing, simulating user behavior and verifying UI state changes.

Usage Example

To run these tests, execute the Playwright test runner in the project root:

npx playwright test e2e/test/initial-render.test.ts

This will open headless browsers, run all defined tests, and report results indicating whether rendering and retry flows behave as expected.

Visual Diagram

The following flowchart illustrates the typical workflow covered by the tests in this file, focusing on data fetching, error handling, retry, and rendering flows within Suspense boundaries:

flowchart TD
  A[User Navigates to Page] --> B{Initial Data Fetch}
  B -->|Success| C[Render Data UI]
  B -->|Fail| D[Show Error Boundary]
  D --> E[Display Retry Button]
  E -->|User Clicks Retry| F[Trigger SWR mutate]
  F --> B
  C --> G[User Interacts with UI]
  G --> H[Optional Additional Fetches or Mutations]

• Explanation:

  1. User opens a page triggering an initial data fetch (B).

  2. On success, data is rendered (C).

  3. On failure, an error boundary renders an error UI (D).

  4. A retry button is displayed (E).

  5. User clicks retry, triggering SWR's mutate function (F), which re-initiates the fetch (B).

  6. Subsequent interactions may trigger further fetches or mutations (G & H).

Summary

• initial-render.test.ts is a Playwright-driven E2E test suite verifying critical rendering behaviors involving Suspense, retries, preload, and server serialization in React applications using SWR.

• It covers multiple scenarios across React 19 routing paradigms and validates user recovery flows from data fetching errors.

• The tests simulate real user interactions and assert UI correctness, ensuring robustness of SWR integrations in complex async rendering workflows.

• This file plays a vital role in maintaining end-to-end reliability and user experience quality across the SWR example applications and core library features.

End of Documentation for initial-render.test.ts