Freeze the Clock Before You Refactor: Characterization Tests for Impure Code

Characterization tests for impure code focus on freezing behavior, rather than desired behavior. These tests are crucial for dealing with unseeds like wall clock dependencies. To begin, inventory impurity through text search rather than profiling. This is faster and more precise. Count the hits and record the number in the commit message.

Each hit requires a strategy to pin it down. For process-local impurity like clock, RNG, UUIDs, and environment variables, in-process patching suffices. For external impurity such as network, database, and filesystem, recorded fixtures are necessary. The inventory doubles as a review checklist. Any unlisted impurity indicates a gap to watch for later.

Next, insert a boundary module without altering the original code. Create a thin module that substitutes calls to the impure functions with their frozen counterparts. Implement the following methods: now_date() returns a fixed date string; new_id() returns a fixed UUID; pick(seq) returns the first item from the sequence; and env(key, default) returns the environment variable value or a default.

Substitute these methods mechanically in the code. Run the code to ensure the substitution behaves identically to the original. Record the output as a golden file and assert against it in a test. This two-step process ensures the frozen behavior is verified before any changes are made. Finally, create a fixture to freeze the environment, ensuring the test environment remains consistent across runs.