Principle:MaterializeInc Materialize Check Lifecycle
| Knowledge Sources | misc/python/materialize/checks/checks.py |
|---|---|
| Domains | Upgrade Testing, State-Transition Testing, Database Verification |
| Last Updated | 2026-02-08 |
Overview
State-transition testing verifies system correctness by driving components through an initialize → manipulate → validate lifecycle, ensuring that state survives operational changes such as version upgrades.
Description
The Check Lifecycle principle formalizes the idea that every testable property of a system can be expressed as a three-phase state machine:
- Initialize — establish a known baseline state in the system (create tables, insert data, define views).
- Manipulate — perform one or more mutations while the system is running, potentially across different versions or configurations.
- Validate — assert that the state created during initialization and manipulation is still correct after the operational change (upgrade, restart, failover).
This pattern is especially powerful for upgrade testing because the operational change (killing the old version, starting the new version) occurs between the phases. If validation passes after the upgrade, we have evidence that the upgrade preserved data integrity and behavioral correctness.
The principle enforces a strict contract:
- initialize() is called exactly once, before any disruptive event.
- manipulate() returns exactly two actions (phase 1 and phase 2), which may be interleaved with disruptive events.
- validate() may be called multiple times after the final disruptive event to confirm idempotency of the assertion logic.
By separating the three concerns into distinct methods, individual checks become composable: a single scenario can drive hundreds of independent checks through the same lifecycle without coupling them to each other.
Usage
Apply this principle whenever you need to verify that a stateful system retains correctness across an operational boundary. Common situations include:
- Version upgrades — state created on version N must survive migration to version N+1.
- Process restarts — in-memory or on-disk state must be recovered faithfully.
- Configuration changes — altering system variables must not corrupt previously created objects.
- Failover events — replica promotion or storage node replacement must preserve all committed data.
Theoretical Basis
The Check Lifecycle maps directly to the state-transition testing technique from software testing theory. In this model:
- The system under test has a finite set of observable states (e.g., table contents, view definitions, sink outputs).
- A transition is triggered by an external event (upgrade, restart, configuration change).
- The test oracle is defined by the relationship: if the system was in state S before the transition, it must be in state S' after the transition, where S' is deterministically derivable from S.
The three-phase design also aligns with the Arrange-Act-Assert (AAA) pattern from unit testing, extended to distributed systems:
| AAA Phase | Check Lifecycle Phase | Purpose |
|---|---|---|
| Arrange | initialize() |
Set up preconditions |
| Act | manipulate() + disruptive event |
Perform mutations and trigger the state transition |
| Assert | validate() |
Verify postconditions |
The requirement that manipulate() returns exactly two actions enables the framework to interleave disruptive events between manipulation phases, modeling scenarios where half of the mutations occur on the old version and half on the new version. This doubles the coverage surface compared to a single manipulation step.