This tutorial assumes that you have filecheck
installed and have it
available in your PATH:
$ filecheck
/usr/local/bin/filecheck
<check-file> not specified
FileCheck can be seen as an improved version of grep
that makes automated
testing of the command-line tools easier. FileCheck reads an input and scans it
against a number of checks which can be substring or regex matches. If all check
matches are found, FileCheck
exits with an exit code 0
. When a check
without a match found, the FileCheck prints an error message and exits with an
exit code 1
.
The FileCheck program expects a path to a check file and a number of optional option arguments:
$ filecheck <check-file> [<options>]
Create new file hello-world.check
with the following contents:
CHECK: Hello world
Now we can provide a valid input to filecheck
which will match it against
the check file:
$ echo "Hello world" | filecheck hello-world.check
/usr/local/bin/filecheck
$ echo $?
0
Note: By convention, original LLVM’s FileCheck
always prints a full
path to its executable and FileCheck.py
follows this convention.
If we provide an invalid output we will see an error message:
$ echo "What is FileCheck" | filecheck hello-world.check
/usr/local/bin/filecheck
examples/hello-world.check:1:8: error: CHECK: expected string not found in input
CHECK: Hello world
^
<stdin>:1:1: note: scanning from here
What is FileCheck
^
$ echo $?
1
It is as easy as that!
FileCheck
also supports regex matching using special {{ }}
syntax:
Create a new file hello-world-regex.check
with the following contents:
CHECK: {{^Hello world$}}
Let’s run it with a valid input:
echo "Hello world" | filecheck examples/hello-world-regex.check
/usr/local/bin/filecheck
$ echo $?
0
With invalid input:
$ echo "Hello world Hello world" | filecheck examples/hello-world-regex.check
/usr/local/bin/filecheck
examples/hello-world-regex.check:1:8: error: CHECK: expected string not found in input
CHECK: {{^Hello world$}}
^
<stdin>:1:1: note: scanning from here
Hello world Hello world
^
$ echo $?
1
FileCheck is rarely used alone. The main use case for FileCheck is to serve as an string matching tool when it is used in a combination with LIT (LLVM Integrated Tester) and this is what our next tutorial is about. Don’t stop here and check it out right away: Tutorial: LIT and FileCheck.