LLVM Integrated Tester (lit)

18.1.8 · active · verified Sat Apr 11

lit (LLVM Integrated Tester) is a portable command-line tool for executing LLVM and Clang style test suites, summarizing their results, and providing indication of failures. It is designed to be lightweight and flexible, supporting parallel test execution and various test formats. The current version is 18.1.8 and is actively maintained as part of the LLVM project.

Warnings

gotcha lit is primarily a command-line testing tool. While written in Python, its main usage involves running the `lit` executable and configuring test suites via `lit.cfg.py` or `lit.site.cfg.py` files, rather than through direct Python API imports for general application logic. The Python files define test execution logic, not library functions to be called.
Fix: Focus on command-line invocation and Python configuration files (`lit.cfg.py`) for defining test behavior, rather than looking for a traditional Python API to import and call.
gotcha The `lit` command expects a `lit.cfg.py` or `lit.site.cfg.py` file to be present in the root of each test suite or discovered by searching upwards from the input path. Without these configuration files, `lit` cannot properly discover or execute tests.
Fix: Ensure that your test directory hierarchy includes the necessary `lit.cfg.py` (or `lit.site.cfg.py`) files to define test suite parameters like `config.test_format` and `config.suffixes`.
gotcha The `lit` tool, especially for certain test formats, often relies on external LLVM utilities like `FileCheck` and `not`. If these are not available in the system's PATH, or explicitly configured in `lit.cfg.py`, tests that use them will fail.
Fix: Ensure that required LLVM tools (like `FileCheck` and `not`) are installed and accessible in your system's PATH, or specify their full paths using `config.substitutions` or directly in `config.test_format` (e.g., `not_tool='/usr/bin/not'`) within your `lit.cfg.py` file.

Install

pip install lit Install via pip

Imports

lit_config
```
This is a global object implicitly available within lit.cfg.py / lit.site.cfg.py files.
```
lit is primarily a command-line tool that executes Python configuration files (lit.cfg.py). Direct import statements of 'lit' as a Python library for programmatic API calls are uncommon in application code. Configuration relies on predefined global objects like `lit_config` and `config` within these specific config files.
config
```
This is a global object implicitly available within lit.cfg.py / lit.site.cfg.py files.
```
Similar to `lit_config`, the `config` object is exposed globally within `lit`'s Python configuration files (`lit.cfg.py`), allowing users to define test suite behavior without explicit Python imports from the 'lit' package itself.

Quickstart

This quickstart demonstrates how to set up a basic `lit` test suite. It involves creating a `lit.cfg.py` configuration file that `lit` uses to understand how to find and run tests, and a simple test file with `RUN` and `CHECK` directives. `lit` is then invoked from the command line against the test directory.

# 1. Create a test directory and a lit configuration file:
# my_project/
# ├── lit.cfg.py
# └── tests/
#     └── my_test.txt

# --- lit.cfg.py ---
# This file is executed by lit to configure the test suite.
# Define standard test formats.
import lit.formats

config.name = 'MyProject'
config.test_format = lit.formats.ShTest(not_tool='/usr/bin/not')
config.suffixes = ['.txt']

# Add an optional path to tools if they are not in PATH
# config.substitutions = [('%my_tool', '/path/to/my_tool')]

# --- tests/my_test.txt ---
# RUN: echo "Hello, lit!" | FileCheck %s
# CHECK: Hello, lit!

# --- Run lit from the project root ---
# In your terminal:
# cd my_project
# lit tests/

view raw JSON →