web-preset.test.ts

Overview

The web-preset.test.ts file is a Jest test suite designed to verify the behavior of the web preset focus event initialization logic within the SWR library's internal configuration. It tests how the initFocus function reacts to browser environment events on the global window and document objects, specifically focusing on event listeners for focus and visibilitychange events.

The tests ensure that:

• The event listener triggers the provided callback function when the respective browser API is available.

• The listener does not trigger if the respective property (window or document) is missing or lacks the proper event API.

This file simulates browser event targets using a custom helper function and mocks global objects to create isolated test environments.

Detailed Explanation

Constants

• FOCUS_EVENT (string): The event name 'focus' used when testing the window object.

• VISIBILITYCHANGE_EVENT (string): The event name 'visibilitychange' used when testing the document object.

Function: createEventTarget()

Creates a mock event target object that mimics browser event targets by extending Node.js's EventEmitter with DOM-like addEventListener and removeEventListener methods.

Implementation Details

• Assigns addEventListener to EventEmitter.on.

• Assigns removeEventListener to EventEmitter.off.

• Returns a new EventEmitter instance with these methods.

Return Value

• target: An instance of EventEmitter that supports DOM-style event subscription.

Usage Example

const target = createEventTarget();
target.addEventListener('focus', () => console.log('Focused'));
target.emit('focus'); // Logs "Focused"

Function: runTests(propertyName: string)

Sets up and runs a Jest test suite for either the window or document global object, testing the behavior of initFocus in different environments.

Parameters

• propertyName ('window' | 'document'): Specifies which global property to test.

Behavior

• Defines the corresponding event name:

  • 'window' → 'focus'

  • 'document' → 'visibilitychange'

• Mocks global properties (window and document) with Jest spies to control their behavior.

• Resets modules before each test to ensure a clean state.

• Defines two test cases:

  1. Listener triggers when property has browser APIs

     • Mocks the targeted global property to an event target created by createEventTarget.

     • Verifies that the callback passed to initFocus is called when the event is emitted.

     • Verifies that after releasing the listener, the callback is no longer called.

  2. Listener does not trigger when property is falsy or lacks event APIs

     • Mocks the targeted global property as undefined or without event APIs.

     • Ensures the callback is not called when events are emitted.

     • Verifies no calls after releasing the listener.

Usage Example

runTests('window');   // Runs tests on the window object behavior
runTests('document'); // Runs tests on the document object behavior

Important Implementation Details

• Mocking Global Objects: The file uses jest.spyOn to override getters for global.window and global.document to simulate different environments.

• Dynamic Module Import: It dynamically imports initFocus from swr/_internal after setting up mocks to ensure initFocus uses the mocked environment.

• Event Simulation: Events are simulated by calling emit on the mocked event targets.

• EventEmitter Extension: By attaching addEventListener and removeEventListener to EventEmitter, the tests mimic DOM event listeners in a Node.js test environment.

Interaction with Other Parts of the System

• swr/_internal Module: This test file depends on initFocus from the internal configuration of the SWR library. initFocus is the function under test.

• Global Environment: It interacts indirectly with the global browser environment by mocking window and document.

• Test Runner (Jest): Relies on Jest's mocking and testing utilities (describe, it, beforeEach, afterEach, jest.spyOn, jest.fn) for execution and assertions.

Mermaid Diagram

flowchart TD
    A[runTests(propertyName)] -->|calls| B[createEventTarget()]
    A --> C[Mocks global[propertyName]]
    A --> D[Imports initFocus from swr/_internal]
    A --> E[Sets up Jest test suite]
    E --> F[Test: triggers listener if browser API exists]
    E --> G[Test: does not trigger listener if falsy API]
    B --> H[Extended EventEmitter]
    H --> I[addEventListener = on]
    H --> J[removeEventListener = off]
    F --> K[emit event triggers callback]
    G --> L[emit event does not trigger callback]

Summary

The web-preset.test.ts file is a focused test suite validating that SWR's initFocus correctly attaches and detaches event listeners to browser global objects (window and document). It ensures that focus and visibility change events trigger configured callbacks only when appropriate browser APIs are present. The approach uses Jest for mocking and Node.js's EventEmitter to simulate browser event targets in a controlled testing environment. This file is an essential part of the SWR library's testing strategy to maintain reliable focus event handling across different web contexts.