FileCheck

1.0.3 · active · verified Thu Apr 16

FileCheck is a Python-native clone of LLVM's FileCheck tool, designed for flexible and powerful pattern matching in text. It allows developers to define a sequence of regular expression-based checks against a source buffer, enabling robust testing of compiler outputs, log files, or any structured text. The current version is 1.0.3, and it maintains an active release cadence with regular bug fixes and new features.

Common errors

```
TypeError: FileCheck.__init__ missing 2 required positional arguments: 'buffer' and 'checks'
```
cause Attempting to instantiate `FileCheck` without providing the required `buffer` (the text to check) and `checks` (the check directives) arguments.

fix Ensure you pass both `buffer` (a string) and `checks` (a string containing FileCheck directives) as keyword arguments to the `FileCheck` constructor, e.g., `FileCheck(buffer=my_text, checks=my_directives)`.
```
filecheck.exceptions.FileCheckException: No match found for CHECK: Some expected pattern
```
cause The `buffer` content does not contain a substring matching the regular expression defined in your `CHECK` directive, or the match occurs out of the expected order for `CHECK-NEXT`.

fix Carefully compare your `buffer` string with the regex pattern in the `CHECK` directive. Ensure correct order for sequential checks (`CHECK-NEXT`, `CHECK-LABEL`). Use `print(buffer)` and `print(checks)` to debug.
```
filecheck.exceptions.FileCheckException: No checks found for prefix 'CHECK'
```
cause The `checks` string provided to `FileCheck` does not contain any lines starting with the specified prefixes (default is 'CHECK'). This can happen if prefixes are misspelled or not present.

fix Verify that your `checks` string contains directives like `CHECK: ...` or `MYPREFIX: ...` if you specified `check_prefixes=['MYPREFIX']`. Ensure the prefix exactly matches what's in your checks.
```
ImportError: cannot import name 'FileCheck' from 'filecheck.filecheck' (or similar nested import error)
```
cause You are trying to import `FileCheck` from a nested module path like `filecheck.filecheck` or `filecheck.exceptions`, but the main classes are exposed directly at the top level.

fix Change your import statement to `from filecheck import FileCheck` (and `from filecheck import FileCheckException` if needed). The library simplifies imports for its main components.

Warnings

breaking In version 1.0.0, the behavior for empty captures changed from throwing an error to emitting a warning. If your code previously relied on an error being raised for empty captures, it will now only receive a warning.
Fix: Review existing FileCheck directives and update your test logic if you relied on errors for empty captures. Consider adding explicit checks for captured values if their emptiness is critical.
gotcha Version 1.0.2 fixed an issue where non-strict whitespace matching sometimes incorrectly handled newlines. Older versions might have had unintended matches due to this looser interpretation.
Fix: Upgrade to version 1.0.2 or newer to ensure correct and strict whitespace matching behavior. Review any existing checks that might have subtly relied on the previous, less strict behavior.
gotcha The `--match-full-lines` flag was broken in versions prior to 1.0.2. Using this flag might not have produced the expected results for full-line matching.
Fix: Upgrade to version 1.0.2 or newer to ensure the `--match-full-lines` flag (or its programmatic equivalent `match_full_lines=True`) functions as intended.
gotcha The project re-licensed to Apache 2.0 in version 1.0.1. While not a code-breaking change, it's a significant licensing update for users embedding `filecheck` in their projects.
Fix: Review your project's licensing compatibility if you are using versions older than 1.0.1 and plan to upgrade, or if your project has specific licensing requirements.

Install

pip install filecheck Install latest version

Imports

FileCheck
wrong:
```
from filecheck.filecheck import FileCheck
```
correct:
```
from filecheck import FileCheck
```
The FileCheck class is exposed directly under the top-level 'filecheck' package.
FileCheckException
wrong:
```
from filecheck.exceptions import FileCheckException
```
correct:
```
from filecheck import FileCheckException
```
FileCheckException is exposed directly under the top-level 'filecheck' package for convenience.

Quickstart

This quickstart demonstrates how to use the `filecheck` library to validate text against a series of `CHECK` directives. It covers basic `CHECK`, `CHECK-NEXT`, `CHECK-NOT`, and `CHECK-LABEL` directives, error handling, and using custom `check_prefixes`.

import filecheck
from filecheck import FileCheck, FileCheckException

# 1. Define the buffer (the text to be checked)
my_buffer = """
Hello, World!
This is line 2.
    Another line.
Final line.
"""

# 2. Define the FileCheck directives (the checks to run)
my_checks = """
CHECK: Hello, World!
CHECK-NEXT: This is line 2.
CHECK-NOT: hidden_text
CHECK: Another line.
CHECK-LABEL: Final line.
"""

# 3. Instantiate and run FileCheck
try:
    checker = FileCheck(buffer=my_buffer, checks=my_checks)
    checker.run()
    print("FileCheck passed successfully!")
except FileCheckException as e:
    print(f"FileCheck failed: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

# Example with specific prefixes
my_checks_with_prefix = """
MYPREFIX: Hello, World!
MYPREFIX-NEXT: This is line 2.
"""
try:
    checker_prefix = FileCheck(buffer=my_buffer, checks=my_checks_with_prefix, check_prefixes=["MYPREFIX"])
    checker_prefix.run()
    print("FileCheck with custom prefix passed successfully!")
except FileCheckException as e:
    print(f"FileCheck with custom prefix failed: {e}")

view raw JSON →