pytest_test_categories.timers

Real timer implementation for measuring test duration.

Classes

FakeTimer	Controllable timer adapter for testing.
WallTimer	Timer implementation using wall clock time.

Module Contents

class pytest_test_categories.timers.FakeTimer(/, **data)

Bases: pytest_test_categories.types.TestTimer

Controllable timer adapter for testing.

This is a test double that allows tests to control time explicitly rather than depending on the system clock. This eliminates flaky tests caused by timing variations and makes tests deterministic.

The FakeTimer follows hexagonal architecture principles: - Implements the TestTimer port (interface) - Provides controllable time advancement via advance() - Used in tests as a substitute for WallTimer - Enables testing behavior without implementation details

Example

>>> timer = FakeTimer()
>>> timer.start()
>>> timer.advance(0.5)  # Simulate 0.5 seconds
>>> timer.stop()
>>> assert timer.duration() == 0.5  # Exact, deterministic

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

advance(seconds)

Advance the simulated clock by the specified duration.

Parameters:

seconds (float) – Number of seconds to advance the clock.

Return type:

None

duration()

Calculate the simulated duration in seconds.

Returns:

The simulated duration in seconds.

Raises:

RuntimeError – If called before both start and stop.

Return type:

float

reset()

Reset the timer to initial state.

Return type:

None

start()

Start timing, recording the simulated current time.

Return type:

None

stop()

Stop timing, recording the simulated end time.

Return type:

None

current_time: float = None

end_time: float | None = None

start_time: float | None = None

class pytest_test_categories.timers.WallTimer(/, **data)

Bases: pytest_test_categories.types.TestTimer

Timer implementation using wall clock time.

This timer uses time.perf_counter() for high-resolution timing that is not affected by system clock updates.

This is the production adapter that should be used in real pytest runs.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

duration()

Calculate the duration in seconds.

Returns:

The duration in seconds with microsecond precision.

Raises:

RuntimeError – If called before both start and stop.

Return type:

float

reset()

Reset the timer to initial state.

Return type:

None

start()

Start timing, recording the current time.

Return type:

None

stop()

Stop timing, recording the end time.

Return type:

None

end_time: float | None = None

start_time: float | None = None