{"id":9741,"library":"fault","title":"Fault Hardware Testing Framework","description":"Fault is a Python package for testing hardware designs, forming a core part of the magma ecosystem. It provides a unified, high-level interface to simulate and verify digital circuits directly from Python, supporting various hardware description languages and simulation targets like Verilator and Icarus. Currently at version 4.0.1, Fault is actively maintained with major versions typically introducing significant API improvements and architectural refactorings.","status":"active","version":"4.0.1","language":"en","source_language":"en","source_url":"https://github.com/leonardt/fault","tags":["hardware testing","magma","FPGA","ASIC","HDL","simulation","verification"],"install":[{"cmd":"pip install fault","lang":"bash","label":"Install core Fault library"},{"cmd":"pip install fault-verilator","lang":"bash","label":"Install Verilator simulation target (optional)"}],"dependencies":[{"reason":"Fault is built on the Magma hardware construction language and requires it for circuit definition and compilation.","package":"magma"}],"imports":[{"symbol":"Tester","correct":"from fault import Tester"},{"symbol":"MagmaTarget","correct":"from fault.magma_target import MagmaTarget"},{"symbol":"VerilatorTarget","correct":"from fault.verilator_target import VerilatorTarget"}],"quickstart":{"code":"import magma as m\nimport fault\n\n# Define a simple circuit using Magma\nclass MyCircuit(m.Circuit):\n    io = m.IO(I=m.In(m.Bit), O=m.Out(m.Bit))\n    io.O @= io.I\n\n# Create a Tester instance for the circuit\ntester = fault.Tester(MyCircuit)\n\n# Poke inputs and expect outputs\ntester.poke(MyCircuit.I, 1)\ntester.expect(MyCircuit.O, 1)\ntester.poke(MyCircuit.I, 0)\ntester.expect(MyCircuit.O, 0)\n\n# Compile and run the test using a target (e.g., Verilator)\n# Ensure 'verilator' is installed on your system and 'fault-verilator' is installed via pip\ntry:\n    tester.compile_and_run(\"verilator\", magma_output=\"mlir\")\n    print(\"Test passed successfully with Verilator!\")\nexcept Exception as e:\n    print(f\"Test failed: {e}\")\n    print(\"Make sure 'verilator' is installed and in your PATH, and 'pip install fault-verilator' has been run.\")","lang":"python","description":"This quickstart demonstrates how to define a simple Magma circuit, create a `fault.Tester` for it, apply inputs (`poke`), verify outputs (`expect`), and run the simulation using a Verilator target. Note that external simulators like Verilator often require system-level installation in addition to Python packages."},"warnings":[{"fix":"Upgrade Magma to the latest 3.x version: `pip install --upgrade magma`.","message":"Fault 4.0.0 and higher require Magma 3.0.0 or higher. Older versions of Magma are incompatible and will lead to import errors or unexpected behavior.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update import statements to use top-level `from fault import ...` or directly import from `fault-core` if low-level components are explicitly needed.","message":"The package structure underwent a significant refactoring in Fault 3.0.0. Direct imports from internal or deprecated submodules like `fault.core` (which became `fault-core`) may no longer work. Users should rely on top-level imports from `fault`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Consult the `fault` documentation for the 2.x API to adapt custom targets and `compile_and_run` calls.","message":"The `Target` API was substantially revised in Fault 2.0.0, affecting how simulation targets are configured and used. Custom targets or direct interaction with `SimulatorTarget` will require updates, and `compile_and_run` method signatures changed.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure the specific `fault-` Python package for your target is installed (e.g., `pip install fault-verilator`), and that the corresponding external simulator executable (e.g., `verilator`) is installed and available in your system's PATH.","message":"Simulation targets (e.g., Verilator, Icarus, Eldo) often require both a Python wrapper package (e.g., `fault-verilator`) AND the external simulator executable to be installed on your system and discoverable via your system's PATH.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `magma` explicitly: `pip install magma`.","cause":"The core `magma` library, which `fault` depends on, has not been installed.","error":"ModuleNotFoundError: No module named 'magma'"},{"fix":"Use top-level imports directly from the `fault` package (e.g., `from fault import Tester`) or install and import from `fault-core` if you need the low-level components directly.","cause":"This typically occurs when attempting to import from internal or deprecated submodules due to the package restructuring in `fault` 3.0.0.","error":"AttributeError: module 'fault' has no attribute 'CoreTester'"},{"fix":"Install the simulator executable (e.g., `sudo apt-get install verilator` on Debian/Ubuntu) and/or its Python wrapper (`pip install fault-verilator`). Ensure the simulator executable's directory is included in your system's PATH environment variable.","cause":"The specified hardware simulator (e.g., Verilator) is either not installed on your system, not accessible via the system PATH, or its corresponding `fault-` Python wrapper is missing.","error":"RuntimeError: Target 'verilator' not found. Is it installed and in your PATH?"}]}