用途:Platform Checks 是 Materialize 的测试框架,采用"写一次、到处运行"思路,用单个测试在多种场景(重启、升级等)下验证某个功能。用户创建、修改或调试 platform check 时可使用本技能。
核心概念:Check 是一个 Python 类,通过 testdrive 片段测试一个功能;Scenario 是检查运行所处的上下文(如重启、升级);Action 是场景中的单个步骤(如停止容器)。所有检查位于 misc/python/materialize/checks/all_checks/,该目录的 init.py 会自动发现每个 .py 文件,因此新增文件即完成注册。
Check 结构:Check 类需继承 Check 并实现三个方法,每个返回包裹 testdrive 片段字符串的 Testdrive 对象。initialize() 在开始时运行一次,用于建表、插入种子数据、搭建对象;manipulate() 必须返回恰好 2 个 Testdrive 片段,分别在重启/升级阶段后运行,可插入更多数据、ALTER 对象或创建派生对象;validate() 在所有 initialize 和 manipulate 步骤后运行以验证一切存活,且可能被多次调用,必须幂等,其中创建的对象须为 TEMPORARY 或显式删除。
执行顺序:StartMz → initialize() → [重启/升级] → manipulate(phase=0) → [重启/升级] → manipulate(phase=1) → [重启/升级] → validate()。两个 manipulate 阶段始终运行。
装饰器与版本控制:用 @disabled(ignore_reason="...") 禁用检查;若检查向 Kafka/Postgres 摄取非 UPSERT 数据(重放 manipulate 会重复数据),用 @externally_idempotent(False) 标注;仅存在于特定版本的功能可重写 _can_run 进行版本门控;语法随版本变化的行可用 [version>=VVMMPP] 或 [version<VVMMPP] 前缀(如 v0.92.0 对应 9200)。
编写建议:所有对象名加唯一前缀以免与其他检查冲突;manipulate() 返回恰好 2 个元素;validate() 保持幂等;在 manipulate 中而不仅是 initialize 中创建对象,以验证重启/升级后 DDL 可用;在旧、新基础对象上都创建派生对象;覆盖完整 SQL 语法;每个阶段都摄取数据;所有 testdrive 字符串使用 dedent()。
Check 辅助方法:self.base_version(测试起始版本)、self.current_version(当前运行版本)、self._kafka_broker()(返回 testdrive 的 broker 连接串)、self._default_cluster()(返回 "quickstart")、self.rng(带种子的确定性随机实例)。
运行方式:bin/mzcompose --find platform-checks run default --scenario=RestartEntireMz --check=MyFeature;无重启调试可用 --scenario=NoRestartNoUpgrade;默认运行全部检查。
调试 CI 失败:在日志顶部附近找到场景名,在错误前找到失败检查,可本地复现,或用 --scenario=NoRestartNoUpgrade 判断失败是否与重启/升级相关。
限制:本资料未提供该技能的收费、价格、平台支持范围等信息。