Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
11.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Timer.test.tsx
 * @input Uses React Testing Library, fake clocks, React Profiler, and Timer
 * @output Verifies formats, adaptive cadence, render isolation, typography, resources, semantics, and passthrough
 */

import {Profiler, StrictMode, createRef} from 'react';
import {renderToString} from 'react-dom/server';
import {act, fireEvent, render, screen} from '@testing-library/react';
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {Timer} from './Timer';

describe('Timer', () => {
  beforeEach(() => {
    vi.useFakeTimers();
    vi.setSystemTime(new Date('2026-09-22T00:00:00Z'));
  });

  afterEach(() => {
    vi.useRealTimers();
    vi.restoreAllMocks();
  });

  it('renders deterministic zero-duration markup for each standard format', () => {
    const {rerender} = render(<Timer data-testid="timer" />);
    const timer = screen.getByTestId('timer');

    expect(timer.tagName).toBe('TIME');
    expect(timer).toHaveTextContent('0s');
    expect(timer).toHaveAttribute('datetime', 'PT0S');

    rerender(<Timer format="clock" data-testid="timer" />);
    expect(timer).toHaveTextContent('0:00');
    expect(timer).toHaveAttribute('datetime', 'PT0S');
  });

  it('keeps server markup independent of the clock', () => {
    const firstMarkup = renderToString(<Timer startTime={0} />);
    const firstClockMarkup = renderToString(
      <Timer startTime={0} format="clock" />,
    );

    vi.setSystemTime(new Date('2030-01-01T00:00:00Z'));
    const secondMarkup = renderToString(<Timer startTime={0} />);
    const secondClockMarkup = renderToString(
      <Timer startTime={0} format="clock" />,
    );

    expect(firstMarkup).toBe(secondMarkup);
    expect(firstMarkup).toContain('dateTime="PT0S"');
    expect(firstMarkup).toContain('>0s</time>');
    expect(firstClockMarkup).toBe(secondClockMarkup);
    expect(firstClockMarkup).toContain('>0:00</time>');
  });

  it('derives elapsed time from the clock without accumulating callback count', () => {
    let scheduledTick: (() => void) | undefined;
    vi.spyOn(globalThis, 'setTimeout').mockImplementation(callback => {
      scheduledTick = callback as () => void;
      return 1 as unknown as ReturnType<typeof setTimeout>;
    });

    render(<Timer data-testid="timer" />);

    vi.setSystemTime(new Date('2026-09-22T00:00:08.750Z'));
    act(() => {
      scheduledTick?.();
    });

    const timer = screen.getByTestId('timer');
    expect(timer).toHaveTextContent('8s');
    expect(timer).toHaveAttribute('datetime', 'PT8S');
  });

  it('formats elapsed durations across seconds, minutes, and hours', () => {
    const now = Date.now();
    const {rerender} = render(
      <Timer startTime={now - 34_000} data-testid="timer" />,
    );
    const timer = screen.getByTestId('timer');
    expect(timer).toHaveTextContent('34s');
    expect(timer).toHaveAttribute('datetime', 'PT34S');

    rerender(<Timer startTime={now - 128_000} data-testid="timer" />);
    expect(timer).toHaveTextContent('2m 08s');
    expect(timer).toHaveAttribute('datetime', 'PT128S');

    rerender(<Timer startTime={now - 3_753_000} data-testid="timer" />);
    expect(timer).toHaveTextContent('1h 02m');
    expect(timer).toHaveAttribute('datetime', 'PT3720S');
  });

  it('formats clock durations across minutes and hours', () => {
    const now = Date.now();
    const {rerender} = render(
      <Timer format="clock" startTime={now - 128_000} data-testid="timer" />,
    );
    const timer = screen.getByTestId('timer');
    expect(timer).toHaveTextContent('2:08');
    expect(timer).toHaveAttribute('datetime', 'PT128S');

    rerender(
      <Timer format="clock" startTime={now - 3_753_000} data-testid="timer" />,
    );
    expect(timer).toHaveTextContent('1:02:33');
    expect(timer).toHaveAttribute('datetime', 'PT3753S');
  });

  it('uses second cadence until elapsed format reaches an hour, then minute cadence', () => {
    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
    const startTime = Date.now() - 3_599_000;
    render(<Timer startTime={startTime} data-testid="timer" />);
    const timer = screen.getByTestId('timer');

    expect(timer).toHaveTextContent('59m 59s');
    expect(setTimeoutSpy).toHaveBeenLastCalledWith(expect.any(Function), 1000);

    act(() => {
      vi.advanceTimersByTime(1000);
    });
    expect(timer).toHaveTextContent('1h 00m');
    expect(timer).toHaveAttribute('datetime', 'PT3600S');
    expect(setTimeoutSpy).toHaveBeenLastCalledWith(
      expect.any(Function),
      60_000,
    );
  });

  it('keeps clock format on second cadence after an hour', () => {
    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
    render(
      <Timer
        format="clock"
        startTime={Date.now() - 3_723_000}
        data-testid="timer"
      />,
    );

    expect(screen.getByTestId('timer')).toHaveTextContent('1:02:03');
    expect(setTimeoutSpy).toHaveBeenLastCalledWith(expect.any(Function), 1000);
  });

  it('counts from a finite caller-provided start time', () => {
    const now = Date.now();
    render(<Timer startTime={now - 12_400} data-testid="timer" />);

    expect(screen.getByTestId('timer')).toHaveTextContent('12s');
    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT12S');
  });

  it('returns to the original mount origin when startTime is removed', () => {
    const mountedAt = Date.now();
    const {rerender} = render(
      <Timer startTime={mountedAt - 10_000} data-testid="timer" />,
    );

    act(() => {
      vi.advanceTimersByTime(2000);
    });
    rerender(<Timer data-testid="timer" />);

    expect(screen.getByTestId('timer')).toHaveTextContent('2s');
    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT2S');
  });

  it('falls back to mount time for a non-finite start time', () => {
    render(<Timer startTime={Number.NaN} data-testid="timer" />);

    act(() => {
      vi.advanceTimersByTime(2000);
    });

    expect(screen.getByTestId('timer')).toHaveTextContent('2s');
  });

  it('clamps a future origin to zero and schedules its first visible change directly', () => {
    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
    render(<Timer startTime={Date.now() + 5000} data-testid="timer" />);

    expect(screen.getByTestId('timer')).toHaveTextContent('0s');
    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT0S');
    expect(setTimeoutSpy).toHaveBeenLastCalledWith(expect.any(Function), 6000);

    act(() => {
      vi.advanceTimersByTime(6000);
    });

    expect(screen.getByTestId('timer')).toHaveTextContent('1s');
    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT1S');
  });

  it('updates format without remounting or losing current elapsed time', () => {
    const now = Date.now();
    const {rerender} = render(
      <Timer startTime={now - 3_723_000} data-testid="timer" />,
    );
    const timer = screen.getByTestId('timer');
    expect(timer).toHaveTextContent('1h 02m');
    expect(timer).toHaveAttribute('datetime', 'PT3720S');

    rerender(
      <Timer format="clock" startTime={now - 3_723_000} data-testid="timer" />,
    );
    expect(screen.getByTestId('timer')).toBe(timer);
    expect(timer).toHaveTextContent('1:02:03');
    expect(timer).toHaveAttribute('datetime', 'PT3723S');
  });

  it('does not schedule React update commits as time advances', () => {
    const onRender = vi.fn();
    render(
      <Profiler id="timer" onRender={onRender}>
        <Timer />
      </Profiler>,
    );
    expect(onRender).toHaveBeenCalledTimes(1);

    act(() => {
      vi.advanceTimersByTime(5000);
    });

    expect(onRender).toHaveBeenCalledTimes(1);
  });

  it('owns one timer resource and cleans up under StrictMode replay', () => {
    const setTimeoutSpy = vi.spyOn(window, 'setTimeout');
    const clearTimeoutSpy = vi.spyOn(window, 'clearTimeout');
    const {unmount} = render(
      <StrictMode>
        <Timer />
      </StrictMode>,
    );

    expect(setTimeoutSpy).toHaveBeenCalledTimes(2);
    expect(clearTimeoutSpy).toHaveBeenCalledTimes(1);

    unmount();
    expect(clearTimeoutSpy).toHaveBeenCalledTimes(2);
  });

  it('matches Timestamp typography defaults and accepts overrides', () => {
    const {rerender} = render(<Timer data-testid="timer" />);
    const timer = screen.getByTestId('timer');
    const text = timer.parentElement;

    expect(text).toHaveClass('astryx-text');
    expect(text).toHaveClass('astryx-timer');
    expect(text).toHaveAttribute('data-type', 'supporting');
    expect(text).toHaveAttribute('data-color', 'secondary');

    rerender(
      <Timer
        type="body"
        size="lg"
        color="primary"
        weight="bold"
        data-testid="timer"
      />,
    );
    expect(text).toHaveAttribute('data-type', 'body');
    expect(text).toHaveAttribute('data-size', 'lg');
    expect(text).toHaveAttribute('data-color', 'primary');
  });

  it('forwards its time ref and preserves Timestamp-style root styling and time props', () => {
    const ref = createRef<HTMLTimeElement>();
    const onClick = vi.fn();
    render(
      <Timer
        ref={ref}
        id="elapsed"
        className="custom-class"
        style={{color: 'rgb(1, 2, 3)'}}
        aria-live="polite"
        onClick={onClick}
        data-testid="timer"
      />,
    );

    const timer = screen.getByTestId('timer');
    const text = timer.parentElement;
    expect(ref.current).toBe(timer);
    expect(timer).toHaveAttribute('id', 'elapsed');
    expect(text).toHaveClass('astryx-timer');
    expect(text).toHaveClass('custom-class');
    expect(text).toHaveStyle({color: 'rgb(1, 2, 3)'});
    expect(timer).toHaveAttribute('aria-live', 'polite');

    fireEvent.click(timer);
    expect(onClick).toHaveBeenCalledTimes(1);
  });

  it('does not add live-region semantics by default', () => {
    render(<Timer data-testid="timer" />);
    const timer = screen.getByTestId('timer');

    expect(timer).not.toHaveAttribute('aria-live');
    expect(timer).not.toHaveAttribute('role');
  });
});

describe('Timer hardening guards', () => {
  beforeEach(() => {
    vi.useFakeTimers();
    vi.setSystemTime(new Date('2026-09-22T00:00:00Z'));
  });

  afterEach(() => {
    vi.useRealTimers();
    vi.restoreAllMocks();
  });

  it('caps the wait for a distant future origin at the 32-bit timeout ceiling', () => {
    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
    render(
      <Timer
        startTime={Date.now() + 30 * 24 * 60 * 60 * 1000}
        data-testid="timer"
      />,
    );

    // A raw startTime - now delay would exceed the 32-bit setTimeout range and
    // fire immediately in some browsers; the ceiling keeps the wake scheduled.
    expect(setTimeoutSpy).toHaveBeenLastCalledWith(
      expect.any(Function),
      2_147_483_647,
    );
  });

  it('coerces an unknown format to elapsed', () => {
    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
    const now = Date.now();
    const {rerender} = render(
      <Timer
        format={'stopwatch' as never}
        startTime={now - 3_723_000}
        data-testid="timer"
      />,
    );

    // Past one hour, only the elapsed format moves to minute cadence: the
    // next wake is the 57 s left in the minute, not one second.
    expect(screen.getByTestId('timer')).toHaveTextContent('1h 02m');
    expect(setTimeoutSpy).toHaveBeenLastCalledWith(
      expect.any(Function),
      57_000,
    );

    rerender(
      <Timer format="clock" startTime={now - 3_723_000} data-testid="timer" />,
    );
    expect(screen.getByTestId('timer')).toHaveTextContent('1:02:03');
  });
});