{"id":8157,"library":"filecheck","title":"FileCheck","description":"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.","status":"active","version":"1.0.3","language":"en","source_language":"en","source_url":"https://github.com/AntonLydike/filecheck","tags":["testing","llvm","assertion","regex","development","text-processing"],"install":[{"cmd":"pip install filecheck","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The FileCheck class is exposed directly under the top-level 'filecheck' package.","wrong":"from filecheck.filecheck import FileCheck","symbol":"FileCheck","correct":"from filecheck import FileCheck"},{"note":"FileCheckException is exposed directly under the top-level 'filecheck' package for convenience.","wrong":"from filecheck.exceptions import FileCheckException","symbol":"FileCheckException","correct":"from filecheck import FileCheckException"}],"quickstart":{"code":"import filecheck\nfrom filecheck import FileCheck, FileCheckException\n\n# 1. Define the buffer (the text to be checked)\nmy_buffer = \"\"\"\nHello, World!\nThis is line 2.\n    Another line.\nFinal line.\n\"\"\"\n\n# 2. Define the FileCheck directives (the checks to run)\nmy_checks = \"\"\"\nCHECK: Hello, World!\nCHECK-NEXT: This is line 2.\nCHECK-NOT: hidden_text\nCHECK: Another line.\nCHECK-LABEL: Final line.\n\"\"\"\n\n# 3. Instantiate and run FileCheck\ntry:\n    checker = FileCheck(buffer=my_buffer, checks=my_checks)\n    checker.run()\n    print(\"FileCheck passed successfully!\")\nexcept FileCheckException as e:\n    print(f\"FileCheck failed: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n\n# Example with specific prefixes\nmy_checks_with_prefix = \"\"\"\nMYPREFIX: Hello, World!\nMYPREFIX-NEXT: This is line 2.\n\"\"\"\ntry:\n    checker_prefix = FileCheck(buffer=my_buffer, checks=my_checks_with_prefix, check_prefixes=[\"MYPREFIX\"])\n    checker_prefix.run()\n    print(\"FileCheck with custom prefix passed successfully!\")\nexcept FileCheckException as e:\n    print(f\"FileCheck with custom prefix failed: {e}\")","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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)`.","cause":"Attempting to instantiate `FileCheck` without providing the required `buffer` (the text to check) and `checks` (the check directives) arguments.","error":"TypeError: FileCheck.__init__ missing 2 required positional arguments: 'buffer' and 'checks'"},{"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.","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`.","error":"filecheck.exceptions.FileCheckException: No match found for CHECK: Some expected pattern"},{"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.","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.","error":"filecheck.exceptions.FileCheckException: No checks found for prefix 'CHECK'"},{"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.","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.","error":"ImportError: cannot import name 'FileCheck' from 'filecheck.filecheck' (or similar nested import error)"}]}