Contributing

Development Setup

Clone the repository and install in editable mode:

git clone https://github.com/glenzac/svblock.git
cd svblock
pip install -e ".[dev,sphinx]"

Running Tests

The test suite includes 174 tests covering the parser, model, layout, renderer, CLI, themes, and end-to-end snapshot tests.

# Run all tests
pytest

# Run a specific test file
pytest tests/test_parser.py

# Run a single test by name
pytest tests/test_parser.py -k test_simple_module

# Run with verbose output
pytest -v

Linting

The project uses ruff for linting:

ruff check src/ tests/

Type Checking

Type hints are enforced with mypy:

mypy src/svblock/ --ignore-missing-imports

Snapshot Tests

End-to-end tests compare rendered SVG output against golden reference files in tests/snapshots/. If you make changes to the renderer or layout engine that intentionally change the output:

  1. Run the snapshot update script:

    python tests/update_snapshots.py

  2. Review the diffs in tests/snapshots/ to verify the changes are correct.

  3. Commit the updated snapshots with your code changes.

Test Fixtures

Test fixtures are .sv files in tests/fixtures/ that cover a range of SystemVerilog patterns:

  • simple_module.sv – minimal 3-port module

  • annotated_module.sv – explicit @sym group annotations

  • bus_ports.sv – parametric bus widths

  • clock_reset.sv – heuristic clock/reset detection

  • active_low.sv – active-low signal detection

  • interface_ports.sv – interfaces with modports

  • large_module.sv – complex multi-group module

  • params.sv – various parameter types

  • multidim_array.sv – multi-dimensional arrays

  • non_ansi.sv – non-ANSI port style

  • no_ports.sv – empty module edge case

  • partial_annotations.sv – mixed annotated/unannotated ports

  • type_params.sv – parametric types

Project Structure

See Architecture for a detailed overview of the codebase organization and pipeline design.