守门员的眼睛：LLVM/MLIR 自动化测试神器 FileCheck 深度洗劫

在手写了各种硬核的编译器 Pass 之后，每一个编译器架构师都必须面对一个极其残酷的工程现实：你如何确保你手写的 C++ 优化代码，真的吐出了正确的中间表示（IR）？更重要的是，你如何确保几个月后别人修改代码时，没有暗中破坏你的优化成果（即防回归测试）？

在传统的软件工程中，我们通常习惯编写单元测试（Unit Test），比对函数的最终执行输出。但在编译器领域，仅仅比对最终结果是不够的。我们需要验证的是中间过程：比如确认csePass 真的把冗余的乘法删掉了，或者canonicalize真的把乘以 2 优化成了自身相加。

为了给庞大的 IR 变动提供一套极致轻量、高效且直观的断言机制，LLVM 生态祭出了它的工业级杀手锏——FileCheck。

1. 什么是 FileCheck？

FileCheck 并不是 MLIR 内部的某一段 C++ 代码或方言，而是一个独立的、由 LLVM 核心库提供的命令行测试工具。

它的核心工作原理非常纯粹：

1. 它接收一个纯文本文件（通常是你的.mlir测试源文件）作为断言规则库。
2. 它接收标准输入（Standard Input）传过来的文本（通常是mlir-opt运行完你的手写 Pass 后吐出来的最终 IR 文本）。
3. 它拿着断言规则，以严格的行扫描和模式匹配机制去审查输入的 IR 文本。如果完全吻合，则测试通过（退出码 0）；一旦有一行对不上或者顺序错了，直接当场爆出详细的报错信息并熔断测试（退出码非 0）。

2. 工业标准的 Pipeline：FileCheck 是如何协同工作的？

在真实的 MLIR 项目中，FileCheck 通常和Lit（LLVM 集成测试工具）深度绑定。一个标准的测试文件通常会以一行特殊的注释（RUN 注释）作为文件开头：

// RUN: mlir-opt %s --cse | FileCheck %s

这行命令的宏大编排如下：

• %s代表当前的.mlir文件本身。
• mlir-opt %s --cse：读取当前文件，运行全局的 CSE 优化 Pass，并将优化后的新 IR 通过管道（|）源源不断地吐出来。
• FileCheck %s：守在管道的终点，读取当前文件里以// CHECK:开头的特殊注释断言，逐行审查mlir-opt吐过来的代码。

3. FileCheck 的四大硬核断言匹配家族

掌握 FileCheck 的核心，在于精通它的断言前缀。以下这四个前缀几乎统治了 99% 的编译器测试用例：

1.// CHECK:（顺序存在断言）

指示 FileCheck 接下来的输入文本里，必须按顺序出现这一行。

2.// CHECK-NEXT:（严格紧邻断言）

指示被匹配的这一行，必须无缝紧贴着上一个 CHECK 匹配到的行出现，中间绝对不能夹杂任何其他无关的代码行。这对于验证底层汇编指令的精确排布至关重要。

3.// CHECK-NOT:（绝对不存在断言）

这是编译器做优化测试时最爱的神兵利器。它指示在当前的作用域范围内，绝对不能出现特定的代码。通常用来验证某个冗余算子被你的 Pass 物理抹除。

4.// CHECK-LABEL:（作用域锚点断言）

由于一个.mlir文件里通常包含几十个不同的函数（func.func），如果前面的函数测试失败了，不应该影响后面函数的独立审查。CHECK-LABEL用来将整个文件强制切割成一个个独立的测试孤岛，大幅提升报错定位的效率。

4. 实战拆解：用 FileCheck 审判你的手写 Pass

为了让你彻底看清它的运作轨迹，我们用前文手写的“消除 Identity 恒等算子”的 Pass 作为一个标准靶场。

完整的测试用例文件（test_identity_elimination.mlir）

// 1. 编排流水线：运行我们的自定义优化 Pass，并把结果喂给 FileCheck // RUN: mlir-opt %s --my-custom-optimize-pass | FileCheck %s // 2. 设立函数级主锚点 // CHECK-LABEL: func.func @test_cleanup func.func @test_cleanup(%arg0: f32) -> f32 { // 3. 验证优化：我们的 Pass 应该把 identity 彻底扬了 // 因此，优化后的 IR 中绝对不应该再出现 "tosa.identity" 这一行！ // CHECK-NOT: tosa.identity %0 = tosa.identity(%arg0) : f32 // 4. 验证数据流重定向：原本消费 %0 的 return 指令，现在必须直接消费原始输入 %arg0 // 这里利用了 FileCheck 的 [[...]] 变量捕获黑科技（后面会讲） // CHECK: func.return %arg0 : f32 func.return %0 : f32 }

审判流程的物理发生：

当 Lit 驱动起这一行测试时，mlir-opt挥舞着你的 C++ 手术刀，把中间的tosa.identity咔嚓切掉，并将最后的func.return %0改写为func.return %arg0。

随后，FileCheck 进场。它发现tosa.identity真的消失了（满足CHECK-NOT），且随后顺利看到了func.return %arg0（满足CHECK），于是绿灯放行，宣告你的手写 Pass 具备完美的工业鲁棒性。

5. 进阶黑科技：FileCheck 变量捕获机制

在 MLIR 的多级转换中，每次运行 Pass 自动生成的 SSA 变量名（如%0,%1,%b2）是非常不稳定且难以预测的。如果你在测试里硬编码CHECK: arith.addi %0, %1，往往Pass稍作改动测试就会全面崩溃。

FileCheck 引入了**动态变量捕获机制[[变量名:正则表达式]]**，允许你在匹配的同时，动态锁死一个 SSA 变量：

// 原始 IR 片段 // %res = arith.mulf %a, %b : f32 // %final = arith.addi %res, %c : f32 // 完美的 FileCheck 动态捕获书写： // 1. 匹配到 mulf 后，动态把当前自动生成的变量名捕获进自定义变量 RES 里面 // CHECK: %[[RES:[a-zA-Z0-9_]+]] = arith.mulf // 2. 下一行断言直接引用这个捕获到的 RES 变量，锁定上下游严格的数据流拓扑引用关系 // CHECK-NEXT: arith.addi %[[RES]],

这种机制解耦了具体的变量命名，只死死卡住“数据从哪里流入、流向哪里”的图拓扑本质，使得你的编译器测试用例具备极高韧性的同时，还能做到绝对精准。