crosshair-tool

What it is and what it does

CrossHair is a symbolic execution and theorem-proving tool for Python that bridges testing and type systems. You annotate functions with type hints and optional contracts (preconditions, postconditions, invariants), and CrossHair explores execution paths using an SMT solver to find inputs that violate those contracts—essentially automated counterexample generation. It works by repeatedly calling your functions with symbolic inputs, tracking constraints, and asking the solver whether any path can violate your specifications.

Beyond contract checking, CrossHair can generate unit tests by exploring code paths and detecting behavioral differences between function implementations. It integrates with Hypothesis as an optional backend and offers IDE plugins for VS Code and PyCharm. The tool targets developers who want stronger correctness guarantees than traditional testing alone, particularly for functions with clear specifications. Runtime dependencies include z3-solver (the SMT engine), typing-inspect, pygls (for language server protocol), and typeshed-client.

Use it for:

• Find edge cases and counterexamples in functions with type annotations and contracts before they reach production
• Generate test cases automatically by exploring symbolic execution paths through your code
• Verify that refactored or optimized functions behave identically to their original implementations
• Use as a Hypothesis backend for property-based testing with symbolic reasoning
• Catch off-by-one errors, null-pointer-like issues, and invariant violations in class methods

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

CrossHair uses symbolic execution and SMT solving to find counterexamples to type-annotated functions with contracts, and can generate unit tests or detect behavioral differences between implementations.

Yes, if you work with type-annotated Python and want automated counterexample detection beyond traditional testing. The active maintenance, broad Python version support, and zero known vulnerabilities make it safe to adopt. Install friction is moderate due to z3-solver's compilation requirements, but prebuilt wheels are available. Best suited for projects where correctness is critical and you're willing to write contracts alongside type hints.

Install

crosshair-tool on PyPI

pip install crosshair-tool

uv add crosshair-tool

poetry add crosshair-tool

Installing crosshair-tool

Before you install

Medium install friction due to 7 runtime dependencies including z3-solver, a heavyweight SMT solver. Actively maintained with a release 24 days ago and 1314 repository stars. Supports Python 3.8 through 3.15 with prebuilt wheels across macOS, Linux, and Windows.

License in practice

MIT license permits commercial and private use with minimal restrictions, making it suitable for most development contexts.

Quickstart

pip install crosshair-tool

from crosshair.core import analyze

def example(x: int) -> int:
    """post: _ >= 0"""
    return x * 2

analyze(example)

z3-solver is a compiled dependency that may require build tools on some systems; symbolic execution can be computationally expensive for complex functions.

Verify before relying

• Whether IDE integrations for VS Code and PyCharm are actively maintained and compatible with current versions
• Performance characteristics and timeout behavior when analyzing large or complex codebases
• How well symbolic reasoning handles third-party library calls beyond the standard library

Package facts

Evidence: crosshair_tool-0.0.109-cp310-cp310-macosx_10_9_universal2.whl; crosshair_tool-0.0.109-cp310-cp310-macosx_10_9_x86_64.whl; crosshair_tool-0.0.109-cp310-cp310-macosx_11_0_arm64.whl; crosshair_tool-0.0.109-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl; crosshair_tool-0.0.109-cp310-cp310-musllinux_1_2_x86_64.whl; crosshair_tool-0.0.109-cp310-cp310-win32.whl; crosshair_tool-0.0.109-cp310-cp310-win_amd64.whl; crosshair_tool-0.0.109-cp311-cp311-macosx_10_9_universal2.whl; crosshair_tool-0.0.109-cp311-cp311-macosx_10_9_x86_64.whl; crosshair_tool-0.0.109-cp311-cp311-macosx_11_0_arm64.whl; crosshair_tool-0.0.109-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl; crosshair_tool-0.0.109-cp311-cp311-musllinux_1_2_x86_64.whl; crosshair_tool-0.0.109-cp311-cp311-win32.whl; crosshair_tool-0.0.109-cp311-cp311-win_amd64.whl; crosshair_tool-0.0.109-cp312-cp312-macosx_10_13_universal2.whl; crosshair_tool-0.0.109-cp312-cp312-macosx_10_13_x86_64.whl; crosshair_tool-0.0.109-cp312-cp312-macosx_11_0_arm64.whl; crosshair_tool-0.0.109-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl; crosshair_tool-0.0.109-cp312-cp312-musllinux_1_2_x86_64.whl; crosshair_tool-0.0.109-cp312-cp312-win32.whl

Tags

More Testing packages