Skip to content

contributing.md

Latest commit

 

History

History
147 lines (100 loc) · 3.76 KB

contributing.md

File metadata and controls

147 lines (100 loc) · 3.76 KB
Raw

Getting Started

Install the project requirements and the pre-commit framework:

pip install -r requirements.txt
pip install pre-commit

Setting up Pre-Commit Hooks

To ensure code quality and consistency, enable the pre-commit hooks:

pre-commit install --hook-type pre-commit --hook-type pre-push

On every commit, the hooks will run the unit tests located in tests/unit/disable_jit and tests/unit/dont_disable_jit. Functional tests in tests/functional execute on every push. You can trigger all checks manually with pre-commit run --all-files.

Linting

We are working to update the codebase to comply with ruff linting rules. Run this command to view linting results:

ruff check .

Running Tests

Enhanced Test Suite

PyReason uses a unified test runner that handles multiple test configurations automatically. The test suite is organized into four directories:

  • tests/unit/api_tests/ - Tests for main pyreason.py API functions (JIT enabled, real pyreason)
  • tests/unit/disable_jit/ - Tests for internal interpretation logic (JIT disabled, stubbed environment)
  • tests/unit/dont_disable_jit/ - Tests for components that benefit from JIT (JIT enabled, lightweight stubs)
  • tests/functional/ - End-to-end functional tests (JIT enabled, real pyreason, longer running)

Quick Start

# Install testing dependencies
make install-deps

# Run all test suites with unified coverage
make test

# Run only fast test suites
make test-fast

# Generate HTML coverage report
make coverage-html

Individual Test Suites

# API tests (real pyreason, JIT enabled)
make test-api

# JIT disabled tests (stubbed environment)
make test-jit

# JIT enabled tests (lightweight stubs)
make test-no-jit

# Consistency tests
make test-consistency

# Functional/end-to-end tests
make test-functional

Advanced Options

# Run with parallel execution where possible
make test-parallel

# Run without coverage collection (faster)
python run_tests.py --no-coverage

# Run specific suites
python run_tests.py --suite api_tests --suite dont_disable_jit

# Run functional tests (multiple options)
make test-functional          # Using test runner
pytest tests/functional       # Traditional approach

Traditional Pytest (Per Suite)

You can still run pytest directly on individual directories:

# API tests
pytest tests/unit/api_tests/ -v

# JIT disabled tests
NUMBA_DISABLE_JIT=1 pytest tests/unit/disable_jit/ -v

# JIT enabled tests
pytest tests/unit/dont_disable_jit/ -v

# Functional tests
pytest tests/functional/ -v

Coverage Reports

The test runner automatically combines coverage from all suites:

  • Terminal Report: Summary shown after test execution
  • HTML Report: test_reports/htmlcov/index.html
  • XML Report: test_reports/coverage.xml

Troubleshooting

# Check system status and dependencies
make info
make check-deps

# Validate test runner setup
python test_runner_validation.py

# Test pytest configuration
python -c "import configparser; c=configparser.ConfigParser(); c.read('pytest.ini'); print('pytest.ini is valid')"

# Run a single functional test
pytest tests/functional/test_hello_world.py -v

# Clean up generated files
make clean

Common Issues:

  • Functional tests fail with warnings: The pytest.ini has been updated to ignore expected warnings from numba and networkx
  • Tests time out: Functional tests have longer timeouts (600s) and global timeout is disabled
  • Import errors: Ensure pytest and dependencies are installed with make install-deps

Running tests locally before committing or pushing helps catch issues early and speeds up code review. The unified test runner ensures consistent behavior across different development environments.