Workflow:MaterializeInc Materialize Integration Test Development
| Knowledge Sources | |
|---|---|
| Domains | Testing, Docker_Compose, Integration_Testing |
| Last Updated | 2026-02-08 21:00 GMT |
Overview
End-to-end process for writing, configuring, and executing mzcompose-based integration tests that validate Materialize functionality against real services.
Description
This workflow describes how developers create integration tests using the mzcompose framework. Each test is defined as a composition consisting of a mzcompose.py file that declares Docker services (Materialize, Kafka, PostgreSQL, etc.) and workflow functions containing test logic. The Composition class manages service lifecycle, provides SQL execution helpers, and aggregates test results. Tests run in isolated Docker networks with Materialize-specific service definitions and system parameter configuration.
Usage
Execute this workflow when you need to test Materialize features that require interaction with external services (Kafka sources, PostgreSQL CDC, MySQL replication, sinks, etc.), or when validating end-to-end behavior that cannot be captured by unit tests or sqllogictest. This is the primary testing pattern for feature validation in the Materialize repository.
Execution Steps
Step 1: Define Composition Services
Create a mzcompose.py file in the test directory that imports service definitions from the mzcompose services module. Declare the required services (Materialize, Kafka, Schema Registry, PostgreSQL, etc.) and any custom service configurations. Services are defined as Python objects with Docker image references, port mappings, environment variables, and health checks.
Key considerations:
- Use standard service definitions from mzcompose.services for consistency
- Configure system parameters via the Materialized service constructor
- Each composition gets its own Docker network for isolation
- Service dependencies are managed through Docker Compose health checks
Step 2: Write Workflow Functions
Define one or more workflow functions that contain the test logic. Workflows are Python functions registered in the composition that execute SQL queries, verify outputs, manage service state, and assert correctness. The Composition object provides helper methods for SQL execution (c.sql(), c.testdrive()), service management (c.up(), c.kill()), and result tracking.
Key considerations:
- Workflows are named functions called via mzcompose run WORKFLOW_NAME
- Use c.sql() for direct SQL execution and c.testdrive() for testdrive scripts
- Multiple workflows in one composition allow testing different aspects of the same service setup
- WorkflowArgumentParser supports custom arguments for parameterized testing
Step 3: Configure Service Dependencies
Set up connections between Materialize and external services (Kafka brokers, databases, schema registries). Create sources, sinks, and connections within the workflow using SQL statements. Configure system parameters that enable required features.
Key considerations:
- Kafka connections require Schema Registry for Avro/Protobuf formats
- PostgreSQL CDC sources need logical replication configured on the source database
- SSH tunnel services are available for testing network-restricted configurations
- System parameters can enable experimental features needed for testing
Step 4: Execute Tests Locally
Run the composition using bin/mzcompose --find DIRECTORY run WORKFLOW_NAME. The mzcompose CLI discovers the composition, resolves Docker image dependencies through mzbuild, starts services in dependency order, and invokes the workflow function. Failed assertions cause non-zero exit codes.
Key considerations:
- Use --preserve-ports flag for debugging with fixed port assignments
- The --find flag locates compositions by directory name
- Docker images are built and cached via the mzbuild fingerprinting system
- Use bin/mzcompose --find DIRECTORY down to clean up services after testing
Step 5: Register in CI Pipeline
Add the new composition as a step in the Buildkite pipeline template. Specify the composition path, workflow name, and any resource requirements. The mkpipeline generator will include the step in CI runs and apply test trimming based on file dependencies.
Key considerations:
- Declare imported files accurately for test trimming to work correctly
- Group related test steps for parallel execution in the pipeline
- Consider timeout settings for long-running tests
- Test results must be output as JUnit XML for CI reporting