How to add unit test
====================

Unit test brings some advantages, briefly, we can list some of them (reference
[1](https://en.wikipedia.org/wiki/Unit_testing)):

* Tests reduce bugs in new features;
* Tests reduce bugs in existing features;
* Tests are good documentation;
* Tests reduce the cost of change;
* Tests allow refactoring;

With those advantages in mind, it was required to choose a framework which fits
well with C/C++ code.  Hence, it was chosen (google test)
[https://github.com/google/googletest], because it is largely used and it is
relatively easy learn.

Install and configure google test (manually)
--------------------------------------------

In this section, you will see a brief description of how to install google
test. However, it is strongly recommended that you take a look to the official
repository (https://github.com/google/googletest) and refers to that if you
have any problem to install it. Follow the steps below:

* Install: cmake and pthread
* Clone google test project from: https://github.com/google/googletest and
  enter in the project directory
* Inside project directory, type:

```
cmake -DBUILD_SHARED_LIBS=ON .
make
```

* After compilation, copy all "*.so" inside directory "googlemock" and
  "googlemock/gtest" to "/usr/lib/"
* Done! Now you can compile your tests.

If you have any problem, go to the official repository to find help.

Ps.: Some distros already have googletest packed. If your distro supports it,
you can use it instead of compile.

Create new unit test
--------------------

If you want to add new unit tests for Yosys, just follow the steps below:

* Go to directory "yosys/test/unit/"
* In this directory you can find something similar Yosys's directory structure.
  To create your unit test file you have to follow this pattern:
  fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the
  unit test for kernel/celledges.cc, you will need to create a file like this:
  tests/unit/kernel/celledgesTest.cc;
* Implement your unit test

Run unit test
-------------

To compile and run all unit tests, just go to yosys root directory and type:
```
make unit-test
```

If you want to remove all unit test files, type:
```
make clean-unit-test
```