Principle:MaterializeInc Materialize Workflow Function Authoring
| Knowledge Sources | misc/python/materialize/mzcompose/composition.py
|
|---|---|
| Domains | Integration Testing, Test Orchestration, SQL Verification |
| Last Updated | 2026-02-08 |
Overview
Composable test orchestration writes test workflows as Python functions that combine imperative service control with declarative SQL execution and testdrive assertion scripts.
Description
The Workflow Function Authoring principle defines how integration tests in Materialize are structured as Python functions that receive a Composition object and orchestrate a multi-step test scenario. Each workflow function is a top-level function in an mzcompose.py file whose name begins with workflow_. The Composition object provides methods for starting services, executing SQL, running testdrive scripts, and inspecting service state.
This principle combines two complementary paradigms:
- Imperative orchestration: The Python workflow function controls the sequence of operations -- starting services, waiting for health, injecting faults, restarting components, and checking results. This procedural control flow is necessary for testing scenarios that involve temporal ordering, such as "start Kafka, then start Materialized, then create a source, then kill Kafka, then verify the source enters an error state."
- Declarative assertion: Within each workflow step, SQL statements and testdrive scripts provide declarative specifications of expected state. The
Composition.sql()method executes SQL statements against Materialized viapsycopg, splitting multi-statement strings withsqlparse. TheComposition.testdrive()method runs testdrive scripts that combine SQL assertions with Kafka operations, schema registry interactions, and retry logic in a domain-specific language.
Workflows can also accept command-line arguments via WorkflowArgumentParser, which extends argparse.ArgumentParser to automatically consume the arguments passed to the workflow on the command line. This enables parameterized tests where the same workflow can be run with different configurations.
Usage
Use this principle when:
- Writing a new integration test that needs to orchestrate multiple services.
- Combining SQL execution with testdrive assertions in a single test scenario.
- Creating parameterized test workflows that accept command-line arguments.
- Building test scenarios that require multi-step orchestration with fault injection or service restarts between steps.
Theoretical Basis
The principle is grounded in the test orchestration pattern, where test logic is separated into three layers:
- Setup/Orchestration layer: The Python workflow function manages service lifecycle (start, stop, restart, override), forming the imperative scaffolding of the test. This corresponds to the "Arrange" phase of the Arrange-Act-Assert pattern, extended across multiple acts.
- Action layer: SQL statements executed via
Composition.sql()perform the "Act" phase -- creating sources, sinks, materialized views, inserting data, and triggering computations. Each SQL statement is printed to stdout for observability before execution.
- Assertion layer: Testdrive scripts executed via
Composition.testdrive()perform the "Assert" phase with built-in retry logic and rich comparison operators. Testdrive is a domain-specific language that supports waiting for eventually-consistent results, which is essential for testing a streaming database where results may not be immediately available.
The WorkflowArgumentParser adds a parameterized testing dimension, allowing a single workflow definition to serve multiple CI steps or developer scenarios. It wraps argparse.ArgumentParser and automatically uses the arguments passed to the workflow, making the programmatic interface identical to standard argument parsing in Python.
The combination of imperative Python control flow with declarative SQL and testdrive scripts creates a testing framework that is both expressive (it can model complex distributed scenarios) and readable (each step is a clear Python statement or a clear SQL/testdrive block).