Getting Started

Requirements

  • Python 3.6 or higher. Python 2 is not supported.

  • The required Python packages are the following:

archspec==0.1.2
argcomplete==1.12.3
coverage==5.5
importlib_metadata==4.0.1; python_version < '3.8'
jsonschema==3.2.0
lxml==4.6.3
pytest==6.2.3
pytest-forked==1.3.0
pytest-parallel==0.1.0
PyYAML==5.4.1
requests==2.25.1
semver==2.13.0
setuptools==56.0.0
wcwidth==0.2.5
#+pygelf%pygelf==0.4.0

Note

Changed in version 3.0: Support for Python 3.5 has been dropped.

Getting the Framework

Stable ReFrame releases are available through different channels.

Spack

ReFrame is available as a Spack package:

spack install reframe

There are the following variants available:

  • +docs: This will install the man pages of ReFrame.

  • +gelf: This will install the bindings for handling Graylog log messages.

EasyBuild

ReFrame is available as an EasyBuild package:

eb ReFrame-VERSION.eb -r

This will install the man pages as well as the Graylog bindings.

PyPI

ReFrame is available as a PyPI package:

pip install reframe-hpc

This is a bare installation of the framework. It will not install the documentation, the tutorial examples or the bindings for handling Graylog log messages.

Github

Any ReFrame version can be very easily installed directly from Github:

pushd /path/to/install/prefix
git clone -q --depth 1 --branch VERSION_TAG https://github.com/eth-cscs/reframe.git
pushd reframe && ./bootstrap.sh && popd
export PATH=$(pwd)/bin:$PATH
popd

The VERSION_TAG is the version number prefixed by v, e.g., v3.5.0. The ./bootstrap.sh script will fetch ReFrame’s requirements under its installation prefix. It will not set the PYTHONPATH, so it will not affect the user’s Python installation. The ./bootstrap.sh has two additional variant options:

  • +docs: This will also build the documentation.

  • +pygelf: This will install the bindings for handling Graylog log messages.

Note

New in version 3.1: The bootstrap script for ReFrame was added. For previous ReFrame versions you should install its requirements using pip install -r requirements.txt in a Python virtual environment.

Enabling auto-completion

New in version 3.4.1.

You can enable auto-completion for ReFrame by sourcing in your shell the corresponding script in <install_prefix>/share/completions/reframe.<shell>. Auto-completion is supported for Bash, Tcsh and Fish shells.

Note

Changed in version 3.4.2: The shell completion scripts have been moved under share/completions/.

Where to Go from Here

The easiest way to start with ReFrame is to go through Tutorial 1: Getting Started with ReFrame, which will guide you step-by-step in both writing your first tests and in configuring ReFrame. The Configuring ReFrame for Your Site page provides more details on the basic configuration aspects of ReFrame. Advanced Topics explain different aspects of the framework whereas ReFrame Manuals provide complete reference guides for the command line interface, the configuration parameters and the programming APIs for writing tests.