Testing Yosys¶

Running the included test suite¶

The Yosys source comes with a test suite to avoid regressions and keep everything working as expected. Tests can be run by building the test target from the root Yosys directory. By default, this runs vanilla and unit tests.

cmake -B build .
cmake --build build --target test --parallel $(nproc)

Warning

There are limitations when using Ninja as generator, so we suggest using Unix Makefiles to make running tests in parallel possible. However, it is possible to use it directly by running:

cd tests
make -j9

Please note that in this case default build directory is build but can be overwritten by providing BUILD_DIR variable.

Vanilla tests¶

These make up the majority of our testing coverage. They can be run with the test-vanilla CMake target. Usually their structure looks something like this: you write a .ys file that gets automatically run, which runs a frontend like read_verilog or read_rtlil with a relative path or a heredoc, then runs some commands including the command under test, and then uses Selections with -assert-count. Usually it’s unnecessary to “register” the test anywhere as if it’s being added to an existing directory, depending on how the run-test.sh in that directory works.

Unit tests¶

Running the unit tests requires the following additional packages:

Ubuntu

sudo apt-get install libgtest-dev

macOS

No additional requirements.

Unit tests can be run with the test-unit CMake target.

Functional tests¶

Testing functional backends (see Writing a new backend using FunctionalIR) has a few requirements in addition to those listed in Build prerequisites:

Ubuntu

sudo apt-get install racket
raco pkg install rosette
pip install pytest-xdist pytest-xdist-gnumake

macOS

brew install racket
raco pkg install rosette
pip install pytest-xdist pytest-xdist-gnumake

If you don’t have one of the CAD suite(s) installed, you should also install Z3 following their instructions.

Functional tests are disabled by default, to enable them use next code snippet and run tests as usual:

cmake -B build . -DYOSYS_ENABLE_FUNCTIONAL_TESTS=ON
cmake --build build --target test --parallel $(nproc)

Or run just functional tests with:

cmake --build build --target test-functional

Docs tests¶

There are some additional tests for checking examples included in the documentation, which can be run with the test-docs CMake target. This also includes checking some macro commands to ensure that descriptions of them are kept up to date, and is mostly intended for CI.

Automatic testing¶

The Yosys Git repo has automatic testing of builds and running of the included test suite on both Ubuntu and macOS, as well as across range of compiler versions. For up to date information, including OS versions, refer to the git actions page.