PaperTiger.Clock (PaperTiger v0.7.0)

View Source

Manages time for PaperTiger. Three modes:

  • :real - Uses System.system_time(:second)
  • :accelerated - Real time × multiplier (1 real sec = N PaperTiger secs)
  • :manual - Frozen time, advance via PaperTiger.advance_time/1

Examples

# Real time (production/PR apps)
config :paper_tiger, time_mode: :real

# Accelerated time (integration tests)
config :paper_tiger,
  time_mode: :accelerated,
  time_multiplier: 100  # 1 real second = 100 Stripe seconds

# Manual time (unit tests)
config :paper_tiger, time_mode: :manual

# Advance time in tests
PaperTiger.advance_time(days: 30)
PaperTiger.advance_time(seconds: 3600)

Summary

Types

mode()
state()

Functions

advance(seconds)

Advances time by the given amount (manual mode only).

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_mode()

Returns the current clock mode.

now()

Returns the current PaperTiger time as Unix timestamp (seconds).

reset()

Resets the clock to current system time.

set_mode(mode, opts \\ [])

Changes the time mode dynamically.

start_link(opts \\ [])

Starts the Clock GenServer.

Types

mode()

@type mode() :: :real | :accelerated | :manual

state()

@type state() :: %{
  mode: mode(),
  multiplier: pos_integer(),
  offset: integer(),
  started_at: integer()
}

Functions

advance(seconds)

@spec advance(integer() | keyword()) :: :ok

Advances time by the given amount (manual mode only).

Examples

PaperTiger.Clock.advance(seconds: 3600)
PaperTiger.Clock.advance(days: 30)
PaperTiger.Clock.advance(86400)  # 1 day in seconds

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_mode()

@spec get_mode() :: mode()

Returns the current clock mode.

Examples

PaperTiger.Clock.get_mode()
#=> :real

now()

@spec now() :: integer()

Returns the current PaperTiger time as Unix timestamp (seconds).

Behaves differently based on time mode:

  • :real - Returns actual system time
  • :accelerated - Returns system time × multiplier
  • :manual - Returns frozen time + manual offset

reset()

@spec reset() :: :ok

Resets the clock to current system time.

Useful for cleaning up between tests.

set_mode(mode, opts \\ [])

@spec set_mode(
  mode(),
  keyword()
) :: :ok

Changes the time mode dynamically.

This is useful for tests that need to switch between modes.

Options

  • :multiplier - Time multiplier for accelerated mode (default: 1)
  • :timestamp - Starting timestamp for manual mode (default: current time)

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the Clock GenServer.